| DIR(0) |
Input |
DIR(0) is the only required input variable. It is a
three piece variable. The first character of the first piece must be defined
(or first 3 characters for DD-type). Additional characters of the first piece
and the second two pieces are all optional.
The first character of the first up-arrow piece indicates the type of the
input to be read. The second piece describes parameters, delimited by colons,
to be applied to the input. Examples are maximum length for free text data or
decimal digits for numeric data. The third piece is executable MUMPS code that
acts on the input in the same manner as an input transform.
Piece-1 of DIR(0) (Subsequent Characters are Optional):
The first up-arrow piece of DIR(0) can contain other parameters that help to
specify the nature of the input or modify the behavior of the reader. These
characters must appear after the character indicating type (or after the field
number if it is a DD type). They are described below (examples are provided
later in this section):
A Indicates that nothing should be appended to the programmer-supplied prompt
DIR("A"), which is described below. If there is no DIR("A"), then no prompt is
issued.
O Indicates that a response is optional. If this is not included, then a null
response is not allowed. For DD type reads, the O is automatically included if
the field in question is not a required field.
X Only applies to the set of codes. Indicates that an exact match is
requested. No lowercase to uppercase conversion is to be done.
B Only applies to a set of codes; indicates that the possible choices are to
be listed horizontally after the prompt.
M Only applies to a set of codes and indicates that mixed case input is
allowed. Uppercase input, for example, would match a lowercase code. To
achieve this matching, do not include the X parameter since that would
override the M and require an exact match.
U Only applies to free text reads. It allows the user response to contain ^
(up-arrow). A leading up-arrow aborts the read and set DUOUT and DIRUT whether
or not U is in DIR(0). However, the U allows ^s to be embedded in the user
response.
C Only applies to list reads. The values returned in Y and the Y() array are
compressed. They are not expanded to include each individual number; rather,
ranges of values are returned using the hyphen syntax. This is similar to the
format in which the user can enter a ranges of numbers.
This flag is particularly useful when a user may select many numbers; for
example, when decimals are involved. The call is much faster and the
possibility of the local symbol table filling up with nodes in the Y() array
is eliminated.
Piece-2 of DIR(0) (Optional)
Qualifying limits on user response are as described in summary table above.
Piece-3 of DIR(0) (Optional)
The third piece of DIR(0) is executable MUMPS code that acts like the input
transform of a field in a data dictionary. The value that was entered by the
user is contained in the variable X. The code can examine X and, if it is not
appropriate, should kill X. If X is undefined after the execution of the third
piece of DIR(0), the reader knows that the input was unacceptable, issues a
help message, and re-asks for input.
|
DA |
Input |
(Optional) For DD-type reads only, if DIR("B") is not
set, you may retrieve a value from the database to display as a default.
|
DIR("A") |
Input |
(Optional) The reader provides a generic default
prompt for each type, e.g., enter a number, or enter response.
|
DIR("A",#) |
Input |
(Optional) If you want to issue a longer message
before actually reading the input, you can set the DIR("A",#) array in
addition to DIR("A"). The #'s must be numeric.
|
DIR("B") |
Input |
(Optional) Set this variable to the default response
for the prompt issued.
|
DIR("L",#) |
Input |
(Optional) Only applies to set-of-codes fields. Lets
you replace the standard vertical listing of codes that the Reader displays
with your own listing.
|
DIR("S") |
Input |
(Optional) Use the DIR("S") variable to screen the
allowable responses for pointer, set of codes, and list/range reads.
|
DIR("T") |
Input |
(Optional) Time-out value to be used in place of
DTIME. Value is represented in seconds.
|
DIR("?") |
Input |
(Optional) This variable contains a simple help
prompt which is displayed to the user when one question mark is entered.
|
DIR("?",#) |
Input |
(Optional) This array allows the user to display more
than one line of help when the user types a single question mark.
|
DIR("??") |
Input |
(Optional) This variable, if defined, is a two-part
variable. The first up-arrow piece may contain the name of a help frame.
|
X |
Output |
This is the unprocessed response entered by the user.
It is always returned.
|
Y |
Output |
Y is always defined as the processed output.
Date The date/time in VA FileMan format. End-of-page Y=1 for continue (user
pressed <RET>). Y=0 for exit (the user pressed up-arrow). Y="" for time out
(the user timed out). Free-text The data typed in by the user. In this case,
it is the same as X. List or range The list of numeric values, delimited by
commas and ending with a comma.
If the C flag was not included in the first piece of DIR(0), an expanded list
of numbers, including each individual number in a range, is returned. If the
C flag was included, a compressed list that uses the hyphen syntax to indicate
a range of numbers is returned.
Any leading zeros or trailing zeros following the decimal point are removed;
i.e., only canonic numbers are returned. If the list of returned numbers has
more than 245 characters, integer-subscripted elements of Y [Y(1), Y(2), etc.]
contain the additional numbers. Y(0) is always returned equal to Y. Numeric
The canonic value of the number entered by the user; i.e., leading zeros are
deleted and trailing zeros after the decimal are deleted. Pointer The normal
value of Y from a DIC lookup, that is, Internal Entry Number^Entry Name. If
the lookup was unsuccessful, Y=-1. Set of Codes The internal value of the
response. Yes/No Y=1 for yes. Y=0 for no DD (#,#) The first ^-piece of Y
contains result of the variable X after it has been passed through the input
transform of the field specified. Depending on the data type involved,
subsequent ^-pieces may contain additional information. The following list
summarizes the values of Y upon timeout, up-arrows, or <RET>s for all reads.
Exceptions are noted.
Condition Value of Y Comments Timeout Y="" -- Up-arrow (^) Y=^ in all cases
except end-of-page reads. Y=0 upon end-of-page reads. -- Double Up-arrow
(^^) Y=^^ -- Return Y="" for optional reads (reads allowing a null response).
Y=-1 for pointer reads. Y=0 for YES/NO type when NO is default. Y=1 for YES/NO
type when YES is default. Y=1 for end-of-page reads. Y=default when a default
is provided other than forYES/NO type questions.
|
Y(0) |
Output |
This is defined for the set of codes, list, pointer,
date, and Yes/No reads. It is also returned for DD reads when the field has a
set of codes, pointer, variable pointer, or date data type.
|
DTOUT |
Output |
If the read has timed-out, then DTOUT is defined.
|
DUOUT |
Output |
If the user entered a leading up-arrow, DUOUT is
defined.
|
DIRUT |
Output |
If the user enters a leading up-arrow, times out, or
enters a null response, DIRUT is defined.
|
DIROUT |
Output |
If the user entered two up-arrows, DIROUT is defined.
|
DIR("PRE") |
Input |
(Optional) This variable contains M code that acts as
a pre-validation transform. It can either change X, in which case the reader
will proceed as though the new value is what the user entered, or kill X, in
which case the reader will behave as though the user entered an illegal value.
DIR("PRE") is executed almost immediately after the READ takes place, just
after DTOUT is set if the READ timed out, and before any other checking is
done. The only inputs are X and DTOUT, and the only outputs are X and DTOUT.
|