Where allowed to run: All environments (*ALL) Threadsafe: No |
Parameters Examples Error messages |
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:
Top |
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, *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 |
Top |
Specifies a session identifier for this trace. This identifier must be unique across all active traces on the system.
This is a required parameter.
Top |
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
Other values (up to 8 repetitions)
Element 1: Job name
Qualifier 1: Job name
Qualifier 2: User
Qualifier 3: Number
Element 2: Thread ID to include
Single values
Other values (up to 20 repetitions)
Element 3: Subsystem
Top |
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.
Top |
Specifies the types of jobs for which trace data is to be collected.
Top |
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.
Top |
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.
Top |
Specifies the types of job trace data to be stored in the trace file.
You can specify 2 values for this parameter.
Top |
Specifies the component to trace and the level to use. You can specify up to 50 trace components to be traced.
Single values
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 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.
Top |
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.
Top |
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.
Top |
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.
Single values
Element 1: Message to watch
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.
Element 3: Compare against
Specify which part of the message the comparison data specified for element 2 is to be compared against.
Element 4: Message type
Specify the message type assigned to the message to be watched.
Element 5: Relational operator
Specify one relational operator against which the message severity code is compared.
Element 6: Severity code
Specifies the severity code of the message to be watched.
Top |
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
Qualifier 1: Message queue
Qualifier 2: Library
Top |
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
Element 1: Job name
Qualifier 1: Job name
Qualifier 2: User
Qualifier 3: Number
Top |
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
Element 1: Major code
Element 2: Minor code
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.
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.
Top |
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
Other values (up to 5 repetitions)
Element 1: System reference code
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.
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.
Top |
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.
Top |
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:
The "Reserved" parameter must be set to blanks.
Allowed values for the "Error detected" parameter are:
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 identifier 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) Log identifier 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
Qualifier 1: Trace program
Qualifier 2: Library
Top |
Specifies how often the trace exit program will be called.
Top |
Specifies the priority of the job where the watch session work will be run.
Top |
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.
Top |
*ESCAPE Messages
Top |