gtps2m46ACF/SNA Data Communications Reference

Using the Offline PIU Print (PIUPRT) Utility to Create a PIUPRT Report

Use the offline PIUPRT utility to create a PIUPRT report, which you can view or print offline. Unlike using the ZNPIU command to display the PIU trace table online, the PIUPRT utility offers you more flexibility to change the information contained in the PIUPRT report. For example, you can print in the PIUPRT report only the data transferred between the TPF system and a specific remote resource, or only the data that flowed over a specific RTP connection. See Defining the PIUPRT Report for more information.

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

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

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

To create a PIUPRT report, do the following:

  1. Follow the steps in Starting the PIU Trace Facility and Specifying Which Data to Trace to start the PIU trace facility and specify which data you want to trace.
  2. When you are ready to create a PIUPRT 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 PIUPRT utility. See Sample JCL for the PIUPRT Utility for an example.
  4. Define the PIUPRT report by updating the PARM= statement in the PIUPRT JCL. This allows you to specify the format of the PIUPRT report and the data you want to include in it. See Defining the PIUPRT Report for more information.
  5. Submit the PIUPRT JCL to the MVS system to run the PIUPRT utility and create the PIUPRT report. See PIUPRT Utility Return Codes for information.
  6. View or print the PIUPRT report.

Sample JCL for the PIUPRT Utility

Figure 97 is an example of the JCL that you can use to run the PIUPRT utility. Change the tape number, shown as XXXXXX, to the tape number for the real-time tape that contains the PIU trace table. Change the link library name, shown as ACP.DEVP.TEST.LK, to the name of your link library.

Figure 97. JCL for the PIUPRT Utility

//PIU EXEC PGM=PIUPRT,PARM='FORMAT ALL'
//STEPLIB  DD  DISP=SHR,DSN=ACP.DEVP.TEST.LK
//PRINT    DD  SYSOUT=A,DCB=(LRECL=133,BLKSIZE=3990,RECFM=FBA)
//RTL      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 PIUPRT Report

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

Unlike using the ZNPIU command to display a specific number of entries from the PIU trace table, you can actually define the type of data that you want to print in a PIUPRT report. For example, you can print the entire PIU trace table on the real-time tape or you can print only the data that flowed over a particular RTP connection. You can also print only the data for a particular LU-LU session or print only the data that has a time stamp in a specified range.

Specify the CONTROL parameter for the PARM= statement to include HPR control messages in the PIUPRT report. An HPR control message is an NLP that contains an NHDR and THDR, but no data. If you do not specify the CONTROL parameter, the HPR control messages are not printed in the PIUPRT report.

Depending on the data contained in the PIU trace table on the real-time tape and the values that you specify for the PARM= statement in the PIUPRT JCL, a PIUPRT report can contain PIUs in FID2 or FID4 format, NLPs, and 8-byte CTC headers (which are included in all read and write channel programs during normal CTC data transfer operations). There are also two formats in which you can create the PIUPRT report. Use the PARM= statement to specify whether you want to create a compacted PIUPRT report or a formatted PIUPRT report.

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

PARM= Statement for the PIUPRT JCL

Many parameters are available for the PARM= statement in the PIUPRT JCL that allow you to change the contents of the PIUPRT report to your specific needs. The following information shows the syntax for the PARM= statement and describes the parameters.




All
includes in the PIUPRT report all of the path information units (PIUs) and network layer packets (NLPs), except for HPR control messages, in the PIU trace table.

COMPACT
creates a compacted PIUPRT report in which each entry is printed on a single line. See Sample Compacted PIUPRT Report for an example of a compacted PIUPRT report.

Control
includes the HPR control messages in the PIUPRT report. If you do not specify this parameter, the HPR control messages are not included in the PIUPRT report.

FORMAT
creates a formatted PIUPRT report. See Sample Formatted PIUPRT Report for an example of a formatted PIUPRT report.

HEADERS
prints the network layer header (NHDR) and transport header (THDR) for each HPR network layer packet (NLP) included in the PIUPRT report. If you do not specify this parameter, the NHDR and THDR are not printed for the NLPs included in the PIUPRT report.

HPr
includes only HPR traffic (NLPs and ROUTE_SETUP commands) in the PIUPRT report.

HSa sadr
includes in the PIUPRT report only the NLPs for the specified HPR LU-LU session, where sadr is the 16-digit hexadecimal session address of the HPR LU-LU session.

