Retrieve Record Locks (QDBRRCDL) 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 | Record identification information | Input | Char(*) |
| 5 | Member name | Input | Char(10) |
| 6 | Relative record number | Input | Unsigned binary(4) |
| 7 | Error code | I/O | Char(*) |
Optional Parameter Group:
| 8 | Format of record identification information | Input | Char(8) |
| 9 | Lock filters | Input | Char(*) |
| 10 | Format of lock filters | Input | Char(8) |
Default Public Authority: *USE
Threadsafe: No
The Retrieve Record Locks (QDBRRCDL) API lets you generate a list of jobs, threads and lock spaces that are either waiting for or holding locks on one or more records. The Retrieve Record Locks API places the list in the specified receiver variable. Lock information is returned for records in local physical files only and file overrides are not processed.
Authorities and Locks
- Object Authority
- None
- Object Library Authority
- *EXECUTE
- Object Library ASP Device Authority
- *EXECUTE
- File Lock
- *SHRRD
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.
Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is to receive the list of record locks. The size (in bytes) 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:
RRCD0100 Job record lock list. See RRCD0100 Format for details. RRCD0200 Lock holder record lock list. See RRCD0200 Format for details.
- Record identification information
- INPUT; CHAR(*)
The information that is to be used to identify the record or records for which locks are to be retrieved. See Format of Record Identification Information for details.
If the Format of record identification information parameter is omitted, format RRRC0100 is assumed. See RRRC0100 Format for details.
- Member name
- INPUT; CHAR(10)
The name of the member in the specified file that is to be checked for record locks. This value must be blanks if RRRC0200 is specified for the format of record identification information parameter, and in that case the member value must be specified as part of the record identification information parameter. The following special value is allowed:
*FIRST The first member of the specified file is used.
- Relative record number
- INPUT; UNSIGNED BINARY(4)
The record number in the specified file and member for which lock information is to returned. This value must be 0 if RRRC0200 is specified for the format of record identification information parameter, and in that case the relative record number value must be specified as part of the record identification information parameter. The following special value is allowed:
0 Record lock information for all records in the member should 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.
Optional Parameter Group
- Format of record identification information
- INPUT; CHAR(8)
The format of the record identification information. The possible format names are:
RRRC0100 This format is used to identify the file and library for which locks are to be retrieved. See RRRC0100 Format for details. This is the default if this parameter is omitted. RRRC0200 This format is used to identify the records for which locks are to be retrieved. See RRRC0200 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:
RRFL0100 Lock filter format. See RRFL0100 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.
RRCD0100 Format
The following information is returned for RRCD0100 format. When this format is used, only job and thread scope locks are returned. Lock space scope locks are not returned. Thread scope locks for all of the job's threads are returned. For detailed descriptions of the fields in the table, see RRCD0100 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) | Job name |
| 10 | A | CHAR(10) | Job user name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(1) | Lock status |
| 27 | 1B | CHAR(1) | Lock state |
| 28 | 1C | UNSIGNED BINARY(4) | Relative record number |
| 32 | 20 | CHAR(8) | Thread identifier |
| 40 | 28 | UNSIGNED BINARY(4) | Thread handle |
RRCD0100 Format Field Descriptions
Job name. The simple job name of the job that issued the lock request.
Job number. The system-assigned job number of the job that issued the lock request.
Job user name. The user name under which the job that issued the lock request is run.
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. |
Lock state. The lock state to be processed. The possible values are:
| 0 | The record lock is a shared read lock. |
| 1 | The record lock is an exclusive update lock. |
| 2 | The record lock is a shared internal 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 job record lock information is being returned.
Size of information for each record lock returned. The number of bytes of each of the returned record lock information structures. In future releases, the amount of information returned for each record lock may be expanded, so this value should be used to move from one record 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 not a thread 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 not a thread scope lock, this is hex zeros.
RRCD0200 Format
The following information is returned for RRCD0200 format. For detailed descriptions of the fields in the table, see RRCD0200 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) | Job name |
| 10 | A | CHAR(10) | Job user name |
| 20 | 14 | CHAR(6) | Job number |
| 26 | 1A | CHAR(1) | Lock status |
| 27 | 1B | CHAR(1) | Lock state |
| 28 | 1C | BINARY(4) | Relative record number |
| 32 | 20 | CHAR(8) | Thread identifier |
| 40 | 28 | UNSIGNED BINARY(4) | Thread handle |
| 44 | 2C | CHAR(1) | Lock scope |
| 45 | 2D | CHAR(1) | Holder type |
| 46 | 2E | CHAR(20) | Lock space identifier |
| 66 | 42 | CHAR(2) | Reserved |
RRCD0200 Format Field Descriptions
Holder type. If the lock status indicates the lock is held, this indicates the type of holder. If the lock status indicates the lock is not yet held, this indicates the type of holder that is waiting on the lock. This field will be the same as the lock scope field except in the case when a thread is waiting for a lock space scope lock. The possible values are:
| 0 | Job. |
| 1 | Thread. |
| 2 | Lock space. |
Job name. The simple job name of the job that issued the lock request. If the holder type is not job or thread, this is hex zeros.
Job number. The system-assigned job number of the job that issued the lock request. If the holder type is not job or thread, this is hex zeros.
Job user name. The user name under which the job that issued the lock request is run. If the holder type is not job or thread, this is hex zeros.
Lock scope. If the lock status indicates the lock is held, this indicates the type of holder. If the lock status indicates the lock is not yet held, this indicates the type of holder will hold the lock once the lock request is satisfied. This field will be the same as the holder type field except in the case when a thread is waiting for a lock space scope lock. The possible values are:
| 0 | Job. |
| 1 | Thread. |
| 2 | Lock space. |
Lock space identifier. The identifier of the lock space that holds this lock. If the lock scope is not lock space scope, this is hex zeros.
Lock status. The status of the lock. The possible values are:
| 0 | The record lock is held. The holder may be a job, thread or lock space as indicated by the lock holder type field. |
| 1 | The record lock is being waited on. The waiter may be a job or thread as indicated by the lock holder type field. |
Lock state. The lock state to be processed. The possible values are:
| 0 | The record lock is a shared read lock. |
| 1 | The record lock is an exclusive update lock. |
| 2 | The record lock is a shared internal 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 job record lock information is being returned.
Reserved. An unused field.
Size of information for each record lock returned. The number of bytes of each of the returned record lock information structures. In future releases, the amount of information returned for each record lock may be expanded, so this value should be used to move from one record 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 holder type is not thread, 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 holder type is not thread, this is hex zeros.
Format of Record Identification Information
The format of the information that is to be used to identify the record or records for which locks are to be retrieved. If this parameter is specified, the member and relative record number parameters are ignored, and the member and relative number specified in the format fields are used to identify the records.
RRRC0100 Format
The following information is specified for the RRRC0100 format. For detailed descriptions of the fields in the table, see RRRC0100 Format Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | File name |
| 10 | A | CHAR(10) | Library name |
RRRC0100 Format Field Descriptions
File name. The name of the file for which record locks are to be retrieved.
Library name. The name of the library where the object is located. The library is assumed to be in the name space of the thread that called the API. 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. |
RRRC0200 Format
The following information is specified for the RRRC0200 format. For detailed descriptions of the fields in the table, see RRRC0200 Format Field Descriptions
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Record identification information size |
| 4 | 4 | CHAR(10) | File name |
| 14 | E | CHAR(10) | Library name |
| 24 | 18 | CHAR(10) | Member name |
| 34 | 22 | CHAR(10) | Library ASP name |
| 44 | 2C | UNSIGNED BINARY(4) | Relative record number |
RRRC0200 Format Field Descriptions
File name. The name of the file for which record locks are to be retrieved.
Library ASP name. The name of the auxiliary storage pool (ASP) device that contains the file's library. Special values used are:
| * | Thread name space |
| *SYSBAS | System or basic user ASP |
Library name. 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. |
Member name. The name of the member in the specified file that is to be checked for record locks.
The following special value is allowed:
| *FIRST | The first member of the specified file is used. |
Record identification information size. The amount of data provided for the RRRC0200 format. This field must be set to 48.
Relative record number. The record number in the specified file and member for which lock information is to be returned. The following special value is allowed:
| 0 | Record lock information for all records in the member should be returned. |
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 |
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 state value |
| 1 | Return only the shared locks |
| 2 | Return only the exclusive locks |
Default: Do not filter on lock state 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 status 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 status value
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. |
| 16 | All filters are required |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3130 E | Member &2 already in use. |
| CPF3210 E | File &1 in library &2 not correct type. |
| CPF3247 E | Record number &4 does not exist in member &3. |
| CPF3275 E | Member &3 file &1 in &2 not found. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C1E E | Required parameter &1 omitted. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9810 E | Library &1 not found. |
| CPF9812 E | File &1 in library &2 not found. |
API introduced: V5R1
[ Back to top | Database and File APIs | APIs by category ]