Request Statistics Collections (QDBSTRS, QdbstRequestStatistics) API
Required Parameter Group:
| 1 | Input data | Input | Char(*) |
| 2 | Length of input data | Input | Binary(4) |
| 3 | Format of input data | Input | Char(8) |
| 4 | Feedback area | Output | Char(*) |
| 5 | Length of feedback area | Input | Binary(4) |
| 6 | Feedback keys | Input | Array(*) of Binary(4) |
| 7 | Number of feedback keys | Input | Binary(4) |
| 8 | Error code | I/O | Char(*) |
Service Program Name: QDBSTMGR
Default Public Authority: *USE
Threadsafe: Yes
The Request Statistics Collections (QDBSTRS, QdbstRequestStatistics) API allows the user to request one or more statistics collections for a given set of columns of a database file member to be created.
The created statistics collections are stored as part of the database file member.
Options are provided to control whether the statistics are generated in the background or to be processed immediately, and whether the status of the resulting statistics collections is to be maintained automatically by the system or manually by the user.
Section overview
- Authorities and Locks
- Required Parameter Group
- STIR0100 Input Format
- Valid Keys - Feedback
- Feedback Area Format
- Field Descriptions
- Error Messages
- Related Information
Authorities and Locks
- ASP Device Authority
- *EXECUTE
- File Authority
- *OBJALTER, *OBJOPR
- File Library Authority
- *EXECUTE
- File Lock
- *SHRRD
- Translation Table Authority
- *USE
- Translation Table Library Authority
- *EXECUTE
- Translation Table Lock
- *SHRRD
Required Parameter Group
- 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 four-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:
STIR0100 Basic request statistics collections input parameters. Refer to STIR0100 Input Format for more information.
- Feedback area
- OUTPUT; CHAR(*)
The buffer to receive feedback data. See Feedback Area Format for more information. The buffer content has to start at a four-byte boundary.
- Length of feedback area
- INPUT; BINARY(4)
The length of the feedback area buffer provided. The required minimum length is 16, to fit the feedback area header (see Feedback Area Format).
- Feedback keys
- INPUT; ARRAY(*) OF BINARY(4)
The list of fields to return in the feedback area. For a list of valid keys see Valid Keys - Feedback.
- Number of feedback keys
- INPUT; BINARY(4)
The number of fields to return in the feedback area. If zero is specified, all other feedback area parameters (Feedback area, Length of feedback area, and Feedback keys) are ignored.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
STIR0100 Input Format
The basic request statistics collections input parameters. See Field Descriptions for details of the fields listed.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | ASP device name |
| 10 | A | CHAR(10) | File name |
| 20 | 14 | CHAR(10) | File library name |
| 30 | 1E | CHAR(10) | File member name |
| 40 | 28 | CHAR(12) | Collection mode |
| 52 | 34 | BINARY(4) | Offset to statistics collections |
| 56 | 38 | BINARY(4) | Number of statistics collections |
| 60 | 3C | CHAR(*) | Reserved |
The fields below follow the fields above and repeat, in the order listed, for each statistics collection, where the first statistics collection starts at the given Offset to statistics collections.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| +0 | +0 | BINARY(4) | Length of statistics collection |
| +4 | +4 | BINARY(4) | Length of statistics collection name |
| +8 | +8 | CHAR(128) | Statistics collection name |
| +136 | +88 | CHAR(10) | Aging mode |
| +146 | +92 | CHAR(2) | Reserved |
| +148 | +94 | BINARY(4) | Displacement to columns |
| +152 | +98 | BINARY(4) | Number of columns |
| +156 | +9C | CHAR(*) | Reserved |
The fields below follow for each statistics collection definition header structure as described above and repeat, in the order listed, for each column in the current statistics collection, where the data for the first column starts at the given offset Offset to columns.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| +0 | +0 | BINARY(4) | Length of column definition |
| +4 | +4 | CHAR(10) | Column name |
| +14 | +E | CHAR(10) | Translation table name |
| +24 | +18 | CHAR(10) | Translation table library name |
| +34 | +22 | CHAR(2) | Reserved |
| +36 | +24 | ||
Valid Keys - Feedback
Use the following keys to specify the fields to be returned in the feedback area. Each key can only be specified once. See Field Descriptions for details of the fields listed.
| Key | Type | Description |
|---|---|---|
| 1 | CHAR(10) | ASP device name used |
| 3 | CHAR(10) | File library name used |
| 4 | CHAR(10) | File member name used |
| 8 | BINARY(4) | Elapsed time |
| 6 | CHAR(16) | Internal request ID |
| 43 | BINARY(4) | Total number of statistics collections for internal request ID |
| 46 | Array of CHAR(*) | Statistics collection names used |
| 7 | Array of CHAR(*) | Internal statistics IDs created |
Feedback Area Format
The fields returned in the feedback area will be returned in the order requested. See Field Descriptions for details of the fields listed.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Number of bytes returned |
| 4 | 4 | BINARY(4) | Number of bytes available |
| 8 | 8 | BINARY(4) | Number of key fields returned |
| 12 | C | BINARY(4) | Number of key fields available |
| 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 bytes boundary) | ||
Field Descriptions
Aging mode. Whether the system is allowed to age or remove the resulting collected 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. |
ASP device name. The name of one auxiliary storage pool (ASP) device in the ASP group in which the library and file are located. The ASP device must have a status of 'Available'. The documented authority is required for the given ASP and the primary of the corresponding ASP group. The name can be a specific ASP device name (for an ASP with a number greater than 32), or one of the following special values:
| * | Locate the library and file in the name space for the current thread. |
| *SYSBAS | Locate the library and file in the system ASP (ASP number 1) and all basic ASPs (ASP numbers 2 through 32). |
ASP device name used. The actual auxiliary storage pool device name used, after possible resolution of special values.
Collection mode. Where the processing for the statistics collection will be performed, or if merely an estimate is requested. The possible values are:
| *IMMEDIATE | Execute the request immediately. The statistics collection will run in the user's process. Control will not return to the API invoker until the collection is complete. |
| *BACKGROUND | The statistics collection will be scheduled for
execution in system job QDBFSTCCOL. Control will return to the API invoker
immediately.
Note: If the current setting of the system value QDBFSTCCOL does not allow user requested background collections, then the request will be queued until the system value is changed to a level allowing the execution of the request. |
| *ESTIMATE | An estimate is returned immediately for the time, that would be required to run the statistics collection. No statistics collection will actually be created. |
Column name. The name of a single column within a single statistics collection definition.
Data. The data returned for the key identifier.
Displacement to columns. Displacement to the start of the list of column definitions for the current statistics collection definition.
Elapsed time. When the collection mode specified is *IMMEDIATE, the value represents the number of seconds actually spent processing the requested statistics collection.
For any other collection mode, this value represents the estimated time in seconds, that the statistics collection should take.
File library name. Where the file for which statistics collections are being requested is located. You can use these special values for the library name, if the ASP Device Name is *:
| *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. |
File library name used. The actual file library name used, after possible resolution of special values.
File member name. The name of the file member to be used for the statistics collections request.
This value can be a specific file member name or one of the following special values:
| *FIRST | The first member (in the order created) in the specified file. |
| *LAST | The last member (in the order created) in the specified file. |
File member name used. The actual file member name used, after possible resolution of special values.
File name. The name of the file for which statistics collections are being requested. The file has to be an existing local, single format, physical file.
Internal request ID. For a Collection mode of *BACKGROUND only, this field is an unique ID for the complete list of statistics collections requested here. The request ID stays valid until the request is completed and the ID can be used on the Cancel Requested Statistics Collections (QDBSTCRS, QdbstCancelRequestedStatistics) API.
Note: The ID is stored in binary, non printable form in the character array.
Internal statistics IDs created. For a Collection mode of *IMMEDIATE only, this will return an array of the internal statistics ID created for each of the requested and successfully created statistics collections. This statistics ID together with the qualified member name can serve as a unique identifier for the created statistics collection on the input to the QdbstDeleteStatistics, QdbstUpdateStatistics, and QdbstListDetailStatistics APIs. Each ID is returned as a single key value. The single key values will be returned in sequence and in the order the statistics collections were requested in the input format. The array dimension can be determined either by the input format field Number of statistics collections or by requesting this number again as Total number of statistics collections for internal request ID in the feedback.
Note: The internal statistics ID for a statistics collection is also returned on the QdbstListStatistics API.
Note: The ID is stored in binary, non printable form in the character array.
Key identifier. The field returned. For a list of valid keys see Valid Keys - Feedback.
Length of column definition. Length of this column definition.
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 in the feedback area.
Length of statistics collection. Length of this statistics collection definition, which can be used to get to the next definition.
Note: The length includes all the column definitions for this statistics collections.
Length of statistics collection name. Actual length of the statistics collection name, up to the maximum length of 128 characters.
Number of bytes available. Number of bytes that could be returned in the feedback area.
Number of bytes returned. Number of bytes returned in the feedback area.
Number of columns. Number of columns in a single statistics collection definition.
Note: This number must be 1.
Number of key fields available. Number of fields that could be returned in the feedback area.
Number of key fields returned. Number of fields returned in the feedback area.
Number of statistics collections. Number of statistics collection definitions for this request.
Offset to statistics collections. Offset to the start of the list of statistics collection definitions for this request.
Reserved. Reserved for future use. If this field is input, the field must be set to hexadecimal zeros.
Reserved (in feedback area format). Structure padding to guarantee alignment to the next four bytes boundary.
Statistics collection names used. An array of the statistics collection names used. Each name is returned as a single key value and is either the name specified on input, or the system generated name, if the special value *GEN was used on input and if the Collection mode specified is *IMMEDIATE. The single key values will be returned in sequence and in the order the statistics collections were requested in the input format. The array dimension can be determined either by the input format field Number of statistics collections or by requesting this number again as Total number of statistics collections for internal request ID in the feedback.
Statistics collection name. A name unique amongst all statistics collections for the file member. The following special value can be used:
| *GEN | The system will generate a unique name for the statistics collection. |
Note: The name is given in varying length form, where the actual length is passed in the Length of statistics collection name field, to indicate how many of the 128 characters are actually part of the name text.
Total number of statistics collections for internal request ID. Number of statistics collection definitions for this request. Gives the array dimension of Statistics collection names used and Internal statistics IDs created and is a copy of Number of statistics collections in the input format.
Translation table name. This field is relevant just for character columns and must be all blanks otherwise. For character columns, this is the name of a translation table to be applied to the data in this column. The name must be for an existing translation table, or all blanks, if no translation table is to be applied. The Translation table name can also have the following special values: *JOB indicates the value is retrieved from the job; *LANGIDUNQ indicates the unique weight table that corresponds to the LANGID specified in the Translation table library name field is used; *LANGIDSHR indicates the shared weight table that corresponds to the LANGID specified in the Translation table library name field is used; *NONE indicates a translate table is not used.
Translation table library name. Where the translation table is located. The name must be for an existing library or all blanks, if no translation table is to be applied. If the Translation table name field contains the special value of *LANGIDUNQ or *LANGIDSHR, then the Translation table library name field must contain a corresponding language identifier (LANGID).
If none of the special values are used for the Translation table name field, 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. |
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. |
| 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 QdbstRequestStatistics API prototype.
- the <qdbstrs.h> include file in library QSYSINC,
for the QDBSTRS API prototype.
- the system value QDBFSTCCOL.
- Cancel Requested Statistics
Collections (QDBSTCRS, QdbstCancelRequestedStatistics) API
- Delete Statistics Collections
(QDBSTDS, QdbstDeleteStatistics) API
- List Requested Statistics
Collections (QDBSTLRS, QdbstListRequestedStatistics) API
- List Statistics Collection
Details (QDBSTLDS, QdbstListDetailStatistics) API
- List Statistics Collections (QDBSTLS,
QdbstListStatistics) API
- Update Statistics Collections (QDBSTUS, QdbstUpdateStatistics) API
API introduced: V5R2