Start Trace (STRTRC)

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:

Parameters

Keyword Description Choices Notes
SSNID Session ID Name, *GEN Required, Positional 1
JOB Jobs Single values: *
Other values (up to 8 repetitions): Element list		 Optional
Element 1: Job name Qualified job name
Qualifier 1: Job name Generic name, name, *ALL
Qualifier 2: User Generic name, name, *ALL
Qualifier 3: Number 000001-999999, *ALL
Element 2: Thread ID to include Single values: *ALL, *SELECT
Other values (up to 20 repetitions): Character value, *INITIAL
Element 3: Subsystem Generic name, name, *ALLSBS
JOINTRC Join trace *NO, *YES Optional
JOBTYPE Job types *ALL, *ACTIVE, *NEW Optional
MAXSTG Maximum storage to use 1024-4000000, 10000 Optional
TRCFULL Trace full *STOPTRC, *WRAP Optional
JOBTRCTYPE Trace type Values (up to 2 repetitions): *ALL, *FLOW, *DATA, *TRCTYPE Optional
TRCTYPE Trace type Single values: *NONE
Other values (up to 50 repetitions): Element list		 Optional
Element 1: Component Character value, *ASPMGT, *CKMAPI, *CLUSTER, *CMTCTL, *DBDDM, *DBDRDA, *DBHSVR, *DBQRY, *DBSQL, *DBSQLXML, *DEVCFG, *DIRSRV, *EDRSQL, *ENVVAR, *FILESVR, *FLIGHTRCD, *HPT, *HTTP, *IFS, *IPC, *IPPDRV, *LOCKSPACE, *LWI, *NETSVR, *NFS, *NPS, *NWSCFG, *NWSSTG, *OBJLCK, *OPASSIST, *OPENSSL, *POSIXMISC, *POSIXPROC, *PRTTFMSRV, *PTHREAD, *QNTC, *QSHELL, *RAS, *RCDLCK, *REGFAC, *REXEC, *ROUTING, *SAVRST, *SECURITY, *SERVICE, *SIGNAL, *SMTPAPI, *SNMP, *SOCKETS, *SPCLCK, *SPOOL, *SRVCFG, *SVRVRY, *TCPIPCFG, *THREADMGT, *WRKMGT, *WSFM
Element 2: Trace level *ERROR, *INFO, *VERBOSE
TRCFTR Trace filter Name, *NONE Optional
RESTRIPL Restart after next IPL *NO, *YES Optional
WCHMSG Watch for message Single values: *NONE
Other values (up to 5 repetitions): Element list		 Optional
Element 1: Message to watch Generic name, name, *ALL, *IMMED
Element 2: Comparison data Character value, *NONE
Element 3: Compare against *MSGDTA, *FROMPGM, *TOPGM
Element 4: Message type *ALL, *COMP, *DIAG, *ESCAPE, *INFO, *INQ, *NOTIFY, *SCOPE, *STATUS
Element 5: Relational operator *GE, *EQ, *GT, *LT, *LE
Element 6: Severity code 0-99, 00
WCHMSGQ Watched message queue Values (up to 3 repetitions): Element list Optional
Element 1: Message queue Single values: *SYSOPR, *JOBLOG, *HSTLOG
Other values: Qualified object name
Qualifier 1: Message queue Name
Qualifier 2: Library Name, *LIBL
WCHJOB Watched job Single values: *
Other values (up to 5 repetitions): Element list		 Optional
Element 1: Job name Qualified job name
Qualifier 1: Job name Generic name, name
Qualifier 2: User Generic name, name
Qualifier 3: Number 000001-999999, *ALL
WCHLICLOG Watch for LIC log entry Single values: *NONE
Other values (up to 5 repetitions): Element list		 Optional
Element 1: Major code Character value, *ALL
Element 2: Minor code Character value, *ALL
Element 3: Comparison data Character value, *NONE
Element 4: Compare against *ALL, *TDENBR, *TASKNAME, *SVRTYPE, *JOBNAME, *JOBUSR, *JOBNBR, *THDID, *EXCPID, *MODNAME, *MODRUNAME, *MODEPNAME, *MODOFFSET, *MODTSP
WCHPAL Watch for PAL entry Single values: *NONE
Other values (up to 5 repetitions): Element list		 Optional
Element 1: System reference code Character value, *ALL
Element 2: Comparison data Character value, *NONE
Element 3: Compare against *RSCNAME, *RSCTYPE, *RSCMODEL
WCHTIMO Length of time to watch 1-43200, *NOMAX Optional
TRCPGM Trace program Single values: *NONE
Other values: Qualified object name		 Optional
Qualifier 1: Trace program Name
Qualifier 2: Library Name, *LIBL
TRCPGMITV Time interval 1-9999, *NONE Optional
RUNPTY Run priority 1-99, 25 Optional

