CKREWRITE

USING CKREWRITE

In order to call procedure CKREWRITE, the file must be open for both input and output (inputoutput 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.

REWRITE IN SEQUENTIAL MODE. 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 insure 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.

Rewriting Records With Duplicate Keys. 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 key file. 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 which is duplicated, it is good practice to use CKDELETE to delete the selected record and then rewrite it as a new record with CKWRITE.

REWRITE IN RANDOM MODE. 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 the "23".

A call to CKREWRITE in random mode only updates the first record with a key in the chain of duplicate keys.

POSITION OF POINTER. 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,

REWRITE WITH SHARED ACCESS. 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 insure 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 insures that no other users change the position of the pointer while you are sequentially updating the file.

INVALID KEY. 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.

EXAMPLES

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 3-2 Representation of KSAMFILE Used in COBOL Examples and the FINISH procedure from CKCLOSE.