FLOCK

Dynamically locks a file.

 

              IV       LV 

   FLOCK(filenum,lockcond);

The FLOCK intrinsic dynamically locks a file and transfers the latest control information from disc to the buffers. A call to FLOCK is required before any attempt is made to read or modify a file opened for shared access.




	WARNING! Always unlock a locked file (refer to FUNLOCK) after reading or modifying it. Not following this practice may result in corruption of the file.

PARAMETERS

filenum

integer by value (required)

A word supplying the file number of the file to be locked.

lockcond

logical by value (required)

A word specifying conditional or unconditional locking:

TRUE --

Locking will take place unconditionally. If the file cannot be locked immediately, the calling process suspends until the file can be locked.

Bit 15 = 1

FALSE --

Locking will take place only if the file's Resource Identification Number (RIN) is not currently locked. If the RIN is locked, control returns immediately to the calling process, with condition code CCG.

Bit 15 = 0

CONDITION CODES

The condition codes possible when lockcond = TRUE are

CCE: Request granted.
CCG: Not returned when lockcond = TRUE.
CCL: Request denied because this file was not opened with the dynamic locking aoption specified in the FOPEN intrinsic, or the request was to lock more than one file and the calling process does not possess the Multiple RIN Capability.

The condition codes possible if lockcond = FALSE are

CCE: Request granted.
CCG: Request denied because the file was locked by another process.
CCL: Request denied because: this file was not opened with the dynamic locking aoption specified in the FOPEN intrinsic; or the request was to lock more than one file and the calling process does not possess the Multiple RIN Capability.

SPECIAL CONSIDERATIONS

Split stack calls permitted.

Standard Capability sufficient if only one file is to be locked dynamically.

If more than one file is to be locked dynamically, the Multiple RIN Capability is required.

USING FLOCK

The dynamic locking and unlocking capability allows you to complete any update to a file when it is possible for other users to access the file. When dynamic locking is allowed (bit 10 of FOPEN aoptions parameter is set to allow dynamic locking); then you must use the FLOCK intrinsic to lock the file before writing, rewriting, or deleting any records. This requirement insures that another user does not attempt to change the same record at the same time. FLOCK also insures that the most recent data is available in the file. A locked file can be unlocked following the update with the FUNLOCK intrinsic.

When FLOCK is executed, it clears all the buffers and transfers the latest control information from the KSAM file to the buffers. This insures that any subsequent read of the file retrieves the latest information from disc rather than from the buffers. (Note that FCONTROL control code 7 also clears the buffers.)

If you use the Multiple RIN capability, a sequence of file locking should be agreed upon or you should use conditional locking (lockcond = FALSE). Otherwise, it is possible to lock other users from the file. Consider the situation where one program unconditionally locks file A and then attempts to lock file B. If another program unconditionally locks file B and then attempts to lock file A, both programs will wait indefinitely to lock the second file in sequence. To avoid this, both programs should agree to lock the files in the sequence A first, then B; or both programs should use only conditional locks.

For example, suppose you open a KSAM file called DATA1 for shared access in update mode and allow dynamic locking and unlocking:

 

     FIL1:=FOPEN(DATA1,7,%345);

The parameters specified are:

filenum: File number of DATA1, which is assigned to FIL1 when the file is opened.
formal- designator: Name identifying the file contained in DATA1.
foptions: The value 7 specifies that this is an old user file (bits 14,15 = 11) and that it is coded in ASCII (bit 13 = 1).
aoptions: The octal value 345 indicates that the file was opened for update (bits 12 through 15 = 0101), that dynamic locking/unlocking is allowed (bit 10 = 1), and that access is shared (bits 8 and 9 = 11).

This file can then be locked as follows:

 

     FLOCK(FIL1,1)