Required: First character of Piece-1 (first 3 characters for DD-type)

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 M code that acts on the input in the same manner as an INPUT transform. The acceptable types are shown below:

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 and examples are provided later in this section):

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.

Only applies to a set of codes; indicates that the possible choices are to be listed horizontally after the prompt.

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 range 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.

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.

If users do not choose to accept the default response, they must type in their entire response. They will not get the "Replace-With" prompt, regardless of how long the default response is.

Only applies to free text reads. It allows the user response to contain ^ (Up-arrow). A leading up-arrow aborts the read and sets DUOUT and DIRUT whether or not U is in DIR(0). However, the U allows ^s to be embedded in the user response.

Only applies to the set of codes. Indicates that an eXact match is requested. No lowercase to uppercase conversion is to be done.

Piece-2 of DIR(0) (Optional)

Qualifying limits on user response are as described in the summary table above.

Piece-3 of DIR(0) (Optional)

The third piece of DIR(0) is executable M 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. It is unnecessary to put checks for minimum and maximum or length in the third piece. These should be specified in the second piece of DIR(0). An example of DIR(0) with all three pieces is:

    S DIR(0)="F^3:30^K:X'?.U X"

which says that if the input is not all uppercase, then the data is unacceptable. The check for a length from 3 to 30 characters takes place automatically because of the second piece. The third piece is not executed if the specifications in the second piece are not met. If the user combines the DD data type with a third piece in DIR(0), for example:

   S DIR(0)="19,.01^^K:X'?1""DI"" X"

then the third piece of DIR(0) is not executed until after the INPUT transform has been executed and X was not KILLed by the transform.

For pointer-type reads, the third piece of DIR(0) is executed after an entry is selected from the file.

