List Requested Statistics Collections (QDBSTLRS, QdbstListRequestedStatistics) API
Required Parameter Group:
| 1 | Qualified user space name | Input | Char(20) |
| 2 | Format of output | Input | Char(8) |
| 3 | Input data | Input | Char(*) |
| 4 | Length of input data | Input | Binary(4) |
| 5 | Format of input data | Input | Char(8) |
| 6 | Error code | I/O | Char(*) |
Service Program Name: QDBSTMGR
Default Public Authority: *USE
Threadsafe: Yes
The List Requested Statistics Collections (QDBSTLRS, QdbstListRequestedStatistics) API lists details for not yet completed, or not successfully completed statistics collection requests, requested by a call to the Request statistics collections (OPM, QDBSTRS; ILE QdbstRequestStatistics) API, the Update Statistics Collection (QDBSTUS, QdbstUpdateStatistics) API, or automatically by the system. The generated list replaces any existing list in the user space.
Section overview
- Authorities and Locks
- Required Parameter Group
- STIP0100 Input Format
- Valid Keys - Request Output
- Format of the Generated List
- Input Parameter Section
- Header Section
- List Data Section
- Field Descriptions
- Error Messages
- Related Information
Authorities and Locks
- User Space Authority
- *CHANGE
- User Space Library Authority
- *EXECUTE
- User Space Lock
- *EXCLRD
- ASP Device Authority
- *EXECUTE
- File Authority
- *OBJOPR
- File Library Authority
- *EXECUTE
Required Parameter Group
- Qualified user space name
- INPUT; CHAR(20)
The user space that is to receive the generated list and the library in which it is located. The first 10 characters contain the user space name, and the second 10 characters contain the library name. You can use these special values for the library name:
*CURLIB The job's current library or QGPL if the current library is not set. *LIBL The library list. *USRLIBL Libraries listed in the user portion of the library list.
- Format of output
- INPUT; CHAR(8)
The format of the statistics collections list to be returned. If Format STOP0100 is specified, the fields that were selected by the caller are returned for each statistics collection request in the list. Possible format names are:
STOP0100 Statistics collection requests list with keyed return fields. Refer to Format of the Generated List and STOP0100 Output Format for more information.
- Input data
- INPUT; CHAR(*)
The buffer containing the input parameters according to the format of input data parameter. The buffer content has to start at a 4-byte boundary.
- Length of input data
- INPUT; BINARY(4)
The length of the input data buffer provided.
- Format of input data
- INPUT; CHAR(8)
The format of the input data. Possible values are:
STIP0100 List Requested Statistics Collections input parameters. Refer to STIP0100 Input Format for more information.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
STIP0100 Format
The following table shows the input parameters for this API. See Field Descriptions for details of the fields listed.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | List filter option |
| 4 | 4 | CHAR(48) | Continuation handle |
| 52 | 34 | BINARY(4) | Offset to fields to return |
| 56 | 38 | BINARY(4) | Number of fields to return |
| 60 | 3C | CHAR(*) | Reserved |
| Array(*) of BINARY(4) | Keys of fields to return | ||
| CHAR(*) | Reserved | ||
Valid Keys - Request Output
The keys listed below are used to determine in the STIP0100 Input Format what will be returned per list entry in the List Data Section - STOP0100 Output Format. Each key can only be specified once. See Field Descriptions for details of the fields listed.
Each list entry returned in the output format describes a single request and can be thought of as two groups of related keys:
Group 1: The following keys describe information at request level and are repeated in list entries describing the single statistics collections within a request:
| Key | Type | Description |
|---|---|---|
| 1 | CHAR(10) | ASP device name used |
| 2 | CHAR(10) | File name used |
| 3 | CHAR(10) | File library name used |
| 4 | CHAR(10) | File member name used |
| 6 | CHAR(16) | Internal request ID |
| 34 | CHAR(10) | Name of requesting user profile |
| 35 | CHAR(26) | Time stamp of request |
| 36 | CHAR(1) | Request status |
| 37 | CHAR(26) | Time stamp |
| 38 | CHAR(26) | Qualified job name |
| 39 | CHAR(8) | Thread ID |
| 40 | BINARY(4) | Progress percentage |
| 8 | BINARY(4) | Estimated time |
| 42 | CHAR(7) | Message ID |
| 49 | CHAR(*) | Message Data |
| 50 | CHAR(10) | Message File Library |
| 51 | CHAR(10) | Message File |
| 43 | BINARY(4) | Total number of statistics collections for internal request ID |
Group 2: The following keys describe information at statistics collection level for a request:
| Key | Type | Description |
|---|---|---|
| 44 | BINARY(4) | Running number of statistics collection for internal request ID |
| 46 | CHAR(*) | Statistics collection name |
| 18 | CHAR(10) | Aging mode |
| 28 | BINARY(4) | Number of columns |
| 29 | Array(*) of CHAR(10) | Column names |
| 30 | Array(*) of CHAR(20) | Qualified translation table names |
Format of the Generated List
The statistics collections list consists of:
- A user area
- A generic header
- An input parameter section
- A header section
- A list data section
The user area and generic header are described in User spaces. The remaining items are described in the following sections.
Input Parameter Section
The following information is returned in the input parameter section. For detailed descriptions of the fields in this table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | User space name specified |
| 10 | A | CHAR(10) | User space library name specified |
| 20 | 14 | CHAR(8) | Format of output specified |
| 28 | 1C | BINARY(4) | Length of input data specified |
| 32 | 20 | CHAR(8) | Format of input data specified |
| 40 | 28 | BINARY(4) | List filter option specified |
| 44 | 2C | CHAR(48) | Continuation handle specified |
| 92 | 5C | BINARY(4) | Offset to fields to return specified |
| 96 | 60 | BINARY(4) | Number of fields to return specified |
| 100 | 64 | BINARY(4) | Displacement to specified fields to return |
| 104 | 68 | Array(*) of BINARY(4) | Keys of fields to return specified |
Header Section
For detailed descriptions of the fields in this table, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(48) | Continuation handle |
| 48 | 30 | ||
List Data Section - STOP0100 Output Format
The following information is returned in the list data section per statistics collection list entry for Format STOP0100. The fields are returned in the order requested. See Field Descriptions for details of the fields listed.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Length of list entry |
| 4 | 4 | BINARY(4) | Number of key fields returned |
| These fields repeat, in the order listed, for each key selected. | BINARY(4) | Length of field information returned | |
| BINARY(4) | Key identifier | ||
| BINARY(4) | Length of data | ||
| CHAR(*) | Data | ||
| CHAR(*) | Reserved (padding to the next 4-byte boundary) | ||
Field Descriptions
ASP device name used. The actual auxiliary storage pool device name used, after possible resolution of special values.
Note: If the API caller does not have the documented ASP Device Authority for the ASP device, the ASP device name returned will be set to all blanks.
Aging mode. Whether the system is allowed to age or remove the statistics collection. The possible values are:
| *SYS | Refresh or removal of the resulting statistics collections will be performed automatically by the system. |
| *USER | Refresh or removal will only occur when a user requests it. |
Column names. The array of names of the columns within the statistics collection, in the same order as at request time. Each array elements also corresponds to the array element at the same position in the Qualified translation table names field. The array dimension is given by the Number of columns field.
Note: If the API caller does not have the documented ASP Device Authority , File Authority, and File Library Authority for the file containing these specific columns, the column names returned will be set to all blanks.
Continuation handle (input section). The handle used to continue from a previous call to this API that resulted in partially complete information. You can determine if a previous call resulted in partially complete information by checking the Information Status variable in the generic user space header following the API call.
If the API is not attempting to continue from a previous call, this parameter must be set to blanks. Otherwise, a valid continuation value must be supplied. The value may be obtained from the list header section of the user space used in the previous call. When continuing, the first entry in the returned list is the entry that immediately follows the last entry returned in the previous call.
Continuation handle (header section). A continuation point for the API. This value is set based on the contents of the Information Status variable in the generic header for the user space. The following situations can occur:
| Information status-C | The information returned in the user space is valid and complete. No continuation is necessary and the continuation handle is set to blanks. |
| Information status-P | The information returned in the user space is valid but incomplete. The user may call the API again, starting where the last call left off. The continuation handle contains a value which may be supplied as an input parameter in later calls. |
| Information status-I | The information returned in the user space is not valid and incomplete. The content of the continuation handle is unpredictable. |
Data. The data returned for the key identifier.
Displacement to specified fields to return. The displacement to the start of the array of specified fields to return.
Note: This is not the offset specified on input, but the displacement within the input parameter section. See Offset to fields to return specified instead.
Estimated time. The estimated time in seconds to collect the statistics for this request. This will be zero for all request statuses but '0' (pending),'1' (active), and '3' (candidate).
Note: For request status '1' (active), the estimate is for the complete request, not for the remaining work to be done. The also returned progress percentage can be used to calculate the estimated time left before the request is complete.
File library name used. The actual file library name used, after possible resolution of special values.
Note: If the API caller does not have the documented ASP Device Authority and File Library Authority for this specific library, the library name returned will be set to all blanks.
File member name used. The actual file member name used, after possible resolution of special values.
Note: If the API caller does not have the documented ASP Device Authority, File Authority, and File Library Authority for the file containing this specific member, the file member name returned will be set to all blanks.
File name used. The actual file name used.
Note: If the API caller does not have the documented ASP Device Authority, File Authority, and File Library Authority for this specific file, the file name returned will be set to all blanks.
Internal request ID. Uniquely identifies a requested statistics collections. See the Request statistics collections (OPM, QDBSTRS; ILE QdbstRequestStatistics) API.
Key identifier. The field returned. For a list of valid keys see Valid Keys - Request output.
Keys of fields to return. The list of fields to return per list entry. For a list of valid keys see Valid Keys - Request output.
Length of data. The length of the data returned for the field.
Length of field information returned. Total number of bytes returned for this field.
Length of list entry. Number of bytes returned for this list entry.
List filter option. The statistics collection requests to return. The filter option is a bit field and can be computed by adding up desired single filter values from the following list:
| 1 | List requests in '0' (pending) status. |
| 2 | List requests in '1' (active) status. |
| 4 | List requests in '2' (error) status. |
| 8 | List requests in '3' (candidate) status. |
For information on the request status, see the Request Status field.
Message ID. For request status '2' (error) only: A message ID describing the error.
Message File. For request status '2' (error) only: The message file for the Message ID.
Message File Library. For request status '2' (error) only: The library where the Message File is located.
Message Data. For request status '2' (error) only: The message field data for the Message ID.
Name of requesting user profile. The name of user profile that requested the statistics collection. The name will be *SYS for statistics collections automatically requested by the system.
Number of columns. Number of columns within the single statistics collection.
Number of fields to return. The number of fields to return for each list entry.
Number of key fields returned. Number of fields actually returned.
Offset to fields to return specified. Offset to fields to return as specified on the call of the API.
Progress percentage. For request status '1' (active) only: The percentage of completion of the request. For all other request statuses this will be zero.
Qualified job name. Depending on the request status, the following values are valid:
| '0' (pending), '3' (candidate) | The job that submitted the request. |
| '1' (active) | The job processing the request. |
| '2' (error) | The job that did process the request. |
The qualified job name has three parts:
| Job name | Char(10). |
| User name | Char(10). |
| Job number | Char(6). |
Qualified translation table names. The array of names of the translation tables that were specified, when the statistics collection was requested, in the same order as requested. Each array elements corresponds to the array element at the same position in the Column names field. The first 10 characters contain the translation table name, and the second 10 characters contain the name of the library where the table is located. The array dimension is given by the Number of columns field.
Note: For system initiated requests, the translation table name and the library can be set to the following special value:
| *UNKNOWN | The information is not available in a suitable form. |
Request status. The current status of the requested statistics collection. The possible values are:
| '0' | Pending. Request is scheduled for later processing. |
| '1' | Active. Request is currently being processed. |
| '2' | Error. Request processing did end in error and no
statistics data was stored.
Note: Only the most recently-ended requests are listed. |
| '3' | Candidate. Request is scheduled for possible later processing, but could be discarded by the system beforehand. |
Reserved. Reserved for future use. If this field is input, the field must be set to hexadecimal zeros.
Reserved (in STOP0100 output format). Structure padding to guarantee alignment to the next 4-byte boundary.
Running number of statistics collections for internal request ID. Current index of the statistics collection definition for this request. The statistics collection definitions will be returned in the same order as requested.
Statistics collection name. A name unique among all statistics collections for the file member.
Thread ID. For request status '1' (active) only: The thread that is currently processing the request.
Time stamp. Depending on the request status, this time stamp shows:
| '0' (pending), '3' (candidate) | The time the request was made (same as time stamp of request). |
| '1' (active) | The time processing started. |
| '2' (error) | The time the request ended in error. |
Time stamp of request. The time stamp showing when the statistics collection was requested.
Total number of statistics collections for internal request ID. The number of statistics collection definitions for this request, identified by the internal request ID.
User space name specified. The user space name as specified on the call of the API.
User space library name specified. The user space library name as specified on the call of the API.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF0623 E | Field &1 not found in record format &2. |
| CPF1866 E | Value &1 for number of fields to return not valid. |
| CPF2105 E | Object &1 in &2 type *&3 not found. |
| CPF2113 E | Cannot allocate library &1. |
| CPF2173 E | Value for ASPDEV not valid with special value for library. |
| CPF218C E | &1 not a primary or secondary ASP. |
| CPF3141 E | Member &2 not found. |
| CPF34C0 E | Value &1 for number of fields to return parameter not valid. |
| CPF3C07 E | Error occurred while retrieving information from object &1. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C29 E | Object name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C3B E | Value for parameter &2 for API &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C89 E | Key &1 specified more than once. |
| CPF3CE2 E | Continuation handle not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF4268 E | Object &1 in &2 type *&3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| CPF9804 E | Object &2 in library &3 damaged. |
| CPF980B E | Object &1 in library &2 not available. |
| CPF9810 E | Library &1 not found. |
| CPF9812 E | File &1 in library &2 not found. |
| CPF9814 E | Device &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9822 E | Not authorized to file &1 in library &2. |
| CPF9825 E | Not authorized to device &1. |
| CPF9826 E | Cannot allocate file &2. |
| CPF9830 E | Cannot assign library &1 |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
| CPFB401 E | API &3 failed with reason code &1. |
| CPFB8ED E | Device description &1 not correct for operation. |
Related Information
- the <qdbst.h> include file in library QSYSINC, for
API-related structure declarations and special value declarations.
- the <qdbstmgr.h> include file in library QSYSINC,
for the QdbstListRequestedStatistics API prototype.
- the <qdbstlrs.h> include file in library QSYSINC,
for the QDBSTLRS API prototype.
- Cancel Requested Statistics
Collections (QDBSTCRS, QdbstCancelRequestedStatistics) API
- Delete Statistics Collections
(QDBSTDS, QdbstDeleteStatistics) API
- List Statistics Collection
Details (QDBSTLDS, QdbstListDetailStatistics) API
- List Statistics Collections (QDBSTLS,
QdbstListStatistics) API
- Request Statistics Collections
(QDBSTRS, QdbstRequestStatistics) API
- Update Statistics Collections (QDBSTUS, QdbstUpdateStatistics) API
API introduced: V5R2