Trace Connection (TRCCNN)

The Trace Connection (TRCCNN) command allows the tracing of encrypted data flowing over internet protocol (IP) version 4 (IPv4) and version 6 (IPv6), and Secure Sockets Layer (SSL) connections. Specific types of traces are started and stopped by using this command.

TRCCNN uses the Trace Internal (TRCINT) command to collect the trace records, which can be dumped to a stream file in Packet Capture (PCAP) format or sent to a spooled file. When SSL data is captured, only a spooled file can be created.

You can use also use TRCCNN with a QPCSMPRT spooled file generated by using TRCINT directly. TRCCNN can extract and format the IP and SSL connection-related trace records. This allows you to use TRCINT to collect many types of trace records and then use TRCCNN to format the subset of trace records related to IP or SSL connections.

Restrictions:

Parameters

Keyword Description Choices Notes
SET Trace option setting *ON, *OFF, *END, *FORMAT Required, Positional 1
TRCTYPE Trace type Values (up to 2 repetitions): *IP, *SSL, *IPV4, *IPV6 Optional
TRCFULL Trace full *WRAP, *STOPTRC Optional
TRCTBL Trace table name Character value, *GEN Optional
SIZE Size Single values: *MAX, *MIN
Other values: Element list
Optional
Element 1: Number of units 1-998000, 16000
Element 2: Unit of measure *KB, *MB
OUTPUT Output *PRINT, *STMF Optional
FMTDTA Trace data to be formatted 72-99999, *CALC Optional
CCSID Coded character set identifier 1-65533, *EBCDIC, *ASCII Optional
JOB Job name Single values: *
Other values: Qualified job name
Optional
Qualifier 1: Job name Name
Qualifier 2: User Name
Qualifier 3: Number 000000-999999
SPLNBR Spooled file number 1-999999, *ONLY, *LAST Optional
JOBSYSNAME Job system name Name, *ONLY, *CURRENT, *ANY Optional
CRTDATE Spooled file created Single values: *ONLY, *LAST
Other values: Element list
Optional
Element 1: Creation date Date
Element 2: Creation time Time, *ONLY, *LAST
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
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

Trace option setting (SET)

Specifies whether tracing is started, stopped or ended. Also, you can select to format trace record data collected previously using the TRCCNN or TRCINT (Trace Internal) command.

This is a required parameter.

*ON
The collection of internal trace records is started for the trace types specified in the TRCTYPE parameter. If *GEN is specified in the TRCTBL parameter then the trace table name will be QTRCCNNxxxxxx where xxxxxx is the job number of the current job. Otherwise the trace table name will be the name specified on the TRCTBL parameter.
*OFF
Collection of trace records stops and the trace table is deleted. Either a stream file or a spooled file named can be generated, as indicated by Output (OUTPUT) parameter.
*END
Collection of trace records stops and the trace table is deleted. No output is generated.
*FORMAT
Formats trace data in a QPCSMPRT spooled file created by a previous invocation of TRCCNN or TRCINT. The formatted data is written to a spooled file named QSYSPRT. The user data for the QSYSPRT spooled file is 'TRCCNN'. Use the TRCTYPE parameter to specify which connection-related trace records to format. Use the JOB, SPLNBR, JOBSYSNAME and CRTDATE parameters to identify which QPCSMPRT file to use.

Trace type (TRCTYPE)

If SET(*ON) is specified, identifies the types of trace records to start collecting. If SET(*FORMAT) is specified, identifies the types of collected trace records to format. Multiple trace types may be specified.

*IP
Trace IP (internet protocol version 4 and version 6) data.
*SSL
Trace SSL (Secure Sockets Layer) connection data.
*IPV4
Trace IPv4 (internet protocol version 4) data.
*IPV6
Trace IPv6 (internet protocol version 6) data.

Trace full (TRCFULL)

Specifies whether the trace records wrap (replace the oldest records with new records) or stop tracing when the trace table is 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 table name (TRCTBL)

Specifies the trace table to hold the collected trace data.

*GEN
The trace table name will be QTRCCNNxxxxxx where xxxxxx is the job number of the current job.
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.

Size (SIZE)

