BKLOCK
MPE documents | |
 Complete PDF | |
| Table of Contents | |
| Index | |
| E0300 Edition 4 ♥ | |
| E0394 Edition 3 |
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.
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$;" ";S$[1;1];&
" DETAIL ";S$[2]
1010 CALL BKERROR(S$,M$)
1020 PRINT M$
1030 DOEND
|
BKERROR |
BKOPEN |