Retrieve Lock Space Record Locks (QTRXRLRL) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format of receiver information | Input | Char(8) |
| 4 | Lock space identifier | Input | Char(20) |
| 5 | Lock filters | Input | Char(*) |
| 6 | Format of lock filters | Input | Char(8) |
| 7 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Lock Space Record Locks (QTRXRLRL) API lets you generate a list of record locks held by the specified lock space. Record locks that are being waited for on behalf of a lock space are not returned. Use the Retrieve Job Record Locks (QDBRJBRL) or Retrieve Lock Information (QWCRLCKI) API to retrieve record locks that are being waited for by a thread on behalf of a lock space.
Lock information is returned for local physical files only. The Retrieve Lock Space Record Locks API places the list in the specified receiver variable.
Authorities and Locks
- Job authority
- The caller of the API must be running under a user profile that has job control (*JOBCTL) special authority.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the list of record locks. The size of this variable is specified in the length of receiver variable parameter.
See Format of Receiver Information for details on the format of the receiver information.
- Length of receiver variable
- INPUT; BINARY(4)
The number of bytes that are provided in the Receiver variable parameter. At least 16 bytes must be provided. If the size of the receiver variable provided is less than the length of the list that is available, the list will be truncated; this can be determined by examining the first two fields in the receiver variable, the number of record locks returned, and the number of record locks available. If the receiver variable length specified is greater than the actual receiver variable, the results are unpredictable.
- Format of receiver information
- INPUT; CHAR(8)
The format of the information returned in the receiver variable. The format name is:
RLRL0100 Record lock list. See RLRL0100 Format for details.
- Lock space identifier
- INPUT; CHAR(20)
The identifier of the lock space for which record locks are to be returned.
- Lock filters
- INPUT;CHAR(*)
Filters used for the lock information that is returned. See Format of Lock Filters for further information.
- Format of lock filters
- INPUT; CHAR(8)
The format of the lock filters used on the returned data. The possible format name is:
RLRF0100 Lock filter format. See RLRF0100 Format for details.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Format of Receiver Information
The format of the information returned in the receiver variable.
RLRL0100 Format
The following information is returned for the RLRL0100 format. For detailed descriptions of the fields in the table, see Field Descriptions for RLRL0100 Format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of record locks available |
| 12 | C | BINARY(4) | Number of record locks returned |
| 16 | 10 | BINARY(4) | Offset to list of record locks |
| 20 | 14 | BINARY(4) | Size of information for each record lock returned |
Each record lock returned will have the following structure.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Database file name |
| 10 | A | CHAR(10) | Database file library name |
| 20 | 14 | CHAR(10) | Database member name |
| 30 | 1E | CHAR(1) | Reserved |
| 31 | 1F | CHAR(1) | Lock state |
| 32 | 20 | UNSIGNED BINARY(4) | Relative record number |
| 36 | 24 | CHAR(10) | Database file ASP name |
| 46 | 2E | CHAR(10) | Database file library ASP name |
| 56 | 38 | BINARY(4) | Database file ASP number |
| 60 | 3C | BINARY(4) | Database file library ASP number |
Field Descriptions for RLRL0100 Format
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 entries are returned.
Database file library ASP name. The name of the auxiliary storage pool (ASP) that contains the library. The following special values also may be returned:
| *SYSBAS | The library is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP device cannot be determined. |
Database file library ASP number. The numeric identifier of the ASP containing the library. 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 number cannot be determined. |
Database file library name. The name of the library that contains the file.
Database file name. The name of the file.
Database member name. The name of the member.
Database file ASP name. The name of the auxiliary storage pool (ASP) that contains the file. The following special values also may be returned:
| *SYSBAS | The file is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP device cannot be determined. |
Database file ASP number. The numeric identifier of the ASP containing the file. The following values may be returned:
| 1 | The file is located in the system ASP. |
| 2-32 | The file is located in a basic user ASP. |
| 33-255 | The file is located in an independent ASP. |
| -1 | The ASP number cannot be determined. |
Lock state. The state of the lock. The possible values are:
| 0 | Shared Read. |
| 1 | Exclusive Update. |
| 2 | Shared Internal. |
Number of record locks available. The number of record lock structures that are available to be returned. If this field is the same as the number of record locks returned field, all the record lock information has been returned.
Number of record locks returned. The number of record lock structures that were returned to the caller of the API. If enough space is provided in the receiver variable, all record locks are returned. If there is more record lock information than can fit in the space provided, the number of record locks returned is less than the number of record locks available.
Offset to list of record locks. The byte offset from the beginning of the receiver variable to the first record lock information structure.
Relative record number. The relative record number for which record lock information is being returned.
Reserved. An unused field.
Size of information for each lock returned. The number of bytes of each of the returned lock information structures. In future releases, the amount of information returned for each lock may be expanded, so this value should be used to move from one lock structure to another.
Format of Lock Filters
The format of the lock filters used on the returned lock information.
RLRF0100 Format
The following information is to be specified for the RLRF0100 format. For detailed descriptions of the fields in the table, see Field Descriptions for RLFL100 Format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Filter size |
| 4 | 4 | BINARY(4) | Filter lock state |
| 8 | 8 | CHAR(10) | Filter file name |
| 18 | 12 | CHAR(10) | Filter file member name |
| 28 | 1C | CHAR(10) | Filter file library name |
| 38 | 26 | CHAR(10) | Filter file library ASP name |
Field Descriptions for RLRF0100 Format
Filter lock state. Filters information that is returned so that it contains only information about locks that have a certain lock state. The default is do not filter on lock state value.
| 0 | Do not filter on lock state value |
| 1 | Return only the shared locks |
| 2 | Return only the exclusive locks |
Filter file library ASP name. The name of the library's auxiliary storage pool (ASP) on which to filter. A special value of *SYSBAS can be specified. A blank field will cause no filtering to be done on this field. The default is to not filter on this field.
Filter file library name. The library name on which to filter. A blank field will cause no filtering to be done on this field. The default is to not filter on this field.
Filter file member name. The member name on which to filter. A blank field will cause no filtering to be done on this field. The default is to not filter on this field.
Filter file name. The file name on which to filter. A blank field will cause no filtering to be done on this field. The default is to not filter on this field.
Filter size. The size of the filter information passed. Valid values are:
| 4 | No filtering will be performed. The default values will be used for each filter. |
| 48 | All filters will be required. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C3B E | Value for parameter &2 for API &1 not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPFBDD1 E | Lock space &1 not found. |
| CPFBDD2 E | No authority to lock space &1. |
API introduced: V5R2