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 “Dynamically Locking a KSAM File with BKLOCK” contains an example of locking a file with BKLOCK.

Figure 6-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 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]<*gt;"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

PARAMETERS

USING BKLOCK