gtpc1m7nTransmission Control Protocol/Internet Protocol

Using the Offline IPTPRT Utility to Create an IPTPRT Report

Use the offline IPTPRT utility to create an IPTPRT report, which you can view or print offline. Unlike using the ZIPTR command to display the IP trace table online, the IPTPRT utility offers you more flexibility in selecting the information to include in the IPTPRT report. For example, you can print in the IPTPRT report only the data transferred between the TPF system and a specific IP router, or only the data between the TPF system and a specific remote resource. See Defining the IPTPRT Report for more information.

Another difference between creating an IPTPRT report and using the ZIPTR command to display the IP trace table online is that you create an IPTPRT report from the IP trace table on a real-time tape rather than in core storage. If you enter the ZIPTR command to display the IP trace table online while you are tracing active resources, the oldest entries in the IP trace table may be overwritten with new data. Therefore, after this happens, you cannot display those entries online. However, because you create an IPTPRT report from the IP trace table on a real-time tape, you never have this problem.

The IPTPRT utility runs on an MVS system. Before you can use the IPTPRT utility to create an IPTPRT report, you must do the following:

  1. Compile the IPTPRT utility.
  2. Submit the object code to the object library.
  3. Link the object code to the link library.

To create an IPTPRT report, do the following:

  1. Follow the steps in Starting the IP Trace Facility and Specifying Which Data to Trace to start the IP trace facility and specify which data you want to trace.
  2. When you are ready to create an IPTPRT report, perform a tape switch for the real-time tape. See TPF Operations for more information about performing a tape switch.
  3. Create the job control language (JCL) needed to run the IPTPRT utility. See Sample JCL for the IPTPRT Utility for an example.
  4. Define the IPTPRT report by updating the PARM= parameter in the IPTPRT JCL. This allows you to specify the format of the IPTPRT report and the data you want to include in it. See Defining the IPTPRT Report for more information.
  5. Submit the IPTPRT JCL to the MVS system to run the IPTPRT utility and create the IPTPRT report. See IPTPRT Messages for information on possible return codes.
  6. View or print the IPTPRT report.

Sample JCL for the IPTPRT Utility

Figure 36 shows an example of the JCL that you can use to run the IPTPRT utility. Change the tape number, shown as XXXXXX, to the tape number for the real-time tape that contains the IP trace table. Change the link library name, shown as NNN.NNNN.NNNN.NN, to the name of your link library.

Figure 36. JCL for the IPTPRT Utility