Leid leid1 leid2
includes in the PIUPRT report only the PIUs for the specified origin or destination network extension facility (NEF) logical endpoint identifier (LEID) or range of LEIDs, where leid1 and leid2 are 6-digit hexadecimal LEIDs.

LONG
creates a formatted PIUPRT report. See Sample Formatted PIUPRT Report for an example of a formatted PIUPRT report.
Note:
This parameter is the same as the FORMAT parameter.

NAme netid.name
includes in the PIUPRT report only the PIUs and NLPs for the specified resource, where netid is the 1- to 8-character network identifier and name is the 1- to 8-character resource name. The network ID and name of a resource must both begin with a letter (A-Z), @, #, or $. The remaining characters can be letters (A-Z), numbers (0-9), @, #, or $. 

Use the asterisk (*) as a wildcard character to specify a group of network identifiers or resource names that begin or end with a common string of characters. For example, to include in the PIUPRT report all of the resources that have a name beginning with T46, specify T46*.

NE nadr1 nadr2
includes in the PIUPRT report only the PIUs for the specified origin or destination network address or range of network addresses, where nadr1 and nadr2 are 6-digit hexadecimal network addresses.

NET4 nadr1 nadr2
includes in the PIUPRT report only the PIUs for the specified origin or destination network address or range of network addresses, where nadr1 and nadr2 are 6-digit hexadecimal network addresses.

NODATA
omits the RU from the PIU trace table entries contained in the PIUPRT report. If you do not specify this parameter, the RU for each PIU trace table entry contained in the PIUPRT report is printed.

Pcid pcid
includes in the PIUPRT report only the PIUs and NLPs for the specified procedure correlation identifier (PCID), where pcid is the 16-digit hexadecimal PCID.

RId rid1 rid2
includes in the PIUPRT report only the PIUs and NLPs for the specified origin or destination resource identifier (RID) or range of RIDs, where rid1 and rid2 are 6-digit hexadecimal RIDs.

RTp index
includes in the PIUPRT report only the NLPs for the specified RTP connection, where index is the 6-digit hexadecimal RTPCB index of the RTP connection.

SA sub1 sub2
includes in the PIUPRT report only the PIUs for the specified origin or destination subarea or range of subareas, where sub1 and sub2 are 4-digit hexadecimal subareas.

SID0 sid
includes in the PIUPRT report only the PIUs for a specific PU 2.1 LU-LU session, where sid is the 4-digit hexadecimal TPF-assigned session identifier (ID).

SID1 sid
includes in the PIUPRT report only the PIUs for a specific PU 2.1 LU-LU session, where sid is the 4-digit hexadecimal NCP-assigned session ID.

STatchng
includes in the PIUPRT report only ROUTE_SETUP commands and NLPs for RTP connections that are starting, ending, or performing a path switch.

SUB sub1 sub2
includes in the PIUPRT report only the PIUs for the specified origin or destination subarea or range of subareas, where sub1 and sub2 are 4-digit hexadecimal subareas.

S0 sid
includes in the PIUPRT report only the PIUs for a specific PU 2.1 LU-LU session, where sid is the 4-digit hexadecimal TPF-assigned session ID.

S1 sid
includes in the PIUPRT report only the PIUs for a specific PU 2.1 LU-LU session, where sid is the 4-digit hexadecimal NCP-assigned session ID.

TCid tcid
includes in the PIUPRT report only NLPs for the specified transport connection identifier (TCID), where tcid is the 16-digit hexadecimal TCID.

TIme ti1 ti2 dt
includes in the PIUPRT report only the PIUs and NLPs in the specified time-stamp range, where ti1 and ti2 are the beginning and ending times in the format hh.mm.ss, and dt is the date in the format ddmmm; for example 11:45:00 12:00:00 15DEC.

Sample PARM= Statements for the PIUPRT JCL

A compacted PIUPRT report of all the data in the PIU trace table, including HPR control messages, is created in the following example.

    //PIU EXEC PGM=PIUPRT,PARM='CONTROL'
 

A compacted PIUPRT report is created in the following example. The report includes all data transferred between the TPF system and remote resources that have a name beginning with T46.

    //PIU EXEC PGM=PIUPRT,PARM='NA T46*'
 

A formatted PIUPRT report of all HPR traffic is created in the following example. HPR control messages and the NHDR and THDR for each NLP are included in the PIUPRT report. However, no RU data is included in the PIUPRT report.

    //PIU EXEC PGM=PIUPRT,PARM='FORMAT HEADERS NODATA CONTROL HPR'
 

