Trace Internal (TRCINT)

The Trace Internal (TRCINT) command is the command interface to the Trace Licensed Internal Code service tool and is used for problem analysis. Specific types of traces are started and stopped by using this command. While previously started internal traces are being performed, additional internal traces can be started through this command. The output created by the trace is placed in a trace table. The records from the trace table can be written to a spooled printer file, to a database file, to a stream file, or to tape or optical media.

Restrictions:

  1. To use this command, you must have service (*SERVICE) special authority, or be authorized to the Service trace function of IBM i through System i 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.
  2. The following user profiles have private authorities to use the command:
    • QSRV
  3. 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.
  4. 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 IBM i through System i 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.
  5. 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.
  6. 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.
  7. You must have the following authorities when the Stream file options (TOSTMF) or From stream file (FROMSTMF) parameters are specified:
    • Execute (*X) authority to directories in the path name prefix of the stream file.
    • Write (*W) authority to the stream file if the stream file already exists.
    • Write and execute (*WX) authority to the stream file's parent directory if the stream file does not already exist.
    • Read (*R) authority to the stream file.

Parameters

Keyword Description Choices Notes
SET Trace option setting *ON, *OFF, *END, *HOLD, *SAVE, *SIZE, *PRINT Required, Positional 1
TRCTBL Trace table name Character value, *SYSDFT Optional
SIZE Trace table size Single values: *NOCHG, *MAX, *MIN
Other values: Element list		 Optional
Element 1: Number of units 1-998000
Element 2: Unit of measure *KB, *MB
TRCFULL Trace full *NOCHG, *WRAP, *STOPTRC Optional, Positional 4
TRCTYPE Trace type Values (up to 50 repetitions): 000000-999999, *SVL, *MPL, *TNS, *TTPERF, *ACTCALL, *ALTTCP, *APPCOVRTCP, *APPCPS, *APPNALL, *APPNCPM, *APPNCPPS, *APPNDS, *APPNLM, *APPNMST, *APPNTRS, *AUTMGT, *AUXSTGALL, *AUXSTGMGT, *BSSMGT, *CCIOM, *CLUE, *CMNACCMTH, *CMNTRC, *CMTMGT, *COMMON, *CRPSRV, *CSTALL, *CSTCMN, *CTXMGT, *DBGINT, *DBMGT, *DLUR, *DSPPASTHR, *EREP, *ERRLOG, *EVTMGT, *EXCMGT, *FRCA, *HDWRSC, *HEAPMGT, *IDXMGT, *IFS, *IPCF, *ISCSI, *ISDN, *JRNMGT, *LNKTST, *LODDMP, *MCHOBS, *MITFMALL, *MITFMEVAL, *MITFMHEAP, *MITFMINT, *MITFMMI, *MITFMSTG, *MODMGT, *MOD2, *MSCP, *MSMCALL, *MSMDTL, *M36ALL, *M36ASC, *M36BSC, *M36CSP, *M36DKT, *M36DSK, *M36ILAN, *M36PRT, *M36SDLC, *M36TAP, *M36TRN, *M36WS, *M36X25, *NTBTCP, *OPC, *PASE, *PFRCOLSRV, *PGMBND, *PGMMGT, *PORTUTIL, *PRCMGT, *PRCTBL, *PSEUDOTERM, *PWRMGT, *QMGT, *QSMGT, *RCYMGT, *RMTSPT, *RSCMGT, *SCK, *SCKASCIO, *SCKNET, *SCKOTHER, *SCKOVRMPTN, *SCKOVRPEC, *SCKRSLV, *SCKSEL, *SCKSSL, *SCKSTDIO, *SIG, *SMBSVR, *SPCOBJMGT, *SRCSINK, *STGMGTALL, *STM, *SYNCMGT, *SYSCALL, *SYSJRNMGT, *TCPIP, *TLI, *TRXMGT, *VRTDEVMGT, *VRTIO Optional, Positional 2
JOB Job name Single values: *NOCHG
Other values (up to 10 repetitions): Qualified job name		 Optional
Qualifier 1: Job name Generic name, name, *ALL
Qualifier 2: User Generic name, name, *ALL
Qualifier 3: Number 000000-999999, *ALL
SLTTHD Thread ID to include Single values: *NOCHG, *ALL, *SELECT
Other values (up to 20 repetitions): Hexadecimal value		 Optional
SVRTYPE Server type Single values: *ALL, *NOCHG
Other values (up to 5 repetitions): Generic name, name		 Optional
TASK Task name Single values: *ALL, *NOCHG
Other values (up to 10 repetitions): Generic name, name		 Optional
TASKNBR Task number Single values: *ALL, *NOCHG
Other values (up to 10 repetitions): Hexadecimal value		 Optional
SLTTRCPNT Select trace points Single values: *NOCHG
Other values (up to 5 repetitions): Element list		 Optional
Element 1: Trace point qualifier 0-65535
Element 2: To trace point qualifier 0-65535
OMTTRCPNT Omit trace points Single values: *NOCHG
Other values (up to 5 repetitions): Element list		 Optional
Element 1: Trace point qualifier 0-65535
Element 2: To trace point qualifier 0-65535
STOPTRCPNT Stop on trace point Single values: *NOCHG
Other values (up to 4 repetitions): Element list		 Optional
Element 1: Trace point type Character value
Element 2: Trace point qualifier 0-65535
Element 3: Trace point entry 1-65535
Element 4: Trace point entry offset Hexadecimal value
Element 5: Trace point match value Character value
JOBTYPE Job types Single values: *NONE, *ALL
Other values (up to 12 repetitions): *DFT, *ASJ, *BCH, *EVK, *INT, *MRT, *RDR, *SBS, *SYS, *WTR, *PDJ, *PJ, *BCI		 Optional
JOBTRCITV Job trace interval 0.1-9.9, 0.5 Optional
TCPDTA TCP/IP data Element list Optional
Element 1: Protocol *TCP, *UDP, *ICMP, *IGMP, *ARP, *ICMP6
Element 2: Local port Values (up to 2 repetitions): 1-65535
Element 3: Remote port Values (up to 2 repetitions): 1-65535
Element 4: Local IP address Character value
Element 5: Remote IP address Character value
Element 6: Line description Name
Element 7: Line type *PPP, *OPC
SCKDTA Sockets data Element list Optional
Element 1: Address family *INET, *UNIX, *INET6, *NETBIOS
Element 2: Socket type *STREAM, *DGRAM, *RAW, *SEQPACKET
Element 3: Descriptor Values (up to 2 repetitions): 0-65535
Element 4: Socket option *SODEBUG
DEV Device Single values: *NONE
Other values (up to 16 repetitions): Name		 Optional, Positional 3
CTL Controller Single values: *NONE
Other values (up to 16 repetitions): Element list		 Optional
Element 1: Controller Name
Element 2: Attached devices *NODEV, *ALLDEV
LIN Line Single values: *NONE
Other values (up to 16 repetitions): Element list		 Optional
Element 1: Line Name
Element 2: Attached controllers *NOCTL, *ALLCTL
NWI Network interface Single values: *NONE
Other values (up to 16 repetitions): Name		 Optional
NWS Network server Single values: *NONE
Other values (up to 16 repetitions): Name		 Optional
RSRCNAME Resource name Single values: *NONE
Other values (up to 10 repetitions): Name		 Optional
OUTDEV Output device Name Optional
TASKINF Task information *ALL, *TRCREF Optional
OUTPUT Output *PRINT, *OUTFILE, *STMF Optional
OUTFILE File to receive output Qualified object name Optional
Qualifier 1: File to receive output Name
Qualifier 2: Library Name, *LIBL, *CURLIB
OUTMBR Output member options Element list Optional
Element 1: Member to receive output Name, *FIRST
Element 2: Replace or add records *REPLACE, *ADD
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
TOSTMF Stream file options Element list Optional
Element 1: Stream file Path name
Element 2: Replace file *NO, *YES
FROMSTMF From stream file Path name Optional

