HP 3000 Manuals HP 3000 Manuals
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-word 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. (Refer to Filetable Parameter
discussion earlier in this section.)
status one word (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.
(Refer to Status Parameter discussion earlier in this
section.)
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-word integer (S9(4)COMP) set to the starting
character position of the key in the KSAM data record
(first position is character 1). keyloc 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.
USING CKREADBYKEY
In order to use the CKREADBYKEY procedure, the file must be opened for
either input or inputoutput. 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.
In order to delete records in random or dynamic mode, CKREADBYKEY must be
called before executing CKDELETE. It is not required prior to CKREWRITE.
EXAMPLES
In the following examples, update information is read into the area
called DAT in the WORKINGSTORAGE SECTION. (Note that in this as in the
preceding examples, the WORKING-STORAGE SECTION from Figure 3-2 continues
to be useful.) In the first example, the primary keys of records in
KSAMFILE are searched for values matching the value read into NAME in the
DAT record; in the second example, an alternate key at location 23 is
searched for values matching the value read into PHONE in the DAT record.
1. Read a record located by its primary key value:
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
77 KEYLOC PIC S9(4) COMP.
.
.
.
PROCEDURE DIVISION.
START.
.
.
.
MOVE 2 TO I-O-TYPE, A-MODE.<--- prepare to open for input-output, dynamic access
CALL "CKOPEN" USING FILETABLE, STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "CKOPEN ERROR NO. ", RESULT.
IF STATUS-KEY-1 NOT="O" THEN
DISPLAY "CKOPEN FAILED"
STOP RUN.
FIND-RECORD.
READ NEW-DATA INTO DAT;<------- read update records
AT END GO TO FINISH.
MOVE 3 TO KEYLOC.
CALL "CKREADBYKEY" USING FILETABLE, STAT, REC, NAME OF DAT,
KEYLOC, RECSIZE.
IF STATUS = "00" THEN
DISPLAY "RECORD FOUND", REC
GO TO FIND-RECORD
IF STATUS = "23" THEN
DISPLAY "RECORD NOT FOUND,KEY=", NAME OF DAT
GO TO FIND-RECORD.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NO. ", RESULT
GO TO FIND-RECORD.
To find a record by the value of an alternate key, simply change
two statements in the preceding example so that KEYLOC contains
the location of the alternate key and the key value for comparison
is found in item PHONE OF DAT rather than in NAME OF DAT:
FIND RECORD.
READ NEW-DATA INTO DAT;
AT END GO TO FINISH.
MOVE 23 TO KEYLOC.
CALL "CKREADBYKEY" USING FILETABLE, STAT, REC, PHONE OF DAT,
KEYLOC, RECSIZE.
.
.
.