Retrieve Lock Request Information (QWCRLRQI) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format of lock request information | Input | Char(8) |
| 4 | Lock request handle | Input | Char(64) |
| 5 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Lock Request Information (QWCRLRQI) API takes as input a lock request handle that was returned in other APIs and returns information about the program that requested the lock. This API must be called from the same thread that called the API that returned the lock request handle.
The handle is a temporary value. A storage limitation will allow a thread to create up to 1 million valid handles. Once the storage limit has been reached the oldest handle information will be overwritten. This can cause a handle to no longer be valid.
The QSYS2.OBJECT_LOCK_INFO view can be used as an alternative to this API. See OBJECT_LOCK_INFO view for more information.
Authorities and Locks
None.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable provided. The length of the receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of the receiver variable specified is larger then the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
- Format of lock request information
- INPUT; CHAR(8)
The format of the information returned in the receiver variable. The possible format names are:
LRQI0100 Lock request information. See Format LRQI0100 for details.
- Lock request handle
- INPUT; CHAR(64)
This contains the handle that will be used to locate the lock request information. This value is created by a previous call to another lock API. The previous lock API call must have been made by the current thread. This value is a temporary value and may become invalid.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format LRQI0100
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Offset to statement identifiers |
| 12 | C | BINARY(4) | Number of statement identifiers returned |
| 16 | 10 | BINARY(4) | Offset to procedure name |
| 20 | 14 | BINARY(4) | Length of procedure name |
| 24 | 18 | CHAR(10) | Program name |
| 34 | 22 | CHAR(10) | Program library name |
| 44 | 2C | CHAR(10) | Program ASP name |
| 54 | 36 | CHAR(10) | Program library ASP name |
| 64 | 40 | BINARY(4) | Program ASP number |
| 68 | 44 | BINARY(4) | Program library ASP number |
| 72 | 48 | BINARY(4) | MI instruction number |
| 76 | 4C | CHAR(10) | Module name |
| 86 | 56 | CHAR(10) | Module library name |
| * | * | ARRAY OF CHAR(10) | Statement identifiers |
| * | * | CHAR(*) | Procedure name |
Field Descriptions
Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.
Bytes returned. The number of bytes of data returned. Only complete fields are returned.
Length of procedure name. The length of the procedure name in bytes. This field is zero if the program is not an ILE program.
MI instruction number. The current machine instruction number in the program. This field is not meaningful for integrated language environment (ILE) procedures. A zero is returned for ILE procedures.
Module library name. The name of the library in which the module is located. The following special values may be returned:
| *N | The module library name is unavailable. Either the program has been destroyed or the library containing the program is locked. |
| blanks | The program is not an ILE program. |
Module name. The module containing the integrated language environment (ILE) procedure. The following special values may be returned:
| *N | The module name is unavailable. Either the program has been destroyed or the library containing the program is locked. |
| blanks | The program is not an ILE program. |
Number of statement identifiers returned. The actual number of statement identifiers returned.
Offset to procedure name. The offset in bytes from the beginning of the receiver variable to the procedure name. This value will be zero if the program is not an ILE program.
Offset to statement identifiers. The offset in bytes from the beginning of the receiver variable to the statement identifiers. This value will be zero if no statement identifiers are returned.
Procedure name. The name of the procedure.
Program ASP name. The name of the auxiliary storage pool (ASP) device in which the program is located. The following special values may also be returned:
| *SYSBAS | The program is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP cannot be determined. |
Program ASP number. The numeric identifier of the ASP containing the program. The following values may be returned:
| 1 | The library is located in the system ASP. |
| 2-32 | The library is located in a basic user ASP. |
| 33-255 | The library is located in an independent ASP. |
| -1 | The ASP device cannot be determined. |
Program library ASP name. The name of the ASP in which the program library is located. The following special values may also be returned:
| *SYSBAS | The program library is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP cannot be determined. |
Program library ASP number. The numeric identifier of the ASP containing the program library. The following values may be returned:
| 1 | The library is located in the system ASP or in a basic user ASP. |
| 2-32 | The library is located in a basic user ASP. |
| 33-255 | The library is located in an independent ASP. |
| -1 | The ASP device cannot be determined. |
Program library name. The name of the library in which the program is located. The following special value may be returned:
| *N | The program library name is unavailable. The library containing the program has been destroyed or is locked. |
Program name. The name of the program. This can be any type of program object, including objects of type *PGM and *SRVPGM. The following special value may be returned:
| *N | The program is unavailable. Either the program has been destroyed or the library containing the program is locked. |
Statement identifiers. The high-level language statement identifier. If this field contains the character representation of a number, the number is right-adjusted in the field and padded on the left with zeros (for example, '0000000246'). If the lock is for an integrated language environment (ILE) procedure, more than one statement identifier may exist because of the compilers used for ILE languages.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF18C2 E | Object lock handle or lock request handle not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error occured during running of &1 API. |
API introduced: V5R2