Additional filters for SYSTCPIP

The following additional trace filters for limiting the volume of trace data are available:

The IPADDR keyword filters by IP address
The PORT keyword filters by port number
The EID keyword filters by event identifier
The EID keyword specifies up to 16 trace event identifiers. Each identifer is 8 hexadecimal characters. For example: EID(00010001,00090001,40030003). Use the EID keyword only with the direction of IBM® service personnel.

To execute a trace on a particular IP address, use the IP address, port number, ASID, and JOBNAME as targets for filtering the records.

To use this function, start by issuing the TRACE command:

TRACE CT,ON,COMP=SYSTCPIP,SUB=(tcpip_procedure_name)
 R 01,OPTIONS=(IPADDR(12AB:0:0:CD30::/60),PORT(1012))
 R 02,OPTIONS=(ENGINE,PFS),END

Trace records of type ENGINE or PFS for an IP address of 12AB:0:0:CD30::/60 and a port number of 1012 are captured. The IP address used is the foreign session partner IP address. The port number is the local session partner port number.

When filters are used, the trace record must be accepted by each filter. Each filter can specify multiple values (up to 16), and the trace record must match one of the values.

Table 1 lists the data types and corresponding description.

Table 1. Data types
Data type	Description
Inbound	Data received at the IP layer is considered inbound data. The source IP address and the destination port number are used.
Outbound	Data sent in the PFS layer is considered outbound data. The destination IP address and the source port number are used.

The following are five criteria for selecting trace records for recording:

TYPE
JOBNAME
ASID
IPADDR
PORT

Each criterion can specify one or more values. If a criterion has been specified, the record to be traced must match one of the values for that criterion. If a criterion has not been specified, the record is not checked and does not prevent the record from being recorded. However, the record must match all specified criteria.

In the above example, JOBNAME and ASID were not specified, so the value of JOBNAME and ASID in the record are not checked.

Restriction: IPADDR and PORT are exceptions. Some trace records do not have a IP address or a port number. Therefore, the IP address in the trace record is only checked if it is nonzero, and the port number is checked only if it is nonzero.

You can also specify a range of IP addresses to trace. For example,

TRACE CT,ON,COMP=SYSTCPIP,SUB=(TCPIP_PROC_NAME)
  R xx, OPTIONS = (IPADDR(nn.nn.nn.nn,{nn.nn.nn.nn/mm.mm.mm.mm}),PORT(pppp{,pppp}))

IPADDR: An IP address. Up to 16 addresses can be specified. IPv4 addresses are in dotted decimal notation, for example: 192.48.24.57. IPv6 addresses are in colon-hexadecimal notation or in a combination of both colon-hexadecimal and dotted decimal for IPv4-mapped IPv6 addresses, for example: beef::c030:1839. Use an IP address of 0 for trace records that do not have an IP address. A subnet mask is indicated by a slash (/) followed by the prefix length in decimal or by a dotted decimal subnet mask for IPv4 addresses. The prefix length is the number of one bits in the mask. For IPv4 addresses it might be in the range of 1–32; for IPv6 addresses it might be in the range of 1–128, for example: 192.48.24/24 or 2001:0DB8::0/10, respectively.
PORT: The list of port numbers to be filtered. Up to 16 port numbers can be specified. The port numbers, specified in decimal, must be in the range 0–65535. A trace record with a zero port number is not subject to port number filtering.

You can specify the IPADDR and PORT keywords multiple times in an OPTIONS string. If you do, all the values are saved.

Restriction: All the values in the OPTIONS keyword must be specified in one trace command. The next trace command with an OPTIONS keyword replaces all the options specified.