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, or to tape or optical media.

Restrictions:

To use this command, you must have service (*SERVICE) special authority, or be authorized to the Service Trace function of Operating System through iSeries Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that are allowed to perform trace operations.
The following user profiles have private authorities to use the command:
- QSRV
When the Watched job (WCHJOB) parameter is specified, the issuer of the command must be running under a user profile which is the same as the job user identity of the job being watched, or the issuer of the command must be running under a user profile which has job control (*JOBCTL) special authority. Job control (*JOBCTL) special authority is also required if a generic user name is specified for the WCHJOB parameter.
If you specify a generic user name in the WCHJOB parameter, you must have all object (*ALLOBJ) special authority, or be authorized to the Watch Any Job function of Operating System through iSeries Navigator's Application Administration support. The Change Function Usage (CHGFCNUSG) command, with a function ID of QIBM_WATCH_ANY_JOB, can also be used to change the list of users that are allowed to start and end watch operations.
You must have operational (*OBJOPR) and execute (*EXECUTE) authorities to the user exit program if specified in Trace program (TRCPGM) parameter, and execute (*EXECUTE) authority to the library where the program is located.
You must have use (*USE) authority to the message queues specified in Watched message queue (WCHMSGQ) parameter, and use (*USE) authority to the library where the message queue is located.

Parameters

Keyword	Description	Choices	Notes
SET	Trace option setting	ON, OFF, END, HOLD, SAVE, SIZE	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	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 identifier	Name
	Element 2: Comparison data	Character value, *NONE
	Element 3: Compare against	MSGDTA, FROMPGM, *TOPGM
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
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

Top

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.

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

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 type (TRCTYPE)

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

Component data trace codes cause active procedures to be traced within the system.
General trace codes cause the iSeries instruction supervisor linkage, multiprogramming, transaction, or task and thread performance functions to be traced.

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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/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.

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.

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:

specifying SET(*ON) multiple times for the same trace table
specifying *ALLDEV on the CTL parameter
specifying *ALLCTL on the LIN parameter

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

specifying SET(*ON) multiple times for the same trace table
specifying *ALLDEV on the CTL parameter
specifying *ALLCTL on the LIN parameter

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.

specifying SET(*ON) multiple times for the same trace table
specifying *ALLDEV on the CTL parameter
specifying *ALLCTL on the LIN parameter

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.

specifying SET(*ON) multiple times for the same trace table
specifying *ALLDEV on the CTL parameter
specifying *ALLCTL on the LIN parameter

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.

specifying SET(*ON) multiple times for the same trace table
specifying *ALLDEV on the CTL parameter
specifying *ALLCTL on the LIN parameter

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.

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.

Watch for message (WCHMSG)

Specifies up to five message identifiers which are to be watched for. 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.

Single values

*NONE: No messages will be watched for.

Element 1: Message identifier

name: Specify the 7-character message identifier to be watched for.

Element 2: Comparison data

Specify comparison data to be used if a message matching the specified message ID 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 ID 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.

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 fields compared of a watched for log entry, the watch condition is considered to be true. This text is case sensitive. The LIC log fields which can 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.

Trace program (TRCPGM)

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

The trace program will be called:

Before the application trace starts.
After a match of a message identifier specified for the WCHMSG parameter, or a match of a Licensed Internal Code (LIC) log entry specified for the WCHLICLOG parameter occurs.
When the time interval specified on the TRCPGMITV parameter is reached.
When the length of time to watch specified on WCHTIMO parameter is reached.

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

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 ID
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).

For more information on the trace exit program interface, refer to the System API Reference information in the iSeries Information Center at http://www.iseries.ibm.com/infocenter .

Single values

*NONE: No trace exit program is defined. If a watched for message or licensed internal code (LIC) log 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.

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.

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