$Read: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (Mlarocca moved page $READ to $Read: Lower case change)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<p>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|$READ]].    </p>
<p>
<b>Syntax</b>
The <var>$Read</var> function enables the user to enter data from the terminal as a request is evaluated. <var>$Read</var> is useful when creating generalized requests. You can also use <var>$Read</var> to read a sequential input file; see [[#Using the $Read function to read sequential input|Using the $Read function to read sequential input]].    </p>
<p>The format for the $READ function is:</p>
 
<p class="code">$READ([prompt][,option])  
==Syntax==
</p>
<p>
<p>where:</p>
The format for the <var>$Read</var> function is:</p>
<p class="syntax">$Read([<span class="term">prompt</span>][, <span class="term">option</span>])  
</p>  
<p>Where:</p>
<ul>
<ul>
<li>prompt is the literal to appear on the terminal, prompting for input. This argument is optional.</li>
<li><var class="term">prompt</var> is the literal to appear on the terminal, prompting for input. This argument is optional.</li>
</li>
 
<li>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.  </li>
<li><var class="term">option</var> indicates how the input value is to be returned. The only valid option is <var>TRANSPARENT</var>. When this argument is present, <var>$Read</var> does not translate <var>LINEND</var> characters as the logical end of line nor a hyphen as the continuation character, remove trailing blanks, or convert lowercase characters to uppercase. <var>$Read</var> simply returns the input line of up to 255 characters exactly as entered.  </li>
</li>
</ul>
</ul>
<b>Prompting the user for a line of input</b>
 
<p>Each time $READ is evaluated, <var class="product">Model&nbsp;204</var> prompts the user for a line of input. The response becomes the character string value returned by the function. For example: </p>
==Prompting the user for a line of input==
<p class="code">$READ('HELLO')  
<p>Each time <var>$Read</var> is evaluated, <var class="product">Model&nbsp;204</var> prompts the user for a line of input. The response becomes the character string value returned by the function. For example: </p>
<p class="code">$read('HELLO')  
</p>
</p>
<p>causes <var class="product">Model&nbsp;204</var> to respond:</p>
<p>causes <var class="product">Model&nbsp;204</var> to respond:</p>
<p class="code">$$HELLO  
<p class="code">$$HELLO  
</p>
</p>
<p>and wait for the user to enter a reply each time the function is evaluated. </p>
<p>
<p>If the user keys in:</p>
and wait for the user to enter a reply each time the function is evaluated. </p>
<p>
If the user keys in:</p>
<p class="code">GOODBYE  
<p class="code">GOODBYE  
</p>
</p>
<p>in reply, the function returns a value equal to the quoted string 'GOODBYE'. </p>
<p>
<p>If no prompt argument is specified, as $READ (), the prompt is:</p>
in reply, the function returns a value equal to the quoted string 'GOODBYE'. </p>
<p>
If no prompt argument is specified, as $Read(), the prompt is:</p>
<p class="code">$$  
<p class="code">$$  
</p>
</p>
<p>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.</p>
<p>
<b>Including $READ functions and dummy strings in a procedure</b>
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.</p>
<p>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.</p>
 
==Including $Read functions and dummy strings in a procedure==
<p>
If <var>$Read</var> functions are included in a procedure, one or more responses to the <var>$Read</var> 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.</p>
<p class="code">PROCEDURE ENTRY
<p class="code">PROCEDURE ENTRY
BEGIN
BEGIN
Line 44: Line 54:
END PROCEDURE  
END PROCEDURE  
</p>
</p>
<p>You can include the procedure and specify responses for the $READ functions and dummy strings included in the procedure by issuing the following:</p>
<p>
You can include the procedure and specify responses for the <var>$Read</var> functions and dummy strings included in the procedure by issuing the following:</p>
<p class="code">INCLUDE ENTRY, PERSONNEL, ROBERT, 27, YES, LOUISE, 28, NO  
<p class="code">INCLUDE ENTRY, PERSONNEL, ROBERT, 27, YES, LOUISE, 28, NO  
</p>
</p>
<p>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.  </p>
<p>
<p>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, <var class="product">Model&nbsp;204</var> prompts for a response as if no list had been specified.</p>
Dummy string responses must appear first, followed by <var>$Read</var> responses. If any <var>$Read</var> responses are included in the list, it also must include a response for each dummy string encountered before the first <var>$Read</var> is executed.  </p>
<p>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. <var class="product">Model&nbsp;204</var> prints the prompts for the next $READs but does not wait for the user to reply to each one.</p>
<p>
<b>Results of $READ prompts</b>
As dummy strings and <var>$Read</var> 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 <var>$Read</var>s than responses in the list, <var class="product">Model&nbsp;204</var> prompts for a response as if no list had been specified.</p>
<p>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.</p>
<p>
<p class="code">INCLUDE ENTRY  
Alternatively, if the user responds to a request with several <var>$Read</var> statements in a row, the user can wait for the first prompt and then enter several replies at once, separating them by semicolons. <var class="product">Model&nbsp;204</var> prints the prompts for the next <var>$Read</var>s but does not wait for the user to reply to each one.</p>
 
==Results of $Read prompts==
<p>
Results of <var>$Read</var> prompts contain leading or intermediate blanks that the user enters if the <var>TRANSPARENT</var> argument is not specified. However, trailing blanks are dropped. This occurs when the <code>ENTRY</code> procedure shown in the preceding section is included. Note the stacking of responses on a single input line. User entries are in bold.</p>
<p class="code"><b>INCLUDE ENTRY</b>
??TYPE  
??TYPE  
PERSONNEL  
<b>PERSONNEL</b>
$$NAME  
$$NAME  
ROBERT  
<b>ROBERT</b>
$$AGE  
$$AGE  
27  
<b>27</b>
$$MORE?  
$$MORE?  
YES  
<b>YES</b>
$$NAME  
$$NAME  
LOUISE 28 28
<b>LOUISE 28</b> 
$$AGE
$$AGE
$$MORE?  
$$MORE?  
YES  
<b>YES</b>
$$NAME  
$$NAME  
DALE 24; YES; RICHARD; 37; YES: THO-  
<b>DALE 24; YES; RICHARD; 37; YES: THO-  
MAS 59; NO  
MAS 59; NO </b>
$$AGE
$$AGE
$$MORE?
$$MORE?
Line 78: Line 94:
$$MORE?  
$$MORE?  
</p>
</p>
<p>This example illustrates the differences between dummy strings and the $READ function. </p>
<p>
<p>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.</p>
This example illustrates the differences between dummy strings and the <var>$Read</var> function. </p>
<p>$$ 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:</p>
<p>
Dummy strings allow the user to fill in pieces of the request text just before compilation begins. The user's replies to <var>??</var> prompts are substituted before the text is compiled. <code>??TYPE</code> is replaced only once, at compilation time, by <code>PERSONNEL</code>.</p>
<p>
<var>$$</var> prompts and <var>$Read</var> function input not specified at <var>INCLUDE</var> 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:</p>
<p class="code">BEGIN
<p class="code">BEGIN
PRINT.COUNT: FIND AND PRINT COUNT
PRINT.COUNT: FIND AND PRINT COUNT
Line 94: Line 113:
END  
END  
</p>
</p>
<p>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 <var class="product">Model&nbsp;204</var> searches for records with AGE fields containing the string '10 OR 11'.</p>
<p>
<p>If the user presses the attention key (<var>ATTN, BREAK</var>, or<var> PA1</var>, depending on terminal type) or enters <var>*CANCEL</var> in response to a $READ prompt, <var class="product">Model&nbsp;204</var> performs the action specified in the ON ATTENTION unit (see [[Subroutines#ON units|ON units]]) if one is specified in the request. </p>
In the first request, if the user replies <code>10 OR 11</code> to the <code>??AGE</code> prompt, the line <code>AGE = 10 OR 11</code> is properly compiled and the request searches for records with <code>AGE</code> either 10 or 11. However, if the user replies <code>10 OR 11</code> to the <code>$$ENTER AGE</code> prompt in the second request, <code>10 OR 11</code> is considered a character string and <var class="product">Model&nbsp;204</var> searches for records with AGE fields containing the string <code>10 OR 11</code>.</p>
<p>If ON ATTENTION is not specified, <var class="product">Model&nbsp;204</var> terminates the request and all nested procedures. Control is returned to the command level at the user's terminal.  </p>
<p>
<b>Using the $READ function to read sequential input</b>
If the user presses the attention key (<var>ATTN, BREAK</var>, or <var> PA1</var>, depending on terminal type) or enters <var>*CANCEL</var> in response to a <var>$Read</var> prompt, <var class="product">Model&nbsp;204</var> performs the action specified in the <var>ON ATTENTION</var> unit (see [[Subroutines#ON units|ON units]]) if one is specified in the request. </p>
<p>You can use the $READ function to read sequential input:</p>
<p>
If <var>ON ATTENTION</var> is not specified, <var class="product">Model&nbsp;204</var> terminates the request and all nested procedures. Control is returned to the command level at the user's terminal.  </p>
 
==Using the $Read function to read sequential input==
<p>
You can use the <var>$Read</var> function to read sequential input:</p>
<ol>
<ol>
<li>Run <var class="product">Model&nbsp;204</var> in batch mode. $READ assumes terminal input in online mode and sequential input (for example, tape or disk) in batch mode.  </li>
<li>Run <var class="product">Model&nbsp;204</var> in batch mode. <var>$Read</var> assumes terminal input in online mode and sequential input (for example, tape or disk) in batch mode.  </li>
<li>Concatenate a User Language procedure to the sequential input to be read. The following JCL is required:   </li>
 
</ol>
<li>Concatenate a SOUL procedure to the sequential input to be read. The following JCL is required:
 
<p class="code">// CCAIN DD DSN=USER.LANG.PROCEDURE,DISP=OLD
<p class="code">// CCAIN DD DSN=USER.LANG.PROCEDURE,DISP=OLD
         DD DSN=SEQU.INPUT.FILE,DISP=OLD  
         DD DSN=SEQU.INPUT.FILE,DISP=OLD  
</p></li>
<li>Use the <var>[[$Substr]]</var> function to parse the input. For example:
<p class="code">%fielda=$Substr(%input,1,10)
%fieldb=$Substr(%input,11,5)
</p>
</p>
<ol>
<p>
<li>Use the $SUBSTR function to parse the input. For example:</li>
The input is read into the %variable, for example, <code>%input</code>). It cannot exceed 255 characters in length. </p>
</li>
</ol>
</ol>
<p class="code">%FIELDA=$SUBSTR(%INPUT,1,10)
 
%FIELDB=$SUBSTR(%INPUT,11,5)  
==Read Image does not return INCLUDE command tokens==
The <var>[[Read Image statement|Read Image]]</var> statement with the <var>Terminal</var> option can be useful to obtain user input, and in some cases is more advantageous than <var>$Read</var> because it is independent of the argument string on an <var>INCLUDE</var> command.  For example, consider this procedure:
 
<p class="code">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
</p>
 
If the  above procedure is invoked as follows, the user is not prompted, and no input is taken from the user:
 
<p class="code">INCLUDE FOO MYFILE</p>
 
The string <code>MYFILE</code>, which is the first token in the above <var>INCLUDE</var> command argument string, is returned as the value of <var>$Read</var>. However, in the following approach, the user <b>is</b> prompted to input the password value:
 
<p class="code">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
</p>
</p>
<p>The input is read into the %variable, for example, %INPUT). It cannot exceed 255 characters in length.  </p>
 
[[Category:SOUL $functions]]
[[Category:SOUL $functions]]

Latest revision as of 17:10, 17 May 2016

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