Trace option setting (SET)

Specifies whether internal tracing is started, stopped, ended, held, or saved. You can also specify whether the trace table size is changed, or you can specify whether previous internal trace records saved to a stream file (STMF) are converted into a readable spooled or output file.

This is a required parameter.

*ON
The collection of internal trace records is started for the trace types specified for the Trace type (TRCTYPE) parameter. If the trace table already contains trace records, the new trace records are added to the table. If the table is full, the action specified for the Trace full (TRCFULL) parameter is taken. If a trace table name other than *SYSDFT is specified for the TRCTBL parameter and the table does not exist, it will be automatically created.
*OFF
Collection of internal trace records requested through previous Trace Internal (TRCINT) commands stops, and the records are written to the spooled printer file QPCSMPRT, dumped to a stream file, or sent to a database file as indicated by Output (OUTPUT) parameter.
*END
Internal tracing ends and the internal trace records are deleted. No spooled output is generated. If a trace table name other than *SYSDFT is specified for the TRCTBL parameter, it will be automatically deleted.
*HOLD
Internal traces are stopped, and the collected internal trace records are held in the trace table. Held records can be printed later if another Trace Internal (TRCINT) command is entered that specifies *OFF for this prompt; or, the held records can be put on tape or optical media if *SAVE is specified.
*SAVE
Internal traces are stopped, and the trace records are written to a tape or optical device specified by the OUTDEV parameter.
*SIZE
The size of the trace table is changed. The new size is specified on the Trace table size (SIZE) parameter.
*PRINT
Internal trace records collected and directed to a stream file (STMF) through previous Trace Internal (TRCINT) commands are written to the spooled printer file QPCSMPRT or sent to a database file as indicated by the Output (OUTPUT) parameter.

Trace table name (TRCTBL)

Specifies the trace table to hold the collected trace data.

*SYSDFT
The system default trace table is used.
name
Specify the name of the trace table to be used. If SET(*ON) is specified and the name specified does not match an existing trace table, a new trace table by the specified name will be created.

Trace table size (SIZE)

Specifies the size of the trace table. This parameter can be specified only when *SIZE is specified for the Trace option setting (SET) parameter or if SET(*ON) is specified and tracing is not currently active for the trace table specified (TRCTBL parameter).

Note: The storage indicated on this parameter is immediately allocated from the system auxiliary storage pool (ASP 1). This storage is not dynamically allocated as it is needed. This storage space will not be available for use by the system except to record trace-related information. Before specifying a large value on this parameter, the amount of free space in the system ASP should be checked. Use the Work with System Status (WRKSYSSTS) command to determine the amount of available free space in the system ASP. System performance degradation may result if the size of the free space in the system ASP is significantly reduced as a result of the value specified.

Note: If tracing data over a gigabit Ethernet line the trace table size should be greater than 128000 kilobytes or 128 megabytes.

Single values

*NOCHG
The trace table size is not changed. If a new trace table is specified (TRCTBL parameter), a default size of 128 kilobytes will be used.
*MAX
The trace table is set to the maximum size of 258048 megabytes.
*MIN
The trace table is set to the minimum size of 128 kilobytes.

Element 1: Number of units

Specify the size of the trace table.

1-998000
Specify the size of the trace table in kilobytes or megabytes.

Element 2: Unit of measure

Specifies whether the value specified for the first element should be treated as number of kilobytes or number of megabytes.

*KB
The trace table size is specified in kilobytes. The valid range is 128 through 998000.
*MB
The trace table size is specified in megabytes. The valid range is 1 through 258048.

Trace full (TRCFULL)

