Trace Job (TRCJOB)

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:

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

Parameters

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.

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.

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.)

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.

Program to call before trace (EXITPGM)

This parameter is no longer used.

Select procedures to trace (SLTPRC)

This parameter is no longer used.

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.

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.

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.

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.

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.

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.