The Change User Trace Buffer (CHGUSRTRC) command changes the user trace buffer associated with the specified job. Each user trace buffer is a user space (*USRSPC) object in library QUSRSYS by the name QP0Znnnnnn, where 'nnnnnn' is the job number of the job using the user trace.

The user trace supports user-generated trace records written using the Qp0zUprintf, Qp0zDump, Qp0zDumpStack, and Qp0zDumpTargetStack APIs. Refer to the System API Reference information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter, OS/400 UNIX-type APIs for more information on the Problem Determination APIs.

The trace records written to the user trace buffer with the Problem Determination APIs can be formatted and placed into a file or written to the stdout file by using the DMPUSRTRC (Dump User Trace Buffer) CL command.

User trace buffer spaces can be deleted by using the DLTUSRTRC (Delete User Trace Buffer) CL command.

Parameters

Keyword	Description	Choices	Notes
JOB	Job name	Single values: * Other values: Qualified job name	Optional, Key, Positional 1
	Qualifier 1: Job name	Name
	Qualifier 2: User	Name
	Qualifier 3: Number	000000-999999
CLEAR	Clear trace buffer	*NO, *YES	Optional
MAXSTG	Maximum storage to use	10-16382, *SAME	Optional
TRCFULL	Trace full	*WRAP, *STOPTRC, *SAME	Optional

Top

Job name (JOB)

Specifies the job for which the user trace buffer is being changed.

The possible values are:

*

The user trace buffer for the job that the command is running in is changed.

job-name

Specify the name of the job whose user trace buffer is being changed. If no user name or job number qualifier is given, all of the jobs currently in the system are searched for the simple job name. If duplicates of the specified name are found, a qualified job name must be specified.

user-name

Specify the name of the user of the job whose user trace buffer is being changed.

job-number

Specify the six-digit number of the job whose user trace buffer is being changed.

Clear trace buffer (CLEAR)

Specifies whether all trace records currently stored in the user trace buffer space should be removed.

The possible values are:

*NO

No trace records are removed from the user trace buffer.

*YES

All trace records currently stored in the user trace buffer are removed.

Maximum storage to use (MAXSTG)

Specifies the size, in kilobytes, that the user trace buffer will be created to (if it doesn't exist) or resized to (if it exists). If this parameter is specified, *YES must also be specified for the CLEAR parameter.

The possible values are:

*SAME

The user trace size is not changed. The default size (300 kilobytes) is used to create the user trace buffer when the first user trace API is called.

maximum-kilobytes

Specify the maximum amount of storage, in kilobytes, used to store user trace records. One kilobyte equals 1024 bytes.

Trace full (TRCFULL)

Specifies whether the trace records wrap (replace oldest records with new records) or whether the trace stops when all of the storage specified by the MAXSTG parameter has been used.

The possible values are:

*SAME

The current attribute does not change. The default when a user trace buffer space is created is TRCFULL(*WRAP).

*WRAP

When the trace file is full, the trace wraps to the beginning. The oldest trace records are written over by new ones as they are collected.

*STOPTRC

Tracing stops when the trace buffer space is full of trace records.

Examples

Example 1: Changing the User Trace Buffer Size for the Current Job

CHGUSRTRC   JOB(*)  MAXSTG(100)  CLEAR(*YES)

This command changes the user trace buffer size for the current job to 100 kilobytes.

Example 2: Clearing the User Trace Buffer for a Specific Job

CHGUSRTRC   JOB(123581/DEPT2/WS1)  CLEAR(*YES)

This command clears the user trace buffer for job WS1, which is associated with the user profile DEPT2, and has the job number 123581.

Error messages

*ESCAPE Messages

CPFA98A

A User Trace option could not be changed for job &3/&2/&1.

CPFA98C

Job &3/&2/&1 not unique.

CPF1070

Job &3/&2/&1 not found.