Specifies whether the trace records wrap (replace the oldest records with new records) or tracing stops when the trace table is full. This parameter can be specified when *ON is specified for the Trace option setting (SET) parameter.

*NOCHG
The trace table full action is not changed. If a new trace table is specified (TRCTBL parameter), the default action is for trace records to wrap when the trace table becomes full.
*WRAP
When the trace table is full, the trace wraps to the beginning. The oldest trace records are written over by new ones as they are collected.
*STOPTRC
Tracing is stopped when the trace table is full of trace records.

Trace type (TRCTYPE)

Specifies the type of traces to start. The two groups of trace types are:

If trace code types are specified, *ON must be specified for the Trace option setting (SET) parameter. If a value other than *ON is specified for the SET parameter, TRCTYPE is ignored. Each trace type is identified by a special value or 6-digit code; all 6 digits must be specified. For a complete list of trace codes and special values, position the cursor on this parameter while prompting this command and press F4. Specify up to 50 types from the following code table: 

                                  COMPONENT
                                  OR GENERAL   SPECIAL
TYPE OF TRACE                     TRACE CODE   VALUE
MI instruction supervisor           030000     *SVL
  linkage (SVL)
Multiprogramming level (MPL)        040000     *MPL
Transaction                         080000     *TNS
Task/thread performance             090000     *TTPERF
Activation/Call                     014400     *ACTCALL
Alternate TCP/IP stack              016900     *ALTTCP
MPTN - APPC over TCP/IP MPTN        014203     *APPCOVRTCP
APPC presentation services          014301     *APPCPS
APPN -- (all)                       012506     *APPNALL
APPN control point management       012501     *APPNCPM
APPN control point                  012504     *APPNCPPS
  presentation services
APPN directory services             012502     *APPNDS
APPN location management            012505     *APPNLM
APPN management services            012507     *APPNMST
  transport
APPN topology and routing           012503     *APPNTRS
  services
Authority management                010900     *AUTMGT
Auxiliary storage management        011104     *AUXSTGALL
  -- detailedd
Auxiliary storage management        011101     *AUXSTGMGT
Byte string space management        012600     *BSSMGT
Common class input/output           011900     *CCIOM
  management (CCIOM)
Cluster engine                      016402     *CLUE
Communications access method        015900     *CMNACCMTH
Commit management                   011700     *CMTMGT
Communications trace service        012300     *CMNTRC
  function
Common functions                    011200     *COMMON
Cryptographic services              013600     *CRPSRV
Cluster -- (all)                    016400     *CSTALL
Cluster communications              016401     *CSTCMN
Context management                  011000     *CTXMGT
Debugger interpreter                014500     *DBGINT
Database management (events         010400     *DBMGT
  for all database files are
  traced)
Dependent LU Requester              015400     *DLUR
  (DLUR) Communication
Display station pass-through        010804     *DSPPASTHR
Environmental recording,            012200     *EREP
  editing and printing (EREP)


Error log                           012100     *ERRLOG
Event management                    010600     *EVTMGT
Exception management                010200     *EXCMGT
Fast Response Cache Accelerator     016600     *FRCA
Hardware resources                  014700     *HDWRSC
Heap management                     013400     *HEAPMGT
Independent index management        011400     *IDXMGT
Integrated File System (IFS)        014800     *IFS
Inter-process communications        012000     *IPCF
  facility (IPCF)
Internet SCSI host adapter          017000     *ISCSI
Communications answer               012700     *ISDN
  management (ISDN)
Journal management                  011600     *JRNMGT
Link test service function          012400     *LNKTST
Load/dump (save/restore)            010801     *LODDMP
Machine observation                 011300     *MCHOBS
Machine Interface (MI) Transformer  015100     *MITFMALL
MI Transformer - expression         015101     *MITFMEVAL
  evaluation
MI Transformer - heap operations    015102     *MITFMHEAP
MI Transformer - interpreter        015103     *MITFMINT
  instructions
MI Transformer - MI Instructions    015104     *MITFMMI
MI Transformer - storage            015105     *MITFMSTG
  management operations
Module management                   013100     *MODMGT
Modula-2 run time support           012800     *MOD2
Machine services control            010802     *MSCP
  point
Main storage management             011102     *MSMCALL
  -- calls
Main storage management             011103     *MSMDTL
  -- details
NetBios on TCP/IP                   015700     *NTBTCP
OptiConnect                         015500     *OPC
Portable Application Solutions      016100     *PASE
  Environment
Performance collection services     016200     *PFRCOLSRV
Program binder                      013200     *PGMBND
Program management                  010300     *PGMMGT
Portability utilities               015200     *PORTUTIL
Process management                  010500     *PRCMGT
Process table                       015300     *PRCTBL
Pseudo terminal component           016500     *PSEUDOTERM
Power management                    012900     *PWRMGT
Queue management                    010700     *QMGT
Queue space management              013300     *QSMGT
Recovery management                 013500     *RCYMGT
Remote Support                      016300     *RMTSPT
Resource management                 010100     *RSCMGT
Sockets -- (all APIs)               014000     *SCK
Sockets Asynchronous and Overlapped 014002     *SCKASCIO
  Input/Output APIs
Sockets Network APIs                014004     *SCKNET
Other Socket APIs                   014007     *SCKOTHER
MPTN AF_INET Sockets over           014201     *SCKOVRMPTN
  SNA MPTN
MPTN AF_INET Sockets over           014202     *SCKOVRPEC
  SNA PEC
Sockets Berkeley Resolver APIs      014005     *SCKRSLV
Sockets Select API                  014003     *SCKSEL
Secure Sockets Layer (SSL) APIs     014006     *SCKSSL
Sockets Standard Input/Output APIs  014001     *SCKSTDIO
Signals                             015600     *SIG
SMB server                          015800     *SMBSVR
Space object management             011500     *SPCOBJMGT
Source/sink (device support)        010803     *SRCSINK
  management