Session ID (SSNID)

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

This is a required parameter.

*GEN
The system will generate a unique session identifier for this trace.
name
Specify the session identifier for this trace.

Job name (JOB)

Specifies which jobs are to be traced. If the specified jobs are in the specified subsystem, then those jobs will be part of the trace collection and data will be collected for those jobs.

Single values

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

Other values (up to 8 repetitions)

Element 1: Job name

Qualifier 1: Job name

*ALL
All jobs names with the specified job user name are traced. *ALL for the job name is considered to be a generic job specification because it will trace all jobs that meet the job user name qualifiers that you specified.
generic-name
Specify the generic name of the jobs 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.
name
Specify the name of the job to be traced. Up to eight job names may be specified.

Qualifier 2: User

*ALL
All job user names with the specified job name are traced. *ALL for the job user name is considered to be a generic job specification because it will trace all jobs that meet the job name qualifiers that you specified.
generic-name
Specify the generic user name of the jobs from which trace records are to be collected. 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 user name specifies all jobs with user names that begin with the generic prefix.
name
Specify the user name of the job to be traced.

Qualifier 3: Number

*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.
000001-999999
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 or generic user name qualifier is specified.

Element 2: Thread ID to include

Single values

*ALL
All threads within the specified job name and user name are 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.

Other values (up to 20 repetitions)

*INITIAL
Only the initial thread within the specified job name and user name is traced.
thread-identifier
Specify the identifiers of up to twenty threads whose information is to be included. This is the thread ID as shown by the Work with Job (WRKJOB) command.

Element 3: Subsystem

*ALLSBS
The specified jobs will be part of the trace collection regardless of which subsystem the jobs are in.
generic-name
Specify the generic name of the subsystem that contains the jobs to be included in the trace collection. 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.
name
Specify the name of the subsystem that contains the jobs to be included in the trace collection.

Join trace (JOINTRC)

Specifies if the specified jobs will set their trace characteristics in a related job or thread, meaning that the related job or thread will be added to the trace collection. Examples of related threads are jobs submitted because of spawn API being called or pre-start jobs doing work for a parent job.

Note: Only one STRTRC command can be specified to set the trace characteristics of a job in a related job or thread. If another STRTRC command was previously specified with JOINTRC(*YES), an error message is sent and the second STRTRC command fails.

Note: The trace characteristics will be set only to one level. This is, if a related job or thread (that already adopted the trace characteristics of the original job) generates a second job or thread, the trace characteristics will not be set to this job.

*NO
The trace characteristics of the specified jobs will not be set in a related job or thread.
*YES
The trace characteristics of the specified jobs will be set in a related job or thread.

Job types (JOBTYPE)

Specifies the types of jobs for which trace data is to be collected.

*ALL
All jobs that meet the job name selection criteria will be included in this trace collection. This includes jobs that are currently active on the system. If a generic job name was specified, new jobs that start after this trace session begins and meet the generic job name selection criteria, will be included in the trace collection as well.
*ACTIVE
Only jobs that are currently active at the time this trace session is being activated and meet the job name selection criteria will be included in this trace collection.
*NEW
Only new jobs that begin after this trace session is activated and meet the generic job name selection criteria will be included in this trace collection.

