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