Storage management -- (all)         011105     *STGMGTALL
Streams                             013900     *STM
Synchronization management          013700     *SYNCMGT
MI system call                      015200     *SYSCALL
System journal management           014100     *SYSJRNMGT
Transmission Control Protocol/      013800     *TCPIP
  Internet Protocol (TCP/IP)
Transport Layer Interface           016000     *TLI
Transaction Management              016800     *TRXMGT
Virtual I/O                         016700     *VRTIO
Virtual terminal management         013000     *VRTDEVMGT

Note: If *TTPERF trace code is specified, it must be the first one in the TRCTYPE parameter list.

Job name (JOB)

Specifies the jobs from which trace records are to be collected. Only trace records which are generated in the specified job(s) are collected. A list of up to ten qualified job names can be specified. The trace records will be collected if they were generated from a job that matches any of the qualified job name values.

This parameter can be specified when *ON is specified for the Trace option setting (SET) parameter. If a value other than *ON is specified on the SET parameter, JOB is ignored.

Single values

*NOCHG
If any qualified job names had been specified for the JOB parameter on a previous TRCINT command for an active trace, the job name filtering information is not changed. If no value was specified on a previous TRCINT command for an active trace, *NOCHG will behave the same as *ALL/*ALL/*ALL for the JOB parameter.

Qualifier 1: Job name

*ALL
All trace records generated by the defined trace are collected, regardless of what job name the trace record was generated from.
generic-name
Specify the generic name of the job 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 job name specifies all jobs with job name that begin with the generic prefix.
name
Specify the name of the job from which trace records are to be collected.

Qualifier 2: User

*ALL
All trace records generated by the defined trace are collected, regardless of what job user name the trace record was generated from.
generic-name
Specify the generic user name of the job 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 name of the user of the job from which trace records are to be collected.

Qualifier 3: Number

*ALL
All trace records generated by the defined trace are collected, regardless of what job number the trace record was generated from. *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.
000000-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 generic user name is specified.

Thread ID to include (SLTTHD)

Specifies the job threads from which trace records are to be collected. Only trace records which are generated in the specified thread(s) are collected. There can be only one job that has thread IDs associated with it. It must be the first qualified job name specified for the JOB parameter, and the job must be active.

Single values

*NOCHG
If any thread identifiers had been specified for the SLTTHD parameter on a previous TRCINT command for an active trace, the thread ID filtering information is not changed. If no value was specified on a previous TRCINT command for an active trace, *NOCHG will behave the same as *ALL for this parameter.
*ALL
All trace records generated by the defined trace are collected, regardless of what thread ID the trace record was generated from.
*SELECT
A list of thread identifiers is shown from which you can select up to twenty threads. Trace records from any of the selected thread identifiers are to be collected. *SELECT is only valid if the TRCINT command is run in an interactive job.

Other values

hexadecimal-value
Specify the identifier of the thread from which trace records are to be collected. Up to twenty thread identifiers can be specified.

Server type (SVRTYPE)

Specifies the server type attribute for a job or task which is used to determine whether the trace record is collected. Only trace records which are generated in a job or task with the specified server type are collected. For a list of possible server types, see Work management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/

Single values

*NOCHG
If a value was specified for the server type on a previous TRCINT command for an active trace, the value is not changed. If no value was specified on a previous TRCINT command, *NOCHG will behave the same as *ALL for this parameter.
*ALL
All trace records generated by the defined trace are collected, regardless of the server type attribute of the job or task the trace record was generated from.

Other values

generic-name
Specifies the generic server type for 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 server type specifies all jobs with a server type that begins with the generic prefix.
name
Specify the server type for which trace records are to be collected. A list of up to five server types can be specified.

Task name (TASK)

Specifies the Licensed Internal Code (LIC) tasks from which trace records are to be collected. Only trace records which are generated from the specified LIC tasks are collected.

Single values

*NOCHG
If a value was specified for the task name (TASK parameter) on a previous TRCINT command for an active trace, the value is not changed. If no value was specified on a previous TRCINT command, *NOCHG will behave the same as *ALL for the task name.
*ALL
All trace records generated by the defined trace are collected, regardless of what LIC task the trace record was generated from.

Other values

generic-name
Specify the generic name of the LIC tasks for 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 task name specifies all tasks with task names that begin with the generic prefix.
name
Specify the name of the LIC task for which trace records are to be collected. Up to ten LIC task names can be specified.

Task number (TASKNBR)

Specifies the Licensed Internal Code (LIC) task numbers from which trace records are to be collected. Only trace records which are generated in the specified LIC tasks are collected.

Single values

*NOCHG
If a value was specified for the task number on a previous TRCINT command for an active trace, the value is not changed. If no value was specified on a previous TRCINT command, *NOCHG will behave the same as *ALL for this parameter.
*ALL
All trace records generated by the defined trace are collected, regardless of the task number of the LIC task the trace record was generated from.

Other values

hexadecimal-value
Specify a LIC task number for which trace records are to be collected. A list of up to ten task numbers can be specified.

Select trace points (SLTTRCPNT)

Specifies a list of up to five individual trace points or trace point ranges whose trace records are to be included. Trace records for trace points not specified on SLTTRCPNT will not be collected. If SLTTRCPNT is specified for a trace table that is currently active, the specified trace points will be added to the set of trace points for which trace records are being collected.

Note: This parameter and the OMTTRCPNT parameter are mutually exclusive. SLTTRCPNT cannot be specified for an active trace table that is using OMTTRCPNT to exclude specific trace points.

Single values

*NOCHG
The list of trace points for which trace records are being collected does not change.

Element 1: Trace point qualifier

0-65535
Specify a single trace point qualifier or the start of a range of trace point qualifiers whose trace records are to be included. Up to five individual trace point qualifiers or trace point qualifier ranges may be specified.

Element 2: To trace point qualifier

0-65535
Specify the end of a range of trace point qualifiers whose trace records are to be included. A value should not be specified for this parameter element if only a single trace point is to be included.

Omit trace points (OMTTRCPNT)

Specifies a list of up to five individual trace points or trace point ranges whose trace records are to be excluded. Trace records for all trace points not specified on OMTTRCPNT will be collected. If OMTTRCPNT is specified for a trace table that is currently active, the specified trace points will be added to the set of trace points for which trace records are not being collected.

Note: This parameter and the SLTTRCPNT parameter are mutually exclusive. OMTTRCPNT cannot be specified for an active trace table that is using SLTTRCPNT to include only specific trace points.

Single values

*NOCHG
The list of trace points for which trace records are being excluded does not change.

Element 1: Trace point qualifier

0-65535
Specify a single trace point qualifier or the start of a range of trace point qualifiers whose trace records are to be excluded. Up to five individual trace point qualifiers or trace point qualifier ranges may be specified.

Element 2: To trace point qualifier

0-65535
Specify the end of a range of trace point qualifiers whose trace records are to be excluded. A value should not be specified for this parameter element if only a single trace point is to be excluded.

Stop trace points (STOPTRCPNT)

Specifies one or more trace points which, if they are encountered, will cause collection of trace records to stop. The trace table records are not deleted and can later be written to a spooled file or an output device by invoking TRCINT with SET(*OFF) or SET(*SAVE).

Up to four trace points may be specified. Tracing will be stopped if any of the specified trace points match a trace record being added to the specified trace table.

A specified trace point can have either two parts (trace point type and trace point qualifier) or five parts (trace point type, trace point qualifier, trace point entry number, trace point entry offset, and trace point match value). A two-part condition will stop trace data collection if any trace record is collected for the specified trace point. A five-part condition will stop trace data collection only if the specified trace point match value exactly matches the data at the specified trace point entry offset.

Single values

*NOCHG
The list of stop trace points associated with the trace table does not change.

Element 1: Trace point type

character-value
Specify the two-character trace point type.

Element 2: Trace point qualifier

0-65535
Specify the trace point qualifier number.

Element 3: Trace point entry

1-65535
Specify the trace point entry number.

Element 4: Trace point entry offset

hexadecimal-value
Specify the offset (in hexadecimal) in the trace point entry.

Element 5: Trace point match value

character-value
Specify the match value to be compared to the trace record data. The match value may be specified in character or hexadecimal. Character strings will be converted to the equivalent hexadecimal strings.

Job types (JOBTYPE)

Specifies the types of jobs for which trace data is to be collected for use in the batch job trace report. A maximum of 11 job types can be specified. This parameter can be specified only if TRCTYPE(*MPL) or TRCTYPE(040000) is specified.

Note: The value *DFT includes the values *ASJ, *BCH, *EVK, *MRT, *PDJ, *PJ and *BCI. The value *BCH includes the values *EVK, *MRT, *PDJ, *PJ, and *BCI.

Single values

*NONE
No jobs are traced.
*ALL
All of the job types are traced.

Other values

*DFT
Batch and autostart jobs are traced.
*ASJ
Autostart jobs are traced.
*BCH
Batch jobs are traced.
*EVK
Jobs started by a procedure start request are traced.
*INT
Interactive jobs are traced.
*MRT
Multiple requester terminal jobs are traced.
*RDR
Reader jobs are traced.
*SBS
Subsystem monitor jobs are traced.
*SYS
System jobs are traced.
*WRT
Writer jobs are traced.
*PDJ
Print driver jobs are traced.
*PJ
Prestart jobs are traced.
*BCI
Batch Immediate jobs are traced.

Job trace interval (JOBTRCITV)

Specifies the time (in CPU seconds) between each collection of the job trace data. This parameter can be specified only if TRCTYPE(*MPL) or TRCTYPE(040000) is specified.

0.5
A time slice interval value of 0.5 CPU seconds is used.
0.1-9.9
Specify the number of CPU seconds to be used as the trace interval value.

TCP/IP data (TCPDTA)

Specifies whether a subset of TCP/IP and/or Sockets trace data should be collected. This parameter can be specified only if TRCTYPE(*TCPIP) or TRCTYPE(013800) or TRCTYPE(*SMBSVR) or TRCTYPE(015800) or TRCTYPE(*FRCA) or TRCTYPE(016600) is specified, or if one or more of the socket trace types is specified (*SCK, *SCKSTDIO, *SCKASCIO, *SCKSEL, *SCKNET, *SCKRSLV, *SCKSSL, *SCKOTHER or 014000, 014001, 014002, 014003, 014004, 014005, 014006, 014007). Each parameter element is optional; if no element value is specified, no filtering of TCP/IP and/or Sockets trace data is done for that element. For example, if *UDP is specified for element 1, only trace records where the UDP protocol is used are collected. If no value is specified for element 1, trace records using all TCP/IP protocols are collected.

If no values are specified for any element of TCPDTA and tracing of TCP/IP or Sockets data was not already active, no filtering of TCP/IP or Sockets trace data is done. If tracing of TCP/IP or Sockets data was already active and no TCPDTA values are specified, previous data filtering values will remain in effect.

Element 1: Protocol

Specify a TCP/IP protocol to be traced.

*TCP
Enable trace for transmission control protocol.
*UDP
Enable trace for user datagram protocol.
*ICMP
Enable trace for internet control message protocol.
*IGMP
Enable trace for internet group management protocol.
*ARP
Enable trace for address resolution protocol. This will only apply for TCP/IP.
*ICMP6
Enable trace for internet control message protocol version 6.

Element 2: Local port

Specify one or two local port numbers for which trace data is collected.

Element 3: Remote port

Specify one or two remote port numbers for which trace data is collected.

Element 4: Local IP address

Specify a local internet protocol address.

Element 5: Remote IP address

Specify a remote internet protocol address.

Element 6: Line description

Specify the name of a line description for which TCP/IP trace data is to be collected.

Element 7: Line type

Specify whether the collection of trace information should be restricted to the specified line type.

*PPP
The collection of trace information is restricted to Point-to-point lines.
*OPC
The collection of trace information is restricted to Opticonnect.

Sockets data (SCKDTA)

Specifies whether a subset of Sockets trace data should be collected. This parameter can be specified only if one or more of the socket trace types is specified (*SCK, *SCKSTDIO, *SCKASCIO, *SCKSEL, *SCKNET, *SCKRSLV, *SCKSSL, *SCKOTHER or 014000, 014001, 014002, 014003, 014004, 014005, 014006, 014007). Each parameter element is optional; if no element value is specified, no filtering of Sockets trace data is done for that element. For example, if *INET is specified for element 1, only trace records where the AF_INET address family is used are collected. If no value is specified for element 1, trace records using all socket address families are collected.

If no values are specified for any element of SCKDTA and tracing of Sockets data was not already active, no filtering of Sockets trace data is done. If tracing of Sockets data was already active and no SCKDTA values are specified, previous data filtering values will remain in effect.

The subset values specified on the SCKDTA parameter are used in combination with any subset values specified on the TCPDTA parameter to generate the complete subsetting criteria.

Element 1: Address family

Specify a sockets address family for which trace data is collected.

*INET
Enable trace for AF_INET address family.
*UNIX
Enable trace for AF_UNIX and AF_UNIX_CCSID address families.
*INET6
Enable trace for AF_INET6 address family.
*NETBIOS
Enable trace for AF_NETBIOS address family.

Element 2: Socket type

Specify a socket type for which trace data is collected.

*STREAM
Enable trace for SOCK_STREAM (full-duplex stream) socket type.
*DGRAM
Enable trace for SOCK_DGRAM (datagram) socket type.
*RAW
Enable trace for SOCK_RAW (direct to network protocol) socket type.
*SEQPACKET
Enable trace for SOCK_SEQPACKET (full-duplex sequenced packet) socket type.

Element 3: Descriptor

Specify one or two socket descriptor numbers for which trace data is collected.

Element 4: Socket option

Specify a socket option for which trace data is collected.

*SODEBUG
Applications with the SO_DEBUG Socket Option set on will have trace data collected.

Device (DEV)

Specifies the names of the devices for which the associated internal events are traced. This parameter can be specified only if 010803 or *SRCSINK is specified on the Trace type (TRCTYPE) parameter. Up to 16 device names may be specified.

The total number of source/sink objects that can be named on the device(DEV), controller(CTL), line(LIN), network interface(NWI) and network server(NWS) parameters is 16. For example, if you enter 16 values for the DEV parameter, you cannot enter values for the other parameters.

The maximum number of source/sink objects that can be traced in a single trace table is 256. Even if you stay within the limit of 16 named source/sink objects on one TRCINT command, you may exceed the 256 source/sink object limit. Examples of ways to exceed the limit are:

*NONE
No devices are traced by this command.
name
Specify the name of the device for which the internal trace is started. The device name must be the same as the name specified in the associated device description.

Controller (CTL)

Specifies the names of the controllers for which the associated internal events are to be traced. This parameter can be specified only if 010803 or *SRCSINK is specified on the Trace type (TRCTYPE) parameter. Up to 16 controller names may be specified.

The total number of source/sink objects that can be named on the device(DEV), controller(CTL), line(LIN), network interface(NWI) and network server(NWS) parameters is 16. For example, if you enter 16 values for the CTL parameter, you cannot enter values for the other parameters.

The maximum number of source/sink objects that can be traced in a single trace table is 256. Even if you stay within the limit of 16 named source/sink objects on one TRCINT command, you may exceed the 256 source/sink object limit. Examples of ways to exceed the limit are:

Single values

*NONE
No controllers are traced by this command.

Element 1: Controller

name
Specify the name of the controller for which the internal trace is started. The controller names must be the same as the names specified in the associated controller description.

Element 2: Attached devices

Specifies if the devices on a controller are traced.

*NODEV
No attached devices for the specified controller are traced.
*ALLDEV
All attached devices for the specified controller are traced. The attached devices do not count toward the maximum of 16 source/sink objects that can be named on the DEV,CTL,LIN,NWI and NWS parameters. However, the attached devices do count toward the maximum of 256 source/sink objects that can be traced in a single trace table.

Line (LIN)

Specifies the names of the lines for which the associated internal events are to be traced. This parameter can be specified only if 010803 is specified on the Trace type (TRCTYPE) parameter. Up to 16 line names may be specified.

The total number of source/sink objects that can be named on the device(DEV), controller(CTL), line(LIN), network interface(NWI) and network server(NWS) parameters is 16. For example, if you enter 16 values for the LIN parameter, you cannot enter values for the other parameters.

The maximum number of source/sink objects that can be traced in a single trace table is 256. Even if you stay within the limit of 16 named source/sink objects on one TRCINT command, you may exceed the 256 source/sink object limit. Examples of ways to exceed the limit are:

Single values

*NONE
No lines are traced by this command.

Element 1: Line

name
Specify the name of the line for which the internal trace is started. The line name must be the same as the name specified in the associated line description.

Element 2: Attached controllers

Specifies if the controllers on a line are traced.

*NOCTL
No attached controllers for the specified line are traced.
*ALLCTL
All attached controllers for the specified line are traced. The attached controllers do not count toward the maximum of 16 source/sink objects that can be named on the DEV,CTL,LIN,NWI and NWS parameters. However, the attached controllers do count toward the maximum of 256 source/sink objects that can be traced in a single trace table.

Network interface (NWI)

Specifies the names of the network interfaces for which the associated internal events are to be traced. This parameter can be specified only if 010803 or *SRCSINK is specified for the Trace type (TRCTYPE) parameter. Up to 16 network interface names may be specified.

The total number of source/sink objects that can be named on the device(DEV), controller(CTL), line(LIN), network interface(NWI) and network server(NWS) parameters is 16. For example, if you enter 16 values for the LIN parameter, you cannot enter values for the other parameters.

The maximum number of source/sink objects that can be traced in a single trace table is 256. Even if you stay within the limit of 16 named source/sink objects on one TRCINT command, you may exceed the 256 source/sink object limit. Examples of ways to exceed the limit are:

Single values

*NONE
No network interfaces are traced by this command.

Other values

name
Specify the name of the network interface for which the internal trace is started. The network interface name must be the same as the name specified in the associated network interface description.

Network Server (NWS)

Specifies the names of the network servers for which the associated internal events are traced. This parameter can be specified only if 010803 or *SRCSINK is specified on the Trace type (TRCTYPE) parameter. Up to 16 network server names may be specified.

The total number of source/sink objects that can be named on the device(DEV), controller(CTL), line(LIN), network interface(NWI) and network server(NWS) parameters is 16. For example, if you enter 16 values for the LIN parameter, you cannot enter values for the other parameters.

The maximum number of source/sink objects that can be traced in a single trace table is 256. Even if you stay within the limit of 16 named source/sink objects on one TRCINT command, you may exceed the 256 source/sink object limit. Examples of ways to exceed the limit are:

Single values

*NONE
No network servers are traced by this command.

Other values

name
Specify the name of the network server for which the internal trace is started. The network server name must be the same as the name specified in the associated network server description.

Hardware Resource (RSRCNAME)

Specifies the names of the hardware resources for which the associated internal events are traced. This parameter can be specified only if 014700 or 011900 is specified on the Trace type (TRCTYPE) parameter.

Note: A combined total of 10 hardware resources (RSRCNAME) are allowed.

Single values

*NONE
No hardware resources are traced by this command.

Other values

name
Specify the names of up to 10 hardware resources for which the internal trace is started.

Device (OUTDEV)

Specifies the tape device or optical device on which the held trace records are written. This parameter must be specified if *SAVE is specified for the Trace option setting (SET) parameter.

name
Specify the name of the device description of the tape or optical device.

Task information (TASKINF)

Specifies whether information for all licensed internal code (LIC) tasks is written to a spooled file or output device. This parameter can be specified if SET(*OFF) or SET(*SAVE) is specified.

*TRCREF
Write information only for LIC tasks that were referenced by trace records in the specified trace table.
*ALL
Write information for all LIC tasks that were in existence while the trace was active.

Specifies whether the output from the command is printed with the job's spooled output, sent to a database file, or sent to a stream file.

*PRINT
The output is printed with the job's spooled output.
*OUTFILE
The output is directed to the database file specified for the File to receive output (OUTFILE) parameter.
*STMF
The output is directed to the stream file specified on the Stream file options (TOSTMF) parameter. You will have to use TRCINT SET(*PRINT) to convert the binary information into a readable spooled file or output file.

File to receive output (OUTFILE)

Specifies the database file to which the output of the command is directed. If the file does not exist, this command creates a database file in the specified library. If the file is created, the public authority for the file is the same as the create authority specified for the library in which the file is created. Use the Display Library Description (DSPLIBD) command to show the library's create authority.

Qualifier 1: File to receive output

name
Specify the name of the database file to which the command output is directed.

Qualifier 2: Library

*LIBL
The library list is used to locate the file. If the file is not found, one is created in the current library. If no current library exists, the file will be created in the QGPL library.
*CURLIB
The current library for the thread is used to locate the file. If no library is specified as the current library for the thread, the QGPL library is used.
name
Specify the name of the library to be searched.

Note: If a new file is created, system file QASCTRCI in system library QSYS is used as a model.

Output member options (OUTMBR)

Specifies the name of the database file member to which the output is directed when *OUTFILE is specified for the Output (OUTPUT) parameter.

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 for the File to receive output (OUTFILE) parameter.
name
Specify the name of the file member that receives the output. If OUTMBR(member-name) is specified and the member does not exist, the system creates it.

If the member exists, you can add records to the end of the existing member or clear the existing member and add the records.

Element 2: Replace or add records

*REPLACE
The existing records in the specified database file member are replaced by the new records.
*ADD
The new records are added to the existing information in the specified database file member.

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/

Stream file options (TOSTMF)

Specifies the stream file to which data is directed and whether the file should be replaced if it exists.

Element 1: Stream file

path-name
Specify the path name for the stream file to be used. All directories in the path name must exist. New directories are not created. If the stream file does not exist, it is created. For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Element 2: Replace file

*NO
No records are copied and an error message is signaled if the file already exists.
*YES
The trace data records replace the existing stream file records.

From stream file (FROMSTMF)

Specifies the stream file from which data is printed.

path-name
Specify the path name for the stream file to be used. For more information on specifying path names, refer to "Object naming rules" in the CL topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.

Examples

Example 1: Starting Component Data Traces and Call Traces 

TRCINT   SET(*ON)  TRCTYPE(010100 010400 050500 051200)

This command starts component data traces and call traces for resource management and database. Database operations associated with database files are used to collect component data trace records.

Example 2: Tracing Lines and Controllers 

TRCINT   SET(*ON)  TRCTYPE(*SRCSINK) TRCTBL(*SYSDFT)
         DEV(WS1 WS2 WS3)  CTL((C1) (C2))  LIN((L1) (L2))

This command starts component data traces for source/sink management (device support) operations involving the devices WS1, WS2, and WS3, lines L1 and L2, and controllers C1 and C2.

Example 3: Stopping Traces and Clearing Trace Table 

TRCINT   SET(*END)  TRCTBL(*SYSDFT)

This command stops all traces and deletes the trace records from the system default trace table.

Example 4: Tracing Communications Trace Service Function 

TRCINT   SET(*ON)  TRCTYPE(*CMNTRC)

This command starts component data traces for the communications trace service function.

Example 5: Using Job Filtering Capability 

TRCINT   SET(*ON)  TRCTBL(MYFTPTRACE)
         TRCTYPE(*TCPIP)  JOB(QTCP/QTFTP*)

This command starts a TCP/IP trace and will only collect trace records for trace points collected in jobs with user name QTCP and job names that begin with the prefix QTFTP. Trace records will be stored in trace table MYFTPTRACE.

Example 6: Start a Trace and Watch for a Message to End the Trace 

TRCINT   SET(*ON)  TRCTYPE(*CMNTRC)  WCHMSG((MCH2804))
         WCHMSGQ((*SYSOPR) (*JOBLOG))
         WCHJOB((*ALL/MYUSER/MYJOBNAME))
         TRCPGM(MYLIB/TRCEXTPGM)

This command starts component data traces for the communications trace service function. 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 7: Start a Trace and Watch for a LIC Log Entry to End the Trace 

TRCINT   SET(*ON) TRCTYPE(*CMNTRC)
         WCHLICLOG(('99??' 9932 MYJOBNAME))
         WCHTIMO(*NOMAX)

This command starts component data traces for the communications trace service function. 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 TRCINT command is issued manually to stop the trace.

Example 8: Sending the Trace Output to an Outfile 

TRCINT   SET(*OFF)  OUTPUT(*OUTFILE)
         OUTFILE(MYOUTFILE)  OUTMBR(MYOUTMBR)

This command generates the outfile MYOUTFILE with member MYOUTMBR with the data traces.

Example 9: Sending the Trace Output to a Stream File 

TRCINT   SET(*OFF) OUTPUT(*STMF)
         TOSTMF('/MyTrace/TestTrace'  *NO)

This command dumps the information to stream file /MyTrace/TestTrace. If the stream file exists, it will not be replaced.

Example 10: Converting the Stream File Trace Output into a Readable Spooled File 

TRCINT   SET(*PRINT) OUTPUT(*PRINT)
         FROMSTMF('/MyTrace/TestTrace')

This command converts the /MyTrace/TestTrace stream file trace output into a readable spooled file.

Example 11: Converting the Stream File Trace Output into a Readable Output File 

TRCINT   SET(*PRINT) OUTPUT(*OUTFILE)
         OUTFILE(MYOUTFILE)  OUTMBR(MYOUTMBR)
         FROMSTMF('/MyTrace/TestTrace')

This command converts the /MyTrace/TestTrace stream file trace output into the readable output file MYOUTFILE with member MYOUTMBR.

Error messages

*ESCAPE Messages

CPD3683
TRCFULL parameter only valid with SET(*ON).
CPD3684
Specified parameters only valid when SET(*ON) is specified.
CPD3685
SLTTRCPNT or OMTTRCPNT parameters are mutually exclusive.
CPD3686
TCPDTA only valid if *TCPIP or *SMBSVR or *FRCA or one or more of the socket TRCTYPE is specified.
CPD3687
SCKDTA only valid if one or more of the socket TRCTYPE values is specified.
CPD3688
Job types (JOBTYPE) parameter only valid with TRCTYPE(*MPL).
CPD3689
Job trace interval (JOBTRCITV) parameter only valid with TRCTYPE(*MPL)
CPD368A
Cannot change trace point selection criteria for active trace table.
CPD36C0
OUTDEV parameter only valid with SET(*SAVE).
CPD36C1
SIZE parameter only valid with SET(*ON) or SET(*SIZE).
CPD36CD
TASKINF parameter only valid with SET(*OFF) or SET(*SAVE).
CPD3983
Range of parameter SIZE not valid.
CPD3990
User number qualifier not valid.
CPD3991
Job, thread identifier or task not active.
CPF3515
Too many trace requests or objects.
CPF3516
Trace table is full.
CPF3517
Cannot specify *SELECT for the thread ID to include.
CPF3518
End time and date earlier than start time and date.
CPF3659
Total of specified CTL, DEV, LIN, NWI, and NWS greater than allowed.
CPF3679
Service function returned completion code &1 qualifier &2.
CPF3683
Error occurred trying to open printer file.
CPF3684
Error occurred while trying to close a print file.
CPF3685
Error occurred while data being put to print file.
CPF3686
Service function ended with error message.
CPF3687
Error occurred while trying to open file.
CPF3688
Error occurred while tape or optical file being closed.
CPF3689
Error occurred while writing data to tape or optical device.
CPF368A
Trace table size not changed.
CPF3692
Error occurred while trying to write data to tape or optical device.
CPF3693
Service function ended because error occurred.
CPF3694
Cannot start service function.
CPF3695
No trace tables exist.
CPF3696
No traces recorded.
CPF3697
Trace type parameter value missing.
CPF6614
Error occurred while writing trace data to file.
CPF6615
Error during creation of stream file.
CPF6616
Error occurred while reading data from stream file.
CPF7A11
Trace table &1 not found.
CPF7A13
Trace table cannot be created.
CPF7A15
Trace buffer must be cleared.
CPF7A17
Trace already is active.
CPF7A1A
Cannot change trace point selection criteria for active trace table.
CPF7A1C
IP address not valid.
CPF98A2
Not authorized to &1 command or API.
CPFA0D4
File system error occurred. Error number &1.