Domain: PROCEDURE
Command description
The READ-VARIABLE command is used to read data from an input medium and to store the data in a variable. The data is read record by record. The operation is terminated when the string *END-OF-CMD or the end of a file (EOF) is encountered.
The input medium may be any of the following:
the terminal
a cataloged file
a variable
a library element
the SYSDTA system file
Notes concerning reading data from SYSDTA
Data is read from SYSDTA exactly as it is from a file. However, there is one exception: If the read operation is terminated before SYSDTA EOF, the next SYSDTA record is accessed the next time that data is read in from SYSDTA. This allows reading of specific data from SYSDTA. This is useful, for example, if only a single simple variable is to be read.
Input ends at the end of the SYSDTA system file, i.e. either at the end of the file if a cataloged file is assigned to SYSDTA, or with the next command if SYSDTA is assigned to SYSCMD (default value for S procedures).
It is not possible to interrupt the input of data read from SYSDTA by means of HOLD-PROGRAM,
or BEGIN-BLOCK PROGRAM-INPUT=*MIXED-WITH-CMD (in order to switch to command mode). These commands and actions only result in the termination of input, i.e. SYSDTA EOF (end-of-file) being reported to the appropriate command. Only the SEND-DATA command does not terminate the READ-VARIABLE command.
Note on reading in a file
When the complete contents of a file are not required for further processing, the volume of data can be restricted while the file is being read in in the following cases:
Only a contiguous section of the records is required. The numbers of the first and last records required are specified in the BEGIN-RECORD and END-RECORD operands for the range of records to be read in.
- From SDF-P-BASYS V2.5I11:
Only a contiguous section of the last records from the file is required. The number of the records required is specified using the *BEFORE-LAST-RECORD value in the BEGIN-RECORD operand. The number can also be determined with a negative value assignment in the BEGIN-RECORD operand. In both cases, the END-RECORD operand has no effect. Only records which contain specific strings are required. The records to be read in are selected by means of the search string specified in the PATTERN operand. The PATTERN-TYPE operand determines whether the search string is to be evaluated as a string or as a regular expression in accordance with POSIX rules. A simple search string can be entered directly as a string. A regular expression enables a complex search string to be specified which cannot be specified directly as a string (see “POSIX wildcards” (SDF syntax representation ); “regular expressions” are described in the “POSIX Commands” manual [18]).
Note
A search string is always searched for in the entire record, even when only part (range of columns) of the record is to be read in (see Example 5, Case 4).Only part of each record is needed. The part of the record to be read in is specified as a range of columns with the columns of the first and last characters required being specified in the BEGIN-COLUMN and END-COLUMN operands.
Format
READ-VARIABLE |
VARIABLE-NAME = *BY-INPUT(...) / *LIST(...) / list-poss(2000): <composed-name 1..255> *BY-INPUT(...) PREFIX = *NONE / <composed-name 1..255> *LIST(...) LIST-NAME = <composed-name 1..255> ,WRITE-MODE = *REPLACE / *EXTEND ,STRING-QUOTES = *OPTIONAL / *YES / *NO ,INPUT = *TERMINAL(...) / <filename 1..54 without-gen-vers>(...) / *VARIABLE(...) / *LIBRARY-ELEMENT(...) / *SYSDTA(...) *TERMINAL(...) PROMPT-STRING = ’>>’ / <text 0..1800 with-low> ,SECRET-INPUT = *NO / *YES <filename 1..54 without-gen-vers>(...) REMOVE-KEY = *YES / *NO ,BEGIN-RECORD = *FIRST / <integer -2147483646..2147483647> *BEFORE-LAST-RECORD(...) *BEFORE-LAST-RECORD(...) NUMBER-OF-LINES = <integer 0..500000> ,END-RECORD = *LAST / <integer 1..2147483647> ,BEGIN-COLUMN = *FIRST / <integer 1..2147483647> ,END-COLUMN = *LAST / <integer 1..2147483647> ,PATTERN = *NONE / <c-string 0..1800 with-low> ,PATTERN-TYPE = *STRING / *REGULAR-EXPRESSION *VARIABLE(...) VARIABLE-NAME = <composed-name 1..255> *LIBRARY-ELEMENT(...) LIBRARY = <filename 1..54 without-vers> ,ELEMENT = <composed-name 1..64 with-underscore>(...) <composed-name 1..64 with-underscore>(...) VERSION = *HIGHEST-EXISTING / <composed-name 1..24 with-underscore> ,TYPE = S / <alphanum-name 1..8> *SYSDTA(...) REMOVE-KEY = *YES / *NO |
Operands
VARIABLE-NAME =
Designates the variables to which values are to be assigned.
VARIABLE-NAME = *BY-INPUT(...)
Specifies that the variables are in the format generated by the SHOW-VARIABLE command via the PREFIX and FORM operands.
If the variables are not generated by the SHOW-VARIABLE command, they must exist in the SHOW-VARIABLE output format (e.g. there must be a blank before and after the ’=’). If the variables already exist, they are assigned the value.
If a variable does not yet exist, it is implicitly declared, as long as implicit declaration is allowed.
If the superordinate complex variable for a variable element does not exist, it is declared with SCOPE = *CURRENT.
Static structures can be regenerated only as dynamic structures. STRING, INTEGER and BOOLEAN are mapped to ANY if the variables do not exist.
If *BY-INPUT(...) refers to a list element (variable name with (*LIST)), the command is terminated with errors.
If a variable is assigned the value *NO-INIT, its previous contents are deleted (equivalent to a FREE-VARIABLE command call).
The value *END-OF-VAR is ignored. The value *END-OF-CMD terminates the assignment.
PREFIX = *NONE
The variable name is not preceded by a prefix.
PREFIX = <composed-name 1..255>
Designates the name to precede the variable name as a prefix.
VARIABLE-NAME = *LIST(...)
Designates a list variable.
LIST-NAME = <composed-name 1..255>
Name of the list.
If the list already exists, it must have the type ANY, STRING, BOOLEAN or INTEGER. If the list does not exist, or if it cannot be located, it is re-declared with the scope SCOPE = *CURRENT and the data type TYPE = *STRING.
WRITE-MODE=*REPLACE
The list is overwritten.
WRITE-MODE=*EXTEND
New elements are appended to the end of the list.
VARIABLE-NAME = list-poss(2000): <composed-name 1..255>
Names of the variables to which new values are to be assigned.
The values which are read in are assigned in turn to the variables (variable elements) - starting with the first element in the structure.
Error handling is initiated if not all of the variables are assigned values, due to a premature EOF or *END-OF-CMD.
STRING-QUOTES =
Defines how the input value is to be interpreted.
STRING-QUOTES = *OPTIONAL
Makes it possible to specify variable values like procedure parameters.
The data type of the variable to which the value is to be assigned is taken into account in interpreting the entry:
If the variable has the data type ANY or STRING, the value is interpreted as a string. Single quotes within the string must be doubled (this, however, applies only if the entire string is enclosed in quotes).
If the variable has the data type INTEGER, the value is interpreted as an integer.
If the variable has the data type BOOLEAN, the value is interpreted as a Boolean value.
STRING-QUOTES = *YES
Interprets values beginning with a single quote (’) or with C and single quote (C’) as a string. If the string does not end with a single quote, or if single quotes are not doubled within the value, this is interpreted as an error.
If a value which is not enclosed in quotes corresponds to one of the keywords for Boolean values, it is interpreted as a Boolean value. In all other instances, it is interpreted as an integer.
STRING-QUOTES = *NO
Interprets all values as a string.
INPUT =
Defines the location from which the values are to be input.
INPUT = *TERMINAL(...)
Prompting: the values are input from the terminal. (However, unlike DECLARE-PARAMETER INITIAL-VALUE =*PROMPT, this does not convert the values to uppercase.)
PROMPT-STRING = ’>>’ / <text 0..1800 with-low>
String expression. Defines the character or character string which is to be used as prompt.
SECRET-INPUT = *NO / *YES
Defines whether or not the user’s input is to be concealed.
INPUT = <filename 1..54 without-gen-vers>(...)
The values are to be input from the specified file.
Each input record is interpreted as a single value.
REMOVE-KEY =
Specifies whether the key is to be omitted when reading from an ISAM file.
REMOVE-KEY = *YES
In the case of an ISAM file, the key is not read in. In the case of a SAM file, only this specification is accepted.
REMOVE-KEY = *NO
In the case of ISAM files with the standard attributes KEY-POSITION=5 and KEY-LENGTH=8, the key is also read in. In the case of ISAM files with other attributes, this specification leads to an error. This specification always leads to an error with SAM files.
BEGIN-RECORD = *FIRST / <integer 1..2147483647>
Specifies the record which is to be the first to be read in. *FIRST specifies the first record of the file as the default.
If the value specified is greater than the number of existing records, an empty file is assumed. In the case of VARIABLE-NAME=*LIST(...), an empty list is created.
From SDF-P-BASYS V2.5I11:
If a negative value is specified, it depicts the records number from the EOF plus the last record to be processed. If the absolute value of the negative number is greater than the number of existing records without the last record, the complete file is processed. If 0 is specified, only the last record is processed.
BEGIN-RECORD = *BEFORE-LAST-RECORD(...)
From SDF-P V5.2I11:
Used if only the last records in the file are of interest.
NUMBER-OF-LINES = <integer 0..500000>
Specifies the number of the entries from the EOF to be processed. If 0 is specified, only the last record is processed.
END-RECORD = *LAST / <integer 1..2147483647>
Specifies the record after which transfer is to be terminated. *LAST specifies the last record of the file as the default.
If the value specified is greater than the number of existing records, *LAST is assumed.
END-RECORD has no effect if *BEFORE-LAST-RECORD or negative value is used in BEGIN-RECORD.
BEGIN-COLUMN = *FIRST / <integer 1..2147483647>
Specifies the column position from which the content of a record is to be read in. *FIRST specifies the start of the record (column position 1) as the default.
If the value specified is greater than the record, an empty list element is created to ensure that the number of list elements always corresponds to the number of lines read.
END-COLUMN = *LAST / <integer 1..2147483647>
Specifies the column position after which the transfer of a record is to be terminated. *LAST specifies the end of the record as the default.
If the value specified is greater than the record, *LAST is assumed.
PATTERN =
Specifies whether only records which contain a particular search string are to be read in.
PATTERN = *NONE
Records are read in regardless of any particular search string.
PATTERN = <c-string 0..1800 with-low>
Only records which contain the search string specified are read in. The PATTERN-TYPE operand determines how the search string is to be evaluated. If a string with length 0 is used, the effect is the same as if the pattern is *NONE - records are read regardless of any particular search string.
PATTERN-TYPE =
Specifies how the search string is to be evaluated.
PATTERN-TYPE = *STRING
Records are selected which contain the specified string.
PATTERN-TYPE = *REGULAR-EXPRESSION
Records are selected which contain the string specified as a regular expression.
INPUT = *VARIABLE(...)
The values are to be input from a list variable.
VARIABLE-NAME = <composed-name 1..255>
Name of the list variable.
This variable must exist, and must have been declared with the data type STRING. (It can also be declared with the data type ANY; however, it may still contain strings only.)
INPUT = *LIBRARY-ELEMENT(...)
The values are to be read in from an element in a PLAM library. Specifying a list of libraries (S variable SYSPLAMALT-<name>) is permissible.
LIBRARY = <filename 1..54 without-vers>
Name of the library.
ELEMENT = <composed-name 1..64 with-underscore>(...)
Name of the library element.
VERSION = *HIGHEST-EXISTING / <composed-name 1..24 with-underscore>
Version of the library element.
TYPE = S / <alphanum-name 1..8>
Type of the library element.
INPUT = *SYSDTA(...)
The values are to be read in from SYSDTA.
REMOVE-KEY =
If SYSDTA is assigned to a file:
Specifies whether the key is to be omitted when reading from an ISAM file. For SAM files, the operand value is ignored.
REMOVE-KEY = *YES
In the case of an ISAM file, the key is omitted.
Only in the case of an ISAM file with the standard attributes KEY-POSITION=5 and KEY-LENGTH=8 is the key also read in. This specification leads to an error tn the case of an ISAM file with other attributes.
Command return codes
It is possible that part of the command has already been processed and executed before the error occurs. In this case, the result of the command is not guaranteed.
(SC2) | SC1 | Maincode | Meaning/Guaranteed messages |
| 0 | CMD0001 | No error | |
| 2 | 0 | SDP2000 | Warning: not all elements of the input list could be processed successfully. Guaranteed message: SDP2000 |
| 1 | CMD0202 | Syntax error | |
| 1 | SDP0118 | Command in false context | |
| 3 | CMD2203 | Incorrect syntax file | |
| 32 | CMD0221 | System error (internal error) | |
| 64 | SDP0089 | INPUT error | |
| 64 | SDP0091 | Semantic error Guaranteed messages: SDP1008 | |
| 64 | SDP0499 | First record greater than last record | |
| 64 | SDP2001 | None of the elements could be read in | |
| 130 | SDP0099 | No further address space available |
Example 1
If a certain number of values must be used in a procedure, these values can be listed in SYSCMD; they do not have to be put in a different file.
/DECLARE-VARIABLE FILES(TYPE=*STRING),MULTIPLE-ELEMENTS=*LIST /READ-VARIABLE *LIST(FILES),INPUT=*SYSDTA FILE1 FILE2 FILE3 /FOR FILE=*LIST(FILES) / IF (NOT IS-CATALOGED-FILE(FILE)) / WRITE-TEXT 'FILE &FILE NOT FOUND.' / END-IF /END-FOR
Example 2
A certain number of lines, which remains constant, is to be read from a file. In this example, the number of lines is 10. Each time the loop is executed, 10 lines of the file ’MY-FILE’ are read and a list ’LINES’ is declared with a limit of 10 list elements. In brief: this example shows the contents of the file ’MY-FILE’.
/ASSIGN-SYSDTA TO=MY-FILE
/DECLARE-VARIABLE LINES(TYPE=*STRING),MULTIPLE-ELEMENTS=*LIST(LIMIT=10)
/REPEAT
/ READ-VARIABLE *LIST(LINES),INPUT=*SYSDTA
/ SHOW-VARIABLE LINES,INFORMATION=*PARAMETERS(NAME=*NONE)
/UNTIL (SIZE('LINES') LT 10)
Example 3
A procedure has the following contents:
/DECLARE-VARIABLE FORENAME /WRITE-TEXT 'Please enter a forename' /READ-VARIABLE FORENAME /SHOW-VARIABLE FORENAME
OutputPlease enter a forename
InputJohn
OutputFORENAME= John
Example 4
A file is to be read from SYSDTA line by line. An error is reported if READ-VARIABLE detects EOF for SYSDTA. The example simply shows the contents of the file ’MY-FILE’.
/ASSIGN-SYSDTA TO=MY-FILE /EOF=FALSE /WHILE (NOT EOF) / READ-VARIABLE LINE,INPUT=*SYSDTA / IF-CMD-ERROR / EOF=TRUE / ELSE / SHOW-VARIABLE LINE,INFORMATION=*PARAMETERS(NAME=*NONE) / END-IF /END-WHILE
Example 5
The SDF-P-FILE file contains the following records:
MUELLER : 55900 : DE : Gladbecker Strasse 7 GRANDY : 74663 : UK : Albert Street 12 DANFERTH : 83092 : DE : Colmberger Strasse 2 GRABATER : 01927 : FR : rue du Couedic 27 SMITH : 54920 : UK : Elizabeth Street 54 DUPONT : 45888 : FR : rue de la Maderie 78 VANDENMORSE : 94958 : BE : Brusselssteenweg 101
Read in range of records
/DECLARE-VARIABLE FILE (TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST /READ-VARIABLE *LIST(FILE), INPUT=SDF-P-FILE (BEGIN-RECORD = 4, - / END-RECORD = 7) /SHOW-VARIABLE FILE FILE(*LIST) = GRABATER : 01927 : FR : rue du Couedic 27 FILE(*LIST) = SMITH : 54920 : UK : Elizabeth Street 54 FILE(*LIST) = DUPONT : 45888 : FR : rue de la Maderie 78 FILE(*LIST) = VANDENMORSE : 94958 : BE : Brusselssteenweg 101
Records 4 through 7 were read in to the FILE variable.
Read in range of columns from range of records
/DECLARE-VARIABLE FILE (TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST /READ-VARIABLE *LIST(FILE), INPUT=SDF-P-FILE (BEGIN-RECORD=5, - / END-RECORD=8, - / BEGIN-COLUMN=17, - / END-COLUMN=21) /SHOW-VARIABLE FILE FILE(*LIST) = 54920 FILE(*LIST) = 45888 FILE(*LIST) = 94958
Columns 17 through 21 from records 5 through 7 were read in to the FILE variable (no 8th record exists).
Read the last n+1 records
/DECLARE-VARIABLE FILE (TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST /READ-VARIABLE VARIABLE-NAME=*LIST(FILE),INPUT=SDF-P-FILE - / (BEGIN-RECORD=*BEFORE-LAST-RECORD(NUMBER-OF-LINES=3)) /SHOW-VARIABLE FILE FILE(*LIST) = GRABATER : 01927 : FR : rue du Couedic 27 FILE(*LIST) = SMITH : 54920 : UK : Elizabeth Street 54 FILE(*LIST) = DUPONT : 45888 : FR : rue de la Maderie 78 FILE(*LIST) = VANDENMORSE : 94958 : BE : Brusselssteenweg 101
The last 4 records (records 4 through 7) were read in to the FILE variable.
/DECLARE-VARIABLE FILE (TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST /READ-VARIABLE VARIABLE-NAME=*LIST(FILE),INPUT=SDF-P-FILE - / (BEGIN-RECORD=-4) /SHOW-VARIABLE FILE FILE(*LIST) = DANFERTH : 83092 : DE : Colmberger Strasse 2 FILE(*LIST) = GRABATER : 01927 : FR : rue du Couedic 27 FILE(*LIST) = SMITH : 54920 : UK : Elizabeth Street 54 FILE(*LIST) = DUPONT : 45888 : FR : rue de la Maderie 78 FILE(*LIST) = VANDENMORSE : 94958 : BE : Brusselssteenweg 101
The last 5 records (records 3 through 7) were read in to the FILE variable
/DECLARE-VARIABLE FILE (TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST /READ-VARIABLE VARIABLE-NAME=*LIST(FILE),INPUT=SDF-P-FILE - / (BEGIN-RECORD=*BEFORE-LAST-RECORD(NUMBER-OF-LINES=0)) /SHOW-VARIABLE FILE FILE(*LIST) = VANDENMORSE : 94958 : BE : Brusselssteenweg 101
Only the last record is read in to the FILE variable.
Search records for string and read in hits
/DECLARE-VARIABLE FILE (TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST /READ-VARIABLE *LIST(FILE), INPUT=SDF-P-FILE (PATTERN=': DE :', - / PATTERN-TYPE=*STRING) /SHOW-VARIABLE FILE FILE(*LIST) = MUELLER : 55900 : DE : Gladbecker Strasse 7 FILE(*LIST) = DANFERTH : 83092 : DE : Colmberger Strasse 2
All records which contain the string “: DE :” were read in to the FILE variable.
/READ-VARIABLE *LIST(FILE), INPUT=SDF-P-FILE (BEGIN-COLUMN=23, - / END-COLUMN=28, - / PATTERN=': DE :', - / PATTERN-TYPE=*STRING) /SHOW-VARIABLE FILE FILE(*LIST) = : DE : FILE(*LIST) = : DE :
Columns 23 through 28 from all records which contain the string “: DE :” were read in to the FILE variable.
/READ-VARIABLE *LIST(FILE), INPUT=SDF-P-FILE (BEGIN-COLUMN=1, - / END-COLUMN=22, - / PATTERN=': DE :', - / PATTERN-TYPE=*STRING) /SHOW-VARIABLE FILE FILE(*LIST) = MUELLER : 55900 FILE(*LIST) = DANFERTH : 83092
Columns 1 through 22 from all records which contain the string “: DE :” were read in to the FILE variable.
Search records for string or regular expression and read in hits
/DECLARE-VARIABLE FILE (TYPE=*STRING), MULTIPLE-ELEMENTS=*LIST /READ-VARIABLE *LIST(FILE), INPUT=SDF-P-FILE (PATTERN=': DE :', - / PATTERN-TYPE=*STRING) /SHOW-VARIABLE FILE FILE(*LIST) = MUELLER : 55900 : DE : Gladbecker Strasse 7 FILE(*LIST) = DANFERTH : 83092 : DE : Colmberger Strasse 2
All records which contain the string “: DE :” were read in to the FILE variable.
/READ-VARIABLE *LIST(FILE) - / , INPUT=SDF-P-FILE (PATTERN=': [DB]E :', - / PATTERN-TYPE=*REGULAR-EXPRESSION) /SHOW-VARIABLE FILE FILE(*LIST) = MUELLER : 55900 : DE : Gladbecker Strasse 7 FILE(*LIST) = DANFERTH : 83092 : DE : Colmberger Strasse 2 FILE(*LIST) = VANDENMORSE : 94958 : BE : Brusselssteenweg 101
All records which contain the regular expression “: [DB]E :” (i.e “: DE :” or “: BE :”) were read in to the FILE variable.