(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. Identify the entry from which the value should come by setting the DA variable to its record number. If a subfile is involved, set up a DA() array where DA equals the record number for the lowest level subfile, DA(1) for the next higher, and so on.

NOTE: Although you can retrieve defaults from the database by using DA, the values in the database are not changed by ^DIR calls.

(Optional) The reader provides a generic default prompt for each type, e.g., enter a number or enter response. To issue a more meaningful prompt, DIR("A") can be set to a character string that more clearly indicates the nature of the data being requested. For example, setting the following:

    S DIR("A")="PRICE PER DISPENSE UNIT: "
    S DIR(0)="NA^0:5:2"

causes the prompt to appear as:

    PRICE PER DISPENSE UNIT:

(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. After the array has been displayed, DIR("A") is issued as the prompt for the read. It is necessary for DIR("A") to be set if the programmer is to use this array. For example, setting the following:

    S DIR("A")="PRICE PER DISPENSE UNIT:"
    S DIR("A",1)="Enter price data with two decimal points."
    S DIR("A",2)="Cost calculations require this precision."

causes the following dialog to appear to the user:

    Enter price data with two decimal points.
    Cost calculations require this precision.
    PRICE PER DISPENSE UNIT:

(Optional) Set this variable to the default response for the prompt issued. It appears after the prompt and before the // (double slashes). If the user simply presses the Enter/Return key, the default response is accepted by the reader.

(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. It is up to you to ensure that the contents of the DIR("L") array match the codes in the second ^-piece of DIR(0).

The format of the DIR("L") array is similar to DIR("A") and DIR("?"). The #'s must be numeric starting from 1. The numeric subscripted array nodes are written first and the DIR("L") node is written last. For example, if you code:

    S DIR(0)="SO^1:ONE;2:TWO;3:THREE;4:FOUR;5:FIVE" 
    S DIR("L",1)="Select one of the following:" 
    S DIR("L",2)="" 
    S DIR("L",3)="  1  ONE      4  FOUR" 
    S DIR("L",4)="  2  TWO      5  FIVE" 
    S DIR("L")="  3  THREE" 
    D ^DIR

the user sees the following:

    Select one of the following: 
 
    1  ONE      4  FOUR 
    2  TWO      5  FIVE 
    3  THREE    

    Enter response:

(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 user had entered the new value in X, 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.

(Optional) Use the DIR("S") variable to screen the allowable responses for pointer, set of codes, and list/range reads. This variable works as the DIC("S") variable does for ^DIC calls. Set DIR("S") equal to M code containing an IF statement. After execution, if $T is set to 1, the user response is accepted; if set to 0, it is not.

For pointer reads, when DIR("S") is executed, the M naked indicator is equal to the 0 node of the entry being screened. The variable Y equals its record number.

For set of codes reads, when the DIR("S") is executed, Y equals the internal code.

For list/range reads, if you also use the C flag in piece 1 of DIR(0), your output is still compressed. Internally during the call, however, the range must be uncompressed so that each number in the range can be screened. So using DIR("S") with the C flag during list/range reads loses the C flag's advantages in speed (but the C flag's advantage in avoiding storage overflows remains).

(Optional) Time-out value to be used in place of DTIME. Value is represented in seconds.

(Optional) This variable contains a simple help prompt which is displayed to the user when one question mark is entered. It usually takes the place of the reader's default prompt. For example, if you code:

    S DIR(0)="F^3:10"
    S DIR("?")="Enter from three to ten characters"
    S DIR("A")="NICKNAME"
    D ^DIR

the user sees the following:

    NICKNAME: ?
    Enter from three to ten characters.

NOTE: When displayed, a period (.) is added to the DIR("?") string. Periods are not appended when displaying the DIR("?",#) array, however.

When one question mark is entered in DD reads, the data dictionary's help prompt is shown before DIR("?"). For pointer reads, a list of choices from the pointed-to file is shown in addition to DIR("?").

As an alternative, you can set DIR("?") to an up-arrow followed by M code, which is executed when the user enters one question mark. An example might be:

    S DIR("?")="^D HELP^%DTC"

Execution of this M code overrides the reader's default prompt. If DIR("?") is defined in this way (a non-null second piece), the DIR("?",#) array is not displayed.

(Optional) This array allows the user to display more than one line of help when the user types a single question mark. The first up-arrow piece of DIR("?") must be set for the array to be used. The second up-arrow piece of DIR("?") must be null, otherwise the DIR("?",#) array is ignored. The #'s must be numeric starting from 1. The numbered lines are written first, that is, first DIR("?",1), then DIR("?",2), etc. The last help line written is DIR("?"). These lines are the only ones written, which means that the reader's default prompt is not issued.

(Optional) This variable, if defined, is a two-part variable. The first up-arrow piece may contain the name of a help frame. The help processor displays this help frame if the user enters two question marks.

The second part of this variable (after the first up-arrow piece) may contain M code that is executed after the help frame is displayed.

For example:

    S DIR("??")="DIHELPXX^D EN^XXX"

NOTE: In order to use this variable, you must have Kernel's help processor on your system.

This is the unprocessed response entered by the user. It is always returned. If the user accepts the default in DIR("B"), it is the default. If the user up-arrows out or just presses the Enter/Return key on an optional input, X is the up-arrow or null.

Y is always defined as the processed output. The values returned are:

The following list summarizes the values of Y upon timeout, up-arrows, or pressing the Enter/Return keys for all reads. Exceptions are noted.

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. It holds the external value of the response for set of codes or Yes/No, the zero node of the entry selected for a pointer, and the external date for a date and variable pointer. To have Y(0) returned for pointer-types, the DIC(0) string in the second piece of DIR(0) must contain a Z, for example:

    DIR(0)="P^19:EMZ"

For list reads, it contains the same values as the Y variable. There may be additional nodes in the Y() array depending on the size of the list selected by the user.

If the read has timed-out, then DTOUT is defined.

If the user entered a leading up-arrow, DUOUT is defined.

If the user enters a leading up-arrow, times out, or enters a null response, DIRUT is defined. A null response results from pressing the Enter/Return key at a prompt with no default or entering the at-sign (@), signifying deletion. If, however, the user presses the Enter/Return key in response to an end of page read, DIRUT is not defined. If DIRUT is defined, the user can enter the following common check to quit after a reader call:

    Q:$D(DIRUT)

If the user entered two up-arrows, DIROUT is defined.