CKOPEN

USING CKOPEN

Upon successful execution of CKOPEN, the file named in filetable is available for the type of processing specified in filetable. Before the file is successfully opened with CKOPEN, no operation can be executed that references the file either explicitly or implicitly. The input-output procedures that can be called to process the file depend on the value of the words in filetable that specify input-output type and access mode. (Refer to Table 3-4 “Procedures Allowed for Input-Output Type/Access Mode Combinations” for the procedures allowed with the various combinations of input-output type and access mode.) A file may be opened for input, output, or input-output, and for sequential, random, or dynamic access in the same program by specifying a different call to CKOPEN for each change in inputoutput type or access mode. Following the initial execution of CKOPEN, each subsequent call to CKOPEN for the same file must be preceded by a call to CKCLOSE for that file. When files are opened for input or input-output, the call to CKOPEN sets the current record pointer to the first record in the primary key chain.

INPUT-OUTPUT TYPE. Word 6 of filetable must be set to one of the following values before calling CKOPEN:

Input Only. In general, if you want to allow records to be read or the file to be positioned without allowing any new records to be written or any existing records to be changed, you should set the input-output type to 0. This input-output type allows you to call CKREAD or CKSTART in sequential processing mode, CKREADBYKEY in random mode, or all three in dynamic mode.

Output Only. If you want to cause all existing records to be deleted when the file is opened and then allow new records to be written, you should set the input-output type to 1. This type of open deletes all existing records so that records are written to an empty file. When a file is opened for output only, you can call CKWRITE in any of the three access modes: sequential, random, or dynamic, but you cannot call any other of the KSAM procedures.

Input-Output. If you want unrestricted file access, you should set the input-output type to 2. This access type allows records to be read, positioned, written, rewritten, or deleted. You may call CKREAD, CKSTART, CKREWRITE, and CKDELETE (but not CKWRITE) when opened in sequential mode; you may call CKREADBYKEY, CKWRITE, CKREWRITE, or CKDELETE (but not CKREAD or CKSTART) when opened in random mode. In dynamic mode, any of the KSAM procedures may be called. With this type of input-output, existing records are not cleared when you write a record with CKWRITE.

ACCESS MODE. Word 7 of filetable must be set to one of the following values before calling CKOPEN:

Sequential Access. With this type of access, records in the file are read in ascending order based on the value of a key within each record. The key is the primary key unless an alternate key was specified with CKSTART. Reading starts with the first record in sequence unless a particular record was specified with CKSTART. Each time a call to CKREAD is executed, the next record in sequence is read from the file. CKREAD and CKSTART are the only procedures that can be called in input mode. CKREADBYKEY cannot be specified for any input-output type if the access mode is sequential.

In output mode, CKWRITE is the only procedure that can be called. When access is sequential, the record to be written must contain a unique primary key that is greater in value than the key of any previously written record. If it is not in sequence, an invalid key sequence error "21", is returned to status.

In input-output mode, CKREWRITE and CKDELETE can be specified as well as CKREAD and CKSTART, but CKWRITE cannot.

Random Access. This type of access allows you to read, write, replace, or delete a record with any value for its primary key. To read a record, the CKREADBYKEY procedure must be called in either input or input-output mode. CKREAD and CKSTART cannot be specified for any input-output type when access mode is random.

When writing a record with CKWRITE in output or input-output mode, the value of the primary key in the record need not be greater than the keys of previously written records; that is, records can be written in any order.

In input-output mode, CKREWRITE can be used to replace any record whose primary key matches the primary key in the record being written. CKDELETE can be used to delete a record specified in a previous CKREADBYKEY call.

CKWRITE can be used to write a record following existing records in the file if you position to follow the last sequential record before writing. Use this input-output type if you want to save existing data in a file to which you are writing.

Dynamic Access. Dynamic access allows you to use any call to process a file opened for inputoutput. When the file is opened in dynamic mode, and a call is made to CKREAD or CKSTART, the file can be read, but not updated, sequentially. For all other calls, dynamic mode is treated as if the file had been opened in random mode. See Random Mode discussion, above. The reason to open a file in dynamic mode is to allow both sequential and random processing on the same file without closing it and then opening it again each time access switches from sequential to random or vice versa.

EXAMPLES

To open a file initially for sequential read:

   WORKING-STORAGE SECTION. 

   77 RESULT PIC 9(4) VALUE ZERO. 

   01 FILETABLE. 

      03 FILENUMBER PIC S9(4) COMP VALUE ZERO. 

      03 FILENAME PIC X(8) VALUE "KSAMFILE". 

      03 I-O-TYPE PIC S9(4) COMP VALUE ZERO.<------ input only

      03 A-MODE PIC S9(4) COMP VALUE ZERO.<------ sequential access

      03 PREV-OP PIC S9(4) COMP VALUE ZERO. 

   01 STAT. 

      03 STATUS-KEY-1 PIC X. 

      03 STATUS-KEY-2 PIC X. 

   . 

   . 

   . 

   PROCEDURE DIVISION. 

   START. 

       CALL "CKOPEN" USING FILETABLE, STAT. 

       IF STATUS-KEY-1 ="0" THEN GO TO S-READ. 

       IF STATUS-KEY-1 ="9" THEN 

          CALL "CKERROR" USING STAT, RESULT 

          DISPLAY "CKOPEN FAILED. . .ERROR NO.", RESULT 

          STOP RUN. 

   S-READ. 

   . 

   . 

   . 

If you subsequently want to write in sequential order to the same file, you should close the file with a call to CKCLOSE (described below), move the value 1 (output to I-O-TYPE and then re-open the file:

   CALL "CKCLOSE" USING FILETABLE, STAT. 

   IF STATUS-KEY-1 ="9" THEN 

     CALL "CKERROR" USING STAT, RESULT 

     DISPLAY "CKCLOSE FAILED -- ERROR NO.", 

     STOP RUN. 

   MOVE 1 TO I-O-TYPE.<------ output only

   CALL "CKOPEN" USlNG FILETABLE, STAT. 

   . 

   . 

   . 

Similarly, to update records in random order in the same file, first close the file, then use the following MOVE statement to alter the input-output type and access mode in FILETABLE and reopen the file:

   CALL "CKCLOSE" USING FILETABLE, STAT. 

   . 

   . 

   . 

   MOVE 2 TO I-O-TYPE.<----------- input-output

   MOVE 1 TO A-MODE.<------------- random access

   CALL "CKOPEN" USING FILETABLE, STAT. 

   . 

   . 

   .