CKSTART
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| E0300 Edition 4 ♥ | |
| E0394 Edition 3 |
CALL "CKSTART" USING filetable, status, relop, key, keyloc,
keylength
In order to position the current record pointer to a location in the file
defined by a key value, call CKSTART. Since CKSTART is used
in preparation for sequential retrieval of records with CKREAD, the
file must be open for sequential or dynamic access, not random, and for input
or input/output, not output only.
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 CKSTART to indicate whether or not the call was successful and if not why not. (Refer to Status Parameter discussion earlier in this section.)
- relop
One halfword integer (S9(4)COMP) code that specifies a relation between the key value specified in the call to CKSTART and the key value in the record to which the record pointer is to be positioned:
0 — record key is equal to key
1 — record key is greater than key
2 — record key is greater than or equal to key
- key
An item whose value is used by CKSTART to locate the record at which to position the record pointer. The values of a specified file key are compared in ascending order to the value of key according to the relation specified by relop.
- keyloc
One halfword integer (S9(4)COMP) set to the starting character location of a key in the KSAM file data record (first position is character 1). The key at keyloc is compared to key.
- keylength
One halfword integer (S9(4)COMP) set to the length of key; the length must be less than or equal to the length of the key defined by keyloc.
Operation Notes
When CKSTART is executed, the index area is searched for the first key in the set of keys at location keyloc whose value when compared with key satisfies the comparison specified by relop. The current record pointer is positioned to the beginning of the record in the data area associated with the key found by CKSTART. The specified length of key (key length) may be less than the length of the key in the file; if so, the comparison proceeds as if the file key were truncated on the right to the same length as key length. If no record can be found whose key value satisfies the comparison, an invalid key condition is returned to status; that is, status is set to 23. If you use CKSTART to position the pointer before reading or updating the file sequentially in a shared environment, you must lock the file with a call to CKLOCK before calling CKSTART. Then, after you have completed the sequential operations, you can unlock the file with a call to CKUNLOCK. If you wait to lock the file until after the call to CKSTART, another user can change the structure of the index area so that the position of the pointer becomes invalid for any subsequent call to a procedure that depends on the pointer position. For the following examples, four new items must be added to the WORKING-STORAGE SECTION in Figure A-2 "Representation of KSAMFILE Used in COBOL Examples"; otherwise, the same WORKING-STORAGE SECTION is used. The new items are:
77 RELOP PIC S9(4) COMP. 77 KEYVAL PIC X(20). 77 KEYLOC PIC S9(4) COMP. 77 KEYLENGTH PIC S9(4) COMP.Each of these items is assigned the value appropriate to the operation to be performed by statements in the PROCEDURE DIVISION. Note that the length of array KEYVAL can be made shorter by assigning a value less than 20 to KEYLENGTH but it cannot be made longer than 20 characters. Since there is no key in KSAMFILE longer than 20 characters, this allows comparison to be made on the longest key. The following example shows the statements needed to display the records in KSAMFILE in order by the alternate key PHONE that starts in location 23 and has a length of 8 characters. It assumes the file is open for input or input/output and that the access mode is sequential. It also assumes the FINISH procedure from the CKCLOSE example.
NEW-POSITION.
MOVE 2 TO RELOP. <-- find key value greater than or equal to
<-- KEYVAL
MOVE "000-0000" TO KEYVAL.
MOVE 23 TO KEYLOC.
MOVE 8 TO KEYLENGTH.
CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC,
KEYLENGTH.
IF STAT = "23" THEN GO TO FINISH. <--- no record found
IF STATUS-KEY-1 = "0" THEN <--- lowest key value found
GO TO READ-BY-PHONE.
DISPLAY "CKSTART ERROR, STATUS", STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NUM", RESULT.
GO TO FINISH.
READ-BY-PHONE.
CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE,
IF STATUS-KEY-1 = "1" THEN GO TO FINISH. <--- end-of-file
IF STATUS-KEY-1 = "O" THEN
DISPLAY REC;
ELSE DISPLAY "CKREAD ERROR,STATUS=", STAT
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NUMBER", RESULT.
GO TO READ-BY-PHONE.
In the next example, CKSTART is used to position to the beginning of
the series of names beginning with the letter "T". The KSAM file key is located
at character position 3 (NAME key); the parameter
KEYVAL is set to the value "T"; the key length for purposes of
comparison is set to 1; and RELOP is set to 0. Thus the record
pointer is positioned at the first key found whose value (when the key is
truncated to 1 character) is equal to "T". Note that this example reads not
only all names beginning with "T", but also reads all names that begin
with letters following "T". To read only the names beginning with
"T", the program must add a test for the end of the "T" names.
POSITION.
MOVE 0 TO RELOP.<--- find key equal to KEY value
MOVE "T" TO KEYVAL.
MOVE 3 TO KEYLOC.
MOVE 1 TO KEYLENGTH.
CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC,
KEYLENGTH.
IF STAT = "23" THEN GO TO FINISH.
IF STATUS-KEY-1 = "0" THEN
GO TO READ-NAMES.
DISPLAY "CKSTART ERROR, STATUS=",STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NUMBER=", RESULT.
GO TO FINISH.
READ-NAMES.
CALL "CKREAD" USING FILETABLE, STAT, REC, RECSlZE.
IF STATUS-KEY-1 ="1" THEN GO TO FINISH.
IF STATUS-KEY-1 ="0" THEN
DISPLAY REC;
ELSE
DISPLAY "CKREAD ERROR, STATUS",STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NUM", RESULT.
GO TO READ-NAMES.
|
CKREWRITE |
CKUNLOCK |