Retrieve Job Locks (QWCRJBLK) 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 | Job or thread identification information | Input | Char(*) |
| 5 | Format of job or thread identification information | Input | Char(8) |
| 6 | Error code | I/O | Char(*) |
Optional Parameter Group:
| 7 | Lock filters | Input | Char(*) |
| 8 | Format of lock filters | Input | Char(8) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Job Locks (QWCRJBLK) API generates a list of objects that have been locked or have lower level locks by the job or thread that is specified in the job or thread identification information input parameter.
The QSYS2.JOB_LOCK_INFO table function can be used as an alternative to this API. See JOB_LOCK_INFO table function for more information.
Authorities and Locks
- Job Authority
- The API must be called from within the job for which the information is being retrieved, or the caller of the API must be running under a user profile that is the same as the job user identity of the job for which the information is being retrieved. Otherwise, the caller of the API must be running under a user profile that has job control (*JOBCTL) special authority.
The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work management topic collection.
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 doesn't match the value in the number of locked object entries returned.
- 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 possible format names are:
JBLK0100 Object level lock format. See JBLK0100 Format for details on the list of objects that this job or thread has locked.
JBLK0200 All object lock format. See JBLK0200 Format for details on the list of objects and members that this job or thread has locked.
- Job or thread identification information
- INPUT; CHAR(*)
The information that is used to identify the job or thread for which the job lock information is to be returned. See Format of Job or Thread Identification Information for details.
- Format of job or thread identification information
- INPUT; CHAR(8)
-
The format of the job or thread identification information. The possible format names are:
JIDF0100 This format is used to retrieve the locks that a job and threads are holding or waiting to hold. See JIDF0100 Format for details on the job or thread identification information.
JIDF0200 This format is used to retrieve the locks that a specific thread is holding or waiting to hold. See JIDF0200 Format for details on the job or thread identification information. - Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group
- Lock filters
- INPUT;CHAR(*)
Filters used for the lock information that is returned. See the Lock Filter Format 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:
JBFL0100 Lock filter format. See JBFL0100 Format for details on the filters contained in this format.
JBLK0100 Format
This format is used to return only IBM® i external objects that are locked.
| 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 |
| 12 | C | BINARY(4) | Offset to list of locked objects |
| 16 | 10 | BINARY(4) | Number of locked object entries returned |
| 20 | 14 | BINARY(4) | Length of locked object entry |
| 24 | 18 | * | Reserved |
| These fields repeat, in the order listed. | CHAR(10) | Object name | |
| CHAR(10) | Object library name | ||
| CHAR(10) | Object type | ||
| CHAR(10) | Extended object attributes | ||
| CHAR(10) | Lock state | ||
| CHAR(2) | Reserved | ||
| BINARY(4) | Lock status | ||
| BINARY(4) | Member locks | ||
| BINARY(4) | Lock count | ||
| CHAR(1) | Lock scope | ||
| CHAR(3) | Reserved | ||
| CHAR(8) | Thread identifier | ||
| BINARY(4) UNSIGNED | Thread handle | ||
| CHAR(20) | Lock space identifier | ||
| CHAR(10) | Object ASP name | ||
| CHAR(10) | Object library ASP name | ||
| BINARY(4) | Object ASP number | ||
| BINARY(4) | Object library ASP number | ||
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 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.
Length of locked object entry. The length of each locked object entry.
Lock count. The number of identical locks on this entity.
Lock scope. The scope of the lock. The lock may be a job scope lock, a thread scope lock, or a lock space scope lock. Lower level locks are returned and can occur when a member of a file is locked, but the file itself is not locked. The possible values are:
| Blank | The object is not locked, but there are locks on lower level objects. |
| 0 | Job scope. |
| 1 | Thread scope. |
| 2 | Lock space scope. |
Lock space identifier. When the lock scope field indicates a lock space scope lock, this field contains the identifier of the lock space for which the lock is being waited on. Otherwise, this field is blank.
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. The possible 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. Lower level locks are returned and can occur when a member of a file is locked but the file itself is not locked. 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 job or thread. |
| 2 | The job or thread is waiting to get the lock on this object (synchronous). |
| 3 | The job or thread has a lock request outstanding for this object (asynchronous). 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. |
Member locks. The number of member locks for a database file. If the object is not a database file, 0 is returned.
Number of locked object entries available. The number of locked object entries that are held by this job and specified threads.
Number of locked object entries returned. The number of locked object entries that are returned.
Object ASP name. The name of the auxiliary storage pool (ASP) containing 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.
The following special value also may be returned:
| *N | The name of the library cannot be determined. |
Object name. The name of the object that is locked.
The following special value also may be returned:
| *N | The name of the object cannot be determined. |
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.
Thread handle. A value that 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 that uniquely identifies a thread within a job holding a thread scope lock or the thread waiting for a lock; otherwise, hexadecimal zeros are returned.
JBLK0200 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 |
| 12 | C | BINARY(4) | Offset to list of locked objects |
| 16 | 10 | BINARY(4) | Number of locked object entries returned |
| 20 | 14 | BINARY(4) | Length of locked object entry |
| 24 | 18 | * | Reserved |
| These fields repeat, in the order listed. | BINARY(4) | Type of entity | |
| CHAR(30) | Extended object name | ||
| CHAR(10) | Object library name | ||
| CHAR(10) | Object ASP name | ||
| CHAR(10) | Object library ASP name | ||
| BINARY(4) | Object ASP number | ||
| BINARY(4) | Object library ASP number | ||
| CHAR(10) | Object type | ||
| CHAR(10) | Extended object attributes | ||
| CHAR(10) | Member name | ||
| CHAR(1) | Member lock type | ||
| CHAR(3) | Reserved | ||
| CHAR(10) | Lock state | ||
| BINARY(4) | Lock status | ||
| BINARY(4) | Member locks | ||
| BINARY(4) | Lock count | ||
| CHAR(1) | Lock scope | ||
| CHAR(3) | Reserved | ||
| BINARY(8) UNSIGNED | Space location lock offset | ||
| CHAR(8) | Thread identifier | ||
| BINARY(4) UNSIGNED | Thread handle | ||
| CHAR(20) | Lock space identifier | ||
| CHAR(64) | Object lock handle | ||
| CHAR(64) | Lock request handle | ||
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 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. 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. If the lock is on a database member then the object name will be the name of the file that owns the member. If the member lock type is member or access path, then the file that owns the member may be either a physical file or a logical file. If the member lock type is data, then the file that owns the member will be a physical file. If the lock is on a lock space then the name will be the lock space id for that lock space.
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 the QWCRLRQI API for additional information.
Lock scope. The scope of the lock. The lock may be a job scope lock, a thread scope lock, or a lock space scope lock. Lower level locks are returned and can occur when a member of a file is locked but the file itself is not locked. The possible values are:
| Blank | The object is not locked but there are locks on lower level objects. |
| 0 | Job scope. |
| 1 | Thread scope. |
| 2 | Lock space scope. |
Lock space identifier. When the lock scope field indicates a lock space scope lock, this field will contain the identifier of the lock space for which the lock is being waited on. Otherwise, this field is blank.
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 job or thread. |
| 2 | The job or thread is waiting to get the lock on this object (synchronous). |
| 3 | The job or thread has a lock request outstanding for this object (asynchronous). 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. |
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 then this field indicates the type of member lock, otherwise it will be 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 then this field is blank. The following special value also can 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 job and specified threads.
Number of locked object entries returned. The number of locked object entries that are returned.
Object ASP name. The name of the Auxiliary Storage 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. Hexadecimal zeros are 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 External object types. For a list of all internal system object types, see Internal object types. Note that if the lock is on a database member the object type will be *FILE.
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.
Space location lock offset. A value in bytes to the location in the space that is locked. For objects that are not space location locks this value will be zero.
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, hexadecimal zeros are returned.
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 | Internal system object |
| 4 | IBM i external object space location |
| 5 | Internal system object space location |
| 6 | Lock space object |
| 999 | Unknown type |
Lock Filter Format
The format of the lock filter used on the returned lock information.
JBFL0100 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) | Include IBM i external objects flag |
| 17 | 11 | CHAR(1) | Include member objects flag |
| 18 | 12 | CHAR(1) | Include internal system objects flag |
| 19 | 13 | CHAR(1) | Include IBM i external object space locations flag |
| 20 | 14 | CHAR(1) | Include internal system object space locations flag |
| 21 | 15 | CHAR(1) | Include lock space objects flag |
| 22 | 16 | CHAR(1) | Include unknown entities flag |
| 23 | 17 | CHAR(10) | Filter object name |
| 33 | 21 | CHAR(10) | Filter object library name |
| 43 | 2B | CHAR(10) | Filter object library ASP name |
Field Descriptions
Filter lock scope: This value is used to filter information that is returned so that 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: This value is used to filter information that is returned so that 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: This value is used to filter information that is returned so that 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 object library ASP name: The name of the library's Auxiliary Storage Pool (ASP) to be filtered on. Special value of *SYSBAS can be specified. A blank field will cause no filtering to be done on this field. The default is not to filter on this field.
Filter object library name: This is the library name to be filtered on. A blank field will cause no filtering to be done on this field. The default is not to filter on this field.
Filter object name: Only locks on the specified object will be returned. In the case of database files, locks on members of the file may also be returned. A blank field will cause no filtering to be done on this field. The default is not to 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. |
| 53 | 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 will cause these values to be excluded from the return data. Note this field is only valid for the JBLK0200 format. The default is to exclude internal system objects.
Include internal system object space locations flag: A value of 1 in this field allows internal system object space location locks to be returned A value of 0 will cause these values to be excluded from the return data. Note this field is only valid for the JBLK0200 format. The default is to exclude internal system object space locations.
Include lock space objects flag: A value of 1 in this field will allow lock space objects locks to be returned. A value of 0 will cause these values to be excluded from the return data. Note this field is only valid for the JBLK0200 format. The default is to include lock space objects.
Include member objects flag: A value of 1 in this field will allow member objects locks to be returned. A value of 0 will cause these values to be excluded from the return data. Note this field is only valid for the JBLK0200 format. The default is to include member objects.
Include IBM i external objects flag: A value of 1 in this field will allow IBM i external object locks to be returned. A value of 0 will cause these objects to be excluded from the return data. Note this field is only valid for the JBLK0200 format. The default is to include IBM i external objects.
Include IBM i external object space locations flag: A value of 1 in this field will allow IBM i external space locations locks to be returned. A value of 0 will cause these values to be excluded from the return data. Note this field is only valid for the JBLK0200 format. The default is exclude IBM i external object space locations.
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. This field is valid for the JBLK0200 format only. The default is exclude unknown types.
Format of Job or Thread Identification Information
The format of the information needed to identify the job or thread whose locked object information is returned.
JIDF0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(16) | Internal job identifier |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | BINARY(4) | Thread indicator |
| 48 | 30 | CHAR(8) | Thread identifier |
Field Descriptions
Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with the job name.
Job name. A specific job name or one of the following special values:
| * | The job in which this program is running. The job
number and user name must contain blanks. |
| *INT | The internal job identifier locates the job. The job number and user name must contain blanks. |
Job number. A specific job number, or blanks when the job name specified is a special value.
Reserved. An unused field. This field must contain hexadecimal zeros.
Thread identifier. A value that uniquely identifies a thread within a job. A valid thread identifier must be specified.
Thread indicator. The value that is used to specify the thread within the job for which information is to be retrieved. The following values are supported:
| 0 | Information should be retrieved for the thread specified in the thread identifier field. |
| 1 | Information should be retrieved for the thread in which this program is running currently. |
| 2 | Information should be retrieved for the initial thread of the identified job. |
| 3 | Information should be retrieved for the job and its associated threads. |
Note: For all supported values, the combination of the internal job identifier, job name, job number, and user name fields must identify the job containing the thread or threads.
User name. A specific user profile name, or blanks when the job name specified is a special value.
JIDF0200 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(16) | Internal job identifier |
| 42 | 2A | CHAR(2) | Reserved |
| 44 | 2C | BINARY(4), UNSIGNED | Thread handle |
| 48 | 30 | CHAR(8) | Thread identifier |
Field Descriptions
Internal job identifier. The internal identifier for the job. The List Job (QUSLJOB) API returns this identifier. If you do not specify *INT for the job name parameter, this parameter must contain blanks. With this parameter, the system can locate the job more quickly than with a job name.
Job name. A specific job name or one of the following special values:
| * | The job in which this program is running. The job number and user name must contain blanks. |
| *INT | The internal job identifier locates the job. The job number and user name must contain blanks. |
Job number. A specific job number, or blanks when the job name specified is a special value.
Reserved. An unused field. This field must contain hexadecimal zeros.
Thread handle. An unused field on this API. This field must contain hex zeros.Thread identifier. A value that uniquely identifies a thread within a job. A valid thread identifier must be specified.
User name. A specific user profile name, or blanks when the job name specified is a special value.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF136A E | Job &3/&2/&1 not active. |
| CPF18BF E | Thread &1 not found. |
| CPF24B4 E | Severe error while addressing parameter list. |
| 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. |
| 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. |
| CPF3C51 E | Internal job identifier not valid. |
| CPF3C52 E | Internal job identifier no longer valid. |
| CPF3C53 E | Job &3/&2/&1 not found. |
| CPF3C55 E | Job &3/&2/&1 does not exist. |
| CPF3C57 E | Not authorized to retrieve job information. |
| CPF3C58 E | Job name specified is not valid. |
| CPF3C59 E | Internal identifier is not blanks and job name is not *INT. |
| CPF3C90 E | Literal value cannot be changed. |
API introduced: V5R1