Maximum storage to use (MAXSTG)

Specifies the requested 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.
1024-4000000
Specify the maximum amount of storage, in kilobytes, to be used to store trace records (one kilobyte equals 1024 bytes).

Trace full (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.

Trace type (JOBTRCTYPE)

Specifies the types of job trace data to be stored in the trace file.

You can specify 2 values for this parameter.

*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 the specific components specified for the Trace type (TRCTYPE) parameter.

Trace type (TRCTYPE)

Specifies the component to trace and the level to use. You can specify up to 50 trace components to be traced.

Single values

*NONE
No component trace is specified.

Element 1: Component

Specify the component to trace. The component can be either a user-defined component name, which is typically defined by an application provider, or a pre-defined special value, which is defined by the operating system. Special value can be selected from the following table: 

TRACE DESCRIPTION                             SPECIAL VALUE
ASP Management                                *ASPMGT
Crytographic Key Management APIs              *CKMAPI
Cluster Resource Services                     *CLUSTER
Commitment Control                            *CMTCTL
Distributed Data Management                   *DBDDM
Distributed Relational Database Architecture  *DBDRDA
Database Host Server                          *DBHSVR
Database Query Engine                         *DBQRY
Database SQL                                  *DBSQL
Database SQL XML                              *DBSQLXML
Device Configuration                          *DEVCFG
Directory Services                            *DIRSRV
Extended Dynamic Remote SQL (EDRS)            *EDRSQL
Environment Variable APIs                     *ENVVAR
File Server                                   *FILESVR
Flight Recorder                               *FLIGHTRCD
Host Print Transform                          *HPT
HTTP Server powered by Apache                 *HTTP
Integrated File System                        *IFS
Interprocess Communication APIs               *IPC
Internet Print Protocol Driver                *IPPDRV
Lock Space Management                         *LOCKSPACE
LightWeight Infrastructure                    *LWI
System i5 NetServer                           *NETSVR
Network File System                           *NFS
Network Print Server                          *NPS
Network Server Configuration                  *NWSCFG
Network Server Storage Spaces                 *NWSSTG
Object Locks                                  *OBJLCK
Operational Assistant                         *OPASSIST
OpenSSL APIs                                  *OPENSSL
POSIX Miscellaneous APIs                      *POSIXMISC
POSIX Process-Related APIs                    *POSIXPROC
Print Transform Services                      *PRTTFMSRV
POSIX Thread APIs                             *PTHREAD
QNTC File System                              *QNTC
Qshell                                        *QSHELL
Remote Access Services                        *RAS
Record Locks                                  *RCDLCK
Registration Facility                         *REGFAC
REXEC Server                                  *REXEC
OSPF and RIP protocols server                 *ROUTING
Save/Restore                                  *SAVRST
Software Security                             *SECURITY
Service Facility                              *SERVICE
Signal APIs                                   *SIGNAL
SMTP APIs                                     *SMTPAPI
Simple Network Management Protocol            *SNMP
Sockets APIs                                  *SOCKETS
Space Location Locks                          *SPCLCK
Spool functions                               *SPOOL
Service Configuration                         *SRVCFG
Integrated Server Vary Processing             *SVRVRY
TCP/IP Configuration                          *TCPIPCFG
Thread Management                             *THREADMGT
Work Management                               *WRKMGT
Workstation Function Manager                  *WSFM

Element 2: Trace level

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

Trace filter (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 for the Trace type (JOBTRCTYPE) parameter. The trace filter applies to the *FLOW (call/return) trace only.

*NONE
No trace filter will be used.
name
Specify the name of the trace filter to be used.

Restart after next IPL (RESTRIPL)

Specifies if the trace will be restarted after the next initial program load (IPL) of the operating system.

Note: Only one STRTRC command can be specified to restart after the next IPL. If another STRTRC command was previously specified with RESTRIPL(*YES), an error message is sent and this STRTRC command fails. This parameter can be specified only if at least one generic job name is specified in the Job name (JOB) parameter. You must run the End Trace (ENDTRC) command for the trace session which specified RESTRIPL(*YES) to clear the storage used to hold the STRTRC command string to be restarted after an IPL. This parameter cannot be specified if any watch-related parameters have been specified.

Note: If the IPL is associated with an install or upgrade of the operating system, the trace will not be restarted.

*NO
The trace will not be restarted after an IPL.
*YES
The trace will be restarted after the next IPL. The trace being started by this STRTRC automatically ends if an IPL of the operating system is performed. The trace started after the next IPL will be a new trace session with new trace data. You can use the ENDTRC command to end the trace.

Watch for message (WCHMSG)

Specifies up to five messages which are to be watched. If a value other than *NONE is specified, you must specify where to watch for the message on the WCHMSGQ parameter. When the watched for message is added to the specified message queue or log, the trace exit program is called; if no trace exit program is defined, the trace stops.

Note: Moved and resent messages will not be watched. Only the original instance of the message can be watched.

Note: Watching for message id CPF1124 or CPF1164 will be ignored in job QSCWCHPS (which handles watch processing). A user exit program will not be triggered when CPF1124 or CPF1164 is issued in job QSCWCHPS.

Single values

*NONE
No messages will be watched.

Element 1: Message to watch

*ALL
All messages are to be watched. This includes stored messages and immediate messages. Be aware that watching for all messages might cause performance degradation on your system. Use it cautiously.
*IMMED
All immediate or impromptu messages will be watched.
generic-name
Specify the generic message identifier to be watched. 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 message name specifies all messages with message identifiers that begin with the generic prefix.
name
Specify the 7-character message identifier to be watched.

Element 2: Comparison data

Specify comparison data to be used if a message matching the specified message is added to the specified message queue or log. If the message data, the "From program" or the "To program" includes the specified text, the watched for condition is true. If the message data, the "From program" or the "To program" does not contain the specified text, the trace function continues.

*NONE
No comparison data is specified. If a message matching the specified message is added to the specified message queue or log, the watched for condition is true.
character-value
Specify the text string used to compare against the message data, the "From program" or the "To program" of the watched for message. This text is case sensitive and can be quoted in order to specify imbedded or trailing blanks.

Element 3: Compare against

Specify which part of the message the comparison data specified for element 2 is to be compared against.

*MSGDATA
The comparison data will be compared against the message replacement data.
*FROMPGM
The comparison data will be compared against the name of the program sending the message, or the name of the ILE program that contains the procedure sending the message.
*TOPGM
The comparison data will be compared against the name of the program the message was sent to, or the name of the ILE program that contains the procedure the message was sent to.

Element 4: Message type

Specify the message type assigned to the message to be watched.

*ALL
All the message types are to be watched. This includes completion, command, diagnostic, escape, informational, inquiry, notify, reply, request, sender's copy, scope and status message types.
*COMP
A completion message is to be watched.
*DIAG
A diagnostic message is to be watched.
*ESCAPE
An escape message is to be watched.
*INFO
An informational message is to be watched.
*INQ
An inquiry message is to be watched.
*NOTIFY
A notify message is to be watched.
*SCOPE
A scope message is to be watched.
*STATUS
A status message is to be watched.

Element 5: Relational operator

Specify one relational operator against which the message severity code is compared.

*GE
Greater than or equal.
*EQ
Equal.
*GT
Greater than.
*LT
Less than.
*LE
Less than or equal.

Element 6: Severity code

Specifies the severity code of the message to be watched.

00
The severity code assigned to the message to be watched for is 00.
Severity-code
Specify a value, ranging from 00 through 99, as the severity level associated with the message to be watched.

Watched message queue (WCHMSGQ)

Specifies where to watch for the messages specified on the WCHMSG parameter. You can specify to watch the message being added to the system operator message queue, the history log, other message queues, and job logs. Up to three message queues or special values can be specified.

Element 1: Message queue

Single values

*SYSOPR
Watch messages added to the system operator message queue (QSYSOPR message queue in library QSYS).
*JOBLOG
Watch messages added to the job logs of the jobs specified for the Watched job (WCHJOB) parameter.
*HSTLOG
Watch messages added to the history log (QHST message queue in library QSYS).

Qualifier 1: Message queue

name
Specify the name of the message queue to watch.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
name
Specify the name of the library where the message queue is located.

Watched job (WCHJOB)

Specifies the job whose job log is watched for the messages specified on the WCHMSG parameter. The specified job will only be watched if *JOBLOG is specified on the WCHMSGQ parameter. Up to five job names may be specified.

Single values

*
Only the job log of the job that issued this trace command is watched.

Element 1: Job name

Qualifier 1: Job name

generic-name
Specify the generic name of the job to be watched. 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.
name
Specify the name of the job to be watched.

Qualifier 2: User

generic-name
Specify the generic name of the user name of the job to be watched. 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 user name specifies all jobs with the specified job name and with user names that begin with the generic prefix.
name
Specify the user name of the job to be watched.

Qualifier 3: Number

*ALL
All jobs with the specified job name and user name are watched.
000001-999999
Specify the job number to further qualify the job name and user name. You cannot specify a job number if a generic job name or a generic user name qualifier is specified.

Watch for LIC log entry (WCHLICLOG)

Specifies up to five licensed internal code (LIC) log entry identifiers which are to be watched for. Each LIC log entry contains a major and a minor code. The watched for condition will be met if a LIC log entry is added that matches the specified major and minor codes and any comparison data specified. When the watched for log entry is added to the LIC log, the trace exit program is called, even when the comparison data specified does not match; if no trace exit program is defined, the trace stops.

Single values

*NONE
No LIC log entries will be watched for.

Element 1: Major code

*ALL
Any LIC log entry major code will be considered to be a match. If *ALL is specified for the major code, you cannot specify *ALL for the LIC log entry minor code.
character-value
Specify the LIC log major code to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the four-digit code. A question mark is a wildcard character that will match any digit in that position. Up to three wildcard characters can be specified.

Element 2: Minor code

*ALL
Any LIC log entry minor code will be considered to be a match. If *ALL is specified for the minor code, you cannot specify *ALL for the LIC log entry major code.
character-value
Specify the LIC log minor code to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the four-digit code. A question mark is a wildcard character that will match any digit in that position. Up to three wildcard characters can be specified.

Element 3: Comparison data

Specify comparison data to be used if a log entry matching the specified major and minor codes is added to the licensed internal code (LIC) log. If this text is found in the LIC log entry data fields of the watched for log entry, the watched for condition is true. If this text is not found in the LIC log entry data fields of the watched for log entry and no exit program is specified on the TRCPGM parameter, the trace function continues. If the log entry matches the specified major and minor codes and an exit program is specified on the TRCPGM parameter, but the entry data does not contain the specified text, the exit program is called to determine if the trace should continue or stop.

*NONE
No comparison data is specified. If a LIC log entry matching the specified major and minor codes is added to the LIC log, the watched for condition is true.
character-value
Specify the text string used to compare against the entry data of the watched for log entry. If this text is found in the LIC log entry data field specified for element 4, the watch condition is considered to be true. This text is case sensitive. If *ALL is specified in the LIC log compare against field, the LIC log fields which will be compared are TDE number, task name, server type, job name, user ID, job number, thread ID, exception ID, LIC module compile timestamp, LIC module offset, LIC module RU name, LIC module name, LIC module entry point name. The comparison data cannot be used to match across two fields, and can match an entire field or a substring of any field.

When watching for an exception ID, all four hexadecimal digits of the exception ID must be specified. Also, the prefix MCH may be specified if you want to compare only against the exception ID field and avoid possible substring matches with the other fields.

Element 4: Compare against

Specify which part of the LIC log the comparison data specified for element 3 is to be compared against.

*ALL
The LIC log comparison data will be compared against all the fields described below.
*TDENBR
The LIC log comparison data will be compared against the number of the task dispatching element (TDE) which requested the LIC log entry.
*TASKNAME
The LIC log comparison data will be compared against the name of the task which requested the LIC log entry. Task name is blank (hex 40s) if the LIC log entry is not requested by a task.
*SVRTYPE
The LIC log comparison data will be compared against the type of server that requested the LIC log entry. Server type is blank (hex 40s) if the LIC log entry is not requested by a server.
*JOBNAME
The LIC log comparison data will be compared against the name of the job which requested the LIC log entry. LIC job name is blank (hex 40s) if the LIC log entry is not requested by a job.
*JOBUSR
The LIC log comparison data will be compared against the user name of the job which requested the LIC log entry. LIC user name is blank (hex 40s) if the LIC log entry is not requested by a job.
*JOBNBR
The LIC log comparison data will be compared against the job number (000001-999999) to further qualify the job name and user name of the job which requested the LIC log entry. LIC job number is blank (hex 40s) if the LIC log entry is not requested by a job.
*THDID
The LIC log comparison data will be compared against the thread which requested the LIC log entry. Thread identifier is binary zeros if the LIC log entry is not requested by a thread.
*EXCPID
The LIC log comparison data will be compared against the exception that caused the LIC log entry to be requested. This is a 2-byte hexadecimal field formed by concatenating to the high-order 1-byte exception group number a low-order 1-byte exception subtype number. Exception identifier is binary zeros if the LIC log entry is not requested as a result of an exception.
*MODNAME
The LIC log comparison data will be compared against the LIC module name which requested the LIC log entry. If the module name is greater than 64 characters, the LIC module name is truncated to 64 characters.
*MODRUNAME
The LIC log comparison data will be compared against the LIC module replacement unit name. LIC module RU name is always in upper case EBCDIC.
*MODEPNAME
The LIC log comparison data will be compared against the name of the entry point which requested the LIC log entry. If the entry point name is greater than 128 characters, the LIC module entry point name is truncated to 128 characters.
*MODOFFSET
The LIC log comparison data will be compared against the byte offset into the LIC module text which requested the LIC log entry.
*MODTSP
The LIC log comparison data will be compared against the timestamp of when the LIC module was compiled. The format for this field is the system time-stamp format.

Watch for PAL entry (WCHPAL)

Specifies up to five Product Activity Log (PAL) entries which are to be watched for. When the watched for PAL occurs, the trace exit program is called; if no trace exit program is defined, the trace stops.

Single values

*NONE
No PAL entries will be watched for.

Other values (up to 5 repetitions)

Element 1: System reference code

*ALL
Any system reference code will be considered to be a match.
character-value
Specify the system reference code (SRC) to be watched for. You can specify either a hexadecimal digit or a question mark for each character in the eight-digit code. A question mark is a wildcard character that will match any digit in that position. Up to seven wildcard characters can be specified. You can also specify a generic SRC that 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 SRC specifies all PAL entries with system reference codes that begin with the generic prefix.

Element 2: Comparison data

Specify comparison data to be used if a PAL entry matching the specified system reference code occurs. If the field specified in element 3 matches the specified text, the watched for condition is true. If the field specified in element 3 does not match the specified text, the watch function just continues.

*NONE
No comparison data is specified. If a PAL entry matching the specified system reference code occurs, the watched for condition is true.
character-value
Specify the text string used to compare against the field specified in element 3 of the watched for PAL entry. This text is case sensitive.

You can specify question mark (?) and asterisk (*) wildcard characters in the text string. A question mark is a single-character wildcard and will match any character in the same position. For example, '??123' will match any value that is five characters long and ends with '123'. Multiple question mark wildcard characters can be specified for the comparison data value.

An asterisk is a multiple-character wildcard character. You can specify a single asterisk wildcard character at the end of the comparison data value. For example, 'ABC*' will match any value that begins with the letters 'ABC'.

Element 3: Compare against

Specify which part of the PAL entry the comparison data specified for element 2 is to be compared against.

*RSCNAME
The comparison data will be compared against the name of the physical device that has the entry in the log. A resource name is assigned at first by the system, but may have been changed to a new value by a user.
*RSCTYPE
The comparison data will be compared against the number or word used to identify a product.
*RSCMODEL
The comparison data will be compared against the numbers or letters used to identify the feature level of a product with a given type.

Length of time to watch (WCHTIMO)

Specifies the time limit, in minutes, for watching for a message or a licensed internal code (LIC) log entry or a Product Activity Log (PAL) entry. When the specified amount of time has elapsed, the trace exit program is called (if one was specified on the TRCPGM parameter), the trace is ended, and message CPI3999 is sent to the history log.

*NOMAX
There is no time limit for watching for a particular message or LIC log entry or PAL entry.
1-43200
Specify the number of minutes that the trace will remain active while none of the watched for conditions have been met.

Trace program (TRCPGM)

Specifies the program to be called for user-defined trace commands and procedures.

The trace program will be called:

There are three input parameters and one output parameter associated with the trace program. The four parameters are required: 

1   Trace option setting   Input    Char(10)
2   Reserved               Input    Char(10)
3   Error detected         Output   Char(10)
4   Comparison data        Input    Char(*)

Allowed values for the "Trace option setting" parameter are:

*ON
The watch for trace facility is starting when the collection of trace information is started.
*MSGID
A match on a message specified on WCHMSG parameter occurred.
*LICLOG
A match on a LIC log specified on the WCHLICLOG parameter occurred.
*CMPDATA
The major and minor code of a LIC log matched, but the comparison data did not.
*INTVAL
The time interval specified on TRCPGMITV parameter is elapsed.
*WCHTIMO
The length of time to watch specified on WCHTIMO parameter is elapsed.
*PAL
A match on a PAL and any associated comparison data specified on the WCHPAL parameter occurred.

The "Reserved" parameter must be set to blanks.

Allowed values for the "Error detected" parameter are:

*CONTINUE
The trace and the watch for trace event facility will continue running.
*STOP
The trace and the watch for trace event facility will be ended.
*ERROR
Error detected by customer trace program.

Allowed values for the "Comparison data" parameter when *MSGID is specified for the "Trace option setting" parameter will be the following structure: 

OFFSET     TYPE         FIELD
Dec Hex
 0   0     BINARY(4)    Length of trace information
 4   4     CHAR(7)      Message watched
11   B     CHAR(9)      Reserved
20  14     BINARY(4)    Offset to comparison data
24  18     BINARY(4)    Length of comparison data
 *   *     CHAR(*)      Message comparison data

Allowed values for the "Comparison data" parameter when *LICLOG or *CMPDATA is specified for the "Trace option setting" parameter will be the following structure: 

OFFSET     TYPE         FIELD
Dec Hex
 0   0     BINARY(4)    Length of trace information
 4   4     CHAR(4)      LIC Log major code
 8   8     CHAR(4)      LIC Log minor code
12   C     CHAR(8)      LIC Log id (keyword DMPID on PRTINTDTA)
20  14     BINARY(4)    Offset to comparison data
24  18     BINARY(4)    Length of comparison data
 *   *     CHAR(*)      LIC log comparison data

Allowed values for the "Comparison data" parameter when *ON, *INTVAL or *WCHTIMO is specified for the "Trace option setting" parameter will be the following structure: 

OFFSET     TYPE         FIELD
Dec Hex
 0   0     BINARY(4)    Length of trace information (always 4).

Allowed values for the "Comparison data" parameter when *PAL is specified for the "Trace option setting" parameter will be the following structure: 

OFFSET     TYPE         FIELD
Dec  Hex
  0    0   BINARY(4)    Length of watch information
  4    4   CHAR(8)      System reference code
 12    C   CHAR(10)     Device name
 22   16   CHAR(4)      Device type
 26   1A   CHAR(4)      Model
 30   1E   CHAR(15)     Serial number
 45   2D   CHAR(10)     Resource name
 55   37   CHAR(8)      Error Log id (keyword ERRLOGID on PRTERRLOG)
 63   3F   CHAR(8)      PAL timestamp
 71   47   CHAR(4)      Reference code
 75   4B   CHAR(8)      Secondary code
 83   53   CHAR(8)      Table identifier
 91   5B   CHAR(1)      Reserved
 92   5C   BINARY(4)    Sequence
 96   60   BINARY(4)    Offset to comparison data
 100  64   BINARY(4)    Length of comparison data
 104  68   CHAR(10)     PAL compare against
 *   *     CHAR(*)      PAL comparison data

For more information on the trace exit program interface, refer to the APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/

Single values

*NONE
No trace exit program is defined. If a watched for message or licensed internal code (LIC) log entry or Product Activity Log (PAL) entry is added, or if the specified watch time limit is exceeded, the trace function ends.

Qualifier 1: Trace program

name
Specify the name of the trace exit program.

Qualifier 2: Library

*LIBL
All libraries in the job's library list are searched until the first match is found.
name
Specify the name of the library where the user exit program is located.

Time interval (TRCPGMITV)

Specifies how often the trace exit program will be called.

*NONE
No time interval is specified. The trace exit program will not be called because a time interval has elapsed.
1-9999
Specify the interval of time, in seconds, of how often the trace exit program will be called. This must be less than the amount of time specified for the Length of time to watch (WCHTIMO) parameter.

Run priority (RUNPTY)

Specifies the priority of the job where the watch session work will be run.

25
A job priority of 25 will be used.
1-99
Specify the run priority of the job. For more information on job run priority, refer to the Work management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/

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.

Example 9: Start a Trace Specifying a Subsystem 

STRTRC   SSNID(MYTRACE)
         JOB((123456/MYUSER/MYJOB (*ALL) *ALLSBS)
             (*ALL/*ALL/QPA* (*ALL) QINTER))

This command starts a new trace on the job with job name MYJOB, job user name of MYUSER, and job number of 123456 regardless of which subsystem the job is in. It also traces all jobs that have a job name that begins with QPA in the QINTER subsystem.

Example 10: Start a Trace Specifying to Set the Trace Characteristics in a Related Job or Thread 

STRTRC SSNID(MYTRACE)
       JOB((123456/QUSER/QZRCSRVSD))
       JOINTRC(*YES)

This command starts a trace on the job 123456/QUSER/QZRCSRVSD. If this job does a spawn or generates some work to be done in one of the prestart jobs named QZRCSRVS, the child job or thread will inherit the trace characteristics of 123456/QUSER/QZRCSRVSD.

Error messages

*ESCAPE Messages

CPF39C7
STRTRC session ID &1 already exists.
CPF39C9
Unexpected STRTRC failure, see low-level messages.
CPF39C5
Job name *ALL and user *ALL not allowed
CPF39C6
Not authorized to trace with generic job users.
CPF39CC
No active jobs found, STRTRC session not started.
CPF39F2
Cannot allocate library &1
CPF98A2
Not authorized to &1 command or API.
CPF39D3
Unable to start/end the trace.
CPF39D4
Another trace session is already active that specified RESTRIPL(*YES).
CPF39D5
Another trace session is already active that specified JOINTRC(*YES).
CPF39D6
Not authorized to set the trace characteristics of the specified jobs in a related job or thread.
CPF9899
Error occurred during processing of command.