Using KSAM/XL and KSAM 64 (32650-90886)

202 AppendixA
COBOL Intrinsics
CKREADBYKEY
CKREADBYKEY
A call to CKREADBYKEY makes available a record identified by key value from a KSAM file.
CALL "CKREADBYKEY" USING filetable, status, record, key, keyloc, recordsize
Records can be read from a KSAM file in an order determined by key value. This order
need not be sequential; in fact, it can be any order you specify. This type of access is used to
access individual records in random order by key value.
Parameters
filetable An 8 halfword record containing the number and name of the file, its
input/output type, access mode, and a code indicating whether the
previous operation was successful and if so what it was.
status One halfword (two 8-bit characters) set to a pair of values upon completion
of the call to CKREADBYKEY indicating whether the call was successful and
if not why not.
record A record defined in the WORKING-STORAGE SECTION into which the
contents of a record located by key value is read.
key An item whose value is used by CKREADBYKEY to locate the record to be
read. Key values in the file identified by
filetable are compared to the
value of
key until the first record with an equal value is found.
keyloc One halfword integer (S9(4)COMP) set to the starting character position of
the key in the KSAM data record (first position is character 1). The
keyloc parameter identifies the file key to be compared with key .
recordsize An integer (S9(4)COMP) containing the length in characters of the record
being read; it must be less than or equal to the maximum record length
established for the file at creation.
Operation Notes
In order to use the CKREADBYKEY procedure, the file must be opened for either input or
input/output. The access mode can be either random or dynamic, but must not be
sequential.
Execution of CKREADBYKEY causes the value of
key to be compared to the value of the key at
location
keyloc in the KSAM file data records. When a key is found whose value is
identical to that of
key , the record pointer is moved to the beginning of that record and the
record is read into the location
record .
If no record can be found whose key value equals that of
key , an invalid key condition is
diagnosed and
status is set to the value 23.
Successful execution of CKREADBYKEY is indicated by the value 0 in the left byte of
status .
Unsuccessful execution is indicated by either the invalid key return or by a value of 9 in
the left byte of
status .