HP 3000 Manuals HP 3000 Manuals
CKOPEN
A call to procedure CKOPEN initiates 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. You can create a KSAM file through the BUILD command of the
KSAMUTIL program (refer to section II).
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-word 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 word (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. Left character is set to "0" if open is
successful, to "9" if not. Right character is set to
"0" if open is successful, to file system error code if
not. (Refer to Status Parameter discussion earlier in
this section.)
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 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.
Table 3-4. Procedures Allowed for Input-Output Type/Access Mode Combinations
![[]](../../pic3k/M010088/TA03043c50.gif)
INPUT-OUTPUT TYPE. Word 6 of filetable must be set to one of the
following values before calling CKOPEN:
0 input only
1 output only
2 input-output
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:
0 sequential access
1 random access
2 dynamic access
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.
.
.
.