HPlogo Using KSAM XL and KSAM 64 > Appendix A COBOL Intrinsics

CKOPEN

MPE documents

Complete PDF
Table of Contents
Index

E0300 Edition 4 ♥
E0394 Edition 3

A call to procedure CKOPEN initiates KSAM file processing. 

  CALL "CKOPEN" USING filetable, status
In order to process a KSAM file, it must be opened with a call to the CKOPEN procedure. CKOPEN initiates processing, specifies the type of processing and the access mode; the file must have been created previously.

To open a file means to make it available for processing, to specify the type of processing (input only, output only, or both), and to specify the access method (sequential, random, or dynamic). If a different type of processing or access method is needed, the file must be closed and opened again with the parameters set to new values.

NOTE: If you want to open the file for shared access, you must use a call to CKOPENSHR, rather than CKOPEN.

Parameters

filetable

An 8 halfword record containing the name of the file, its input/output type, and access mode. When the open is successful, the first word of this table is set to the file number that identifies the opened file. (Refer to Filetable Parameter discussion earlier in this section.)

status

One halfword (two 8-bit characters) set to a pair of values upon completion of the call to CKOPEN to indicate whether or not the file was successfully opened and if not why not. The left character is set to 0 if open is successful, to 9 if not. The right character is set to 0 if the open is successful, to the file system error code if not. (Refer to Status Parameter discussion earlier in this section.)

Operation Notes

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 halfwords in filetable that specify input/output type and access mode. (Refer to Figure A-3 "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 input-output 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.

Figure A-3 Procedures Allowed for Input/Output Type/Access Mode Combinations

[Procedures Allowed for Input/Output Type/Access Mode Combinations]

Halfword 6 of filetable must be set to one of the following values before calling CKOPEN:
0

input only

1

output only

2

input/output

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.

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.

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.

Halfword 7 of filetable must be set to one of the following values before calling CKOPEN:
0

sequential access

1

random access

2

dynamic access

With sequential 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 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 allows you to use any call to process a file opened for input/output. 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. 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.

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 reopen 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.



CKLOCK

CKOPENSHR