TRCCNN (Trace Connection)

TRCCNN Command syntax diagram

 

Purpose

The Trace Connection (TRCCNN) command allows the tracing of encrypted data flowing over internet protocol (IP) 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 and generate an intermediate spooled file named QPCSMPRT. The QPCSMPRT spooled file data is used to generate a spooled file named QSYSPRT. The user data for the QSYSPRT file is 'TRCCNN'.

You can 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

1. This command is shipped with public *EXCLUDE authority.
2. To use this command have *SERVICE special authority, or be authorized to the Service Trace function of Operating System/400

   through iSeries Navigator's Application Administration support.>The Change Function Usage Information (QSYCHFUI) API, 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.

3. The following user profiles have private authorities to use the command:

   • QSRV

 

Required Parameters

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.

*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. A spooled file named QPCSMPRT is generated by the TRCINT command and contains the collected trace record data. TRCCNN formats this data in a second spooled file named QSYSPRT. The user data for the QSYSPRT spooled file is 'TRCCNN'. The trace table is deleted after the spooled files are generated.

*END: Collection of trace records stops and the trace table is deleted. No spooled 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 and SPLNBR parameters to identify which QPCSMPRT file to use.

 

Optional Parameters

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

*SSL: Trace SSL (Secure Sockets Layer) connection data.

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.

For example, if TRCCNN SET(*ON) and TRCTBL(*GEN) are specified and the job identifier of the current job is 016870/QSRV/QPADEV000D, the generated trace table name is TRCCNN016870.

trace-table-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

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.

Element 1: Size

16000: The trace table size is 16000 kilobytes or 16000 megabytes, depending on the Unit of measure value.

table-size: Specify the size of the trace table in kilobytes or megabytes. Valid values range from 128 through 258048.

Element 2: Unit of measure

Specifies whether the value specified for the Size 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.

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

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.

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.

The possible values are:

*EBCDIC: The EBCDIC (37) character code is used.

*ASCII: The ASCII (819) character code is used.

coded-character-set-identifier: Specify a CCSID value to be used when formatting the trace data.

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.

number-of-bytes: Specify the number of bytes of data to be formatted. The minimum number of bytes allowed is 72.

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.

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

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

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

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

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

spooled-file-number: Specify the number of the QPCSMPRT spooled file created by the specified job.

JOBSYSNAME

Specifies the name of the system where the job that create 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.

The possible values are:

*ONLY: There is 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.

job-system-name: Specify the name of the system where the job that created the spooled file ran.

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.

*ONLY: There is 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: Date Spooled File was Created.

date: Specify the date the spooled file was created.

Element 2: Time Spooled File was Created. *ONLY: There is one spooled file with the specified job name, user name, job number, spooled file name, spooled file number, and 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.>

TCPDTA

Specifies whether a subset of TCP/IP and/or Sockets 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 *ARP is specified for element 1, only trace records where the ARP 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 would only apply for TCP/IP.

*ICMP6: Enable trace for internet control message protocol version 6.

Element 2: Local Ports

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

Element 3: Remote Ports

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

Element 4: Local IP Address

Specify a local internet protocol address in the form nnn.nnn.nnn.nnn, where nnn is a number between 1 and 255.

Element 5: Remote IP Address

Specify a remote internet protocol address in the form nnn.nnn.nnn.nnn, where nnn is a number between 1 and 255.

Element 6: Line Description Name

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

Examples for TRCCNN

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) 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) level and stores the trace data in the USER trace table.

Example 7: Specifying a Trace Table Size in Megabytes

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

This command starts tracing for connections at the internet protocol (IP) 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.

Error messages for TRCCNN

No error messages.>