//IP  EXEC PGM=IPTPRT,PARM='ALL COMPACT'
//STEPLIB  DD  DISP=SHR,DSN=NNN.NNNN.NNNN.NN
//PRINT    DD  SYSOUT=A,DCB=(LRECL=133,BLKSIZE=3990,RECFM=FBA)
//IPTR     DD  DSN=RTL,DCB=(LRECL=4095,BLKSIZE=32760,RECFM=U),
//           DISP=OLD,LABEL=(2,BLP),UNIT=TAPE,VOL=SER=XXXXXX
//SYSUDUMP DD  SYSOUT=A
/*
//* RECFM=VB FOR TAPES CREATED IN BLOCKED FORMAT.

Defining the IPTPRT Report

Use the PARM= parameter in the IPTPRT JCL to define the IPTPRT report. You can specify the data that you want to print in the IPTPRT report as well as how you want to format the IPTPRT report.

Unlike using the ZIPTR command to display a specific number of entries from the IP trace table, you can actually define the type of data that you want to print in an IPTPRT report. For example, you can print the entire IP trace table on the real-time tape or you can print only the data that flowed over an IP router. You can also print only the data for a remote resource or print only the data that has a time stamp in a specified range.

There are two formats in which you can create the IPTPRT report. Use the PARM= parameter to specify whether you want to create a compacted IPTPRT report or a formatted IPTPRT report.

See Sample Compacted IPTPRT Report for an example of a compacted IPTPRT report and Sample Formatted IPTPRT Report for an example of a formatted IPTPRT report.

PARM= Parameter for the IPTPRT JCL

Many values are available in the IPTPRT JCL for the PARM= parameter that allow you to change the contents of the IPTPRT report to your specific needs. The following shows the syntax for the PARM= parameter and describes the values.


ALL
includes all of the IP packets in the IP trace table in the IPTPRT report.

ASCII
displays the data portion of the output in ASCII format. This value applies only to a formatted IPTPRT report.

COMPACT
creates a compacted IPTPRT report in which each entry is printed on a single line. See Sample Compacted IPTPRT Report for an example of a compacted IPTPRT report. If you do not specify this value, a formatted IPTPRT report is created.

DATE ddmmm
includes in the IPTPRT report only the IP packets that flowed on the specified date, where dd is the day and mmm is the first 3 characters of the name of the month.

DIP destip
includes in the IPTPRT report only the IP packets whose destination IP address is destip.

DPORT destport
includes in the IPTPRT report only the IP packets whose destination port is destport.

FILE filename
writes the IPTPRT report to the specified file.

FLAG flagname
includes in the IPTPRT report only the IP packets for TCP sockets that have the specified flags set in the TCP header of the packet.

ICCW ipccw
includes in the IPTPRT report only the IP packets that flowed between the TPF system and the IP router or OSA-Express connection whose IP CCW index is ipccw.

IP ip
includes in the IPTPRT report only the IP packets whose destination IP address is ip, or whose source IP is ip.

NARROW
creates the IPTPRT report in a narrow format (80 columns wide). If you do not specify this value, the default is to create an IPTPRT report that is 132 columns wide.

PORT port
includes in the IPTPRT report only the IP packets whose destination port is port, or whose source PORT is port.

PROT protocol
includes in the IPTPRT report only the IP packets whose protocol is protocol.

RC reasoncode
includes in the IPTPRT report only the IP packets that contain a predefined reason code that indicates an exception condition is associated with the packet, where reasoncode is one of the following:

00
includes all possible reason codes.

01
includes all packets with the REJECTED BY FIREWALL reason code value. This reason code occurs when a packet is rejected based on a packet filtering rule. This reason code is shown in the IPTPRT report for both the input packet that generated the exception condition and the output packet that is sent as a result of the exception condition.

02
includes all packets with the DISCARDED BY FIREWALL reason code value. This reason code occurs when a packet is discarded based on a packet filtering rule.

03
includes all packets with the SERVER NOT ACTIVE reason code value. This reason code occurs when a TCP connection request is received for a server that is not active. This reason code is shown in the IPTPRT report for both the input packet that generated the exception condition and the output packet that is sent as a result of the exception condition.

04
includes all packets with the SOCKET DOES NOT EXIST reason code value. This reason code occurs when a TCP message (not a connection request) was received, but the specified socket does not exist. This reason code is shown in the IPTPRT report for both the input packet that generated the exception condition and the output packet that is sent as a result of the exception condition.

05
includes all packets with the BACKLOG LIMIT EXCEEDED reason code value. This reason code occurs when the remote client tries to start a connection with a TCP server on the TPF system, but the backlog limit for this application has been exceeded. This reason code is shown in the IPTPRT report for both the input packet that generated the exception condition and the output packet that is sent as a result of the exception condition.

06
includes all packets with the NO SOCKETS AVAILABLE reason code value. This reason code occurs when a TCP connection request was received, but no socket block entries are available in the TPF system to start a new socket. This reason code is shown in the IPTPRT report for both the input packet that generated the exception condition and the output packet that is sent as a result of the exception condition.

07
includes all packets with the POSSIBLE SYN ATTACK reason code value. This reason code occurs when the TPF system is running out of socket blocks and the connection request from this remote client has been pending for a long period of time. The connection request is cleaned up to free socket block entries.

08
includes all packets with the CLOSED BY APPLICATION reason code value. This reason code occurs when the close function was issued for this socket. The socket was either starting, ending, or had input messages queued that have not been processed.

09
includes all packets with the CLOSED BY SOCKET SWEEPER reason code value. This reason code occurs when the socket sweeper program closes a socket because the socket is no longer being used.

10
includes all packets with the RETRANSMIT LIMIT EXCEEDED reason code value. This reason code occurs when the TPF system closes the socket because the TPF system retransmitted messages that have not been acknowledged by the remote client and the retransmit limit has been reached.

11
includes all packets with the ZTTCP INACTIVATE SOCKETS reason code value. This reason code occurs when the ZTTCP INACTIVATE command is entered with the SOCKETS parameter specified to deactivate the socket.

12
includes all packets with the ZSOCK INACTIVATE SOCKETS reason code value. This reason code occurs when the ZSOCK command was entered with the INACT parameter specified to deactivate one or more sockets.

13
includes all packets with the NOT AUTHORIZED reason code value. This reason code occurs when the TCP/IP native stack support accept connection user exit, UACC, rejected the connection request.

14
includes all packets with the CYCLE DOWN reason code value. This reason code occurs when a socket is closed because the TPF system is cycling down to 1052 state.

15
includes all packets with the TCP OPTIONS NOT VALID reason code value. This reason code occurs when the connection request was received, but was rejected because the TCP options specified by the remote client are not valid. This reason code is shown in the IPTPRT report for both the input packet that generated the exception condition and the output packet that is sent as a result of the exception condition.

16
includes all packets with the SSL DAEMON SHUTDOWN reason code value. This reason code occurs when the socket is associated with a shared SSL session and the SSL daemon processes are shutting down and closing their sockets.

17
includes all packets with the APPLICATION NOT ACTIVE reason code value. This reason code occurs when a UDP message was received, but the specified application (port) is not active. This reason code is shown in the IPTPRT report for both the input packet that generated the exception condition and the output packet that is sent as a result of the exception condition.

18
includes all packets with the DESTINATION NOT TPF reason code value. This reason code occurs when a packet is received from the network, but the destination is not an IP address in the TPF system and the message is discarded.

19
includes all packets with the RESTRICTED CDLC IP ADDRESS reason code value. This reason code occurs when the packet is discarded by the TPF system because the packet was received on a restricted IP address, but across the wrong symbolic device address (SDA).

20
includes all packets with the RETRANSMITTED MESSAGE reason code value. This reason code occurs when the message is retransmitted by the TPF system.

SIP sourceip
includes in the IPTPRT report only the IP packets whose source IP address is sourceip.

SPORT sourceport
includes in the IPTPRT report only the IP packets whose source port is sourceport.

TIME time1 time2
includes in the IPTPRT report only the IP packets in the specified time-stamp range, where time1 and time2 are the beginning and ending times in the format hh.mm.ss.

TOD tod1 tod2
includes in the IPTPRT report only the IP packets in the specified time-stamp range, where tod1 and tod2 are the beginning and ending times in time-of-day clock format.

Sample PARM= Parameters for the IPTPRT JCL

A compacted IPTPRT report of all the data in the IP trace table is created in the following example.

//IP  EXEC PGM=IPTPRT,PARM='ALL COMPACT'

A formatted IPTPRT report is created in the following example. The report includes all data transferred between the TPF system and the remote resource whose IP address is 9.117.102.113.

//IP  EXEC PGM=IPTPRT,PARM='IP 9.117.102.113'

Sample Compacted IPTPRT Report

To create a compacted IPTPRT report, specify the COMPACT value in the PARM= parameter of the IPTPRT JCL.

In a compacted IPTPRT report, each IP packet is printed on a single line and only part of the user data that was traced is included. The following information is displayed:

  RW  
The read/write operation code, where:

 EVEN 
Even numbers represent read operations.

 ODD 
Odd numbers represent write operations.

 IN 
The IP channel command word (IPCCW) area index, where:

 01-C7 
CDLC IP routers.

 D1-EE 
OSA-Express connections.

 FF 
Local sockets.

 SOURCE IP 
The source IP address.

 DEST IP 
The destination IP address.

 SPORT 
The source port. This field has meaning only for packets using TCP or UDP.

 DPORT 
The destination port. This field has meaning only for packets using TCP or UDP.

 PR 
The protocol. Sample values are as follows:

 01 
ICMP

 06 
TCP

 11 
UDP

 FG 
The TCP flag byte. This field has meaning only for packets using TCP.

 DATA 
The user data in the IP packet.

Figure 37 shows a narrow format example of a compacted IPTPRT report.

Figure 37. Compacted IPTPRT Report


************************************************************************
            TRANSACTION  PROCESSING  FACILITY  TCP/IP  TRACE  OUTPUT
************************************************************************
RECORDS MATCHING THE FOLLOWING SELECTION CRITERIA WILL BE PRINTED:
PROTOCOLS: . . . . . . . . ALL
SOURCE PORTS:  . . . . . . ALL
DESTINATION PORTS: . . . . ALL
SOURCE IP ADDRESSES: . . . ALL
DESTINATION IP ADDRESSES:  ALL
REASON CODES:  . . . . . . ALL
IP CCW:  . . . . . . . . . ALL
DATE:  . . . . . . . . . . FROM JAN01 TO DEC31
TIME:  . . . . . . . . . . FROM 00:00:00 TO 23:59:59
TOD (FIRST WORD):  . . . . FROM 00000000 TO FFFFFFFF
TCP FLAGS: . . . . . . . . ALL
NARROW LAYOUT
COMPACT FORMAT
RW IN    SOURCE IP       DEST IP      SPORT DPORT PR FG DATA
32 03    9.117.249.50    9.117.249.51  1024  9999 06 02
31 03    9.117.249.51    9.117.249.50  9999  1024 06 12
52 03    9.117.249.50    9.117.249.51  1024  9999 06 10
32 03    9.117.249.50    9.117.249.51  1024  9999 06 18 D7C9D5C760D7D6D5
32 03    9.117.249.50    9.117.249.51  1024  9999 06 18 4040F1F0F0818181
51 03    9.117.249.51    9.117.249.50  9999  1024 06 10
31 03    9.117.249.51    9.117.249.50  9999  1024 06 18 4040F1F0F0828282
52 03    9.117.249.50    9.117.249.51  1024  9999 06 18 4040F1F0F0818181

Sample Formatted IPTPRT Report

To create a formatted IPTPRT report, do not specify the COMPACT value in the PARM= parameter of the IPTPRT JCL.

In a formatted IPTPRT report, each IP packet is formatted and all the user data that was traced is printed.

Different information is displayed depending on the protocol of the packet (TCP, UDP, or others).

Figure 38 shows an example of a formatted IPTPRT report.

Figure 38. Formatted IPTPRT Report


************************************************************************
            TRANSACTION  PROCESSING  FACILITY  TCP/IP  TRACE  OUTPUT
************************************************************************
RECORDS MATCHING THE FOLLOWING SELECTION CRITERIA WILL BE PRINTED:
PROTOCOLS: . . . . . . . . ALL
SOURCE PORTS:  . . . . . . ALL
DESTINATION PORTS: . . . . ALL
SOURCE IP ADDRESSES: . . . ALL
DESTINATION IP ADDRESSES:  ALL
REASON CODES:  . . . . . . ALL
IP CCW:  . . . . . . . . . ALL
DATE:  . . . . . . . . . . FROM JAN01 TO DEC31
TIME:  . . . . . . . . . . FROM 00:00:00 TO 23:59:59
TOD (FIRST WORD):  . . . . FROM 00000000 TO FFFFFFFF
TCP FLAGS: . . . . . . . . ALL
WIDE LAYOUT
IP FORMATTED TRACE
RWI-52  IPCCW-01  SOURCE IP-9.117.107.167  DEST IP-9.117.249.50  LEN-48
  TOD-B70C206B31D6FB20  PROTOCOL-06 (TCP)  SOURCE PORT-1865  DEST PORT-21
  SEQ-102459496  WINDOW-16384  URGENT OFFSET-0
  TCP FLAG BYTE-02 (SYN)
  IP HEADER   45000030 7F254000 7D0606DF 09756BA7 0975F932
  TCP HEADER  07490015 061B6868 00000000 70024000 55DD0000 02040551 01010402
RWI-51  IPCCW-01  SOURCE IP-9.117.249.50  DEST IP-9.117.107.167  LEN-44
  TOD-B70C206B3254DA00  PROTOCOL-06 (TCP)  SOURCE PORT-21  DEST PORT-1865
  SEQ-112401775  ACK-102459497  WINDOW-32767  URGENT OFFSET-0
  TCP FLAG BYTE-12 (ACK, SYN)
  IP HEADER   4500002C 9E070000 3C066901 0975F932 09756BA7
  TCP HEADER  00150749 06B31D6F 061B6869 60127FFF 06B20000 02040551
RWI-32  IPCCW-01  SOURCE IP-9.117.107.167  DEST IP-9.117.249.50  LEN-40
  TOD-B70C206B371FE785  PROTOCOL-06 (TCP)  SOURCE PORT-1865  DEST PORT-21
  SEQ-102459497  ACK-112401776  WINDOW-17693  URGENT OFFSET-0
  TCP FLAG BYTE-10 (ACK)
  IP HEADER   45000028 7F264000 7D0606E6 09756BA7 0975F932
  TCP HEADER  07490015 061B6869 06B31D70 5010451D 58EE0000

IPTPRT Messages

When you submit the IPTPRT JCL to run the IPTPRT utility, the report will include a list of detected errors. For more information about the error message numbers shown in the report, see Messages (System Error and Offline) and Messages (Online).