READKS, READKSTB, READKSLK

ANSI

The READKS instruction reads ISAM text files in ascending (forward) key sequence without the necessity of specifying each key. The instruction uses the following formats:

Where:

label

Optional. A Program Execution Label.

ifile

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

list

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

;

Optional. A semicolon indicating Partial I/O.

Flags Affected: LESS, OVER

Note the following:

1. READKS and READKSTB are synonyms.

2. If the manual record locking mode is in effect, the READKSLK form locks the record as it is read.

3. If the automatic record locking mode is in effect, all forms of this instruction lock the record as it is read.

4. If a READKS is performed prior to any other ISAM read instruction, it begins with the lowest logical key in the ISAM key file. Otherwise, READKS ascends the ISAM tree from the current key pointer until it passes the highest logical key in the tree at which time the OVER Condition Flag is set and the LESS 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.

5. {list} may be any combination of character string and/or numeric variables (including ARRAY items), character string and/or numeric literals and/or supported list controls separated by commas. If an arrayed variable is given without a specific array element designated, all elements of the array are processed.

6. {list} may be optionally excluded if two semi-colons (;;) are specified after {ifile}. This technique only positions the file pointer to the beginning of the record/sector without actually reading any data.

7. 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

 

8. When using tabbing (*n) in an ISAM file, the tab position is relative to the first position in the record being processed.

9. When using the single unlocking mode, a read to a record that is not locked unlocks the currently locked record before the read is attempted.

10. 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. If set, all DIM fields are CLEARed and all FORM fields are set to zero.

• 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.

11. Record Locking was added in version 8.2 and is not available when using the PLBCE runtime.

See Also: Example Code, READKP, Disk I/O Instructions