$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 $READ.

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 $READs 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 $READs 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 $READs 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 earlier is included. Note the stacking of responses on a single input line.

INCLUDE ENTRY ??TYPE PERSONNEL $$NAME ROBERT $$AGE 27 $$MORE? YES $$NAME LOUISE 28 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 User Language 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

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