HP 3000 Manuals HP 3000 Manuals
CKSTART
A call to procedure CKSTART allows you to position the record pointer to
a particular record defined by its primary or alternate key value.
CALL "CKSTART" USING filetable, status, relop, key, keyloc, keylength
In order to position the current record pointer to a location in the file
defined by a key value, call CKSTART. Since CKSTART is used in
preparation for sequential retrieval of records with CKREAD, the file
must be open for sequential or dynamic access, not random, and for input
or input-output, not output only.
PARAMETERS
filetable an 8-word record containing the number and name of the
file, its input-output type, access mode, and a code
indicating whether the previous operation was successful
and if so, what it was. (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 CKSTART to indicate
whether or not the call was successful and if not why
not. (Refer to Status Parameter discussion earlier in
this section.)
relop one-word integer (S9(4)COMP) code that specifies a
relation between the key value specified in the call to
CKSTART and the key value in the record to which the
record pointer is to be positioned:
0--record key is equal to key
1--record key is greater than key
2--record key is greater than or equal to key
key an item whose value is used by CKSTART to locate the
record at which to position the record pointer. The
values of a specified file key are compared in ascending
order to the value of key according to the relation
specified by relop.
keyloc one-word integer (S9(4)COMP) set to the starting
character location of a key in the KSAM file data record
(first position is character 1). The key at keyloc is
compared to key.
keylength one-word integer (S9(4)COMP) set to the length of key;
the length must be less than or equal to the length of
the key defined by keyloc.
USING CKSTART
When CKSTART is executed, the key file is searched for the first key in
the set of keys at location keyloc whose value when compared with key
satisfies the comparison specified by relop. The current record pointer
is positioned to the beginning of the record in the data file associated
with the key found by CKSTART.
The specified length of key (key length) may be less than the length of
the key in the file; if so, the comparison proceeds as if the file key
were truncated on the right to the same length as key length.
If no record can be found whose key value satisfies the comparison, an
invalid key condition is returned to status; that is, status is set to
"23".
SHARED ACCESS. If you use CKSTART to position the pointer before reading
or updating the file sequentially in a shared environment, you must lock
the file with a call to CKLOCK before calling CKSTART. Then, after you
have completed the sequential operations, you can unlock the file with a
call to CKUNLOCK. If you wait to lock the file until after the call to
CKSTART, another user can change the structure of the key file so that
the position of the pointer becomes invalid for any subsequent call to a
procedure that depends on the pointer position. (Refer to Table 3-3 for
a list of the pointer-dependent procedures.)
EXAMPLES
Four new items must be added to the WORKING-STORAGE SECTION in Figure
3-2; otherwise, the same WORKING-STORAGE SECTION is used. The new items
are:
77 RELOP PIC S9(4). COMP.
77 KEYVAL PIC X(20).
77 KEYLOC PIC S9(4) COMP.
77 KEYLENGTH PIC S9(4) COMP.
Each of these items is assigned the value appropriate to the operation to
be performed by statements in the PROCEDURE DIVISION. Note that the
length of array KEYVAL can be made shorter by assigning a value less than
20 to KEYLENGTH but it cannot be made longer than 20 characters. Since
there is no key in KSAMFILE longer than 20 characters, this allows
comparison to be made on the longest key.
The following example shows the statements needed to display the records
in KSAMFILE in order by the alternate key PHONE that starts in location
23 and has a length of 8 characters. It assumes the file is open for
input or input-output and that access mode is sequential. It also
assumes the FINISH procedure from the CKCLOSE example.
1. Position by alternate key sequence:
NEW-POSITION.
MOVE 2 TO RELOP.<-------- find key value greater than or equal to KEYVAL
MOVE "000-0000" TO KEYVAL.
MOVE 23 TO KEYLOC.
MOVE 8 TO KEYLENGTH.
CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.
IF STATUS = "23" THEN GO TO FINISH.<-------- no record found
IF STATUS-KEY-1 = "0" THEN GO TO READ-BY-PHONE.<--- lowest key value found
DISPLAY "CKSTART ERROR, STATUS", STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NUM", RESULT.
GO TO FINISH.
READ-BY-PHONE.
CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE,
IF STATUS-KEY-1 = "1" THEN GO TO FINISH.<---- end-of-file
IF STATUS-KEY-1 = "O" THEN
DISPLAY REC;
ELSE DISPLAY "CKREAD ERROR,STATUS=", STAT
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NUMBER", RESULT.
GO TO READ-BY-PHONE.
.
.
.
In the next example, CKSTART is used to position to the beginning
of the series of names beginning with the letter "T". The KSAM
file key is located at character position 3 (NAME key); the
parameter KEYVAL is set to the value "T"; the key length for
purposes of comparison is set to 1; and RELOP is set to 0. Thus
the record pointer is positioned at the first key found whose
value (when the key is truncated to 1 character) is equal to "T".
Note that this example reads not only all names beginning with
"T", but also reads all names that begin with letters following
"T". To read only the names beginning with "T", the program must
add a test for the end of the "T" names.
2. Using a Generic Key
POSITION.
MOVE 0 TO RELOP.<------------ find key equal to KEY value
MOVE "T" TO KEYVAL.
MOVE 3 TO KEYLOC.
MOVE 1 TO KEYLENGTH.
CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC, KEYLENGTH.
IF STATUS = "23" THEN GO TO FINISH.
IF STATUS-KEY-1 = "0" THEN
GO TO READ-NAMES.
DISPLAY "CKSTART ERROR, STATUS=",STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NUMBER=", RESULT.
GO TO FINISH.
READ-NAMES.
CALL "CKREAD" USING FILETABLE, STAT, REC, RECSlZE.
IF STATUS-KEY-1 ="1" THEN GO TO FINISH.
IF STATUS-KEY-1 ="0" THEN
DISPLAY REC;
ELSE
DISPLAY "CKREAD ERROR, STATUS",STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "ERROR NUM", RESULT.
GO TO READ-NAMES.