Change Communications Trace Configuration (QSCCHGCT) API
Required Parameter Group:
| 1 | Communications trace operation | Input | Binary(4) |
| 2 | Input buffer | Input | Char(*) |
| 3 | Length of input buffer | Input | Binary(4) |
| 4 | Output buffer | Output | Char(*) |
| 5 | Length of output buffer | Input | Binary(4) |
| 6 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: No
The Change Communications Trace Configuration (QSCCHGCT) API sets, resets and retrieves information for the current and maximum amount of storage reserved for all communications trace sessions.
Authorities and Locks
- Authority to use the API
- To use this API, you must have service (*SERVICE) special authority or must be authorized to the Service Trace
function of the IBM i through System i™ Navigator's Application Administration support. The Change Function Usage
(CHGFCNUSG) command, with a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that
are allowed to perform trace operations.
Required Parameter Group
The following parameters are required.
- Communications trace operation
- INPUT; BINARY(4), UNSIGNED
Specifies the type of communications trace operation to perform. The possible values are:
1 Retrieve information about storage used and reserved for active communications traces. 2 Set the maximum storage to be used by communications traces. 3 Restore default storage values (2 megabytes for each communications trace session and 8 megabytes for all communications trace sessions).
- Input buffer
- INPUT; CHAR(*)
Information that is required for a given operation. The input buffer parameter should be set as follows:
1 NULL (no input buffer is required). 2 CTOP0200 Format containing the new storage values. For a detailed description of this format, see CTOP0200 Format. 3 NULL (no input buffer is required).
- Length of input buffer
- INPUT;BINARY(4), UNSIGNED
The length of the input buffer provided. The length of the input buffer parameter may be specified up to the size of the input buffer area specified by the user program. The length of the input buffer should be 0 when the input buffer is NULL.
- Output buffer
- OUTPUT; CHAR(*)
Information that is provided by a given communications trace operation. The output buffer parameter should be as follows:
1 CTOP0100 Format receives current storage amount value for the communications trace. For a detailed description of this format, see CTOP0100 Format. 2 NULL (no input buffer is required). 3 NULL (no input buffer is required).
- Length of output buffer
- INPUT; BINARY(4), UNSIGNED
The length of the output buffer provided. The length of the output buffer parameter may be specified up to the size of the output buffer area specified by the user program. The length of the output buffer should be 0 when the output buffer is NULL.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Output Buffer Description
The following table describes the order and format of the data returned in the output buffer for each of the communications trace operations. For a detailed description of each field, see Field Descriptions.
CTOP0100 Format
This structure is used to return current amount of storage used and the maximum storage allowed for all communications trace session.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4), UNSIGNED | Bytes returned |
| 4 | 4 | BINARY(4), UNSIGNED | Bytes available |
| 8 | 8 | BINARY(4), UNSIGNED | Current amount of storage used |
| 12 | C | BINARY(4), UNSIGNED | Maximum amount of storage |
Input Buffer Description
The following table describes the order and format of the data given in the input buffer parameter for each of the communications trace operations. For a detailed description of each field, see Field Descriptions.
CTOP0200 Format
This structure is used to set the amount of storage for all communications trace sessions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4), UNSIGNED | Maximum amount of storage to be set |
Field Descriptions
Bytes available. The number of bytes of data available to be returned to the user in the output buffer. If all data is returned, bytes available is the same as the number of bytes returned. If the receiver variable was not large enough to contain all of the data, this value is set based on the total size that could be returned.
Bytes returned. The number of bytes of data returned to the user in the output buffer.
Current amount of storage used. The current amount of storage (in megabytes) reserved for all communications trace sessions.
Maximum amount of storage. The maximum amount of storage (in megabytes) available for all communications trace sessions.
Maximum amount of storage to be set. The amount of storage (in megabytes) to be reserved for all communications trace sessions. The special value 0xFFFFFFFF can be used to let the system calculate it according to the available storage in the partition. The maximum size allowed is 16384 megabytes.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF98A2 | Not authorized to &1 command or API. |
| CPF3C1D | Length specified in parameter &1 not valid. |
| CPF3C3A | Value for parameter &2 for API &1 not valid. |
| CPF3CF1 | Error code parameter not valid. |
| CPF39D7 | Communications trace operation failed. |
API introduced: IBM® i 7.1
[ Back to top | Problem Management APIs | APIs by category ]