READKG, READKGTB, READKGLK

ANSI

The READKG instruction allows retrieval of subsequent records that met the key criteria for a previous AAM READ instruction. The instruction uses the following format;

Where:

label

Optional. A Program Execution Label.

afile

Required. A previously defined and opened AFILE variable from that 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. READKG and READKGTB are synonyms.

2. If the manual record locking mode is in effect, the READKGLK 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 READKG is performed prior to a valid AAM read instruction, an I/O error occurs.

5. Once no further records meet the original AAM READ criteria, the OVER Condition Flag is set to TRUE and the LESS Condition Flag is set to FALSE. All variables are left in their original state unless the PLB_RDCLR environment variable is set for PLBCMP that CLEARs all DIM and FORM fields.

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

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

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

 

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

10. None of the key fields that were used in the READ instruction may be changed between the READ and the READKG instruction.

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

12. 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 position in the retrieval set of the locked record.

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

See Also: Example Code, Disk I/O Instructions