Specifies the size of the trace table. The amount of storage to be allocated can be specified in units of kilobytes (*KB) or megabytes (*MB). If the size is specified in kilobytes, the amount of storage allocated for the table will be rounded up to the nearest megabyte. Valid table size values range from one megabyte to 258048 megabytes.

Note: The amount of storage specified by this parameter is immediately allocated from the system auxiliary storage pool (ASP 1). This storage space 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

*MAX
The trace table is set to the maximum size of 258048 megabytes.
*MIN
The trace table is set to the minimum size of one megabyte.

Element 1: Number of units

16000
The trace table size is either 16000 kilobytes or 16000 megabytes, depending on the value specified for the second element of this parameter.
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.
*MB
The trace table size is specified in megabytes.

Output (OUTPUT)

Specifies the output file that will be generated from the traced information.

*PRINT
A spooled file named QSYSPRT is generated by formatting QPCSMPRT, which is generated by the TRCINT command. The user data for the QSYSPRT spooled file is 'TRCCNN'.
*STMF
Dumps the traced data in Packet Capture (PCAP) format to the stream file specified in the Stream file options (TOSTMF) parameter. PCAP format is used by network protocol analyzers in other operating systems, such as Linux and AIX. A stream file can only be created with trace data different than SSL.

Trace data to be formatted (FMTDTA)

Specifies the number of bytes of traced data to be formatted.

*CALC
The system determines the number of bytes of data to be formatted.
72-99999
Specify the number of bytes of data to be formatted.

Coded character set identifier (CCSID)

Specifies whether the extended binary-coded decimal interchange code (*EBCDIC- 37) or the American National Standard Code for Information Interchange (*ASCII- 819) character code or any other is used for the formated output.

*EBCDIC
The EBCDIC (37) character code is used.
*ASCII
The ASCII (819) character code is used.
1-65533
Specify the coded character set identifier (CCSID) value to be used when formatting the trace data.

Job name (JOB)

Specifies the name or qualified name of the job that created the input QPCSMPRT spooled file (SPLNBR parameter). This parameter is valid only if SET(*FORMAT) is specified.

Single values

*
The job that issued this command is the job that created the input QPCSMPRT spooled file.

Qualifier 1: Job name

name
Specify the name of the job that created the input QPCSMPRT spooled file.

Qualifier 2: User

name
Specify the user name that identifies the user profile under which the job was run that created the input QPCSMPRT spooled file.

Qualifier 3: Number

000000-999999
Specify the system-assigned job number of the job that created the input QPCSMPRT spooled file.

Spooled file number (SPLNBR)

Specifies the file number of the QPCSMPRT spooled file from the job (JOB parameter) that created the spooled file. This parameter is valid only if SET(*FORMAT) is specified.

*LAST
The highest-numbered spooled file named QPCSMPR created by the specified job is used.
*ONLY
Only one spooled file named QPCSMPRT was created by the specified job; therefore, the number of the spooled file is not necessary. If *ONLY is specified and more than one spooled file for the specified job is named QPCSMPRT, an error message is issued.
1-999999
Specify the number of the QPCSMPRT spooled file created by the specified job.

Job system name (JOBSYSNAME)

Specifies the name of the system where the job that created the spooled file (JOB parameter) ran. This parameter is considered after the job name, user name, job number, spooled file name and spooled file number parameter requirements have been met.

*ONLY
There is only one spooled file with the specified job name, user name, job number, spooled file name, spooled file number and spooled file creation date and time.
*CURRENT
The spooled file created on the current system with the specified job name, user name, job number, spooled file name, spooled file number and creation date and time is used.
*ANY
The job system name is not used to determine which spooled file is used. Use this value when the spooled file creation date and time parameter is to take precedence over the job system name when selecting a spooled file.
name
Specify the name of the system where the job that created the spooled file ran.

Spooled file created (CRTDATE)

Specifies the date and time the spooled file was created. This parameter is considered after the job name, user name, job number, spooled file name, spooled file number and job system name parameter requirements have been met.

Single values

*ONLY
There is only one spooled file with the specified job name, user name, job number, spooled file name, spooled file number and job system name.
*LAST
The spooled file with the latest creation date and time of the specified job name, user name, job number, spooled file name, spooled file number and job system name is used.

