VARY TCPIP,,DATTRACE

Use the VARY TCPIP,,DATTRACE command to trace socket data (transforms) into and out of the physical file structure (PFS). For TCP and UDP sockets, this command also creates the following records:

A Start record with the API Data Flow Starts State field that indicates the first data sent or received by the application for the associated socket.
An End record with the API Data Flow Ends State field that indicates that the socket is closed.

Format


>>-Vary--TCPIP,--+----------+----------------------------------->
                 '-procname-'   

>--,--DATtrace--+------+--| TRACE |----------------------------><
                +-,ON--+              
                '-,OFF-'              

TRACE

   .-FULL----------------------.     .-JOBNAME=*--------.      
|--+---------------------------+--,--+------------------+--,---->
   |         .-200-----------. |     '-JOBNAME=job_name-'      
   '-ABBREV=-+---------------+-'                               
             '-abbrev_length-'                                 

   .-IP=*---------------------.  .-PORTNum=*-----------.   
>--+--------------------------+--+---------------------+--------|
   '-IP=-+-| IPv4_address |-+-'  '-PORTNum=port_number-'   
         '-| IPv6_address |-'                              

IPv4_address

                 .-,SUBNet=255.255.255.255-.   
|--ipv4_address--+-------------------------+--------------------|
                 +-,SUBNet=subnet_mask-----+   
                 '-/num_mask_bits----------'   

IPv6_address

                 .-/128----------.   
|--ipv6_address--+---------------+------------------------------|
                 '-/prefixLength-'

Parameters

procname: The name of the member in a procedure library that was used to start the server or address space.
ON: Turns on socket data tracing, clears all settings previously defined, and refreshes just the default settings.
OFF: Turns off socket data tracing.
ABBREV: Specifies that a truncated portion of the socket data is to be traced. You can specify a length in the range 0 – 65 535 or use the default value 200. The ABBREV parameter can be used to reduce the volume of data stored in the trace file.
FULL: Specifies that all of the socket data is to be traced
JOBNAME: Specifies the name of the application address space to be traced. The default (*) is for all jobs.
IP: Specifies an IP address (either a 32-bit IPv4 address in dotted decimal notation, or a 128-bit IPv6 address in colon hexadecimal notation) that is compared with both the source and destination addresses of associated sockets. If either the source or destination address of a socket matches the specified IP address, the data is traced. If the IP option is omitted, or an asterisk (*) is specified, then all IP addresses are traced.
If an IPv6 address is specified, then an optional prefixLength (range 1 – 128) is allowed. IPv4 addresses and IPv4-mapped IPv6 addresses are treated as equivalent addresses. The default prefixLength is 128. If an IPv4 address is specified, then /num_mask_bits can be used. The num_mask_bits and SUBNET are mutually exclusive. An error message is displayed if both are coded.

Note: IP address selection is not recommended for use with DATTRACE.
PORTNUM: Specifies a port number that is compared with the source and destination port numbers of associated sockets. The port number must be an integer in the range 1 – 65 535. If either the source or the destination port matches the specified port number, the data is traced. If you omit the PORTNUM option or if you specify an asterisk (*), packets are not filtered based on source or destination ports.
Rule: Packets that use the RAW protocol type are not traced if you specify the PORTNUM option. The PORTNUM parameter applies only to the TCP and UDP protocols.
SUBNET: Specifies a subnet mask that applies to the host and network portions of the IP address specified on the IP=ipv4_address parameter. The subnet mask must be specified in dotted decimal notation and must be specified in conjunction with the IP=ipv4_address parameter. With an IPv4 address specified, the /num_mask_bits can be used. The num_mask_bits and SUBNET are mutually exclusive. An error message is displayed if both are coded.

Examples

You can start data traces for all job names using the VARY command:

IPv4 addressing: v tcpip,,dat,jobname=*,ip=9.67.113.61/32
IPv6 addressing: v tcpip,,dat,full,jobname=*,ip=C5::1:2:3:4/126

You can use the Netstat CONFIG/-f command to display data traces. The following example shows a data trace for a single entry.

Data Trace Setting:
   Jobname: *                   TrRecCnt: 0000000000    Length: FULL
   IpAddr:  *                   SubNet: 255.255.255.255
   PortNum: *

The following example shows a data trace for multiple entries:

Data Trace Setting:
 JobName: *           TrRecCnt: 00000000  Length: FULL
 IpAddr/PrefixLen:  10.1.1.1/24
 PortNum: *
  
 JobName: *           TrRecCnt: 00000000  Length: FULL
 IpAddr/PrefixLen:  5555:4444::2222/128
 PortNum: *

Usage

Users can be authorized to invoke the command by permitting their user IDs for CONTROL access to the RACF® profile name MVS™.VARY.TCPIP.DATTRACE.