Retrieve Lock Space Locks (QTRXRLSL) 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 Locks (QTRXRLSL) API generates a list of objects that have been locked or that have lower level locks held by the specified lock space. Locks that are being waited for on behalf of a lock space are not returned. Use the Retrieve Job Locks (QWCRJBLK) or Retrieve Lock Information (QWCRLCKI) API to retrieve locks that are being waited for by a thread on behalf of a lock space.
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 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. For example, this may mean that the number of locked object entries available in the receiver variable do not match the value in the number of locked object entries returned.
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 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 receiver information
- INPUT; CHAR(8)
The format of the information returned in the receiver variable. The format name is:
RLSL0100 The object and member lock format. See RLSL0100 Format for details on the list of objects and members that this lock space has locked.
- 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 format name is:
RLSF0100 Lock filter format. See RLSF0100 Format for details on the filters contained in this format.
- 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.
RLSL0100 Format
This format is used to return objects and members that are locked. For detailed descriptions of the fields in the table, see Field Descriptions for RLSL0100 Format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Number of locked object entries available |
| 16 | 10 | BINARY(4) | Offset to list of locked objects |
| 12 | C | BINARY(4) | Number of locked object entries returned |
| 20 | 14 | BINARY(4) | Length of locked object entry |
Each locked object returned will have the following structure.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Type of entity |
| 4 | 4 | CHAR(30) | Extended object name |
| 34 | 22 | CHAR(10) | Object library name |
| 44 | 2C | CHAR(10) | Object ASP name |
| 54 | 36 | CHAR(10) | Object library ASP name |
| 64 | 40 | BINARY(4) | Object ASP number |
| 68 | 44 | BINARY(4) | Object library ASP number |
| 72 | 48 | CHAR(10) | Object type |
| 82 | 52 | CHAR(10) | Extended object attributes |
| 92 | 5C | CHAR(10) | Member name |
| 102 | 66 | CHAR(1) | Member lock type |
| 103 | 67 | CHAR(3) | Reserved |
| 106 | 6A | CHAR(10) | Lock state |
| 116 | 74 | BINARY(4) | Lock status |
| 120 | 78 | BINARY(4) | Member locks |
| 124 | 7C | BINARY(4) | Lock count |
| 128 | 80 | CHAR(64) | Object lock handle |
| 192 | C0 | CHAR(64) | Lock request handle |
Field Descriptions for RLSL0100 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.
Extended object attributes. The extended attributes of an object. Extended attributes further describe the object. For example, an object type of *PGM may have a value of RPG (RPG program) or CLP (CL program). This field will be blank if there is no extended attribute associated with the object type.
Extended object name. The name of the object that is locked. If the lock is on a database member, the object name is the name of the file that owns the member to which the lock applies. If the member lock type is member or access path, the file that owns the member may be either a physical file or a logical file. If the member lock type is data, the file that owns the member is a physical file. The following special value also may be returned:
| *N | The name of the object cannot be determined. |
Length of locked object entry. The length of each locked object entry.
Lock count. The number of identical locks on this entity.
Lock request handle. A handle to lock request information. Using the Retrieve Lock Request Information (QWCRLRQI) API and passing in this handle, you can retrieve additional information about the program that requested this lock. A value of hexadecimal zero is returned when additional information cannot be retrieved. This value is a temporary value that can expire. See Retrieve Lock Request Information (QWCRLRQI) API for additional information.
Lock state. The lock condition for the lock request. Lower level locks are returned and can occur when a member of a file is locked, but the file itself is not locked. Possible other values are:
| Blank | The object is not locked, but there are locks on lower level objects. |
| *SHRRD | Lock shared for read. |
| *SHRUPD | Lock shared for update. |
| *SHRNUP | Lock shared, no update. |
| *EXCLRD | Lock exclusive, read allowed. |
| *EXCL | Lock exclusive, no read allowed. |
Lock status. The status of the lock request. Possible values are:
| 0 | The object is not locked, but there are locks on lower level objects. |
| 1 | The lock on this object currently is held by the lock space. |
Member locks. The number of member locks for a database file. If the object is not a database file, 0 is returned.
Member lock type. If the lock is on a member, this field indicates the type of member lock; otherwise, it is blank. Possible values are:
| Blank | The object type is not a member. |
| 0 | The lock is a member lock. |
| 1 | The lock is a data lock. |
| 2 | The lock is an access path lock. |
Member name. The name of the member that has a lock held or waiting on it. If the type of entity is not a member object, this field is blank. The following special value also may be returned:
| *N | The name of the object cannot be determined. |
Number of locked object entries available. The number of locked object entries that are held by this lock space.
Number of locked object entries returned. The number of locked object entries that are returned.
Object ASP name. The name of the auxiliary sptorage pool (ASP) that contains the object that is locked. The following special values also may be returned:
| *SYSBAS | The object is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP device cannot be determined. |
Object ASP number. The numeric identifier of the ASP containing the locked object. The following values may be returned:
| 1 | The object is located in the system ASP. |
| 2-32 | The object is located in a basic user ASP. |
| 33-255 | The object is located in an independent ASP. |
| -1 | The ASP number cannot be determined. |
Object library ASP name. The name of the ASP containing the library of the locked object. The following specials value also may be returned:
| *SYSBAS | The object's library is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP device cannot be determined. |
Object library ASP number. The numeric identifier of the ASP containing the library of the locked object. 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. |
Object library name. The name of the library containing the locked object. This field will be blank if the type of entity is an internal system object or is an internal system object space location. The following special value also may be returned:
| *N | The name of the library cannot be determined. |
Object lock handle. An identifier that can be input to Retrieve Lock Information (QWCRLCKI) API to find additional information about other holders of locks on this object. A value of hexadecimal zero is returned when additional information cannot be retrieved. The object lock handle is a temporary value that can expire. See the QWCRLCKI API for additional information.
Object type. The object type. For a list of all the available external IBM i object types, see the Control language topic collection.
Offset to list of locked objects. The offset in bytes from the beginning of the receiver variable to the first entry.
Reserved. An unused field.
Type of entity. A value that identifies the type of entity for which the lock information is returned. The following values may be returned:
| 1 | IBM i external object |
| 2 | Member object |
| 3 | Internal system object |
Format of Lock Filters
The format of the lock filters used on the returned lock information.
RLSF0100 Format
The following information is to be specified for the RLSF0100 format. For detailed descriptions of the fields in the table, see Field Descriptions for RLSF0100 Format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Filter size |
| 4 | 4 | BINARY(4) | Filter lock state |
| 8 | 8 | CHAR(1) | Include IBM i external objects flag |
| 9 | 9 | CHAR(1) | Include member objects flag |
| 10 | A | CHAR(1) | Include internal system objects flag |
| 11 | B | CHAR(1) | Include lock space objects flag |
| 12 | C | CHAR(1) | Include unknown entities flag |
| 13 | D | CHAR(1) | Reserved |
| 14 | E | CHAR(10) | Filter object name |
| 24 | 18 | CHAR(10) | Filter object library name |
| 34 | 22 | CHAR(10) | Filter object library ASP name |
Field Descriptions for RLSF0100 Format
Filter lock state. Filters information that is returned so that it only contains 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 object 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 object library name. This is 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 object name. Only locks on the specified object are returned. In the case of database files, members of the file also may be returned. 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. |
| 44 | All filters will be required. |
Include internal system objects flag. A value of 1 in this field allows internal system object locks to be returned. A value of 0 causes these values to be excluded from the return data. The default is to exclude internal system objects.
Include lock space objects flag. A value of 1 in this field allows lock space objects locks to be returned. A value of 0 causes these values to be excluded from the return data. The default is to include lock space objects.
Include member objects flag. A value of 1 in this field allows member objects locks to be returned. A value of 0 causes these values to be excluded from the return data. The default is to include member objects.
Include IBM i external objects flag. A value of 1 in this field allows IBM i external object locks to be returned. A value of 0 causes these objects to be excluded from the return data. The default is to include IBM i external objects.
Include unknown types flag. A value of 1 in this field allows locks that are of an unknown entity type to be returned. A value of 0 causes these values to be excluded from the return data. The default is to exclude unknown types.
Reserved. An unused field.
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