Lock and Unlock Range in Stream File (QHFLULSF) API

The Lock and Unlock Range in Stream File (QHFLULSF) API locks or unlocks a range of bytes in an open stream file. An application can lock part of a file instead of the entire file to temporarily keep other open instances from accessing that part.

An open instance is the state of a file having been opened and assigned an open file handle. The same job can open a file more than once. At each open operation, the file is assigned a unique open file handle, and the system treats the resulting state of being open as unique. Locks obtained during one open instance are honored by other open instances, even when the later open instances occur during the same job.

A locked range can be located anywhere in a file, and locking beyond the end of the file is allowed. Locks on a range are independent of the lock mode specified when the file is opened with the Open Stream File (QHFOPNSF) API.

Once a lock is obtained, the specified access is denied to all other requests to access that range in the file. The specified access is denied until the range is explicitly unlocked, the file is explicitly closed by the job, or the file is implicitly closed when the job ends. Closing a file releases all locks on the file.

If both unlocking and locking are specified on the request, the range is unlocked first. When unlocking is complete, the range is locked. This allows one open instance to keep other open instances from using a range that must be unlocked and relocked.

Your application should keep track of the ranges it locks. The QHFLULSF API does not track them, and HFS does not provide an API that lists locks.

Authorities and Locks

None.

Required Parameter Group

Open file handle

INPUT; CHAR(16)

The file handle returned when the file was opened with the QHFOPNSF API.

Lock information

INPUT; CHAR(6)

Additional information specifying the action to take. Valid values for the 6 characters in this parameter are:

1

The lock mode, indicating what access other open instances can have to this range of the file. Valid values are: 0 No lock. Use this when requesting an unlock operation only. 2 Deny write. Other open instances have read-only access to the locked range. The range can overlap or include other ranges locked in deny write mode, but it cannot overlap or include other ranges locked in deny read/write mode. 4 Deny read/write. This is an exclusive lock mode that denies other open instances all access to the locked range. The range cannot overlap or include any other locked range.

2-6

Reserved. These characters must be blank.

File offset where lock begins

INPUT; BINARY(4) UNSIGNED

The number of bytes from the beginning of the file where the range to lock begins.

Bytes to lock

INPUT; BINARY(4) UNSIGNED

The number of bytes to lock. If this is an unlock operation only, use zero for this parameter.

File offset where unlock begins

INPUT; BINARY(4) UNSIGNED

The number of bytes from the beginning of the file where the range to unlock begins.

Bytes to unlock

INPUT; BINARY(4) UNSIGNED

The number of bytes to unlock. If this is a lock operation only, use zero for this parameter.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Error Messages

[ Back to top | Hierarchical File System APIs | APIs by category ]