TRCJOB (Trace Job)

TRCJOB Command syntax diagram

 

Purpose

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. This command, which sets a trace on or off, can trace module flow, OS/400 system data acquisition (including CL command traces), or both.

As the trace records are collected, they are stored in an internal trace storage area. When the trace is ended, the trace records can be written to a spooled printer file, QPSRVTRC. The trace records can also be directed to a database output file.

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 trace output from the serviced job is returned to the servicing job after the trace is set off or after the serviced job has ended.

 

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. This command is shipped with public *EXCLUDE authority.
4. The following user profiles have private authorities to use the command:

   • QPGMR
   • QSRV
   • QSRVBAS
   • QSYSOPR
   • QRJE

 

Required Parameters

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.

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

TRCTYPE

Specifies the type of trace data to be stored 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 that is provided at predefined trace points within the OS/400 system is stored in trace records. This includes trace records for the CL commands that have run.

MAXSTG

Specifies the maximum amount of storage in kilobytes (K) used for collected trace records.

4096: Up to 4096 K-bytes of storage is used.

maximum-K-bytes: Specify the maximum amount of storage, in K-bytes, used to store trace records (one K equals 1024 bytes).

Note:

The maximum amount of storage, in kilobytes, is 16000.

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.

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

EXITPGM

Specifies the qualified name of a user-written program that is given control just prior to the collection of each trace record.

Note:

Items being traced can be missed when an exit program is used. Do not use an exit program if you do not want to risk losing a trace record.

*NONE: No user-written program is called.

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the name of the user-written program called before each trace record is collected. This program can examine the trace record passed to it as a parameter, and alter the first two characters. If it replaces the first two characters in the trace record with blanks or binary zeros, the entire trace record is suppressed.

This program can also call any of the service dump commands and must return control when it completes its task. If the user-written program runs other OS/400 system commands, the output from those commands is associated with the job in which they are run. The dump and trace commands associate their output data either with the job that enters the dump and trace commands or with the job being serviced as the result of the STRSRVJOB command.

SLTPRC

Specifies which ILE procedure calls and returns are included in the trace.

*ALL: All ILE procedure calls and returns are included in the trace.

*NONE: No ILE procedure calls or returns are included in the trace.

Element 1: Program Name

The name of the program can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

program-name: Specify the names of a maximum of 50 bound programs and bound service programs for which all procedure calls and returns are included in the trace.

Element 2: Program Type

*PGM: The specified program is a bound program.

*SRVPGM: The specified program is a bound service program.

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.

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

thread-identifier: Specify the identifiers of up to twenty threads whose trace records are to be included.

OUTPUT

Specifies whether the output from the command is shown at the requesting workstation or printed with the job's spooled output. More information on this parameter is in Commonly used parameters.

*PRINT: The output is printed with the job's spooled output.

*OUTFILE: The output is directed to the database file specified on the OUTFILE parameter.

OUTFILE

Specifies the physical database file to which the trace output is directed. If the output file already exists, the system tries to use it. Records replace existing data in the file member. If the output file does not exist, the system creates a database physical file (with the name specified in the OUTFILE parameter) in the specified library. A member is created for the file with the name specified in the OUTMBR parameter. If the file is created, the text is "OUTFILE created by TRCJOB command," and *EXCLUDE authority is given to users with no specific authority.

The name of the file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

file-name: Specify the name of the file to receive the trace output.

OUTMBR

Specifies the name of the database file member to which the output is directed. If a member already exists, the system uses the second element of this parameter to determine whether the member is cleared before the new records are added. If the member does not exist and a member name is not specified, the system creates a member with the name of the output file specified on the OUTFILE parameter. If an output file member name is specified, but the member does not exist, the system creates it.

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 on the OUTFILE parameter.

member-name: Specify the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it.

Element 2: Operation to Perform on Member

*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 for TRCJOB

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 Flow of Control - Selecting Specific ILE Procedures

TRCJOB  SET(*ON)  TRCTYPE(*FLOW)                                                
  SLTPRC((MYLIB/MYPGM1 *PGM) (MYLIB/MYSRVPGM1 *SRVPGM))                         

This command traces the flow of the current job. Trace records are collected for all OPM program calls and returns and the ILE procedure calls and returns of bound program MYPGM1 and bound service program MYSRVPGM1.

Example 4: Tracing one thread

TRCJOB  SET(*ON)  SLTTHD(00000001)                                              

This command traces only the specified thread on the job.

Error messages for TRCJOB

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

CPF9810

Library &1 not found.