BKLOCK

Dynamically locks KSAM file during shared access.

   CALL BKLOCK(filenum,status[,condition])

When more than one user accesses the same file, BKLOCK can be used to make access to the file exclusive for one user while he writes to or updates the file. In order to use BKLOCK, the file must be opened with dynamic locking allowed by all users who are sharing the file. When finished with the changes that required exclusive access, the user who has locked the file with BKLOCK should unlock it with BKUNLOCK.




	NOTE: Note that a file opened for shared access must be locked by `BKLOCK` before the file can be modified by `BKWRITE`, `BKREWRITE`, or `BKDELETE`.

Parameters

filenum

A numeric variable containing the file number that identifies the file; this number was returned to filenum by the last call to BKOPEN. It should not be altered unless the file is successfully closed by BKCLOSE. (Required parameter)

status

A four-character string variable to which is returned a code that indicates whether or not the call to BKLOCK was successful and if not, why not. The first character is set to zero when the call succeeds, to another value if it fails. (Required parameter)

condition

A numeric expression whose value determines the action taken if the file is locked by another user when BKLOCK is executed. If the value of condition is:

Zero-locking is unconditional.
If the file cannot be locked immediately because another user has locked it, your program suspends execution until the file can be locked. (default value)
Non-zero-locking is conditional.
If the file is already locked, control returns immediately to your program with status set to 71.

(Optional parameter) Default: If omitted, locking is unconditional.

Operation Notes

In order to call BKLOCK, the file must be opened with dynamic locking allowed. That is, the parameter lock in the BKOPEN procedure must be set to 1. Also, since dynamic locking is useful only when access is shared, probably the file will have been opened with the exclusive parameter in BKOPEN set to 3.

Users who share the same file should cooperate on how they will share the file. Unless they all agree to allow locking, no one will be able to lock the file. Also, it is important to avoid situations where one user locks the file and forgets to unlock it. If this occurs when condition is set to a non-zero value, the calling process is not halted. But if the file is locked already and you attempt to lock a file with condition omitted or set to zero, your process is halted until the other user either unlocks the file or logs off.

You should always check the status parameter immediately following a call to BKLOCK in order to determine if the call was completed successfully. If you locked with condition set to a nonzero value, you should check if the file was locked before continuing. If it was locked, status will have a 0 in the first character, but if another user had locked the file preventing your call to BKLOCK from working, then status contains the value 71.

Figure B-3 “Dynamically Locking a KSAM File with BKLOCK” contains an example of locking a file with BKLOCK.

Figure B-3 Dynamically Locking a KSAM File with BKLOCK

 
    830 REM ******************************************************** 
    840 REM * LOCK A KSAM FILE * 
    850 REM ******************************************************** 
    855 REM 
    860 REM F IS THE FILE NUMBER OF A KSAM FILE 
    870 REM OPENED BY A CALL TO BKOPEN 
    890 REM 
    900 REM THE THIRD PARAMETER INDICATES THAT LOCKING IS 
    910 REM TO TAKE PLACE UNCONDITIONALLY 
    920 REM 
    930 CALL BKLOCK(F,S$,0) 
    940 REM 
    950 REM NOW DETERMINE WHETHER THIS CALL HAS SUCCEEDED 
    960 REM 
    970 IF S$[1;1]<>"0" THEN DO 
    980 REM N$ CONTAINS THE NAME OF THE KSAM FILE 
    990 REM S$ CONTAINS THE STATUS CODE SET BY THE PRECEDING CALL 
   1000 PRINT "UNABLE TO LOCK ";$N;" ERROR ";N$;" "LS$[1;1];" DETAIL ";S$[2] 
   1010 CALL BKERROR(S$,M$) 
   1020 PRINT M$ 
   1030 DOEND

BKLOCK

Technical documentation

» Table of Contents

» Index

Parameters

Operation Notes