End Trace (ENDTRC)

Where allowed to run: All environments (*ALL)
Threadsafe: No

The End Trace (ENDTRC) command ends a trace session that was started by a STRTRC (Start Trace) command.

Restrictions:

To use this command, you must have service (*SERVICE) special authority, or be authorized to the Service trace function of 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.
If DTAOPT(*LIB) is specified, you must have authority to the library and the database files within that library where the trace data is stored.
If PRTTRC(*YES) is specified, you must have authority to the PRTTRC (Print Trace) command.

Parameters

Keyword	Description	Choices	Notes
SSNID	Session ID	Name, *PRV	Required, Positional 1
OPTION	Option	END, EXTRACT	Optional
DTAOPT	Data option	LIB, DLT	Optional
DTALIB	Data library	Name, *CURLIB	Optional
RPLDTA	Replace data	YES, NO	Optional
SLTJOB	Select jobs	Single values: *ALL Other values (up to 8 repetitions): Element list	Optional
	Element 1: Job name	Qualified job name
	Qualifier 1: Job name	Name
	Qualifier 2: User	Name
	Qualifier 3: Number	000001-999999
	Element 2: Thread ID to include	Single values: ALL Other values (up to 20 repetitions): Character value, INITIAL
PRTTRC	Print trace data	NO, YES	Optional

Top

Session ID (SSNID)

Specifies a session identifier for the trace to be ended. This name must match the session identifier of a trace that had been previously started and is still active.

This is a required parameter.

*PRV: The trace session most recently started by the same user who is running this ENDTRC command will be ended. For example, if the job running the ENDTRC command is running under user profile BOB, the last trace session started under user profile BOB is ended.
name: Specify the session identifier of the trace to be ended.

Top

Option (OPTION)

Specifies if trace data will be preserved in the internal buffers where it was collected after the session is ended.

*END

The trace data will not be preserved in the internal buffers where it was collected. After session is ended, the session can be:

Printed with PRTTRC command if DTAOPT(*LIB) is specified.

*EXTRACT

The trace data will be preserved in the internal buffers where it was collected. After data is extracted, the session can be:

Printed with PRTTRC command.
Extracted again with ENDTRC OPTION(*EXTRACT) command.
Ended with ENDTRC OPTION(*END) command.

Top

Data option (DTAOPT)

Specifies if the trace data that has been collected is stored into database files.

*LIB: The trace data will be copied into database files. The PRTTRC parameter on this command or the Print Trace (PRTTRC) command can be used to format and print the data.
*DLT: The trace data will not be copied into database files and the trace data will be deleted from the internal buffers where it was collected.
Note: This option is only valid if *END was specified for the Option (OPTION) parameter.

Top

Data library (DTALIB)

Specifies the name of the library in which the trace data will be stored. A set of database files will be created in this library to contain the trace data. The files will be created if they do not already exist.

Note: This parameter is valid only if *LIB is specified for the Data option (DTAOPT) parameter.

*CURLIB: The trace data is stored in files in the current library for the job. If no library is specified as the current library for the job, QGPL is used.
name: Specify the name of the library to contain the trace data files. The library must already exist when the ENDTRC command is run.

Top

Replace data (RPLDTA)

Specifies whether trace data that was collected by a previous trace session with the same session identifier is replaced with new trace data. This is determined by checking if the set of database files where the trace data is to be stored already have file members with the same name as the specified trace session identifier (SSNID parameter).

Note: This parameter is valid only if *LIB is specified for the Data option (DTAOPT) parameter.

*YES: If trace data already exists with the specified session identifier, the old trace data is lost and replaced by the new trace data.
*NO: If trace data already exists for the specified session, an error message is sent to the user.

Top

Select jobs (SLTJOB)

Specifies which jobs to include in the data collection. This allows the user to reduce the size of the trace data by selecting only a subset of the jobs that were part of the collection. Up to 8 qualified job names can be specified.

Note: This parameter is valid only if *LIB is specified for the Data option (DTAOPT) parameter.

Single values

*ALL: All jobs that were part of the data collection are included.

Other values (up to 8 repetitions)

Element 1: Job name

Qualifier 1: Job name

name: Specify the name of the job to be included in the data collection.

Qualifier 2: User

name: Specify the name of the user of the job to be included in the data collection.

Qualifier 3: Number

000001-999999: Specify the number of the job to be included in the data collection.

Element 2: Thread ID to include

Single values

*ALL: All threads of the specified job are included.

Other values (up to 20 repetitions)

*INITIAL: Only the initial thread of the specified job is included.
thread-identifier: Specify the thread identifier of the job to be included. This is the thread ID as shown by the Work with Job (WRKJOB) command.

Top

Print trace data (PRTTRC)

Specifies whether trace data is formatted and printed after it is stored in the trace database files.

Note: This parameter is valid only if *LIB is specified for the Data option (DTAOPT) parameter.

*NO: The PRTTRC (Print Trace) command is not run as part of this command.
*YES: The PRTTRC (Print Trace) command is run after the trace data has been stored in the database files.

Top

Examples

Example 1: End Most Recently Started Trace

ENDTRC   SSNID(*PRV)

This command ends the trace session started most recently by the same user who is running the ENDTRC command. The trace data will be stored in a set of files in the current library of the job, or QGPL if there is no current library for the job.

Example 2: End a Trace and Delete Trace Data

ENDTRC   SSNID(DCG1)
         OPTION(*END)
         DTAOPT(*DLT)

This command ends the trace session DCG1 and deletes the trace data.

Example 3: End a Trace Session Extracting a Specific Job to be Collected

ENDTRC   SSNID(MYTRACE)
         OPTION(*EXTRACT)
         SLTJOB((123456/MYUSER/MYJOBNAME))

This command ends the trace session MYTRACE; only the 123456/MYUSER/MYJOBNAME job is collected. The session might be extracted again later.

Top

Error messages

*ESCAPE Messages

CPF39CA: Trace session ID &1 not found.
CPF39CB: Trace session ID &1, in library &2, data exists. Specify RPLDTA(*YES).
CPF98A2: Not authorized to &1 command or API.
CPF39D3: Unable to start/end the trace.

Top