| 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(*) |
The Cancel Requested Statistics Collections (QDBSTCRS, QdbstCancelRequestedStatistics) API allows the user to cancel requested, but not yet completed or not successfully completed statistics collections, and also provides an option to restart a single cancelled request.
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.
The length of the input data buffer provided.
The format of the input data. Possible values are:
| STIC0100 | Cancel a single requested statistics collection using an internal request ID. |
| STIC0200 | Cancel all requested statistics collections for a single database file member. |
Refer to STIC0100 Input Format and STIC0200 Input Format for more information.
The buffer to receive feedback data. See Feedback Area Format for more information. The buffer content has to start at a 4-byte boundary.
The length of the feedback area buffer provided. The required minimum length is 16, to fit the feedback area header (see Feedback Area Format).
The list of fields to return in the feedback area. For a list of valid keys, see Valid Keys - Feedback.
The number of fields to return in the feedback area. If 0 is specified, all other feedback area parameters (Feedback area, Length of feedback area, and Feedback keys) are ignored.
The structure in which to return error information. For the format of the structure, see Error code parameter.
Use this format to cancel the single statistics collection uniquely identified by an internal request ID. See Field Descriptions for details of the fields listed.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(16) | Internal request ID |
| 16 | 10 | CHAR(12) | Restart option |
| 28 | 1C | CHAR(*) | Reserved |
Use this format to cancel all not yet completed statistics collection for a given file member. See Field Descriptions for details of the fields listed.
Note: When using this option mainly to target system initiated requests, it is recommended that you first use the blocking function provided by the Update Statistics Collection (QDBSTUS, QdbstUpdateStatistics) API to prevent the system from issuing the requests again.
| 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(*) | Reserved |
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 |
| 2 | CHAR(10) | File name used |
| 3 | CHAR(10) | File library name used |
| 4 | CHAR(10) | File member name used |
| 21 | BINARY(4) | Number of statistics collection requests cancelled. |
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-byte boundary) | ||
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.
Data. The data returned for the key identifier.
File library name. Where the file for which statistics collections are to be cancelled 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 cancel 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 to be cancelled. The file has to be an existing local, single format, physical file.
File name used. The actual file name used.
Internal request ID. Uniquely identifies statistics collections requested earlier. This ID can be obtained from one of the following APIs:
Key identifier. The field returned. For a list of valid keys see Valid Keys - Feedback.
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.
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 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 statistics collection requests cancelled. Number of statistics collection requests actually cancelled .
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-byte boundary.
Restart option. Allows the cancelled request to optionally be restarted. The possible values are:
| *NONE | Do not restart, but just cancel the request, if
its in active state, or remove the request, if its in pending or error state.
Note: When using this option for system-initiated requests, it is recommended that you first use the blocking function provided by the Update Statistics Collection (QDBSTUS, QdbstUpdateStatistics) API to prevent the system from issuing the request again. |
| *IMMEDIATE | Restart 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.
Note: If the request has an active status and not a pending or error status, the cancel request will be ignored. |
| 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. |
[ Back to top | >Database and File APIs | APIs by category ]