STRTRC (Start Trace)

STRTRC Command syntax diagram

 

Purpose

The Start Trace (STRTRC) command starts traces of original program model (OPM) programs, Integrated Language Environment (ILE) procedures and JAVA (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.End of change

The trace session continues until ended with the End Trace (ENDTRC) command. A trace session can be ended from the same job or a different job.

 

Restrictions

  1. To use this command have *SERVICE special authority, or be authorized to the Service Trace function of the operating system through iSeries Navigator's Application Administration support. The Change Function Usage Information (QSYCHFUI) API, 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.

  2. A job can be part of only one active trace session. Once the trace session ends (ENDTRC command), the job can be part of another trace session.

  3. Only one generic job specification can be active across all active trace sessions on your system. Once the trace ends that included a generic job specification, another trace session can be started specifying a generic job name.

 

Required Parameters

SSNID
Specifies a session identifier for this trace. This identifier must be unique across all active traces on the system.

*GEN: The system will generate a unique session identifier for this trace.

session-identifier: Specify the session identifier for this trace.

 

Optional Parameters

JOB
Specifies which jobs are to be traced.

Single Value

*: Only the job that issues the STRTRC (Start Trace) command is traced.

Element 1: Job Identifier>

Job Name Qualifier

job-name: Specify the name of the job to be traced. Up to eight job names may be specified, but only one generic job name is allowed.

generic*-job-name: Specify the generic name of the job to be traced. A generic name is a character string of one or more characters followed by an asterisk (*); for example, ABC*. The asterisk substitutes for any valid characters. A generic job name specifies all jobs with job names that begin with the generic prefix. Only one active trace session can have a generic job specification.

Job User Name Qualifier

user-name: Specify the name of the user of the job to be traced.

Job Number Qualifier

*ALL: All jobs with the specified job name and user name are traced. *ALL for the job number is considered to be a generic job specification because it will trace all jobs that meet the job name and job user name qualifiers that you specified. Only one active trace session can have a generic job specification.

job-number: Specify the job number to further qualify the job name and user name. You cannot specify a job number if a generic job name qualifier is specified.

Element 2: Thread ID to Include

Specifies a list of up to twenty threads in the job whose information is to be included.

*ALL: All threads within the specified job name and user name are traced

*INITIAL: Only the initial thread within the specified job name and user name is traced.

*SELECT: A list of thread identifiers is shown from which the user can select up to twenty to be traced. This value is only valid if the command is run in an interactive job.

thread-identifier: Specify the identifiers of up to twenty threads whose information is to be included.

MAXSTG
Specifies the maximum amount of storage, in kilobytes (K), to use for the collected trace records. The system will calculate the minimum amount of storage that is necessary for the trace; this minimum storage size calculation is dependent upon the system's processor configuration. The minimum amount of storage may be significantly larger than the size specified on the MAXSTG parameter; the system will use the larger of the two values.

10000: Up to 10,000 kilobytes of storage is used.

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

Note: The maximum amount of storage is 4,000,000 kilobytes.

TRCFULL
Specifies whether the trace records wrap (replace the 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 storage 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 storage is full of trace records.

JOBTRCTYPE
Specifies the types of job trace data to be stored in the 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.

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

*TRCTYPE: Trace specific components specified in the trace type parameter.

TRCTYPE
Specifies the component to trace and the level to use.

*NONE: No component trace is specified

Element 1: Trace Type Component

Each trace type is identified by a special value. For a complete list of components, position the cursor on the field for the Trace type prompt (TRCTYPE parameter), and press F4. Specify up to 50 trace components from the following table

Table 1. Trace Type Table

Trace Description Special Value
ASP Management *ASPMGT
Directory Services *DIRSRV
Environment Variable APIs *ENVVAR
HTTP Server powered by Apache *HTTP
Interprocess Communication APIs *IPC
Lock Space Management *LOCKSPACE
POSIX Miscellaneous APIs *POSIXMISC
POSIX Process-Related APIs *POSIXPROC
POSIX Thread APIs *PTHREAD
Qshell *QSHELL
Software Security *SECURITY
Sockets APIs *SOCKETS
Thread Managemet *THREADMGT

Element 2: Trace Level

Specifies the trace level to be used for the specified component

*ERROR: The trace level ERROR will be used. Components typically trace error return codes, exception conditions, and invalid input. The amount of data is usually small.

*INFO: The trace level INFO will be used, which also includes ERROR trace level data. Components typically trace entry and exit from interfaces, parameters and return codes, and major changes of flow or semantics caused by input or other decisions. The amount of data is moderate.

*VERBOSE: The trace level VERBOSE will be used, which also includes INFO and ERROR trace level data. Components typically trace detailed data that could assist in debugging control flow, data corruption, data structures, environment, call stacks, and resource allocations. The amount of data can be large.

TRCFTR
Specifies the trace filter to be used. The Add Trace Filter (ADDTRCFTR) command must be issued to define the trace filter. The filter determines what information is collected in the trace based on the filter values. The filter values are compared to the actual trace data. If a filter is not specified, then all trace information is collected.

The trace filter parameter can only be specified if *ALL or *FLOW has been specified on the job trace type parameter.
 

Note: The trace filter applies to the *FLOW (call/return) trace only.

*NONE: No trace filter will be used.

trace_filter_name: The name of the trace filter created with ADDTRCFTR command.>

Examples for STRTRC

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.End of change

Error messages for STRTRC

*ESCAPE Messages

CPC3921
STRTRC session ID &1 successfully started.
CPC3922
STRTRC session ID &1 started but some jobs not found.
CPF39C6
A generic job STRTRC session is already active.
CPF39C7
STRTRC session ID &1 already exists.
CPF39C8
STRTRC job name conflict with session ID &1.
CPF39C9
Unexpected STRTRC failure, see low-level messages.
CPF39C5
Only one generic job name or job number allowed.
CPF39CC
No active jobs found, STRTRC session not started.
CPI36CE
Job &3/&2/&1 not found.