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