CKSTART

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 GO TO READ-BY-PHONE.<--- lowest key 
value found 
  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.