Element 1: Creation date

date
Specify the date the spooled file was created.

Element 2: Creation time

*ONLY
There is only one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, job system name, and spooled file creation date.
*LAST
The spooled file with the latest creation time of the specified job name, user name, job number, spooled file name, spooled file number,job system name, and spooled file creation date is used.
time
Specify the time the spooled file was created.

TCP/IP data (TCPDTA)

Specifies whether a subset of TCP/IP and/or SSL trace data should be collected. Each parameter element is optional; if no element value is specified, no filtering of trace data is done for that element. For example, if *TCP is specified for element 1, only trace records where the TCP protocol is used are collected. If no value is specified for element 1, trace records using all TCP/IP protocols are collected.

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

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

Element 3: Remote port

1-65535
Specify one or two remote port numbers for which trace data is collected

Element 4: Local IP address

character-value
Specify a local internet protocol address.

Element 5: Remote IP address

character-value
Specify a remote internet protocol address.

Element 6: Line description

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

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

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.

Examples

Example 1: Starting SSL Traces

TRCCNN   SET(*ON)  TRCTYPE(*SSL)

This command starts tracing for Secure Sockets Layer (SSL) connections.

Example 2: Starting IP Traces

TRCCNN   SET(*ON)  TRCTYPE(*IP)

This command starts tracing for connections at the internet protocol (IP) version 4 (IPv4) and version 6 (IPv6) level.

Example 3: Stopping Traces and Clearing Trace Storage

TRCCNN   SET(*END)

This command stops all traces and deletes the trace table. No spooled output is generated.

Example 4: Printing Traces

TRCCNN   SET(*OFF)

This command stops all traces and generates a spooled file (QPCSMTRC) that contains the trace records collected by the TRCINT (Trace Internal) command, and a spooled file (QSYSPRT) that contains the formatted trace data.

Example 5: Formatting Trace Data from TRCINT Command

TRCINT   SET(*ON)  TRCTYPE(*SCK)
TRCINT   SET(*OFF)
TRCCNN   SET(*FORMAT)  TRCTYPE(*SSL)  JOB(*)  SPLNBR(*LAST)

The TRCINT (Trace Internal) commands are used to start collecting trace records related to all usage of sockets, and to stop collecting trace records and create a spooled file named QPCSMPRT. The TRCCNN command will use the trace information in the last spooled file named QPCSMPRT for the current job, and format the trace records related to SSL (Secure Sockets Layer) in a spooled file named QSYSPRT.

Example 6: Specifying a Trace Table

TRCCNN   SET(*ON)  TRCTYPE(*IP)  TRCTBL(USER)

This command starts tracing for connections at the internet protocol (IP) version 4 (IPv4) and version 6 (IPv6) level and stores the trace data in the USER trace table.

Example 7: Specifying a Trace Table Size in Megabytes

TRCCNN   SET(*ON)  TRCTYPE(*IPV6)  SIZE(20000 *MB)

This command starts tracing for connections at the internet protocol version 6 (IPv6) level and stores the data in a 20000-megabyte trace table.

Example 8: Specifying a CCSID for Trace Data

TRCCNN   SET(*OFF)  CCSID(*ASCII)

This command stops all traces and generates a spooled file (QSYSPRT). ASCII (819) CCSID will be used when formatting the trace data.

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

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

This command starts tracing for connections at the internet protocol version 4 (IPv4) level. 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 10: Start a Trace and Watch for a LIC Log Entry to End the Trace

TRCCNN   SET(*ON) TRCTYPE(*IPV4)
         WCHLICLOG(('99??' 9932 MYJOBNAME))
         WCHTIMO(*NOMAX)

This command starts tracing for connections at the internet protocol version 4 (IPv4) level. 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 TRCCNN command is issued manually to end the trace.

Example 11: Sending the Trace to a Stream File

TRCCNN   SET(*OFF) OUTPUT(*STMF)
         TOSTMF('/user/Test.stmf' *YES)

This command stops all traces and dumps the information to stream file /user/Test.stmf in PCAP format. If the stream file exists, it will be replaced. Please note that SSL data cannot be dumped to a stream file in PCAP format.

Error messages

Unknown