Retrieve Lock Information (QWCRLCKI) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Object identification | Input | Char(*) |
| 5 | Object identification format | Input | Char(8) |
| 6 | Number of key fields to be returned | Input | Binary(4) |
| 7 | Key of fields to be returned | Input | Array(*) of Binary(4) |
| 8 | Filters | Input | Char(*) |
| 9 | Filter format | Input | Char(8) |
| 10 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Lock Information (QWCRLCKI) API generates a list of information about lock holders of the item specified.
Authorities and Locks
- Object Library Authority
- *EXECUTE
- Object Library ASP Device Authority
- *EXECUTE
Note: If the user does not have *EXECUTE authority to the object's library and *EXECUTE authority to the object library's ASP device, the user must have *JOBCTL authority or GUI thread control 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 lock information entries returned in the receiver variable doesn't match the value in the number of lock information entries available.
- 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 name
- INPUT; CHAR(8)
The name of the format used to retrieve lock information. You can specify this format:
LCKI0100 Lock Information Format. See LCKI0100 Format for more information.
- Object identification
- INPUT; CHAR(*)
The information that is used to identify the entity that may be locked. See Format of Object Identification for more information.
- Object identification format
- INPUT; CHAR(8)
The format of the entity identification information. Possible format names are:
LOBJ0100 Object name. See LOBJ0100 Format for more information on this format. LOBJ0200 Object lock handle. See LOBJ0200 Format for more information on this format.
- Number of key fields to be returned
- INPUT; BINARY(4)
The number of key fields to be returned in the LCKI0100 format. If the lock holder type returned is a lock space then the values returned in the key fields will be blank or zero.
- Key of fields to be returned.
- INPUT; ARRAY(*) of BINARY(4)
The list of fields returned in the LCKI0100 format. For a list of valid fields, see Valid Keys.
- Filters
- INPUT;CHAR(*)
Filters used for the lock information that is returned. See the Filter Format for further information.
- Filter format
- INPUT; CHAR(8)
The format of the lock filter used on the returned data. The possible format name is:
LKFL0100 See LKFL0100 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 Object Identification
The formats for the object identification are specified.
LOBJ0100 Format
An external object is specified in this format. See the field descriptions for restrictions that may exist.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Object identification size |
| 4 | 4 | CHAR(10) | Object name specified |
| 14 | E | CHAR(10) | Object library name specified |
| 24 | 18 | CHAR(10) | Object library ASP name specified |
| 34 | 22 | CHAR(10) | Object type specified |
| 44 | 2C | CHAR(10) | Member name |
| 54 | 36 | CHAR(2) | Reserved |
| 56 | 38 | BINARY(4) | Record lock indicator |
| 60 | 3C | UNSIGNED BINARY(4) | Relative record number |
Field Descriptions
Member name. Lock information is retrieved on the specified member of a database file. This is valid only when a database file has been specified for object parameters. For other than database files, use *NONE. Special values used are:
| *NONE | No member locks are retrieved, but file level locks are retrieved. If the qualified object name is not a database file, use this value. |
Object identification size. The amount of data provided for the LOBJ0100 format. This field must be set to 64.
Object library ASP name specified. The name of the auxiliary storage pool (ASP) device that contains the object's library. This parameter must be * if the library portion of the qualified object name is *CURLIB or *LIBL. Special values used are:
| * | The current thread's library name space will be searched. |
| *SYSBAS | The system ASP and defined basic user ASPs will be searched. |
Object library name specified. The name of the library where the object is located. You can use these special values for the library name:
| *CURLIB | The current library is used to locate the object. If there is no current library, QGPL (general purpose library) is used. |
| *LIBL | The library list is used to locate the object. |
Object name specified. The name of the external IBM® i object whose lock information entries are to be placed in the list.
Object type specified. The type of IBM i object. For a list of all the available external IBM i object types, see the Control language topic collection.
Record lock indicator. The indicator that controls the retrieval of record locks that may exist if the object specified is a file and member. If the object specified is not a database file and member or the special value of *ALL is specified for member, then the value 0 must be used for this field. One of the following values are required for this field.
| 0 | No record lock information is retrieved. |
| 1 | The record lock information in the specified file and member will be returned. |
Relative record number. The record number in the specified database file and member for which lock information is to be returned. If the object specified is not a database file and member, the value 0 must be used for this field. The following special value is allowed:
| 0 | Record lock information for all records in the member should be returned. |
Reserved. This field must be set to hexadecimal zeros.
LOBJ0200 Format
This format is used to find locks where a handle was passed that has been returned in a previous lock call to the Retrieve Job Locks (QWCRJBLK) API. This call must have been made in the same thread for the handle to be valid. The following fields are used if LOBJ0200 input format is specified.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Object handle size |
| 4 | 4 | CHAR(64) | Object lock handle |
Field Descriptions
Object lock handle. A value that identifies the object that is stored from a previous API call. 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.
Object identification size. The amount of data provided for the LOBJ0200 format. This field must be set to 68.
Filter Format
The format of the lock filter used on the returned lock information.
LKFL0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Filter size |
| 4 | 4 | BINARY(4) | Filter lock state |
| 8 | 8 | BINARY(4) | Filter lock scope |
| 12 | C | BINARY(4) | Filter lock status |
| 16 | 10 | CHAR(1) | Filter lock holder type |
| 17 | 11 | CHAR(1) | Filter member lock type |
Field Descriptions
Filter lock holder type. Filters information that is returned so it contains only information about a type of lock holder.
| 0 | Do not filter on holder type. |
| 1 | Return only locks with a holder type of job or thread. |
| 2 | Return only locks with a holder type of lock space. |
| Default | Do not filter on holder type. |
Filter lock scope. Filters information that is returned so it contains only information about locks that have a certain lock scope.
| 0 | Do not filter on lock scope. |
| 1 | Return only the job scope locks. |
| 2 | Return only the thread scope locks. |
| 3 | Return only the lock space scope locks. |
| Default | Do not filter on lock scope. |
Filter lock state. Filters information that is returned so it contains only information about locks that have a certain lock state.
| 0 | Do not filter on lock state. |
| 1 | Return only the shared locks. |
| 2 | Return only the exclusive locks. |
| Default | Do not filter on lock state. |
Filter lock status. Filters information that is returned so it contains only information about locks that have a certain lock status.
| 0 | Do not filter on lock status. |
| 1 | Return only locks with a status of held. |
| 2 | Return only locks with a status of waiting. |
| 3 | Return only locks with a status of requested. |
| Default | Do not filter on lock status. |
Filter member lock type. Filters information that is returned so it contains only information about locks that have a certain member lock type.
| 0 | Do not filter on member lock type. |
| 1 | Return only locks with member lock type of member. |
| 2 | Return only locks with member lock type of data. |
| 3 | Return only locks with member lock type of access path. |
| Default | Do not filter on member lock type. |
Filter size. The size of the filter information passed. Valid values are:
| 4 | No filtering will be performed. |
| 18 | All filters will be required. |
Lock Information Format
The formats for the lock information.
LCKI0100 Format
Header Section
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Type of entity |
| 12 | C | CHAR(30) | Extended object name returned |
| 42 | 2A | CHAR(10) | Object library name returned |
| 52 | 34 | CHAR(10) | Object ASP name returned |
| 62 | 3E | CHAR(10) | Object library ASP name returned |
| 72 | 48 | BINARY(4) | Object ASP number returned |
| 76 | 4C | BINARY(4) | Object library ASP number returned |
| 80 | 50 | CHAR(10) | Object type returned |
| 90 | 5A | CHAR(10) | Extended object attribute returned |
| 100 | 64 | BINARY(4) | Number of lock information entries available |
| 104 | 68 | BINARY(4) | Offset to list of lock information entries |
| 108 | 6C | BINARY(4) | Number of lock information entries returned |
| 112 | 70 | BINARY(4) | Length of lock information entry |
Lock Information Entry Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields repeat, in the order listed. | CHAR(10) | Lock state | |
| CHAR(2) | Reserved | ||
| BINARY(4) | Lock status | ||
| CHAR(1) | Lock scope | ||
| CHAR(3) | Reserved | ||
| CHAR(20) | Lock space identifier | ||
| CHAR(64) | Lock request handle | ||
| BINARY(4) | Lock count | ||
| CHAR(10) | Member name returned | ||
| CHAR(1) | Member lock type | ||
| CHAR(1) | Reserved | ||
| BINARY(4) | Relative record number | ||
| BINARY(4) | Displacement from lock information to holder identification | ||
| BINARY(4) | Displacement from lock information to key information | ||
| BINARY(4) | Number of keys returned | ||
| BINARY(4) | Holder type | ||
| CHAR(*) | Holder identification | ||
Key Information Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| These fields repeat, in the order listed, for each key selected. | BINARY(4) | Length of field information returned | |
| BINARY(4) | Key field | ||
| CHAR(1) | Type of data | ||
| CHAR(3) | Reserved | ||
| BINARY(4) | Length of data | ||
| CHAR(*) | Data | ||
| CHAR(*) | Reserved | ||
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 lock information entries are returned.
Data. The data returned for the key field.
Displacement from lock information to holder identification. The byte displacement from the start of the current lock information entry to the holder identification.
Displacement from lock information to key information. The byte displacement from the start of the current lock information entry to the key information requested.
Extended object attribute returned. The extended attribute of the object for which the list of locks is returned, such as a program or a file type. Extended attributes further describe the object. For example, an object type of *FILE may have an extended object attribute of PHY (physical file), LGL (logical file), DSP (display file), SAV (save file), and so forth.
Extended object name returned. The name of the object for which the lock information entries are placed in the list. This field will be blank if the name is for an internal system object or an internal system object space location, and the user does not have *JOBCTL special authority.
Holder identification. This field contains information about the lock holder. This can be either a qualified job name as described in Job Format specifier or a lock space identifier as described in Lock Space Format specifier.
Holder type. This value is set to indicate what type of holder is holding or is waiting to hold a lock on the specified object.
| 0 | The lock holder is a job or thread. See the Job Format for more information. |
| 1 | The lock holder is a lock space. See the Lock Space Format for more information. |
Key field. The field returned. See Valid Keys for the list of valid keys.
Length of data. The length of the data returned for the field.
Length of field information returned. The total length of information returned for this field. This value is used to increment to the next field in the list.
Length of lock information entry. The length of a lock information entry. This value is used to increment to the next entry.
Lock count. The number of identical locks.
Lock request handle. This value is used to identify a handle to lock request process 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.
Lock scope. The scope of the lock. The possible values are:
| 0 | Job scope |
| 1 | Thread scope |
| 2 | Lock space scope |
Lock space identifier. This field contains a value only when the lock scope value is lock space scope and the lock is being waited on by a thread. This field will then contain the lock space ID value for which the lock is being waited on.
Lock state. The lock condition for the lock request. The possible values are:
| *SHRRD | Lock shared for read. |
| *SHRUPD | Lock shared for update. |
| *SHRNUP | Lock shared no update. |
| *EXCLRD | Lock exclusive allow read. |
| *EXCL | Lock exclusive no read. |
| *RECRD | Lock is a record shared read lock |
| *RECUP | Lock is a record exclusive update lock. |
| *RECINT | Lock is a record shared internal lock |
Lock status. The status of the lock. The lock may be a single request or part of a multiple lock request for which some other object specified in the request has been identified as unavailable. The possible values are:
| 1 | The lock is currently held by the job or thread. |
| 2 | The job or thread is waiting for the lock (synchronous). |
| 3 | The job or thread has a lock request outstanding for the object (asynchronous). |
Member lock type. If the lock is on a member then this field indicates the type of member lock, otherwise it will be blank. The possible values are:
| Blank | The object type is not a member |
| 1 | Lock on the member control block |
| 2 | Lock on the actual data within the member |
| 3 | Lock on the access path used to access a member's data |
Member name returned. The name of the member that lock information is being returned for. Blanks will be returned if the object is not a member of a database file.
Number of keys returned. The number of keys that were returned.
Number of lock information entries available. The number of lock information entries that were found.
Number of lock information entries returned. The number of lock information entries that are returned.
Object ASP name returned. The name of the ASP in which the object is located. The following special values may also be returned:
| *SYSBAS | The object is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP cannot be determined. |
Object ASP number returned. 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 returned. The name of the ASP in which the object's library is located. The following special values may also be returned:
| *SYSBAS | The library is located in the system ASP or a basic user ASP. |
| *N | The name of the ASP cannot be determined. |
Object library ASP number returned. The numeric identifier of the ASP device containing the object's library. The following special values may also 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 returned. The name of the library that contains the object whose lock information entries are placed in the list.
Object type returned. The type of object for which locks are retrieved. For a list of all the available external IBM i object types, see External object types. For a list of all internal system object types, see Internal object types.
Offset to list of lock information entries. The offset in bytes from the beginning of the receiver variable to the first entry.
Relative record number. The relative record number for which record lock information is being returned. If this is not a record lock then this value will be zero.
Reserved. An unused field.
Type of data. The type of data returned.
| C | The data is returned in character format. |
| B | The data is returned in binary format. |
Type of entity. This is a value that will identify 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 | IBM i external object space location |
| 4 | Internal system object |
| 5 | Internal system object space location |
Valid Keys
The following table contains a list of valid keys.
See Field Descriptions in the Work Management API Attributes Descriptions for the descriptions of the valid key fields. All fields are scoped to the job unless specifically noted. See Considerations for Attribute Scope and Thread Safety for complete information.
Note: If the holder type is a lock space holder then character fields will contain blanks and the binary fields will be zero.
| Key | Type | Description |
|---|---|---|
| 101 | CHAR(4) | Active job status |
| 103 | CHAR(4) | Active job status for jobs ending |
| 502 | CHAR(1) | End status |
| 601 | CHAR(10) | Function name |
| 602 | CHAR(1) | Function type |
| 902 | CHAR(16) | Internal job identifier |
| 1014 | BINARY(4) | Job end reason |
| 1307 | CHAR(1) | Message reply |
| 2010 | CHAR(4) | Thread status |
Holder ID
This field contains an identifier for the job or lock space that is holding or waiting to hold a lock on the specified object or space location.
Job Format
For a job, the returned data in this field will be in this format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Holder identification size |
| 8 | 8 | CHAR(10) | Job name |
| 18 | 12 | CHAR(10) | User name |
| 28 | 1C | CHAR(6) | Job number |
| 34 | 22 | CHAR(8) | Thread identifier |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | UNSIGNED BINARY(4) | Thread handle |
Field Descriptions
Holder identification size. The size of the holder identification.
Job name. The simple job name of the job that issued the lock request. If the job name is MACHINE and the job user name entry is blank, the lock is held by an internal machine process.
Job number. The system assigned job number of the job that issued the lock request. This value will be blank if the job name is MACHINE and the user name entry is blank.
Thread handle. A value which addresses a particular thread within a job holding a thread scope lock or the thread waiting for a lock, otherwise this is zero. While the thread identifier uniquely identifies the thread within the job, the thread handle can improve performance when referencing the thread.
Thread identifier. A value which uniquely identifies a thread within a job holding a thread scope lock or the thread waiting for a lock, otherwise this is zero.
Reserved. This field will be blank.
User name. The user name under which the job that issued the lock request is started. If the job name is MACHINE and the lock is held by an internal machine process then this field will be blank.
Lock Space Format
For a lock space the returned data in this field will be in this format.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Holder identification size |
| 4 | 4 | CHAR(20) | Holder lock space identifier |
Field Descriptions
Holder identification size. The size of the holder identification.
Holder lock space identifier. The identifier of the lock space that holds a lock.
Reserved. A blank field.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0951 E | QSYS only valid library for object type &2. |
| CPF18C2 E | Value for handle has expired. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C31 E | Object type &1 is not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF2 E | Error(s) occurred while running API &1. |
| CPF9801 E | Object &1 type &3 not found in library &2. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R2