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	Type	Field
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	Type	Field
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 ]