Trace Job (TRCJOB)

Trace Job (TRCJOB)

Where allowed to run: All environments (*ALL)
Threadsafe: Yes Parameters
Examples
Error messages

The Trace Job (TRCJOB) command controls traces of original program model (OPM) programs and Integrated Language Environment (ILE) procedure calls and returns that occur in the current job or in the job being serviced as a result of the Start Service Job (STRSRVJOB) command directed to that job. The command, which sets a trace on or off, can trace module flow, operating system data acquisition (including CL command traces), or both.
If the Start Service Job (STRSRVJOB) command is entered before the TRCJOB command, the job that is traced is the one identified by the STRSRVJOB command.
The TRCJOB command issues under the covers the STRTRC command when SET(*ON) is specified or the ENDTRC command when SET(*OFF) or SET(*END) is specified.
Restrictions:

The record format of the database output file must match the record format of the IBM-supplied output file QATRCJOB.
The number of trace records processed between the start and end of the trace must not exceed one million.
The Transfer Job (TFRJOB) command must not be issued while TRCJOB command is active.
The following user profiles have private authorities to use the command:

QPGMR
QSRV
QSRVBAS
QSYSOPR
QRJE

Top

Parameters

Keyword Description Choices Notes
SET Trace option setting *ON, *OFF, *END Optional, Positional 1
TRCTYPE Trace type *ALL, *FLOW, *DATA Optional, Positional 2
MAXSTG Maximum storage to use 1-16000, 4096 Optional, Positional 3
TRCFULL Trace full *WRAP, *STOPTRC Optional, Positional 4
EXITPGM Program to call before trace Single values: *NONE
Other values: Qualified object name Optional
Qualifier 1: Program to call before trace Name
Qualifier 2: Library Name, *LIBL, *CURLIB
SLTPRC Select procedures to trace Single values: *ALL, *NONE
Other values (up to 50 repetitions): Element list Optional
Element 1: Program Qualified object name
Qualifier 1: Program Name
Qualifier 2: Library Name, *LIBL, *CURLIB
Element 2: Type *PGM, *SRVPGM
SLTTHD Thread ID to include Single values: *ALL, *SELECT
Other values (up to 20 repetitions): Hexadecimal value Optional
OUTPUT Output *PRINT, *OUTFILE Optional
OUTFILE File to receive output Qualified object name Optional
Qualifier 1: File to receive output Name
Qualifier 2: Library Name, *LIBL, *CURLIB
OUTMBR Output member options Element list Optional
Element 1: Member to receive output Name, *FIRST
Element 2: Replace or add records *REPLACE, *ADD

Top

Trace option setting (SET)

Specifies whether the collection of trace records starts or stops.

*ON

The collection of trace records is started.

*OFF

The collection of trace records is stopped, and the trace records are written to the spooled printer file or output file.

*END

The collection of trace records is stopped, and all existing trace records are deleted. No spooled printer file is created.

Top

Trace type (TRCTYPE)

Specifies the type of trace data to store in a trace file.

*ALL

All the trace data collected is stored in trace records. This includes tracing the flow of control and the trace data itself.

*FLOW

The flow of control is traced when OPM programs and ILE procedures are called and when they return control.

*DATA

The data is provided at predefined trace points within the operating system stored in trace records. This includes trace records for the CL commands that have run.

Top

Maximum storage to use (MAXSTG)

Specifies the maximum amount of storage used for collected trace records.

4096

A maximum of 4096 kilobytes of storage is used.

1-16000

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

Top

Trace full (TRCFULL)

Specifies whether the trace records are to wrap (replace oldest records with new records) or to set trace off when all of the storage has been used.

*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 file is full of trace records.

Top

Program to call before trace (EXITPGM)

This parameter is no longer used.

Top

Select procedures to trace (SLTPRC)

This parameter is no longer used.

Top

Thread ID to include (SLTTHD)

Specifies a list of up to twenty threads whose calls and returns are included in the trace. Only trace records for the specified thread identifiers are included.
Single values

*ALL

All threads calls and returns are included in the trace.

*SELECT

A list of thread identifiers is shown from which the user can select up to twenty whose trace records are to be included.

Other values

hexadecimal-value

Specify the identifiers of up to twenty threads whose trace records are to be included.

Top

Output (OUTPUT)

Specifies whether the output from the command is printed with the job's spooled output or sent to a database file.

*PRINT

The output is printed with the job's spooled output.

*OUTFILE

The output is directed to the database file specified for the File to receive output (OUTFILE) parameter.

Top

File to receive output (OUTFILE)