A compacted PIUPRT report is created in the following example. The report includes all of the PIUs and NLPs in the PIU trace table that have an origin or destination RID in the range 000001-000100 and a time stamp in the range 9:30-9:40 on August 14.

    //PIU EXEC PGM=PIUPRT,PARM='RID 000001 000100 TIME 09:30:00 09:40:00 14AUG'
 

Sample Compacted PIUPRT Report

To create a compacted PIUPRT report, specify the COMPACT parameter in the PARM= statement of the PIUPRT JCL; also specify the CONTROL parameter if you want to print the HPR control messages in the PIUPRT report. See Defining the PIUPRT Report for more information.

In a compacted PIUPRT report, each PIU, NLP, or CTC header is printed on a single line and only part of the RU that was traced is included. Different information is printed in the compacted PIUPRT report depending on whether you are printing FID2 PIUs, FID4 PIUs, NLPs, or CTC headers.

Figure 98 shows an example of a compacted PIUPRT report. The header in the PIUPRT report contains three lines. The first line describes the information printed for an FID4 PIU. The second line describes the information printed for an FID2 PIU. The third line displayed describes the information printed for an NLP.

The example prints four entries in the PIU trace table in the following order:

Figure 98. Compacted PIUPRT Report


***********************************************************************************************************************************
                                    TRANSACTION  PROCESSING  FACILITY  SNA   PIU   TRACE  OUTPUT
***********************************************************************************************************************************
A DISPLAY OF PIUS BASED ON THE FOLLOWING USER PARAMETERS WILL BE PERFORMED:
COMPACT ALL
 
                                    TRANSACTION PROCESSING FACILITY PIU TRACE REPORT
RW IN  DRID   ORID   DNA     ONA  VRSQ SEQ  CNT    RH   RU
RW IN  DRID   ORID   LNKHDR   TH  SID  SEQ         RH   RU
RW IN  DRID   ORID   RTP         PCID       SEQ    RH   RU
*************************     THESE PIUS WERE WRITTEN TO TAPE ON 18AUG AT 12.17.32 *************************
32 01 000002 000010 0B0000 230000 0000 0000 0018 2B0000 0F00000100000000230000000B010100000023FF00
51 02 000174 000138 007B0000 2D00 0101 0174      6B8000 31010202004000020000A7008000000000000000000000000000000FE5E3C1D4D5C5E34BC7
31 02 00023E 00091A 000001 E383BE951E86713C 0001 039000 F5C31140401D4011C1C21DF011C1501D4011C2D21DF011C2601D4011C3E21DF011C3F01D40
05 0B                                                   001D000198991015

See IBM Systems Network Architecture Network Product Formats for more information about PIU and NLP formats.

Sample Formatted PIUPRT Report

To create a formatted PIUPRT report, specify the FORMAT or LONG parameter in the PARM= statement of the PIUPRT JCL; also specify the CONTROL parameter if you want to include HPR control messages in the PIUPRT report.

For a formatted PIUPRT report, you can also specify the HEADERS parameter to print the NHDR and THDR for NLPs in the PIU trace table. If you do not specify the HEADERS parameter, the NHDR and THDR are not printed. Be sure to specify the HEADERS parameter when you specify the CONTROL parameter

You can also specify the NODATA parameter if you do not want to print the RU for PIUs and NLPs in the PIUPRT report. This can be useful when you want to view control data at the RTP connection level. If you do not specify the NODATA parameter, the RU is printed.

In a formatted PIUPRT report, each PIU, NLP, or CTC header is formatted and the entire RU that was traced is printed (if you did not specify the NODATA parameter). In addition, the RH indicators and the THDR optional segments (for NLPs) are translated and printed in the PIUPRT report.

Different information is printed in the formatted PIUPRT report depending on whether you are including FID2 PIUs, FID4 PIUs, NLPs, or CTC headers.

Figure 99 shows an example of a formatted PIUPRT report. The entries are printed in the following order:

Figure 99. Formatted PIUPRT Report


***********************************************************************************************************************************
                                    TRANSACTION  PROCESSING  FACILITY  SNA   PIU   TRACE  OUTPUT
***********************************************************************************************************************************
A DISPLAY OF PIUS BASED ON THE FOLLOWING USER PARAMETERS WILL BE PERFORMED:
FORMAT HEADERS ALL
 
                                    TRANSACTION PROCESSING FACILITY PIU TRACE REPORT
