CKREWRITE
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| E0300 Edition 4 ♥ | |
| E0394 Edition 3 |
CALL "CKREWRITE" USING filetable, status, record, recordsizeYou can replace an existing record in a KSAM file with the procedure CKREWRITE. This procedure replaces a record previously read from the file with another record whose primary key matches the primary key of the record being replaced.
Parameters
- filetable
An 8 halfword record containing the number and name of the file, its input/output type, access mode, and a code indicating whether the previous operation was unsuccessful and if so what it was.
- status
One halfword (two 8-bit characters) set to a pair of values upon the completion of the call to CKREWRITE indicating whether or not the call was successful and if not why not. (Refer to Status Parameter discussion earlier in this section.)
- record
A record defined in the WORKING-STORAGE SECTION containing data to be written as a logical record to the file replacing the record with a matching primary key.
- recordsize
An integer (S9(4)COMP) containing the length in characters of the record to be written. It must not exceed the maximum record length established for the file when it was created.
Operation Notes
In order to call procedure CKREWRITE, the file must be open for both input and output (input/output type=2). The access mode can be sequential, random, or dynamic. If access mode is sequential, CKREAD must have been executed successfully just prior to the call to CKREWRITE. In random or dynamic mode, no prior read is required; the system searches the file for the record to be rewritten. When the file is opened in sequential mode (access mode = 0), CKREAD must be executed before CKREWRITE. The primary key in the record to be written by CKREWRITE must be identical to the primary key in the record read by CKREAD. A simple way to ensure that the keys match is to read a record into WORKING-STORAGE, modify it without altering the primary key, and then write it back to the file using CKREWRITE. Since the primary key is not changed, the sequence of records in the file is not affected. If you want to rewrite in sequential mode all the records in a chain of records with duplicate keys, use either CKSTART or CKREADBYKEY to position to the first record in the chain. Then call CKREWRITE to update the first record in the chain. Subsequent calls depend on whether you are changing any key value in the record (not necessarily the selected key). If no key in the record is changed, the record pointer continues to point to the current record. Only a subsequent CKREAD advances the pointer to the next record in the duplicate key chain. In this case, you can issue CKREAD and CKREWRITE calls until all records with the duplicated key value have been rewritten. If any key in the record is changed, the new key is written to the end of the chain of duplicate keys in the index area. After the first call to CKREWRITE, the record pointer points to the record whose key value follows the changed key. Since this key is now at the end of the chain of duplicate keys, a subsequent call to CKREWRITE skips all records with keys in the duplicate key chain and rewrites the record with the next higher key value. In this case, you must precede each call to CKREWRITE with a call to CKSTART or CKREADBYKEY in order to update all subsequent records with duplicate keys. If you are updating a primary key value that is duplicated, it is good practice to use CKDELETE to delete the selected record and then rewrite it as a new record with CKWRITE. When the file is opened in random or dynamic mode (access mode = 1 or 2), no prior call to a read procedure is needed. You specify the record to be written in WORKING-STORAGE and then call CKREWRITE. However, you must use the primary key to position to the record to be modified. When the procedure is executed, the file is searched for a record whose primary key matches that of the record to be written. If such a record is found, it is replaced by the record specified in CKREWRITE. If not found, an invalid key condition is diagnosed and status is set to 23. A call to CKREWRITE in random mode updates only the first record with a key in the chain of duplicate keys. Regardless of the mode, after any call to CKREWRITE that does not modify a key value, the record pointer is positioned to the key of the record just modified. However, if any key in the modified record was changed, the record must be deleted and then rewritten by a write procedure. If the access mode is sequential and a key was modified, the pointer is moved to the record with the next key value in ascending sequence after the modified key. If the access mode is random or dynamic, and a key was modified, the pointer is moved to the record with the next key in ascending sequence after the primary key in the modified record. This means that in random or dynamic mode the key pointer may change if it was pointing to an alternate key before the call to CKREWRITE. If the file was opened for shared access with CKOPENSHR, then you must lock the file with a call to CKLOCK before rewriting any records with CKREWRITE. After the records are rewritten, you should unlock the file with CKUNLOCK. To ensure that you are updating the correct record in sequential mode, you should call CKLOCK before positioning the pointer with CKSTART or CKREADBYKEY, then specify the sequential calls to CKREAD and CKREWRITE before unlocking the file with CKUNLOCK. This ensures that no other users change the position of the pointer while you are sequentially updating the file. In sequential mode, the invalid key condition exists when the record just read by CKREAD and the record to be written by CKREWRITE do not have the same primary key value. In random or dynamic mode, an invalid key condition exists if no record can be found in the file whose primary key matches that of the record to be written by CKREWRITE. In either case, status is set to the value 23. Regardless of mode, an invalid key condition occurs if an alternate key value in the record to be written duplicates a corresponding alternate key for which duplicates are prohibited. When rewriting a record, try to avoid specifying an alternate key value that may duplicate a value existing in the file unless duplicates are allowed for the key. A duplicate key condition where duplicates are not allowed causes status to be set to 22 and the procedure is not executed. Use CKSTART to position the current record pointer to the start of the file. Then read each record in sequence and set its non-key items to blanks. The first example is of a sequential update that clears the value of an item in each record of the file. The second example searches the file for a record whose primary key has a particular value in order to change the alternate key for that record. Both examples assume the WORKING-STORAGE SECTION from Figure A-2 "Representation of KSAMFILE Used in COBOL Examples" and the FINISH procedure from CKCLOSE.
 |
