$Read - Revision history

JAL: /* Results of $Read prompts */ typo

2016-05-17T17:10:52Z

Results of $Read prompts: typo

← Older revision		Revision as of 17:10, 17 May 2016
Line 76:		Line 76:
	<b>27</b>		<b>27</b>
	$$MORE?		$$MORE?
	<b>YES<b>		<b>YES</b>
	$$NAME		$$NAME
	<b>LOUISE 28</b>		<b>LOUISE 28</b>

JAL: /* Read Image does not return INCLUDE command tokens */ minor wordsmithing

2016-05-17T16:50:58Z

Read Image does not return INCLUDE command tokens: minor wordsmithing

← Older revision		Revision as of 16:50, 17 May 2016
Line 150:		Line 150:
	%password is string len 255		%password is string len 255
	%file = %(system):arguments:unspace:toUpper		%file = %(system):arguments:unspace:toUpper
	%password = $read('Password?', 'TRANSPARENT') ;* TRANSPARENT in case ~~password~~ ends in a hyphen, say		%password = $read('Password?', 'TRANSPARENT') ;* TRANSPARENT used in case pwd ends in a hyphen, say
	openC %file password %password		openC %file password %password
	end		end
Line 156:		Line 156:
	</p>		</p>

	If the above procedure is invoked as:		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>		<p class="code">INCLUDE FOO MYFILE</p>

	~~Then the user is not prompted, and no input is taken from the user. Instead, the~~ string <code>MYFILE</code>, which is the first token in the <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:		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		<p class="code">PROCEDURE FOO

JAL: link repair

2016-02-09T17:14:55Z

link repair

← Older revision		Revision as of 17:14, 9 February 2016
Line 143:		Line 143:

	==Read Image does not return INCLUDE command tokens==		==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:
	The <var>[[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		<p class="code">PROCEDURE FOO
Line 151:		Line 150:
	%password is string len 255		%password is string len 255
	%file = %(system):arguments:unspace:toUpper		%file = %(system):arguments:unspace:toUpper
	%password = $read('Password?', 'TRANSPARENT') ;* TRANSPARENT ~~just~~ in case password ends in a hyphen, say		%password = $read('Password?', 'TRANSPARENT') ;* TRANSPARENT in case password ends in a hyphen, say
	openC %file password %password		openC %file password %password
	end		end

Dme: /* Using the $Read function to read sequential input */

2016-02-02T01:40:50Z

Using the $Read function to read sequential input

@@ Line 141: / Line 141: @@
 </li>
 </ol>
 [[Category:SOUL $functions]]

JAL: more conversion cleanup

2014-08-21T19:04:19Z

more conversion cleanup

Show changes

Mlarocca: Mlarocca moved page $READ to $Read: Lower case change

2014-07-29T14:17:50Z

Mlarocca moved page $READ to $Read: Lower case change

← Older revision	Revision as of 14:17, 29 July 2014
(No difference)

Alex: Automatically generated page update

2013-04-20T13:19:22Z

Automatically generated page update

New page

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]]. 
Syntax
The format for the $READ function is:
$READ([prompt][,option])

where:
<ul>
<li>prompt 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>
</ul>
Prompting the user for a line of input
Each time $READ is evaluated, <var class="product">Model 204</var> prompts the user for a line of input. The response becomes the character string value returned by the function. For example: 
$READ('HELLO')

causes <var class="product">Model 204</var> 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, <var class="product">Model 204</var> 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. <var class="product">Model 204</var> 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 <var class="product">Model 204</var> searches for records with AGE fields containing the string '10 OR 11'.
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 204</var> performs the action specified in the ON ATTENTION unit (see [[Subroutines#ON units|ON units]]) if one is specified in the request. 
If ON ATTENTION is not specified, <var class="product">Model 204</var> 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:
<ol>
<li>Run <var class="product">Model 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>Concatenate a User Language procedure to the sequential input to be read. The following JCL is required: </li>
</ol>
// CCAIN DD DSN=USER.LANG.PROCEDURE,DISP=OLD
DD DSN=SEQU.INPUT.FILE,DISP=OLD

<ol>
<li>Use the $SUBSTR function to parse the input. For example:</li>
</ol>
%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. 
[[Category:SOUL $functions]]