NOVELL TECHNICAL INFORMATION DOCUMENT TITLE: TRACE FILE FORMATS DOCUMENT ID: TID022037 DOCUMENT REVISION: A DATE: 15FEB95 ALERT STATUS: Yellow INFORMATION TYPE: Issue README FOR: TRACE.EXE NOVELL PRODUCT and VERSION: LANalyzer for NetWare 1.0 LANalyzer for Windows 2.0 LANalyzer for Windows 2.1 NetWare LANalyzer Agent 1.0 ManageWise 1.0 ABSTRACT: The packets collected by LANalyzer may be stored in binary form in trace files. This appendix describes the naming conventions used for these files and explains how to interpret their contents. ----------------------------------------------------------------- DISCLAIMER THE ORIGIN OF THIS INFORMATION MAY BE INTERNAL OR EXTERNAL TO NOVELL. NOVELL MAKES EVERY EFFORT WITHIN ITS MEANS TO VERIFY THIS INFORMATION. HOWEVER, THE INFORMATION PROVIDED IN THIS DOCUMENT IS FOR YOUR INFORMATION ONLY. NOVELL MAKES NO EXPLICIT OR IMPLIED CLAIMS TO THE VALIDITY OF THIS INFORMATION. ----------------------------------------------------------------- TRACE FILE FORMATS The packets collected by LANalyzer may be stored in binary form in trace files. This appendix describes the naming conventions used for these files and explains how to interpret their contents. Filename Conventions LANalyzer trace files are split into subfiles. A trace file can contain up to 35 subfiles. The filename convention for the trace subfiles is the same: you provide the main filename and the LANalyzer software provides the extension. For trace files the extension is TRn. n indicates the subfile within the file; n has a range of 1 to 9 and then A to Z, for a total of 35 subfiles. A trace subfile can contain as many as 32,000 Kbytes. This means that if several large files are to be used, multiple drives may be required. Record Formats The trace files consist of a collection of records. The records are stored in binary form, with no end-of-record character. All records in trace files have the same general format. The first two words of each record have a fixed definition. The first word (16 bits) is the record type. The second word is the length of the data portion of the record, in bytes (the length does not include the "record type" and the "record length" fields). Following the length field is the data field. The format of the data depends on the record type. All data are stored in Intel 8086 format. Hence, on other processors it might be necessary to byte-swap the data and word-swap within the doubleword fields. Data Formats Table E-1 describes the various data formats used in the trace files. Table E-1 Trace File Data Formats DATA FORMAT EXPLANATION BYTE 8-bit ASCII or integer field WORD 16-bit unsigned integer in Intel 8086 format DWORD 32-bit unsigned integer in Intel 8086 format (doubleword) NADR Network address. This type is 6 bytes long and is in the order specified by the IEEE 802.3 specification. DATE 4-byte field consisting of the following types: Type Field Name Description BYTE day Date BYTE mon Month WORD year Year TIME 6-byte field consisting of the following types: Type Field Name Description BYTE second Second BYTE minute Minute BYTE hour Hour BYTE day Day WORD (blank) Reserved TIMESTAMP Each trace record is timestamped. The timestamp is a three-word integer in units of 0.5 microsecond that gives the amount of time elapsed since 00:00:00 of the day during which the test was started. When a LANalyzer test is started, the TIMESTAMP timer is set to the current time of day. The time- stamp always increases, even when the time crosses midnight. To display the timestamp, the hours field should be displayed in mod 24. The following example shows the timestamp in a file, the actual timestamp and the timestamp reported on the LANalyzer screen: Timestamp in File: F2 36 8D 0D 16 00 Actual Timestamp: 0016 0D8D 36F2 Time of Day: 13:09:18.319.481 Trace File Format Each trace subfile consists of 10 unique records followed by multiple trace packet data records in the following order: Trace header record (regular or cyclic) Trace receive channel name record Trace transmit channel name record Trace filter name record Trace receive template name record Trace transmit template name record Trace display options record Trace summary record Trace subfile summary record Trace cyclic information record Trace index record Trace packet data records Each of these records is described in the following subsections. Trace Header Record The trace header record identifies the trace file and its type. A value of 1001H in the type code field indicates a regular trace file and a value of 1007H indicates a cyclic trace file. The data portion of this record contains the fields listed in Table E-2. Table E-2 Trace Header Record Fields Field Description Major version One byte identifying the trace file's major number version number Minor version One byte identifying the trace file's minor number version number File type name An ASCII string identifying the type of file Trace Receive-Channel Name Record The trace receive-channel name record contains the user-defined names for the eight receive channels. Each channel name is a null-terminated, eight-byte ASCII string. The starting character of the nth channel name is located at offset ((n-1)*9) in the data portion of the trace channel name record. The type code for this record is 1006H. Trace Transmit-Channel Name Record The trace transmit-channel name record contains the user-defined names for the six transmit channels. Each channel name is a null-terminated, eight-byte ASCII string. The starting character of the nth channel name is located at offset ((n-1)*9) in the data portion of the trace transmit channel name record. The type code for this record is 100BH. Trace Filter Name Record The Trace Filter name record contains the user-defined names for the 16 filters used in the Enhanced Filter mode. This record is present only when the trace file contains packets collected by running an Enhanced Filter mode application. The type code for this record is 1032H. Trace Receive-Template Name Record The trace receive-template name record contains the user-defined names for the eight templates for the eight receive channels. Each template name is a null-terminated, eight-byte ASCII string. The starting character of the nth template name is located at offset ((n-1)*9) in the data portion of the trace receive template name record. The type code for this record is 1035H. Trace Transmit-Template Name Record The trace transmit-template name record contains the user-defined names for the six templates for the six transmit channels. Each template name is a null-terminated, eight-byte ASCII string. The starting character of the nth template name is located at offset ((n-1)*9) in the data portion of the trace transmit template name record. The type code for this record is 1036H. Trace Display Options Record This record contains the trace display options record. The type code for this record is 100AH. Trace Summary Record The trace summary record contains global information about the test that generated this trace. The type code for this record is 1002H. The data of the trace summary records contain the fields listed in Table E-3. Trace Subfile Summary Record The trace subfile record contain information about this subfile only. The type code for this record is 1003H. The data portion of the trace subfile records contains the fields listed in Table E-4. Trace Cyclic Information Record This record contains information about the cyclic trace files. The type code for this record is 1009H. The data portion of this record contains the fields described in Table E-5. Table E-3 Trace Summary Record Fields Type Field Name Description DATE datcre The date the trace file was created DATE datclo The date the trace file was closed TIME timeopn The time the trace file was created TIME timeclo The time the trace file was closed EADR statadr Network address for the LANalyzer 325 board on which the test was run WORD mxseqno Number of subfiles in trace file WORD slcoff Trace slice offset. This is the value given in the Trace Slice Offset field when defining a test. WORD mxslc Maximum slice size of all subfiles in the trace file. This value can be used for dynamically alloating memory for the packet slices. DWORD totpktt Total number of packet slices in the trace file (all subfiles) DWORD statrg Number of the packet that fired the start trigger, if any (refer to Table 6-2). If there was none, this field is set to -1. DWORD stptrg Number of the packet that fired the stop trigger, if any (refer to Table 6-2). If there was none, this field is set to -1. DWORD mxpkta[36] Ending packet number for all subfiles. This is an array of ending packet numbers for all the trace subfiles. mxpkta[0]=0, mxpkta[1]=last packet number in file_name.TR1, mxpkta[2]=last packet number in file_name.TR2, etc. WORD board type A value of 226 indicates an LANalyzer 325 board; a value of 227 indicates an LANalyzer 325TR board. WORD board version Hardware version number BYTE reserved [18] Reserved Table E-4 Trace Subfile Record Formats Type Field Name Description WORD seqno Sequence number of this subfile in the trace file DWORD totpktf Total number of packets in this subfile Table E-5 Trace Cyclic Information Record Fields Type Field Name Description DWORD cycpkts Number of packets DWORD staoffset Start offset DWORD stpoffset Stop offset DWORD startbuf Start buffer offset DWORD readstop Read stop buffer offset DWORD strtpkt Start packet in second segment WORD strtidx Start index for second segment Trace Index Record The trace index record contains the file position for certain packet numbers in this subfile. This information can be used to speed the retrieval of random traces. This record is created when the subfile is created, but no information is placed into it until the first time the trace file is read by the LANalyzer software. A field in the record indicates that the index information has been placed in the record. The trace index record has a type code of 1004H. The data within the trace index records contain the fields listed in Table E-6. The space for the trace index record is pre-allocated. The pre-allocated record contains space for the number of index entries specified by the field "idxsp." When the index entries have been made, the field "idxct" is updated to reflect this. Table E-6 Trace Index Record Fields Type Field Name Description WORD idxsp Total number of index entries WORD idxct Number of index spaces used BYTE idxgranu Index granularity-the number of packets between each index entry. If the granularity is d and the first packet in the subfile is packet number y, then the starting byte position of packet y is trcidx[0], the starting byte position of packet y + d is trcidx[1], and the starting byte position for packet y + (n*d) is trcidx[n]. BYTE idxvd A value of 1 in the first bit of this field indicates the presence of indexes; a value of 0 indicates that no indexes have been built yet. If the first bit is 1, then the remaining 7 bits show the index major granularity. If the first bit is 0, the remaining 7 bits are not meaningful. DWORD trcidx[idxsp] Array of indexes Trace Packet Data Record The trace packet data record contains a descriptor and a slice of the trace packet. This record has a type code of 1005H. This record consists of a descriptor data block followed by the packet slice data block. The fields of the descriptor data block are listed in Table E-7. The packet slice data block contains the packet slice data. Table E-7 Trace Packet Data Record Fields Type Field Name Description WORD rx_channels Bit array of receive channels satisfied by this packet. The least significant bit of the word (bit 0) is set to 1 if channel 1 was satisfied, bit 1 is set to 1 if channel 2 was satisfied, and so forth. WORD rx_errors Bit array of errors this packet contains. The bit array can contain the following values: 0001H-CRC/Alignment error 0002H-Local Collision error 0004H-Remote Collision error 0008H-No error 000FH-Number of collisions (mask of the last four bits, which represent the values 0 to 15) (transmitted packet) 0010H-Frame activated the start trigger 0020H-Frame activated the stop trigger 0040H-Hardware problem when saving frame (received packet) 0080H-At least one frame is missing before this frame (received packet) 0100H-Frame shorter than 64 bytes 0200H-Frame longer than 1518 bytes 1000H-Transmitted packet had a CRC error 2000H-Deferred during transmission 4000H-Excessive collisions (transmitted packet) 8000H-Transmitted packet WORD rx_frm_len Length of the packet in bytes WORD rx_frm_sln Length of packet slice in bytes TIMESTAMP rx_time Timestamp for this packet DWORD pktno Packet number WORD prvlen Previous record length WORD offset Offset of slice WORD tx_errs Transmit errors WORD rx_filters Filter mask BYTE reserved[2] Reserved WORD hwcolls Number of collisions in preamble(s) WORD hwcollschans Channels satisfied by preamble collisions BYTE data[tx_frm_sln] Packet data Self-Extracting File Name: TRACE.EXE Revision: A Files Included Size Date Time \ TRACE.TXT (This File) ----------------------------------------------------------------- Any trademarks referenced in this document are the property of their respective owners. Consult your product manuals for complete trademark information. -----------------------------------------------------------------