 |
» |
|
|
|
|  | |
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 inndicating whether the call wassuccessful and if not why not. (Refer to Status Parameter discussion earlier inthis 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 Representation of KSAMFILE Used in COBOL Examples
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. 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.
.
.
.
|
|
