Exit Program for Lock and Unlock Range in Stream File (QHFLULSF) API

Required Parameter Group:

1	Operation (LULSF)	Input	Char(5)
2	File system job handle	Input	Char(16)
3	Open file handle	Input	Char(16)
4	Lock information	Input	Char(6)
5	File offset where lock begins	Input	Binary(4)
6	Bytes to lock	Input	Binary(4) Unsigned
7	File offset where unlock begins	Input	Binary(4) Unsigned
8	Bytes to unlock	Input	Binary(4) Unsigned

Before applications can use the Lock and Unlock Range in Stream File (QHFLULSF) API with your file system, you must:

Write an exit program that performs the lock and unlock operation on behalf of the API. For a detailed description of the API and its calling parameters, see Lock and Unlock Range in Stream File (QHFLULSF) API.
Give the exit program's name when you register the file system with the Register File System (QHFRGFS) API.

After that, when an application calls the QHFLULSF API, the API calls your exit program and passes it the parameters specified by the application. Your exit program performs the work and returns any data to the API. The API passes the data back to the calling application.

Authorities and Locks

None.

Required Parameter Group

The API passes this information to your exit program:

Operation (LULSF): INPUT; CHAR(5)
The abbreviation for the operation being performed (LULSF).
File system job handle: INPUT; CHAR(16)
The work area or job identifier for use by the file system.

The following parameters are the same as the parameters for the API.

Open file handle: INPUT; CHAR(16)
Lock information: INPUT; CHAR(6)
File offset where lock begins: INPUT; BINARY(4) UNSIGNED
Bytes to lock: INPUT; BINARY(4) UNSIGNED
File offset where unlock begins: INPUT; BINARY(4) UNSIGNED
Bytes to unlock: INPUT; BINARY(4) UNSIGNED

API Functions

The QHFLULSF API performs the standard functions described in Standard HFS API Functions and these additional functions:

Verifies that the bytes to lock and bytes to unlock parameters are not both zero. In other words, the API ensures that a lock, unlock, or both operations are to be performed. If both parameters are zero, an error is returned.
Verifies that the lock information parameter contains valid values, and that the lock mode value is applicable to the lock or unlock operation requested.

Exit Program Requirements

You must create an exit program that performs the standard functions described in Standard HFS Exit Program Requirements and these additional functions:

Verifies that the file offsets to lock and unlock are valid offsets.
Verifies that the number of bytes to lock and unlock are valid values.
For an unlock operation, verifies that this job previously locked the range.
For a lock operation, verifies that no part of the range already has a lock that does not allow the access requested.
Unlocks or locks the range requested.

Error Messages for Exit Program Use

This section lists the messages that the exit program can return to the API.

Message ID	Error Message Text
CPF1F2E E	Range of bytes in file in use.
CPF1F2F E	Unlock range of bytes in file failed.
CPF1F28 E	Damaged file.
CPF1F32 E	Number of locks on file exceeds limit.
CPF1F4B E	Value for number of bytes not valid.
CPF1F4C E	Lock information value not valid.
CPF1F4D E	File offset value not valid.
CPF1F41 E	Severe error occurred while addressing parameter list.
CPF1F62 E	Requested function failed.
CPF1F66 E	Storage needed exceeds maximum limit for user profile &1.
CPF1F71 E	Exception specific to file system occurred.
CPF1F73 E	Not authorized to use command.
CPF1F74 E	Not authorized to object.
CPF1F77 E	Severe parameter error occurred on call to file system.

Exit Program Introduced: V2R1

Top | Hierarchical File System APIs | APIs by category