$Read

The $Read function enables the user to enter data from the terminal as a request is evaluated. $Read is useful when creating generalized requests. You can also use $Read to read a sequential input file; see Using the $Read function to read sequential input.

Syntax

The format for the $Read function is:

$Read([prompt][, option])

Where:

• prompt is the literal to appear on the terminal, prompting for input. This argument is optional.
• option indicates how the input value is to be returned. The only valid option is TRANSPARENT. When this argument is present, $Read does not translate LINEND characters as the logical end of line nor a hyphen as the continuation character, remove trailing blanks, or convert lowercase characters to uppercase. $Read simply returns the input line of up to 255 characters exactly as entered.

Prompting the user for a line of input

Each time $Read is evaluated, Model 204 prompts the user for a line of input. The response becomes the character string value returned by the function. For example:

$read('HELLO')

causes Model 204 to respond:

$$HELLO

and wait for the user to enter a reply each time the function is evaluated.

If the user keys in:

GOODBYE

in reply, the function returns a value equal to the quoted string 'GOODBYE'.

If no prompt argument is specified, as $Read(), the prompt is:

$$

The end of the user's reply is delimited by a carriage return or a semicolon. However, if the user ends the first line of reply with a hyphen, the carriage return is ignored, and the reply can be continued on another line.

Including $Read functions and dummy strings in a procedure

If $Read functions are included in a procedure, one or more responses to the $Read statements can be specified in the command that invokes the procedure, along with responses to dummy strings included in the procedure. The following procedure contains a typical data entry request.

PROCEDURE ENTRY BEGIN NAME.AND.AGE: %A = $READ('NAME') %B = $READ('AGE') STORE RECORD TYPE = ??TYPE NAME = %A AGE = %B END STORE IF $READ('MORE?') EQ 'YES' THEN - JUMP TO NAME.AND.AGE END IF END END PROCEDURE

You can include the procedure and specify responses for the $Read functions and dummy strings included in the procedure by issuing the following:

INCLUDE ENTRY, PERSONNEL, ROBERT, 27, YES, LOUISE, 28, NO

Dummy string responses must appear first, followed by $Read responses. If any $Read responses are included in the list, it also must include a response for each dummy string encountered before the first $Read is executed.

As dummy strings and $Read statements are encountered in the procedure being executed, entries are retrieved from the list specified in the INCLUDE or IF line. No prompts are issued for responses taken from the list. If there are more dummy strings and $Reads than responses in the list, Model 204 prompts for a response as if no list had been specified.

Alternatively, if the user responds to a request with several $Read statements in a row, the user can wait for the first prompt and then enter several replies at once, separating them by semicolons. Model 204 prints the prompts for the next $Reads but does not wait for the user to reply to each one.

Results of $Read prompts

Results of $Read prompts contain leading or intermediate blanks that the user enters if the TRANSPARENT argument is not specified. However, trailing blanks are dropped. This occurs when the ENTRY procedure shown in the preceding section is included. Note the stacking of responses on a single input line. User entries are in bold.

INCLUDE ENTRY ??TYPE PERSONNEL $$NAME ROBERT $$AGE 27 $$MORE? YES $$NAME LOUISE 28 $$AGE $$MORE? YES $$NAME DALE 24; YES; RICHARD; 37; YES: THO- MAS 59; NO $$AGE $$MORE? $$NAME $$AGE $$MORE? $$NAME $$AGE $$MORE?

This example illustrates the differences between dummy strings and the $Read function.

Dummy strings allow the user to fill in pieces of the request text just before compilation begins. The user's replies to ?? prompts are substituted before the text is compiled. ??TYPE is replaced only once, at compilation time, by PERSONNEL.

$$ prompts and $Read function input not specified at INCLUDE time are processed when the request is evaluated. Substitutions for these prompts are accepted as character strings; no text or character evaluation is made. Consider the following example:

BEGIN PRINT.COUNT: FIND AND PRINT COUNT AGE = ??AGE END FIND END BEGIN %AGE = $READ('ENTER AGE') PRINT.COUNT: FIND AND PRINT COUNT AGE = %AGE END FIND END

In the first request, if the user replies 10 OR 11 to the ??AGE prompt, the line AGE = 10 OR 11 is properly compiled and the request searches for records with AGE either 10 or 11. However, if the user replies 10 OR 11 to the $$ENTER AGE prompt in the second request, 10 OR 11 is considered a character string and Model 204 searches for records with AGE fields containing the string 10 OR 11.

If the user presses the attention key (ATTN, BREAK, or PA1, depending on terminal type) or enters *CANCEL in response to a $Read prompt, Model 204 performs the action specified in the ON ATTENTION unit (see ON units) if one is specified in the request.

If ON ATTENTION is not specified, Model 204 terminates the request and all nested procedures. Control is returned to the command level at the user's terminal.

Using the $Read function to read sequential input

You can use the $Read function to read sequential input:

1. Run Model 204 in batch mode. $Read assumes terminal input in online mode and sequential input (for example, tape or disk) in batch mode.
2. Concatenate a SOUL procedure to the sequential input to be read. The following JCL is required:

   // CCAIN DD DSN=USER.LANG.PROCEDURE,DISP=OLD DD DSN=SEQU.INPUT.FILE,DISP=OLD

3. Use the $Substr function to parse the input. For example:

   %fielda=$Substr(%input,1,10) %fieldb=$Substr(%input,11,5)

   The input is read into the %variable, for example, %input). It cannot exceed 255 characters in length.

Read Image does not return INCLUDE command tokens

The Read Image statement with the Terminal option can be useful to obtain user input, and in some cases is more advantageous than $Read because it is independent of the argument string on an INCLUDE command. For example, consider this procedure:

PROCEDURE FOO begin %file is longstring %password is string len 255 %file = %(system):arguments:unspace:toUpper %password = $read('Password?', 'TRANSPARENT')  ;* TRANSPARENT used in case pwd ends in a hyphen, say openC %file password %password end END PROC FOO

If the above procedure is invoked as follows, the user is not prompted, and no input is taken from the user:

INCLUDE FOO MYFILE

The string MYFILE, which is the first token in the above INCLUDE command argument string, is returned as the value of $Read. However, in the following approach, the user is prompted to input the password value:

PROCEDURE FOO begin %file is longstring %password is string len 255 %file = %(system):arguments:unspace:toUpper image str s is string len 255 end image open terminal for input read image str from terminal prompt 'Password?' openC %file password %str:s end END PROC FOO