Retrieve Lock Space Attributes (QTRXRLSA) 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 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Lock Space Attributes (QTRXRLSA) API returns information for the specified lock space. A lock space is an internal object that is used by other objects to hold object and record locks.
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 lock space attributes. 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 length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than 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 receiver information
- INPUT; CHAR(8)
The format of the information returned in the receiver variable. The format name is:
RLSA0100 Lock space attributes. See RLSA0100 Format for details.
- Lock space identifier
- INPUT; CHAR(20)
The identifier of the lock space for which attributes are to be returned.
- 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.
RLSA0100 Format
The following information is returned for the RLSA0100 format. For detailed descriptions of the fields in the table, see Field Descriptions for RLSA0100 Format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Lock space type |
| 12 | C | BINARY(4) | Lock space state |
| 16 | 10 | BINARY(8) | Lock wait time |
| 24 | 18 | BINARY(8) | Active state timer |
| 32 | 20 | BINARY(4) | Number of threads with lock space attached |
| 36 | 24 | BINARY(4) | Maximum number of threads with lock space attached |
| 40 | 28 | CHAR(8) | Reserved |
| 48 | 30 | CHAR(30) | Lock space name |
| 78 | 4E | CHAR(10) | Lock space library name |
| 88 | 58 | CHAR(10) | Lock space ASP name |
| 98 | 62 | CHAR(10) | Lock space library ASP name |
| 108 | 6C | BINARY(4) | Lock space ASP number |
| 112 | 70 | BINARY(4) | Lock space library ASP number |
Field Descriptions for RLSA0100 Format
Active state timer. The maximum amount of time, in seconds, that a lock space can remain in the active state before it is switched to the disabled state. The following special value may be returned:
| 0 | The active state timer is disabled for the lock space. |
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.
Lock space ASP name. The name of the auxiliary storage pool (ASP) that contains the lock space. The following special values also may be returned:
| *SYSBAS | The lock space is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP device cannot be determined. |
Lock space ASP number. The numeric identifier of the ASP containing the lock space. The following values may be returned:
| 1 | The lock space is located in the system ASP. |
| 2-32 | The lock space is located in a basic user ASP. |
| 33-255 | The lock space is located in an independent ASP. |
| -1 | The ASP number cannot be determined. |
Lock space 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. |
Lock space 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. |
Lock space library name. The name of the library that contains the lock space.
Lock space name. The name of the lock space.
Lock space state. The current state of the lock space. The lock space state is used to determine whether object and record locks can be obtained or held by the lock space. The possible values are:
| 0 | Inactive. The lock space cannot hold object or record locks. |
| 1 | Active. The lock space can hold object or record locks. |
| 2 | Disabled. The lock space can hold object or record locks, but new object or record locks cannot be obtained. |
Lock space type. The type of object that is using the lock space to hold object and record locks. The possible values are:
| 1 | Lock space used for UDB-managed commitment definitions. |
| 2 | Lock space used for externally managed commitment definitions with job scoped locks. |
| 3 | Lock space used for externally managed commitment definitions with lock space scoped locks. |
| -1 | The lock space type cannot be determined. |
Lock wait time. The maximum anount of time, in seconds, that a thread is allowed to wait for an object or record lock that is to be held by the lock space. The following special values may be returned:
| 0 | The lock wait time for the lock space is ignored. The lock wait time specified on the lock request is used. |
| -1 | The lock wait is indefinite. |
| -2 | The lock request will return immediately if the lock cannot be obtained. |
Maximum number of threads with lock space attached. The maximum number of threads to which the lock space can be attached concurrently. The following special value may be returned:
| -1 | There is no limit to the number of threads to which the lock space can be attached. |
Number of threads with lock space attached. The number of threads to which the lock space is currently attached.
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