Specifies the database file to which the output of the command is directed. If the file does not exist, this command creates a database file in the specified library. If the file is created, the public authority for the file is the same as the create authority specified for the library in which the file is created. Use the Display Library Description (DSPLIBD) command to show the library's create authority.
Qualifier 1: File to receive output

name

Specify the name of the database file to which the command output is directed.

Qualifier 2: Library

*LIBL

The library list is used to locate the file. If the file is not found, one is created in the current library. If no current library exists, the file will be created in the QGPL library.

*CURLIB

The current library for the thread is used to locate the file. If no library is specified as the current library for the thread, the QGPL library is used.

name

Specify the name of the library to be searched.

Top

Output member options (OUTMBR)

Specifies the name of the database file member that receives the output of the command.
Element 1: Member to receive output

*FIRST

The first member in the file receives the output. If OUTMBR(*FIRST) is specified and the member does not exist, the system creates a member with the name of the file specified for the File to receive output (OUTFILE) parameter. If the member already exists, you have the option to add new records to the end of the existing member or clear the member and then add the new records.

name

Specify the name of the file member that receives the output. If it does not exist, the system creates it.

Element 2: Replace or add records

*REPLACE

The system clears the existing member and adds the new records.

*ADD

The system adds the new records to the end of the existing records.

Top

Examples

Example 1: Tracing Flow of Control
 TRCJOB   TRCTYPE(*FLOW)  MAXSTG(40)
This command traces the flow of the current job. Trace records are collected for each OPM program and ILE procedure call and return that occurs in the job. The trace file contains 40K of storage and wraps (oldest records are replaced by new records) if that amount of storage is filled with trace records.
Example 2: Stopping the Trace Operation
 TRCJOB   SET(*OFF)  OUTPUT(*OUTFILE)
         OUTFILE(QGPL/TRCJOB)  OUTMBR(TRCDTA)
This command stops the trace and directs the output to the database file QGPL/TRCJOB. The output is directed to the member TRCDTA.
Example 3: Tracing One Thread
 TRCJOB   SET(*ON)  SLTTHD(00000001)
This command traces only the specified thread of the current job.

Top

Error messages

*ESCAPE Messages

CPF2C94

Error occurred during OUTFILE processing. Trace stopped.

CPF2C95

Trace already active.

CPF2C96

Trace already off.

CPF3510

User exit program not found in specified library.

CPF3511

Trace already active.

CPF3512

Trace already off.

CPF3513

Cannot set Trace Off, trace started from another job.

CPF3521

Not enough storage for the trace table.

CPF3530

Conflicting entries in index QSERVICE.

CPF3542

Job not traced because it is being serviced.

CPF3548

Serviced job completed running.

CPF3675

Cannot allocate QSYS library.

CPF3909

Service command will not be processed.

CPF3918

Service request canceled.

CPF3925

Cannot open file &1.

CPF3936

Job being serviced ended before trace started.

CPF3950

Error message &2 received for file &1. Request ended.

CPF3951

File &1 cannot be overridden by file name &2.

CPF3957

Not authorized to use exit program library &2.

CPF3969

Error during close of file &1. Output may not be complete.

CPF6611

Error occurred during OUTFILE processing, trace ended.

CPF6801

Command prompting ended when user pressed &1.

CPF9810

Library &1 not found.

CPF98A4

Thread restrictions exist for some other process.

Top

Keyword	Description	Choices	Notes
SET	Trace option setting	ON, OFF, *END	Optional, Positional 1
TRCTYPE	Trace type	ALL, FLOW, *DATA	Optional, Positional 2
MAXSTG	Maximum storage to use	1-16000, 4096	Optional, Positional 3
TRCFULL	Trace full	WRAP, STOPTRC	Optional, Positional 4
EXITPGM	Program to call before trace	Single values: NONE Other values: Qualified object name*	Optional
	Qualifier 1: Program to call before trace	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
SLTPRC	Select procedures to trace	Single values: ALL, NONE Other values (up to 50 repetitions): Element list	Optional
	Element 1: Program	Qualified object name
	Qualifier 1: Program	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
	Element 2: Type	PGM, SRVPGM
SLTTHD	Thread ID to include	Single values: ALL, SELECT Other values (up to 20 repetitions): Hexadecimal value	Optional
OUTPUT	Output	PRINT, OUTFILE	Optional
OUTFILE	File to receive output	Qualified object name	Optional
	Qualifier 1: File to receive output	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
OUTMBR	Output member options	Element list	Optional
	Element 1: Member to receive output	Name, *FIRST
	Element 2: Replace or add records	REPLACE, ADD