READ, READTAB, READLK (IFILE)

ANSI

The READ instruction retrieves information from disk and transfers that information into data variables. The statement format is as follows:

(1)	[label]	READ	{ifile},{key};[{list}][;]
(2)	[label]	READ	{ifile},{key};[columnname={variable][,...][;]
(3)	[label]	READTAB	{ifile},{key};[{list}][;]
(4)	[label]	READTAB	{ifile},{key};[columnname={variable][,...][;]
(5)	[label]	READLK	{ifile},{key};[{list}][;]
(6)	[label]	READLK	{ifile},{key};[columnname={variable][,...][;]

Where:

label

Optional. A Program Execution Label.

ifile

Required. A previously defined and opened IFILE variable from which data is read.

key

Required. A previously defined Character String Variable, Numeric Variable, or Expression that selects the record to read.

list

Optional. Any combination of previously defined Character String Variables, or Numeric Variables, string or numeric ARRAYs, individual array elements, VARLISTs of string or numeric variables, or valid Disk I/O List Controls.

;

Optional unless list not specified. A semicolon indicating Partial I/O.

columnname

Required. The column name as specified in the VIEW that was assigned to the file variable by the OPEN or PREPARE instruction. The column named is not case sensitive.

variable

Required. The variable that has been previously declared and is loaded with data read.

Flags Affected: LESS, OVER, ZERO

Note the following:

READ and READTAB are synonyms.
If the manual record locking mode is in effect, the READLK form locks the record as it is read.
If manual record locking is in effect, a READ performs a traditional read operation with an implied FILEPI and temporarily locks the data record only for the duration of the READ statement. The READ clears the temporary record lock when the operation is completed. The READ in this case honors the WAIT mode as expected for the record locking operations.
If the automatic record locking mode is in effect, all forms of this instruction lock the record as it is read.
If {key} is a numeric variable equal to or greater than zero, it designates a sector in the file for random or direct access. If it is a negative numeric variable equal to -1, -2, -3 or -4, sequential file processing is indicated (see READ (FILE), Random Access Method, or Sequential Access Method for more information).
If {key} is a character string variable, an ISAM READ instruction is performed.
{list} may be any combination of character string and/or numeric variables (including arrayed items), character string and/or numeric literals and/or supported list controls separated by commas. If an ARRAY variable is given without a specific array element designated, all elements of the array are processed.
When reading a data field into a FORM variable, any non-leading white space characters read are converted to zero characters. This read IO behavior exists because this was the legacy behavior that existed for the original Databus IO read instructions. As an example, if the data being read is 's1s2s3', where the 's' character is a white space, the resulting FORM variable value would be 's10203' where 's' character is a white space. This read IO behavior is the default for Sunbelt runtimes. For runtime versions 9.4D or later, this behavior can be changed using the PLB_ANSIIO runtime keyword or the SETMODE *PLBANSIIO keyword to force a FORMAT error when non-leading white space characters are encountered.
{list} may be optionally excluded if two semi-colons (;;) are specified after {key}. This technique only positions the file pointer to the beginning of the record/sector without actually reading any data.
The supported list controls are as follows:

Control	Function
*ABSON	Enable absolute transfer of file data
*ABSOFF	Disable *ABSON
*CDFOFF	Disable *CDFON
*CDFON	Enable comma-delimited Field support
*EDIOFF	Disable *EDION
*EDION	Enable Electronic Data Information support
*LC	Disable *UC (default)
*LL	Set the Length Pointer to last non-blank character
*{n}	Tab to the {n}'th character offset in the given record
*PL	Disable *LL (default)
*TAB={n}	Tab to the {n}'th character offset in the given record
*UC	Convert lower case data to upper case

When using tabbing (*n) in an ISAM file, the tab position is relative to the first position in the record being processed.
When reading with a NULL key, the last read ISAM record is re-read.
Attempting to read a nonexistent ISAM record sets the OVER Condition Flag (TRUE) and clears the LESS Condition Flag (FALSE). All variables are left in their original state unless the PLB_RDCLR environment variable is set for PLBCMP. That keyword clears all DIM fields and zeros all FORM fields. The pointer in the ISAM key file is then positioned where the record should have been so that a READKS (Read Key Sequential) instruction would retrieve the next sequential key record in the ISAM tree.
If an attempt is made to read past the End Of File (EOF) indicator (using -1 or -2) or if an attempt is made to read before the beginning of the file (using -4), the OVER Condition Flag is set, the LESS Condition Flag is cleared, all numeric variables in the list are set to 0 and all character string variables in the list are blank-filled and CLEARed.
If a semi-colon (;) terminates the list, the rules relevant to partial reads apply (see Partial I/O).
If deleted characters are found (Hex/Octal 00), the ZERO Condition Flag is set TRUE.
If a FORMAT error occurs, the record pointer is returned to its original position prior to the read.
If a locking conflict occurs, the read fails and the following actions take place:

The LESS Condition Flag is set and the OVER Condition Flag is cleared.
All variables are left in their original state unless the PLB_RDCLR environment variable is set for PLBCMP. That keyword clears all DIM fields and zeros all FORM fields.
The current data file position and the sequential data file position are set to the position of the locked record.
The update data file position is set to invalid.
The index file position is set to the key in the index that was found.

Record Locking was added in version 8.2 and is not available when using the PLBCE runtime.
When a view schema is assigned to an IFILE variable (9.4), the READ instruction can optionally use the column name syntax (format 2, 4, and 6 above). When the column name syntax is being used, all variables used in the instruction variable list must have column names specified. When the column name syntax is not being used, no variables in the instruction variable list can have column names.

If the column name syntax specified with the 'columnname' parameter is being used, the 'columnname' parameter can be one of the following:

Column name as specified by the VIEW column definitions.

@{svar} where {svar} is a variable that contains the column name as specified by the VIEW column definitions.

Example:

IFILE IFILE

myKey DIM 10

myProdid DIM 10

myParam DIM 50

...

. Both of these READ syntax formats give the same results when

. using a VIEW definition column name of 'PRODID' and the IFILE

. is opened with VIEW definition being used.

READ IFILE, myKey; PRODID=myProdid

MOVE "PRODID", myParam

READ IFILE, myKey; @myParam=myProdid

If the column name syntax format is being used, partial IO using the ';' character is allowed.
If the column name syntax format is being used, the data is retrieved from the data record using the VIEW data type, location, and field size that has been defined for a column. After the column data field is retrieved, the data is moved into the final destination variable specified by {variable}.