NOTE: If the file was opened for shared access with a call to CKOPENSHR, then the file should be locked with a call to CKLOCK before the call to CKSTART. The file should be unlocked with a call to CKUNLOCK only when the final record is updated, probably in the FINISH procedure. |
DATA DIVISION.
.
.
.
WORKING-STORAGE SECTION.
77 RELOP PIC S9(4) COMP.|
77 KEYVAL PIC X(20). |<--- items required by CKSTART
77 KEYLOC PIC S9(4) COMP.|
77 KEYLENGTH PIC S9(4) COMP.|
.
.
.
PROCEDURE DIVISION.
START.
MOVE 2 TO I-O-TYPE.
MOVE 0 TO A-MODE.
CALL "CKOPEN" USING FILETABLE, STAT.
.
. <--- check status
.
UPDATE-FILE.
MOVE 1 TO RELOP.
MOVE "000-0000" TO KEYVAL.<-- set up CKSTART parameters to
MOVE 23 TO KEYLOC. <-- start reading at lowest
MOVE 8 TO KEYLENGTH. <-- alternate key value
CALL "CKSTART" USING FILETABLE, STAT, RELOP, KEYVAL, KEYLOC,
KEYLENGTH.
IF STATUS-KEY-1="0" THEN
GO TO READ-RECORD;
ELSE
DISPLAY "CKSTART ERROR, STATUS", STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "CKERROR NO.", RESULT
GO TO FINISH.
READ-RECORD.
CALL "CKREAD" USING FILETABLE, STAT, REC, RECSIZE.
IF STATUS-KEY-1 = "1" THEN
GO TO FINISH. <------------------ end of file
IF STATUS-KEY-1 = "0" THEN
GO TO WRITE-RECORD
ELSE
DISPLAY "CKREAD ERROR,STATUS =", STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "CKERROR NO. ", RESULT
GO TO READ-RECORD.
WRITE-RECORD.
MOVE SPACES TO OTHERDATA OF REC.
CALL "CKREWRITE" USING FILETABLE,
IF STATUS-KEY-1 = "0" THEN
DISPLAY NAME OF"DATA CLEARED"
GO TO READ-RECORD.
DISPLAY "CKREWRITE ERROR, STATUS=",
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT,
DISPLAY "CKERROR NO.=",
GO TO READ-RECORD.
The second example finds the record with the primary key "ECKSTEIN, LEO "and
changes the value of the secondary key to "257-5137":
PROCEDURE DIVISION.
START.
.
.
.
MOVE 2 TO I-O-TYPE, A-MODE.
CALL "CKOPEN" USING FILETABLE, STAT.
IF STATUS-KEY-1 = "0" THEN
GO TO F-UPDATE.
DISPLAY "CKOPEN ERROR, STA", STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "CKERROR NO.=", RESULT
GO TO FINISH.
F-UPDATE.
MOVE "ECKSTEIN, LEO "TO NAME OF REC.
MOVE "257-5137" TO PHONE OF REC.
MOVE SPACES TO OTHERDATA OF REC.
CALL "CKREWRITE" USING FILETABLE, STAT, REC, RECSlZE.
IF STATUS-KEY-1="0" THEN
DISPLAY REC "UPDATED"
GO TO FINISH.
IF STAT = "23" THEN
DISPLAY NAME OF REC "NOT FOUND"
GO TO FINISH.
DISPLAY "CKREWRITE ERROR, STATUS =", STAT.
IF STATUS-KEY-1 = "9" THEN
CALL "CKERROR" USING STAT, RESULT
DISPLAY "CKERROR NO.=", RESULT.
GO TO FINISH.
|
CKREADBYKEY |
CKSTART |