READ, READTAB, READLK (FILE)
ANSI
The READ instruction retrieves information from disk and transfers that information into data variables. The statement format is as follows:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Where:
label
Optional. A Program Execution Label.
file
Required. A previously defined and opened FILE variable from which data is read.
record
Required. A previously defined Numeric Variable or Expression that selects the record to read.
list
Optional. Any combination of previously defined Character String Variables, Numeric Variable, string or numeric ARRAYs, or 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 {record} is equal to or greater than zero, it designates a sector in the file for random or direct access (see Random Access Method). The first sector in the file is zero (0) and each subsequent sector increments the reference appropriately. The relative sector size defaults to 256 bytes but may be adjusted using the BUFFER/FIX/FIXED FILE declaration parameter.
If {record} is a negative number equal to -1, -2, -3 or -4, it indicates sequential file processing (see Sequential Access Method). The differences are as follows:
|
Value |
Action |
|
-1 |
Sequential forward processing |
|
-2 |
Sequential forward processing |
|
-3 |
Position to End Of File (EOF) prior to processing |
|
-4 |
Sequential backward processing |
{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 {record}. 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 |
|
Enable absolute transfer of file data | |
|
Disable *ABSON | |
|
Disable *CDFON | |
|
Enable comma-delimited Field support | |
|
Disable *EDION | |
|
Enable Electronic Data Information support | |
|
Disable *UC (default) | |
|
Set the Length Pointer to last non-blank character | |
|
Tab to the {n}'th character offset in the given record | |
|
Disable *LL (default) | |
|
Tab to the {n}'th character offset in the given record | |
|
Convert lower case data to upper case |
When using tabbing (*n) in a text file, the tab position is relative to the first position in the sector being processed.
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 and the LESS Condition Flag is cleared, all numeric variables in the list are set to zero (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).
It is assumed the data file may have space compression and FORM fields may be in minus overpunch format during the input mode. If space compression is present in the file and record locking is not in effect, the LESS Condition Flag is set. If record locking is in effect, the LESS Condition Flag indicates a lock failure.
If deleted characters are found (Hex/Octal 00), the ZERO Condition Flag is set.
An I44 error can occur with a random read if the data has been deleted.
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.
Record Locking was added in version 8.2 and is not available when using the PLBCE runtime.
When a view schema is assigned to a FILE 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:
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}.
See Also: Example Code, WRITE (FILE), Disk I/O Instructions
|
|