User data records

This topic describes the format of user trace records requested using the GTRACE macro.

If the application using GTRACE specifies more than 256 bytes of data, the user records may be split. If a user trace record is a split record, the AID will contain a value of X'F0', X'F1', or X'F2'. Split records contain the optional sequence and total length fields.

The records have the general format shown in Figure 1.

Figure 1. Unformatted User trace record Format

┌──────┬─────┬─────┬─────┬──────────┬─────┬──────────┬──────────┬────────────┬─────┬────────┐
│length│ res │ AID │ FID │time stamp│ EID │   SID    │ sequence │total length│ ASCB│job name│ … data …
└──┬───┴──┬──┴──┬──┴──┬──┴────┬─────┴──┬──┴────┬─────┴────┬─────┴─────┬──────┴──┬──┴───┬────┘
   2      2     1     1       8        2       2          2           4         4      8
 bytes  bytes  byte  byte   bytes    bytes   bytes      bytes       bytes     bytes  bytes
                                           (optional) (optional)  (optional)

The fields in the record contain the following information:

length

Total length of the record, in bytes.

res

Two bytes of zeros. Reserved for IBM® use.

AID

Application identifier, which is one of the following:

X'FF'-- Non-split record
X'F0'-- The first record of a series of split records
X'F1'-- A middle record in a series of split records
X'F3'-- The last record in a series of split records

FID

Format identifier of the routine that will format the trace record. See Format Identifiers (FIDs) for USR trace records for a list of FIDs and associated formatting routines.

time stamp

Time stamp showing the eight-byte Greenwich mean time (GMT) when the record was created.

EID

Event identifier, which identifies the event that produced the trace record. See Event Identifiers (EIDs) for USR trace records for a list of the EIDs and associated products for user trace records.

SID

System identifier, which identifies the system where the record was produced. This 2-byte field only exists in the following cases:

GTF trace data from multiple systems was merged using the IPCS COPYTRC command.
The record is a split one. If the trace data containing this split record was not merged from multiple systems, the SID field for the split record contains zeros.

You can use the SID from merged trace data as an array index to locate the source descriptor information for a particular system. For example, if the SID value for a record is 3, the source descriptor information for the system issuing the record is the third source descriptor in the control record.

To check to see whether trace data for a block of output comes from multiple systems, look in the control record for the options field and see if the GTWCFSID bit is set on. See Control records for the options field.

sequence

Sequence number, in hexadecimal, of this split record. This field only exists for split records.

total length

Total length of the split trace data. This field only exists for split records.

ASCB

The address of the address space control block (ASCB) for the address space where the GTRACE macro was issued.

jobname

The name of the job associated with the task where the GTRACE macro was issued.

data

Contains the trace data gathered for the requested event. The length of this field varies according to the event being traced. The number of bytes of data in the data field for user records is equal to the number of bytes specified on the GTRACE macro.