Open List of Threads (QWCOLTHD) API
Required Parameter Group:
| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Receiver variable definition information | Output | Char(*) |
| 5 | Length of receiver variable definition information | Input | Binary(4) |
| 6 | Job identification information | Input | Char(*) |
| 7 | Format of job identification information | Input | Char(8) |
| 8 | List Information | Output | Char(80) |
| 9 | Number of records to return | Input | Binary(4) |
| 10 | Sort information | Input | Char(*) |
| 11 | Number of fields to return | Input | Binary(4) |
| 12 | Key of fields to be returned | Input | Array(*) of Binary(4) |
| 13 | Reset status statistics | Input | Char(1) |
| 14 | General return data | Output | Char(*) |
| 15 | Length of general return data | Input | Binary(4) |
| 16 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes.
The Open List of Threads (QWCOLTHD) API generates a list of active threads for the job specified in the Job identification parameter. The list may be sorted depending on the value of the sort parameter. Upon successful completion of this API, a handle is returned in the list information parameter. You may use this handle on subsequent calls to the following APIs:
- Get List Entries (QGYGTLE)
- Find List Entry (QGYFNDE)
- Close List (QGYCLST)
Authorities and Locks
None.Required Parameter Group
- Receiver variable
- OUTPUT; CHAR(*)
The variable that is used to return the list of active thread information.
- Length of receiver variable
- INPUT; BINARY(4)
The length of the receiver variable.
- Format name
- INPUT; CHAR(8)
The format of the thread list to be returned. The performance varies depending on the number of fields selected. The possible format names follow:
OLTH0100 List of active threads with keyed return fields. See Format of Receiver Variable for more information.
- Receiver variable definition information
- OUTPUT; CHAR(*)
The variable that is used to return the description of how the keyed portion of the list is returned in the receiver variable. See Format of Receiver Variable Definition Information for a description of the layout of this parameter.
- Length of receiver variable definition information
- INPUT; BINARY(4)
The length of the receiver variable definition information. This must be large enough to hold the information for all key fields that are specified in the key of fields to be returned parameter.
- Job identification information
- INPUT; CHAR(*)
The information that is used to identify the job for which the list of threads is to be returned. See Format of Job Identification Information for details.
- Format of job identification information
- INPUT; CHAR(8)
The format of the job identification information. The possible format name is:
JIDF0100 See Format of Job Identification Information for details on the job identification information.
- List Information
- OUTPUT; CHAR(80)
Information about the list that is created by this program. For a description of the layout of this parameter, see Open list information format.
- Number of records to return
- INPUT; BINARY(4)
The number of records in the list to put into the receiver variable after sorting has been done.
- Sort information
- INPUT; CHAR(*)
Information on what fields within the record of information to sort. See Format of Sort Information for a description of the layout of this parameter.
- Number of fields to return
- INPUT; BINARY(4)
The number of fields to return. If this parameter is 0, the key of fields to be returned parameter is not used, the receiver variable definition information parameter is not modified, and the length of receiver variable definition information must be 0.
- Key of fields to be returned
- INPUT; ARRAY(*) of BINARY(4)
The list of the fields to be returned. For a list of the valid key fields, see List of Keys Supported for Format OLTH0100.
- Reset status statistics
- INPUT; CHAR(1)
The elapsed time and all the key fields that are based on the elapsed time are reset to zero. The following special values may be specified:
0 The elapsed time and the key fields based on the elapsed time are not reset. 1 The elapsed time and the key fields based on the elapsed time are reset back to zero.
- General return data
- OUTPUT; CHAR(*)
General output information that applies to the list of threads returned. See General Return Data for a description of the data returned.
- Length of general return data
- INPUT; BINARY(4)
The length of the general output information. The general output information field must be a minimum of 8 bytes.
- 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 Variable
The following tables describe the order and format of the data that is returned in the receiver variable.
OLTH0100 Format
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(8) | Thread identifier |
| 8 | 8 | BINARY(4), UNSIGNED | Thread handle |
| 12 | C | BINARY(4) | Total length of data returned |
| 16 | F | CHAR(*) | Reserved |
| This information repeats for each key selected. | CHAR(*) or BINARY(4) | Data | |
Field Descriptions
Data. The data returned for the key field.
Reserved. An ignored field.
Thread handle. A value that 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 that is used to uniquely identify a thread within a job. A valid thread identifier must be specified.
Total length of data returned. The length of the data portion of the returned data. This includes the sum of all the keyed data for the list of threads.
Format of Receiver Variable Definition Information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of fields returned |
| 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 | ||
| BINARY(4) | Displacement to data | ||
Field Descriptions
Displacement to data. The displacement from the beginning of the thread record in the receiver variable to the value for this key.
Key field. The field returned. See List of Keys Supported for Format OLTH0100 for the list of valid keys supported for the OLTH0100 format.
Length of data. The length of the data returned for the field.
Length of field information returned. The total length of definition information returned for this field. This value is used to increment to the next field in the list.
Number of fields returned. The number of fields in each record that is returned to the application.
Reserved. An ignored field.
Type of data. The type of data that is returned.
| C | The data is returned in character format. |
| B | The data is returned in binary format. |
Format of Sort Information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of keys to sort on |
| Offsets vary. These fields repeat for each sort key field. | BINARY(4) | Sort key field starting position | |
| BINARY(4) | Sort key field length | ||
| BINARY(2) | Sort key field data type | ||
| CHAR(1) | Sort order | ||
| CHAR(1) | Reserved | ||
Field Descriptions
Number of keys to sort on. The number of fields within the record structure on which to sort. If 0 is specified, the list is not sorted.
Reserved. Reserved field. This field must be set to hexadecimal or binary zero.
Sort key field data type. Data type of field to sort. See Sort (QLGSORT) API for information on the list of data types available.
Sort key field length. The length of the field on which to sort.
Sort key field starting position. Within the record of information, the starting position of the field to sort on. A value of 1 represents the first position within the record.
Sort order. Whether the list should be sorted in ascending or descending order according to the key.
| 1 | Sort in ascending order. |
| 2 | Sort in descending order. |
Format of Job Identification Information
The format of the information needed to identify the job for which the list of threads will be 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 a job name.
Job name. A specific job name or one of the following special values:
| * | The job that this program is running in. 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 hex zeros.
Thread identifier. An unused field on this API. This field must contain hex zeros.
Thread indicator. An unused field on this API. This field must contain hex zeros.
User name. A specific user profile name, or blanks when the job name specified is a special value.
General Return Data
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(8), UNSIGNED | Elapsed time |
| 16 | 10 | CHAR(10) | Job name used |
| 26 | 1A | CHAR(10) | User name used |
| 36 | 24 | CHAR(6) | Job number used |
| 42 | 2A | CHAR(16) | Internal job identifier |
| 58 | 3A | 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.
Elapsed time. The time, in milliseconds, that has elapsed between the measurement start time and the current system time. This value is 0 the first time this API is called by this job. The measurement start is set the first time this API is called and when the Reset status statistics is set to reset the elapsed time.
Internal job identifier. A value that is sent to other APIs to speed the process of locating the job on the system. The identifier is not valid following an initial program load (IPL). If you attempt to use it after an IPL, an exception occurs.
Job name used. The name of the job as identified to the system. For an interactive job, the system assigns the job the name of the workstation where the job started. For a batch job, you specify the name in the command when you submit the job.
Job number used. The system-assigned job number.
Reserved. An ignored field.
User name used. The user profile under which the job is started. The user name is the same as the user profile name and can come from several different sources depending on the type of job.
List of Keys Supported for Format OLTH0100
| Key | Type | Description |
|---|---|---|
| 305 | CHAR(10) | Current user profile |
| 319 | BINARY(8), UNSIGNED | Processing unit time used - total for the thread |
| 320 | BINARY(8), UNSIGNED | Processing unit time used for database - total for the thread |
| 321 | BINARY(4) | Processing unit used - percent during the elapsed time (thread) |
| 322 | BINARY(8), UNSIGNED | Processing unit used - time during the elapsed time (thread) |
| 323 | BINARY(4) | Processing unit used for database - percent during the elapsed time (thread) |
| 324 | BINARY(8), UNSIGNED | Processing unit used for database - time during the elapsed time (thread) |
| 419 | BINARY(8), UNSIGNED | Disk I/O count during the elapsed time (thread) |
| 420 | BINARY(8), UNSIGNED | Disk I/O count - total for the thread |
| 421 | BINARY(8), UNSIGNED | Disk I/O count during the elapsed time - asynchronous I/O (thread) |
| 422 | BINARY(8), UNSIGNED | Disk I/O count during the elapsed time - synchronous I/O (thread) |
| 1610 | BINARY(8), UNSIGNED | Page fault count during the elapsed time (thread) |
| 1804 | BINARY(4) | Run priority (thread) |
| 2010 | CHAR(4) | Thread status |
| 2011 | CHAR(1) | Thread type |
When the length of the data returned for a key is not a multiple of 4 bytes, the length of the field information returned is adjusted so that the next key begins on a 4-byte boundary. This adjustment should be considered when calculating the starting position of a key field to sort on.
Field Descriptions
The field descriptions are in Work Management API Attribute Descriptions (WMAttrDesc).
Usage Notes
When collecting performance statistics, it is important to provide an adequate time interval. The reported values reflect both the performance of the job that the API is looking at and the performance of the job that the API is running in. For example, you may see percentages greater than 100% because of the way the API interacts with the job that it is sampling.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF136A E | Job &3/&2/&1 not active. |
| CPF1866 E | Value &1 for number of fields to return not valid. |
| CPF1867 E | Value &1 in list not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C19 E | Error occurred with receiver variable specified. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C3B E | Value for parameter &2 for API &1 not valid. |
| CPF3C3C E | Value for parameter &1 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. |
| 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. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9F81 E | API &1 requires too much information to be collected prior to sorting. |
| GUI0002 E | &2 is not valid for length of receiver variable. |
| GUI0024 E | &1 is not valid for number of keys to sort on. |
| GUI0025 E | &1 is not valid for sort key field starting position. |
| GUI0026 E | &1 is not valid for sort key field length. |
| GUI0027 E | &1 is not valid for number of records to return. |
| GUI0119 E | Reserved field in sort information not valid. |
| GUI0120 E | Order field in sort information not valid. |
| GUI0132 E | &2 is not valid for length of receiver variable definition information. |
| GUI0149 E | &1 is not valid for number of keys to sort on. |
API introduced: V5R2