CKLOCK

A call to CKLOCK dynamically locks a KSAM file.

CALL "CKLOCK" USING filetable, status, lockcond

When access is shared, you must lock the file before calling CKWRITE, CKREWRITE, or CKDELETE. This ensures that another user cannot attempt to modify the file at the same time. It guarantees that the most recent data is available to each user who accesses the file.

In order to call CKLOCK, the file must have been opened with a call to CKOPENSHR, not CKOPEN.

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 successful and if so, what it was. (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 CKLOCK. It indicates whether or not the file was successfully locked and if not, why not. The status word = 00 if the call was successful. It = 30 if the file was locked by another process. It = 9n, where n is a file system error code, if the call failed for some other reason. (Refer to the Status Parameter discussion earlier in this section.)

lockcond

One halfword computational item whose value determines the action taken if the file is locked by another user when CKLOCK is executed. The value is either zero (0) or one (1).

0: locking is conditional; if the file is already locked, control is returned to your program immediately with the status word set to "30".
1: locking is unconditional; if the file cannot be locked immediately because another use has locked it, your program suspends until the file can be locked.

Operation Notes

In order to call CKLOCK, the file must be opened with dynamic access enabled. This can be done only with the CKOPENSHR procedure. CKOPEN will not open the file for shared access with dynamic locking.

When users are sharing a file, it is essential to lock the file before modifying it. An error is returned if any user attempts to write, rewrite, or delete records without first locking the file. It is also important to avoid situations where one user locks the file and forgets to unlock it. If the file is already locked when you call CKLOCK with lockcond set to zero, the call will fail with 30 returned to status, and your process will continue. If, however, lockcond is set to 1, your process suspends until the other user unlocks the file or logs off.

The following example opens file KSAMFILE for shared access with dynamic locking allowed. It then locks the file unconditionally. If another user has locked the file, the process suspends until the file is unlocked and then continues by locking your file. The status value is checked as soon as control returns to your process to ensure that the file has been locked before continuing.

 
 DATA DIVISION. 
 
 77   LOCKCOND      PICTURE S9(4)   COMP   VALUE 1. 
 77   RESULT        PICTURE 9(4)           VALUE 0. 
 01   STATUSKEY. 
    02 STATUS-KEY1  PICTURE X VALUE " ". 
    02 STATUS-KEY2  PICTURE X VALUE " ". 
 01   FILETABLE. 
    02  FILENUMBER  PICTURE S9(4)   COMP   VALUE 0. 
    02  FILENAME    PICTURE X(8)           VALUE "KSAMFILE". 
    02  I-O-TYPE    PICTURE S9(4)   COMP   VALUE 0. 
    02  A-MODE      PICTURE S9(4)   COMP   VALUE 0. 
    02  PREV-OP     PICTURE S9(4)   COMP   VALUE 0. 
 
 PROCEDURE DIVISION. 
 
START.
    CALL "CKOPENSHR" USING FILETABLE, STATUSKEY. 
    IF STATUS-KEY1 = "0" THEN GO TO LOCK-FILE. 
    IF STATUS-KEY1 = "9" THEN 
	 CALL "CKERROR" USING STATUSKEY, RESULT 
	 DISPLAY "ERROR NO. ",RESULT. 
 
LOCK-FILE. 
    CALL "CKLOCK" USING FILETABLE, STATUSKEY, LOCKCOND. 
    IF STATUSKEY="00" 
       THEN DISPLAY "CKLOCK IS OK" 
    ELSE IF STATUSKEY = "30" 
       THEN DISPLAY "FILE LOCKED BY ANOTHER PROCESS" 
    ELSE IF STATUS-KEY1="9" 
       THEN CALL "CKERROR" USING STATUSKEY, RESULT 
    DISPLAY "ERROR NO.", RESULT.

CKLOCK

Technical documentation

» Table of Contents

» Index

Parameters

Operation Notes