Update Statistics Collections (QDBSTUS, QdbstUpdateStatistics) 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 Update Statistics Collection (QDBSTUS, QdbstUpdateStatistics) API allows the user to update the attributes and to refresh the data of an existing single statistics collection.
In addition, the QdbstUpdateStatistics API allows to block all future system initiated statistics collection requests for a specific database file member.
Section overview
- Authorities and Locks
- Required Parameter Group
- STIU0100 Input Format
- Valid Keys - Update
- 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
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:
STIU0100 Update statistics collection via unique statistics ID and keyed input. Refer to STIU0100 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.
STIU0100 Input Format
Update statistics collection 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(16) | Internal statistics ID |
| 56 | 38 | BINARY(4) | Offset to fields to update |
| 60 | 3C | BINARY(4) | Number of fields to update |
| 64 | 40 | CHAR(*) | Reserved |
| These fields repeat, in the order listed, for each field to be updated, started at the given offset. | BINARY(4) | Length of field information | |
| BINARY(4) | Key identifier | ||
| BINARY(4) | Length of data | ||
| CHAR(*) | Data | ||
| CHAR(*) | Reserved (padding to the next 4-byte boundary) | ||
| CHAR(*) | Reserved | ||
Valid Keys - Update
Use the following keys to specify the fields to be updated when using the STIU0100 Input Format. Each key can only be specified once. See Field Descriptions for details of the fields listed.
| Key | Type | Description |
|---|---|---|
| 45 | CHAR(12) | Statistics data (key value is the collection mode) |
| 18 | CHAR(10) | Aging mode |
| 46 | CHAR(*) | Statistics collection name |
| 47 | CHAR(1) | Block system statistics collections option |
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 |
| 6 | CHAR(16) | Internal request ID |
| 18 | CHAR(10) | Previous aging mode |
| 46 | CHAR(*) | Previous statistics collection name |
| 47 | CHAR(1) | Previous block system statistics collections option |
Feedback Area Format
The fields returned in the feedback area are 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 statistics collection. The possible values to change to are:
| *SYS | Refresh or removal of the 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.
Block system statistics collections option. Whether future system initiated (automatic) statistics collection create or update requests will be allowed for this database file member. The possible values are:
| '0' | Do not block system initiated statistics
collection requests.
Note: This is the system default. |
| '1' | Block system initiated statistics collection requests. |
Note: The internal statistics ID is ignored for this option, which operates at file member level, but the ID has to be a valid statistics ID, if any other update option besides the block option is specified.
Note: Currently active system requests will not be affected by changing this option. See Cancel requested statistics collections (QDBSTCRS, QdbstCancelRequestedStatistics) API.
Data (in feedback area format). The data returned for the key identifier.
Data (in STIU0100 input format). The data with which the field is to be updated.
File library name. Where the file for which statistics collection attributes are to be updated 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 collection update 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 collection attributes are to be updated. The file has to be an existing local, single format, physical file.
Internal request ID. If the update key Statistics Data is specified and its value is *BACKGROUND, this field is an unique ID for the statistics data update requested here. The request ID stays valid until the statistics data update 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 ID. Together with the qualified file name and member name, this represents a unique ID for the statistics collection to be updated. See List statistics collections (OPM, QDBSTLS; ILE QdbstListStatistics) API and Request statistics collections (OPM, QDBSTRS; ILE QdbstRequestStatistics) API.
Note: The ID is stored in binary, non printable form in the character array.
Key identifier (in the STIU0100 input format). The field to be updated. For a list of valid keys see Valid Keys - Update.
Key identifier (in the feedback area format). The field returned. For a list of valid keys see Valid Keys - Feedback.
Keys of fields to update. The list of fields to update per list entry. For a list of valid keys see Valid Keys - Update.
Length of data (in feedback area format). The length of the data returned for the field.
Length of data (in STIU0100 input format). The length of the data the field is to be updated with.
Length of field information. Total number of bytes being passed for the field to be updated.
Length of field information returned. Total number of bytes returned for this field in the feedback area.
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 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 fields to update. The number of fields to update.
Offset to fields to update. Offset to the start of the array of fields to update.
Previous aging mode. The aging mode in effect before the update.
Note: If the aging mode was not requested to be updated, the aging mode returned will be blank.
Previous block system statistics collections option. The block option in effect before the update.
Note: If the block option was not requested to be updated, the block option returned will be blank.
Previous statistics collection name. The name in effect before the update.
Note: If the statistics collection name was not requested to be updated, the statistics collection name returned will have a length of 0.
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.
Reserved (in STIU0100 input format). Structure padding to guarantee alignment to the next four bytes boundary.
Statistics collection name. A name unique amongst all statistics collections for the file member.
Statistics data. The statistics data is to be refreshed. The key value is the collection mode (see also the Request statistics collections (OPM, QDBSTRS; ILE QdbstRequestStatistics) API), under which the refresh should take place. The possible values are:
| *IMMEDIATE | Execute the refresh immediately. The statistics collection will run in the user's process. Control will not return to the API invoker until the refresh is complete. |
| *BACKGROUND | The refresh 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 refresh request will be queued until the system value is changed to a level allowing the execution of the refresh. |
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 QdbstUpdateStatistics API prototype.
- the <qdbstus.h> include file in library QSYSINC,
for the QDBSTUS 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
- Request Statistics Collections
(QDBSTRS, QdbstRequestStatistics) API
API introduced: V5R2