Retrieve Job Record Locks (QDBRJBRL) 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 | Error code | I/O | Char(*) |
Optional Parameter Group:
| 6 | Format of job or thread identification information | Input | Char(8) |
| 7 | Lock filters | Input | Char(*) |
| 8 | Format of lock filters | Input | Char(8) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Job Record Locks (QDBRJBRL) API lets you generate a list of record locks that a specific job or thread is holding or for which it is waiting. Lock information is returned for local physical files only. The Retrieve Job Record Locks API places the list in the specified receiver variable.
Authorities and Locks
- Object Authority
- None
- Object Library Authority
- None
- File Lock
- None
- 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.
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 possible format names are:
RJBL0100 Record lock list. See RJBL0100 Format for details. JOBL0100 Record lock list. See JOBL0100 Format for details.
- 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.
If the Format of record identification information parameter is omitted, format JIDI0100 is assumed. See JIDI0100 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.
Optional Parameter Group
- Format of job or thread identification information
- INPUT; CHAR(8)
The format of the job or thread identification information. The possible format names are:
JIDI0100 This format is used to retrieve the locks that a job is holding or waiting to hold. See JIDI0100 Format for details. This is the default if this parameter is omitted. JIDF0100 This format is used to retrieve the locks that a job or threads are holding or waiting to hold. See JIDF0100 Format for details. JIDF0200 This format is used to retrieve the locks that a specific thread is holding or waiting to hold. See JIDF0200 Format for details.
- Lock filters
- INPUT;CHAR(*)
Filters used for the lock information that is returned. See Format of Lock Filters for further information. If this parameter is omitted, the returned lock information is not filtered.
- Format of lock filters
- INPUT; CHAR(8)
The format of the lock filters used on the returned data. The possible format name is:
RJFL0100 Lock filter format. See RJFL0100 Format for details. If this parameter is omitted, the returned lock information is not filtered.
Format of Receiver Information
The format of the information returned in the receiver variable.
RJBL0100 Format
The following information is returned for the RJBL0100 format. For detailed descriptions of the fields in the table, see RJBL0100 and JOBL0100 Format Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of record locks available |
| 4 | 4 | BINARY(4) | Number of record locks returned |
| 8 | 8 | BINARY(4) | Offset to list of record locks |
| 12 | C | 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) | Lock status |
| 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 |
| 64 | 40 | CHAR(8) | Thread identifier |
| 72 | 48 | UNSIGNED BINARY(4) | Thread handle |
| 76 | 4C | CHAR(20) | Lock space identifier |
| 96 | 60 | CHAR(1) | Lock scope |
| 97 | 61 | CHAR(3) | Reserved |
JOBL0100 Format
The following information is returned for the JOBL0100 format. For detailed descriptions of the fields in the table, see RJBL0100 and JOBL0100 Format Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of record locks available |
| 4 | 4 | BINARY(4) | Number of record locks 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 | UNSIGNED BINARY(4) | Relative record number |
| 34 | 22 | CHAR(1) | Lock status |
RJBL0100 and JOBL0100 Format Field Descriptions
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 may also 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. |
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. |
Lock scope. The scope of the lock. The scope may be job, thread scope, or lock space. The possible values are:
| 0 | Job scope. |
| 1 | Thread scope. |
| 2 | Lock space scope. |
Lock space identifier. This field will contain 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 identifier of the lock space for which the lock is being waited on.
Lock state. The state of the lock. The possible values are:
| 0 | Shared read. |
| 1 | Exclusive update. |
| 2 | Shared internal. |
Lock status. The status of the lock. The possible values are:
| 0 | The record lock is held by the given job or thread. |
| 1 | The job or thread given is waiting for the record lock. |
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.
Thread handle. This is a value which is used to address a particular thread holding a thread scope lock or the thread waiting for a lock. If the lock is a job scope lock, this is zero.
Thread identifier. The unique value that is used to identify the thread holding a thread scope lock or the thread waiting for a lock. If the lock is a job scope lock, this is zero.
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.
JIDI0100 Format
The following information is to be specified for the JIDI0100 format. For detailed descriptions of the fields in the table, see JIDI0100 Format Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Job name |
| 10 | A | CHAR(10) | User name |
| 20 | 14 | CHAR(6) | Job number |
JIDI0100 Format Field Descriptions
Job name. A specific job name.
Job number. A specific job number.
User name. A specific user profile name.
JIDF0100 Format
The following information is to be specified for the JIDF0100 format. For detailed descriptions of the fields in the table, see JIDF0100 Format Field Descriptions.
| 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 |
JIDF0100 Format 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 which is used to uniquely identify a thread within a job.
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(s).
User name. A specific user profile name, or blanks when the job name specified is a special value.
JIDF0200 Format
The following information is to be specified for the JIDF0200 format. For detailed descriptions of the fields in the table, see JIDF0200 Format Field Descriptions.
| 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 | UNSIGNED BINARY(4) | Thread handle |
| 48 | 30 | CHAR(8) | Thread identifier |
JIDF0200 Format 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. A value which is used to address a particular thread within a job. A valid thread handle must be specified. The thread handle is returned on several other interfaces.Thread identifier. A value which is used to uniquely identify a thread within a job.
User name. A specific user profile name, or blanks when the job name specified is a special value.
Format of Lock Filters
The format of the lock filters used on the returned lock information.
RJFL0100 Format
The following information is to be specified for the RJFL0100 format. For detailed descriptions of the fields in the table, see RJFL100 Format Field Descriptions.
| 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(10) | Filter file name |
| 26 | 1A | CHAR(10) | Filter file member name |
| 36 | 24 | CHAR(10) | Filter file library name |
| 46 | 2E | CHAR(10) | Filter file library ASP name |
RJFL0100 Format 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 value |
| 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 value
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 scope value |
| 1 | Return only the shared locks |
| 2 | Return only the exclusive locks |
Default: Do not filter on lock scope value
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 scope value |
| 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 scope value
Filter file 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 file 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 file member name: This is the member 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 file name: This is the file 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 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. |
| 56 | All filters are required. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0941 E | Job &3/&2/&1 no longer in system. |
| CPF18BF E | Thread &1 not found. |
| CPF1321 E | Job &1 user &2 job number &3 not found. |
| CPF136A E | Job &3/&2/&1 not active. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is 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. |
| 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. |
| CPF3CF1 E | Error code parameter not valid. |
API introduced: V5R1