Common real-time trace record attributes
This section describes the common attributes of trace records
that are obtained from the following functions:
- TCP/IP stack traces
- Real-time application-controlled TCP/IP trace NMI
- Real-time TCP/IP network monitoring NMI
Common real-time trace record header
The packet trace header is provided as a common trace
header in trace records for the following types of traces:
- Data trace
- Provided in trace records that are obtained from the following
functions:
- TCP/IP stack data trace
- Real-time TCP/IP network monitoring NMI
- Real-time application-controlled TCP/IP trace NMI
- OSAENTA trace
- Provided in trace records that are obtained from the following
functions:
- TCP/IP stack OSAENTA trace
- Real-time TCP/IP network monitoring NMI
- Packet trace
- Provided in trace records obtained from the following functions:
- TCP/IP stack packet trace
- Real-time TCP/IP network monitoring NMI
- Real-time application-controlled TCP/IP trace NMI
The packet trace header is defined in the following
programming interface files:
| Structure | File name | Language and type | Installed location |
|---|---|---|---|
| PTHDR_T | EZBYPTHA | Assembler macro | SEZANMAC |
| pthdr_t or pthdr_base_T | EZBYPTHH | C/C++ header | SEZANMAC |
The packet trace header provides the following
information:
PTH_Len Length of the packet trace header (PTH) structure. This is also the offset to
the IP header for packet trace.
PTH_Seqnum Sequence number of this packet trace record. This field applies only to
segmented records. See Segmented trace records for more
information about these kind of trace records.
PTH_Flag Flag indicators
PTH_Local 0x80 PTH_Src and PTH_Dest are local IP addresses on the same TCP/IP
stack.
PTH_CfTxt 0x40 The trace record represents AT-TLS confidential data, so none of
the data is included in the trace record. The PTH fields that
provide information about the traced data length are set as
follows:
- Data trace
The PTH_Tlen field is set to 0 and the PTH_Plen and the
PTH_DtPlen fields are set to the original data length.
- Packet trace
The PTH_Tlen field is set to the length of the packet headers
and the PTH_Plen field is set to the original packet length.
PTH_ClearTxt 0x20 IPSec cleartext data was recorded in the packet trace record,
or AT-TLS cleartext data was recorded in the data trace
record. This flag is set only in trace records created by the
real-time application-controlled TCP/IP trace NMI.
PTH_Seg_Offload 0x10 TCP Segmentation Offload
PTH_Pdu 0x08 Data from multiple PDUs. This flag is set only in outbound packet
trace records that represent TCP segments or fragmented packets.
PTH_Adj 0x04 Record size was adjusted by +1 (reflected in the
ctelene and ctelenp). The data length was odd and
a single pad byte was added.
PTH_Abbr 0x02 For records created by the TCP/IP stack packet trace, data trace,
or OSAENTA trace, this flag indicates that the ABBREV parameter
was used on the trace command. For records created by the real-time
application-controlled TCP/IP trace NMI packet trace or data trace,
this flag indicates that the payload option was specified on the
filter control block. The length of the data in the trace record
has been truncated by the payload value.
PTH_Out 0x01 IP packet was sent = 1 rcvd = 0
PTH_Devty The type of device represented by the interface being traced.
PTHLCSE 1 - Ethernet
PTHLCS8 2 - 802.3 Ethernet
PTHLCSE8 3 - Ether|802.3
PTHLCSTR 4 - Token Ring
PTHLCSFD 5 - FDDI
PTHLU62 6 - SNA LU6.2
PTHHCH 10 - HyperChannel
PTHCLWRS 21 - CLAW
PTHCTC 29 - CTC
PTHCDLC 30 - CDLC IP
PTHATM 32 - ATM
PTHVIPA 33 - VIRTUAL
PTHLOOPB 34 - LoopBack
PTHMpc 35 - MPC
PTHX25C 36 - X.25
PTHSNALN 37 - SNA LINK
PTHMPCIG 38 - MPC giga
PTHMPCIE 39 - MPC IPAQENET
PTHMPCOD 40 - MPC OSAFDDI
PTHMPCON 41 - MPC OSAFNET
PTHMPCIH 42 - MPC IPAQTR
PTHQIDIO 43 - iQdio
PTHIQDX 44 - IQDX
PTH6loopb 51 - IPv6 loopback
PTH6vipa 52 - IPv6 VIPA (VIRTUAL)
PTH6ipaqenet 53 - IPv6 MPC IPAQENET6
PTH6mpc 55 - IPv6 MPC
PTH6ipaqidio 56 - IPv6 iQdio6
PTH6IQDX 57 - IPv6 IQDX
PTHRNIC 58 - IPv4/IPV6 RNIC
PTHISM 59 - IPv4/IPV6 ISM
PTH_Tlen Portion of the payload that is actually traced. For records created by the
TCP/IP stack packet trace, data trace, or OSAENTA trace, if ABBREV was not
specified on the trace command then this will be the same as the value in the
PTH_Plen field. If ABBREV was specified, then this is the value specified for
the parameter.
For records created by the real-time application-controlled TCP/IP
trace NMI packet trace or data trace, if the payload option was not specified,
this will be the same as the value in the PTH_Plen field (or, for data trace,
the PTH_DtPlen field). If the payload option was specified then, for packet
trace, this is the length of the packet headers plus the truncated data length.
For data trace, this is the value specified for the payload option.
PTH_Infname For packet trace, the name of the interface the packet was traced on in EBCDIC
character format
PTH_Jobname For data trace, the jobname for the socket request
PTH_DtDomain For data trace, the socket domain (AF_INET or AF_INET6)
PTH_DtType For data trace, the socket type (Sock#_Stream, Sock#_Dgram, Sock#_Raw)
PTH_DtProto For data trace, the socket protocol number for a RAW socket
PTH_DtState For data trace, the Start/End of data flow
PTH_DtStartInb EQU 6 Data Flow starts for Inbound
PTH_DtStartOutb EQU 7 Data Flow starts for Outbound
PTH_DtTerm EQU 8 Data Flow ends
PTH_DtPLen For data trace, the original total data length. This field should be used
instead of the PTH_Plen field because the PTH_Plen field is not large enough
to support the larger data sizes for data trace.
PTH_Time Stored time of day clock when packet trace header was created by the trace
PTH_Src For packet and data trace, the hexadecimal source IP address of this packet
(IPv6 or IPv4)
PTH_Dst For packet and data trace, the hexadecimal destination IP address of this packet
(IPv6 or IPv4)
PTH_Sport For packet and data trace, the hexadecimal source IP port number
PTH_Dport For packet and data trace, the hexadecimal destination IP port
PTH_Trcnt Total count of records traced. This field is supported only in trace records
created by the TCP/IP stack and obtained by using the real-time TCP/IP network
monitoring NMI.
PTH_IQDX For packet trace, the packet was associated with an IQDX or IQDX6 interface.
PTH_IQDC For packet trace, the packet was associated with an IQDC or IQDC6 interface.
PTH_Tcb Task control block address of the sender of the outbound packet or data trace
data. On inbound, this will usually be task associated with the TCP/IP stack.
PTH_Asid Ascbasid of the sender of the outbound packet or data trace data. On inbound,
this will usually be the asid of the TCP/IP stack.
PTH_SeqNr OSAENTA trace sequence number
PTH_Vlan OSAENTA Vlan id field
PTH_VlanPri Vlan priority (0-7)
PTH_VlanId Vlan Id (0-4095)
PTH_NtaFlag OSAENTA Flags
PTH_OutB 1-Outbound, 0-Inbound
PTH_Lpar 1=Lpar_to_Lpar
PTH_DD Data Device is valid
PTH_GVlan VLAN frame
PTH_LS Large Send
PTH_QHdr Qdio header present
PTH_Exhdr 1=Extension header
PTH_Layer2 1=Layer2 0=Layer3
PTH_SmProto For SMC packet trace, the protocol field. This field indicates if the packet
trace contains Shared Memory Communications – RDMA (SMC-R) TCP data
(IPPROTO_TCP = 6) or SMC-R Logical Link Control data (PTH_PROTO_SMCLLC = 252).
PTH_SmVlanid For SMC packet trace, the Vlan id field. This field is optional.
PTH_Lost Total lost record count. This field is supported only in trace records
created by the TCP/IP stack and obtained by using the real-time TCP/IP network
monitoring NMI.
PTH_LinkLen For data trace, this is the length of any ancillary data specified on the
socket request. The length is included in the PTH_Len field of the packet trace
header in which the ancillary data is provided, and the ancillary data
immediately follows the PTH in the trace record. If more than one trace record
is needed to trace all the data, the ancillary data is only provided in the
first record. The maximum length that will be traced is 1024 minus the actual
length of the PTH. For OSAENTA trace, this is the length of the MAC header.
PTH_Plen Original payload length. For packet trace, if TCP segmentation is offloaded,
then this is the total data length of all segments being offloaded plus the
length of one set of headers. For data trace, if the payload length is greater
than 65535, this field will be set to 0. Use PTH_DtPLen instead to obtain the
original payload length.
PTH_InfIx For packet trace, the interface index of the interface for the packet
PTH_Cid For data trace, the communication Id
PTH_DevId For OSAENTA trace, the device Id
PTH_DropRsn For packet trace, the packet discard reason code. PTH_DropRsn can be compared
with the discard reason code that is provided by EZBYCODE in sys1.sezanmac.
A packet can be traced twice, once at the lower level IP layer, and again as
a discarded packet in an upper level protocol layer of TCPIP. This value is
0 if the packet was not discarded.
PTH_OffSegLen For packet and OSAENTA trace, the length of each of the first N-1 segments
being offloaded, not including headers, that is, the MSS (meaningful only when
the PTH_Seg_Offload flag is on).
PTH_NxtHopAddr For packet trace, the hexadecimal next hop IP address for outbound packets
(IPv6 or IPv4)
PTH_NxtHopLen For packet trace, the length of next hop address field
PTH_NxtHopKey For packet trace, the key of next hop address field
PTH_Ext3Len For packet and OSAENTA trace, the length of the OSA-Express input queue
extension header
PTH_Ext3Key For packet and OSAENTA trace, the OSA-Express input queue Extension header key
PTH_Ext3QID For packet and OSAENTA trace, the OSA Express QID - The identifier of the
input queue on which this packet was received. The QID value is 1 when this
packet was received on the primary input queue. The QID value is greater
than 1 when this packet was received on an ancillary input queue using QDIO
inbound workload queueing. For an ancillary input queue the queue type is
indicated in the PTH_Ext3QueueType field.
PTH_Ext3QueueType For packet and OSAENTA trace, the QDIO Inbound Workload Queueing Ancillary
Queue Type - The queue type when the QID is an ancillary input queue. Queue
types are represented by the following values:
PTHMIQBULKDATA 2 Bulk Data
PTHMIQSYSDIST 3 Sysplex Distributor
PTHMIQEE 4 Enterprise Extender
PTH_Ext4Len For SMC packet trace, the length of the SMC-R extension header
PTH_Ext4Key For SMC packet trace, the SMC-R extension header key
PTH_RMBProSeq For SMC packet trace, the remote memory buffer's (RMB) producer
sequence number. This value is incremented every time data
written into the RMB causes a wrap condition - data is written
to the end of the RMB and wraps back to the beginning.
PTH_RMBProCur For SMC packet trace, the remote memory buffer's (RMB) producer
cursor. This is the offset into the RMB where the next data
to be written into this RMB begins.
PTH_RMBConSeq For SMC packet trace, the peer's remote memory buffer's (RMB) consumer
sequence number. This value is incremented every time data
read from the RMB causes the read to wrap back to the beginning
of the RMB.
PTH_RMBConCur For SMC packet trace, the peer's remote memory buffer's (RMB) consumer
cursor. This is the offset into the RMB where the next data
to be read from this RMB begins.
PTH_RMBProFlg For SMC packet trace, the remote memory buffer's (RMB) producer
flags.
Producer flags:
rmbe_wrt_blocked 1 Writer is blocked, 0 Writer is not blocked
rmbe_urg_pending 1 Writer has urgent data to send, 0 No urgent data to send
rmbe_urg_present 1 RMB contains urgent data, 0 RMB contains no urgent data
PTH_RMBConnSt For SMC packet trace, the connection state flags.
Connection state flags:
rmbe_peer_done 1 Writer is done sending data, 0 Writer is not done sending data
rmbe_closed 1 Peer has closed connection, 0 Peer has not closed connection
rmbe_abn_close 1 Peer indicates abnormal close, 0 Peer does not indicate abnormal close
PTH_RemCnidx For SMC packet trace, the peer RMB connection index
PTH_LclCnidx For SMC packet trace, the local RMB connection index
PTH_RemRkey For SMC packet trace, the peer RMB key
PTH_LclRkey For SMC packet trace, the local RMB key
PTH_LclConnId For SMC packet trace, the local SMC-R link's connection id
PTH_RemConnId For SMC packet trace, the peer SMC-R link's connection id
PTH_RemGID For SMC packet trace, the peer "RoCE Express" global id
PTH_RemISMGID For SMC packet trace, the peer ISM global id
PTH_LclGID For SMC packet trace, the local "RoCE Express" global id
PTH_LclISMGID For SMC packet trace, the local ISM global id
PTH_RemQPnum For SMC packet trace, the peer queue pair number
PTH_LclQPnum For SMC packet trace, the local queue pair number
PTH_RMBEyecLn For SMC packet trace, the peer RMB element's eyecatcher length
Pth_MTU For SMC packet trace, the SMC link's MTU value
Pth_LclRMBsz For SMC packet trace, the local RMB element's buffer size
PTH_LclLMBsz For SMC packet trace, the local DMB element's buffer size
Pth_RemRMBsz For SMC packet trace, the peer RMB element's buffer size
PTH_RemLMBsz For SMC packet trace, the peer DMB element's buffer size
Pth_Payload For SMC packet trace, the size of the payload
Pth_AlertTkn For SMC packet trace, the peer alert token
Pth_MsgSeqNum For SMC packet trace, the sequence number of the messages
PTH_LclLMBTkn For SMC packet trace, the local DMB element's token
PTH_RemLMBTkn For SMC packet trace, the peer DMB element's tokenIPv4 address formats in the packet trace header
All of the IP address fields in the packet
trace header are large enough to accommodate a 16-byte IPv6 address.
IPv4 addresses that are provided in these fields are placed in the
last 4 bytes of the field and bytes 1 - 12 of the field contain one
of the following prefix values:
- X'00000000000000000000FFFE'
- Set in data trace records for AF_INET socket requests and in packet trace records for IPv4 packets.
- X'00000000000000000000FFFF'
- Set in data trace records for AF_INET6 socket requests for IPv4 addresses. This value is an IPv4-mapped IPv6 address.
Segmented trace records
The cte header field, ctelenp, provides the
length of each trace record. Because ctelenp is only a 16-bit field, the maximum size of each trace record is 65535 bytes. For packet or data trace, if the trace record length exceeds this
value, the traced data must be segmented into multiple trace
records. For packet trace, a maximum of 2 segmented trace records
can be created for a large packet. For data trace, several segmented
trace records can be created for a large socket request. Segmented
trace records have the following attributes:
- For segmented trace records that are obtained from the real-time TCP/IP network monitoring NMI, the trace records that are subsequent to the first segmented record do not necessarily follow the first trace record in the buffer. Other normal trace records can be interleaved with the segmented trace records.
- The PTH_Time field contains the same value in all the segmented records. Use this value to determine which segmented trace records belong to the same set of trace records.
- The PTH_SeqNum field in the first segmented record is set to 0. The sequence number is incremented by 1 for each subsequent segmented record to a maximum value of 255. Then the sequence number is reset to 1 for additional segmented records.
- For packet trace
- Only the first trace record in the set of segmented records contains the packet headers.
- The Pth_Plen field contains the total length of the original packet and this value is the same in all the segmented records.
- The Pth_Tlen field contains the length of the packet data that was traced, adjusted for the ABBREV parameter (for the TCP/IP stack packet trace), or the payload option for the real-time application-controlled TCP/IP trace NMI. This value is the same in all the segmented records.
- For data trace
- Only the first trace record in the set of segmented records contains any ancillary data.
- The Pth_DtPlen field contains the total length of the original socket request and this value is the same in all the segmented records.
- The Pth_Tlen field contains the length of the socket request data that was traced, adjusted for the ABBREV parameter (for the TCP/IP stack data trace) or the payload option for the real-time application-controlled TCP/IP trace NMI. This value is the same in all the segmented records.
- To determine the amount of traced data in each of the segmented
trace records, use the following formula:
traced data len = ctelenp - size(cte) - size(cteleplg) - PTH_Len – (1 byte if PTH_Adj flag set) - PTH_LinkLen