CL Command Reference - STRTRC
CL Command List > STRTRC Reference
Description:
The Start Trace (STRTRC) command starts traces of original program model (OPM) programs and Integrated Language Environment (ILE) procedures and Java programs (both compiled and JIT). Tracing can be done for multiple jobs using this command. Any number of trace sessions can be started, but active trace session identifiers must be unique across the system. This command can trace call-return flow, data returned by trace points defined in the operating system, component trace information or all three.
The trace session continues until ended with the End Trace (ENDTRC) command or automatically by the watch for trace event functionality. A trace session can be ended from the same job or a different job.
Restrictions:
. To use this command, you must have service (*SERVICE) special authority, or be authorized to the Service Trace function of Operating System through iSeries 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 you specify a generic user name for the Job name (JOB) parameter, you must have all object (*ALLOBJ) special authority, or be authorized to the Trace Any User function of Operating System through iSeries Navigator¡¯s Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_ALLOBJ_TRACE_ANY_USER, can also be used to change the list of users that are allowed to perform trace operations.
. A trace cannot be defined to trace all job names and all users.
. At least one generic job name must be specified if *YES has been specified for the Restart after next IPL (RESTRIPL) parameter.
. Watch-related parameters cannot be specified if *YES is specified for the RESTRIPL parameter.
. Only one STRTRC command across the system can be specified to restart after the next IPL.
. When the Watched job (WCHJOB) parameter is specified, the issuer of the command must be running under a user profile which is the same as the job user identity of the job being watched, or the issuer of the command must be running under a user profile which has job control (*JOBCTL) special authority. Job control (*JOBCTL) special authority is also required if a generic user name is specified for the WCHJOB parameter.
. If you specify a generic user name in the WCHJOB parameter, you must have all object (*ALLOBJ) special authority, or be authorized to the Watch Any Job function of Operating System through iSeries Navigator¡¯s Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_WATCH_ANY_JOB, can also be used to change the list of users that are allowed to start and end watch operations.
. You must have operational (*OBJOPR) and execute (*EXECUTE) authorities to the user exit program if specified in Trace program (TRCPGM) parameter, and execute (*EXECUTE) authority to the library where the program is located.
. You must have use (*USE) authority to the message queues specified in Watched message queue (WCHMSGQ) parameter, and use (*USE) authority to the library where the message queue is located.
Examples:
Example 1: Start a Trace on Your Job
STRTRC SSNID(*GEN)
This command starts a trace on the job that called the STRTRC command. A unique trace session identifier will be generated. The session identifier will be returned in the message data of a completion message sent after the trace session starts successfully.
Example 2: Start a Trace of Another Job
STRTRC JOB(123456/QSYS/QSYSARB) SSNID(ARBTRACE)
This command starts a new trace on the job with job name QSYSARB, job user name of QSYS, and job number of 123456. Only this one job is traced. The trace session identifier is ARBTRACE.
Example 3: Start a Generic Job Trace
STRTRC SSNID(*GEN) JOB(*ALL/QSYS/QTVTELNET*) MAXSTG(80000)
This command starts a new trace on all jobs on the system that have a job name that begins with QTVTELNET and are running under the QSYS user profile. The maximum storage used for the trace will be 80000 kilobytes. A unique session identifier will be generated.
Example 4: Start a Job Trace with a Filter
ADDTRCFTR FTR(MYFTR) PGMTRG(*EQ MYLIB/MYPGM *ALL *PGM *ENTRY)
STRTRC SSNID(MYTRACE)JOB(123456/MYUSER/MYJOB) TRCFTR(MYFTR)
These commands add a trace filter for MYPGM in MYLIB. When the trace is started, call/return trace records will not be collected until MYLIB/MYPGM is called. Once MYLIB/MYPGM is called, the trace will collect call/return trace records until the trace is ended.
Example 5: Start a Job Trace with Component Defined
STRTRC JOB(123456/MYUSER/MYJOB) SSNID(MYTRACE) TRCTYPE(*ENVVAR *VERBOSE)
This command starts a new trace on the job with job name MYJOB, job user name of MYUSER, and job number of 123456. Only this one job is traced. The trace session identifier is MYTRACE. The trace will collect call/return trace information as well as information for the ENVVAR component at VERBOSE level.
Example 6: Start a Job Trace with Threads Selection
STRTRC JOB((123456/MYUSER/MYJOB (11111111 22222222))) SSNID(MYTRACE)
This command starts a new trace on the job with job name MYJOB, job user name of MYUSER, and job number of 123456. Only threads 11111111 and 22222222 are traced. The trace session identifier is MYTRACE.
Example 7: Start a Trace and Watch for a Message to End the Trace
STRTRC SSNID(*GEN) WCHMSG((MCH2804)) WCHMSGQ((*SYSOPR) (*JOBLOG))
WCHJOB((*ALL/MYUSER/MYJOBNAME)) TRCPGM(MYLIB/TRCEXTPGM)
This command starts a trace on the job that called the STRTRC command. The trace will be ended when MCH2804 message is found on the System Operator message queue or within the *ALL/MYUSER/MYJOBNAME job log. Also, MYLIB/TRCEXTPGM is specified as a trace exit program.
Example 8: Start a Trace and Watch for a LIC Log Entry to End the Trace
STRTRC SSNID(*GEN) WCHLICLOG((¡¯99??¡¯ 9932 MYJOBNAME)) WCHTIMO(*NOMAX)
This command starts a trace on the job that called the STRTRC command. The trace will be ended when a Licensed Internal Code (LIC) log entry that has a major code starting with 99 and a minor code of 9932 is generated on the system. Also, the LIC log information should contain the text ¡åMYJOBNAME¡å. *NOMAX on WCHTIMO parameter indicates that the trace will be active until the event occurs or ENDTRC command is issued manually.