CKREAD

Operation Notes

The file from which the record is read must be opened for sequential or dynamic access (access mode = 0 or 2). It may be opened for input only or input/output (input/output type = 0 or 2), but not for output only.

When the file is opened initially for input or input/output, the logical record pointer is positioned at the first sequential record; that is, at the record with the lowest key value. The key used is the primary key unless a previous call to CKSTART has specified an alternate key. When a call to CKREAD is executed, the record at which the record pointer is currently positioned is read into the location specified by record.

If, when CKREAD is executed, there is no next logical record in the file, the at end condition is returned to status; that is, status is set to 10. Note that a call to the procedure CKSTART can be used to reposition the pointer for subsequent sequential access according to primary or alternate key order.

In order to update records in sequential order, CKREAD must be called before executing either of the update procedures CKREWRITE or CKDELETE. When access is shared, it is important to include the call to CKREAD within the same locked portion of code that includes the call to CKREWRITE or CKDELETE. This ensures that the correct record is modified or deleted.

Because CKREAD is a pointer-dependent procedure, the actual record read depends on the current position of the logical record pointer. When access is shared, this pointer position can be made incorrect by other users without your program being aware of it. For this reason, you should lock the file, position the pointer with a pointer-independent procedure, and then call CKREAD. When the last record is read, you should then unlock the file so other users can access the file. Example 2 below illustrates how you should read the file sequentially when access is shared.

Using the WORKING-STORAGE SECTION from Figure A-2 “Representation of KSAMFILE Used in COBOL Examples” and the FINISH procedure in the CKCLOSE example, the following procedures read records in sequential order from file KSAMFILE and display them on the standard output device.

 
PROCEDURE DIVISION. 
 
START.
  .
  .
  .
  MOVE 0 TO I-O-TYPE, A-MODE. 
  CALL "CKOPEN" USING FILETABLE, STAT. 
  IF STATUS-KEY-1 = "9" 
    CALL "CKERROR" USING STAT, RESULT 
    DISPLAY "CKOPEN ERROR NO. ", RESULT. 
  IF STATUS-KEY-1 NOT = "0" 
    DISPLAY "CKOPEN FAILED" 
  STOP RUN. 
    READ-NEXT. 
      CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE. 
      IF STATUS-KEY-1 = "1" GO TO NEW-POSITION. 
      IF STATUS-KEY-1 = "0" 
        DISPLAY REC; 
      ELSE 
        DISPLAY "CKREAD ERROR, STATUS =", STAT. 
      IF STATUS-KEY-1 ="9" 
        CALL "CKERROR" USING STAT, RESULT 
        DISPLAY "FILE ERROR =", RESULT. 
      GO TO READ-NEXT. 
  NEW-POSITION.
    .
    .
    .

The following example provides a sequential read with shared access.

 
PROCEDURE DIVISION. 
START. 
.
.
.
 MOVE 0 TO I-O-TYPE, A-MODE. 
 CALL "CKOPENSHR" USING FILETABLE, STAT <--- open file for shared 
access 
.
.
. <--- test status 
FIND-RECORD. 
 MOVE 2 TO RELOP. 
 MOVE "000-0000" TO KEYVAL. 
 MOVE 23 TO KEYLOC, 
 MOVE 8 TO KEYLENGTH. 
 MOVE 1 TO LOCKCOND. 
 CALL "CKLOCK" USING FILETABLE, STAT, LOCKCOND.<--- lock file 
unconditionally 
 CALL "CKSTART" USING FILETABLE, 
   STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.<--- position pointer to 
lowest key value 
.
.
. <--- test status 
READ-RECORD. 
 CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE<--- read record 
 IF STATUS-KEY-1 ="1"<--- end of file 
   GO TO END-OF-READ. 
 IF STATUS-KEY-1 ="0"<--- if successful, display record read 
   DISPLAY REC. 
.
.
. <--- test status for errors 
 TO TO READ-RECORD. 
END-OF-READ. 
 CALL "CKUNLOCK" USING FILETABLE, STAT.<----- unlock file