READKGP, READKGPLK

ANSI

The READKGP instruction reads, in reverse order, records that meet the key criteria for a previous AAM READ or READLAST. The instruction uses the following format:

Where:

label

Optional. A Program Execution Label.

afile

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

list

Optional. Any combination of previously 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. If the manual record locking mode is in effect, the READKGPLK form locks the record as it is read.

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

3. If a READKGP is performed prior to a valid AAM READ instruction, an I/O error occurs.

4. Once all previously read records have been retrieved, 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 {afile}. 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 AAM file, the tab position is relative to the first position in the record being processed.

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

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

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

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