*************************     THESE PIUS WERE WRITTEN TO TAPE ON 18AUG AT 12.17.08 *************************
RWI=52 CCW=01 DNAME= TPFB              ONAME= N34H710           DRID= 000002 ORID= 000010 PCID=                  TIME= 08.12
   DNA= 0B0000     ONA= 230000     ERVR= 0000   VRSQ= 0000     SEQ= 0001     CNT= 0034     RH= 2B0000
   RU = ER-ACT-RP      RH INDICS: REQ NC FI OIC NR
        0 (  0)   0C000001 00010100 00002300 00000000 0B800000 00000000 00000000 00A9BF17    ........ ........ ........ .....z..
       32 ( 20)   F51D3A23 54000000 00002300 00000001 00                                     5....... ........ .
----------------------------------------------------------------------------------------------------------------------------------
RWI=31 CCW=02 DNAME= ELMNGR            ONAME= VTAMNET.CLUBB002  DRID= 0000EE ORID= 00005F PCID= E383BE956D67FFA3 TIME= 15.33
   LNKHDR= 00790000        TH = 0101       SID= 0101       SEQ= 0465         RH= EB8000
   RU = BIND           RH INDICS: RSP SC FI PRSP
        0 (  0)   31010703 30200002 0081D6D6 81000000 00000000 00000000 0000000E E5E3C1D4    ........ .aOOa... ........ ....VTAM
       32 ( 20)   D5C5E34B C5D3D4D5 C7D90000 10E5E3C1 D4D5C5E3 4BC3D3E4 C2C2F0F0 F26016E3    NET.ELMN GR...VTA MNET.CLU BB002-.T
       64 ( 40)   83BE956D 67FFA30D E5E3C1D4 D5C5E34B E5E3C1D4 F22C0A01 08404040 40404040    c.n...t. VTAMNET. VTAM2... ........
       96 ( 60)   402D0908 C9D5E3C5 D9C1C3E3                                                 ....INTE RACT
----------------------------------------------------------------------------------------------------------------------------------
RWI=31 CCW=01 DNAME= VTAMNET.JFT10010  ONAME= JFT1              DRID= 00092B ORID= 00091C PCID= E383BE95415060AE TIME= 59.13
   LNKHDR= 00DD0000        TCID1= 1F9C92CAC2000005        TCID2= 0D5CAAC700000326        SEQ= 092B
   RTP= 000005        SA1= 30C250A1C3567004        SA2= 0000000000000000        BSN= 000005FA
   NHDR
        0 (  0)   C2088000 0220D000 00000000 0000FF00                                        B....... ........
   THDR                SEGMENTS= ARB
        0 (  0)   0D5CAAC7 00000326 3C040008 000000A9 000005FA 03228000 0010A211 00000000    .*.G.... .......z ........ ..s.....
   FID5= 5D00092BB0C250A1C3567004         RH= 6B8000
   RU = BIND           RH INDICS: REQ SC FI OIC DR
        0 (  0)   31010303 B1903082 01018585 81010200 00000000 18500000 7E00000C E5E3C1D4    .......b ..eea... .....&.. =...VTAM
       32 ( 20)   D5C5E34B D1C6E3F1 00050004 244A0810 E5E3C1D4 D5C5E34B D1C6E3F1 F0F0F1F0    NET.JFT1 .....¢.. VTAMNET. JFT10010
       64 ( 40)   6016E383 BE954150 60AE0DE5 E3C1D4D5 C5E34BE5 E3C1D4F2 2B160101 14461280    -.Tc.n.& -..VTAMN ET.VTAM2 ........
       96 ( 60)   150DE5E3                                                                   ..VT
----------------------------------------------------------------------------------------------------------------------------------
RWI=06 CCW=0B CTC LINK = V2CTCL1            CTC HDR = 03D200012B836A60

See IBM Systems Network Architecture Network Product Formats for more information about PIU and NLP formats.

PIUPRT Utility Return Codes

When you submit the PIUPRT JCL to run the PIUPRT utility, you will receive one of the return codes in the following table:

Table 25. Return Codes for the PIUPRT Utility

Return Code Description
0 PIUPRT report was created with no errors.
1 PIUPRT report was not created. The parameters specified for the PARM= statement in the PIUPRT JCL were not correct. See Defining the PIUPRT Report for more information.
2 PIUPRT report was not created. An error occurred while reading the input file.