HP 3000 Manuals HP 3000 Manuals
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. (Refer to the Status Parameter discussion
earlier in this section.) (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.
USING BKLOCK
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.
NOTE All users who share access to the Ele must agree to allow dynamic
locking in order for any user to dynamically lock the file with
BKLOCK.
The note above points out that 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
if 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 6-3 contains an example of locking a 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 INDTCATES 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 |
___________________________________________________________________________________
Figure 6-3. Dynamically Locking a KSAM File with BKLOCK