home *** CD-ROM | disk | FTP | other *** search
/ Network Support Encyclopedia 96-1 / novell-nsepro-1996-1-cd2.iso / download / netware / trace.exe / TRACE.TXT
Text File  |  1995-03-02  |  17KB  |  397 lines
  1.  
  2.               NOVELL TECHNICAL INFORMATION DOCUMENT
  3.  
  4. TITLE:              TRACE FILE FORMATS
  5. DOCUMENT ID:        TID022037
  6. DOCUMENT REVISION:  A
  7. DATE:               15FEB95
  8. ALERT STATUS:       Yellow
  9. INFORMATION TYPE:   Issue
  10. README FOR:         TRACE.EXE
  11.  
  12. NOVELL PRODUCT and VERSION:
  13. LANalyzer for NetWare 1.0
  14. LANalyzer for Windows 2.0
  15. LANalyzer for Windows 2.1
  16. NetWare LANalyzer Agent 1.0
  17. ManageWise 1.0
  18.  
  19. ABSTRACT:
  20.  
  21. The packets collected by LANalyzer may be stored in binary form in trace
  22. files.  This appendix describes the naming conventions used for these files
  23. and explains how to interpret their contents.
  24.  
  25. -----------------------------------------------------------------
  26. DISCLAIMER
  27. THE ORIGIN OF THIS INFORMATION MAY BE INTERNAL OR EXTERNAL TO NOVELL.  NOVELL
  28. MAKES EVERY EFFORT WITHIN ITS MEANS TO VERIFY THIS INFORMATION.  HOWEVER, THE
  29. INFORMATION PROVIDED IN THIS DOCUMENT IS FOR YOUR INFORMATION ONLY.  NOVELL
  30. MAKES NO EXPLICIT OR IMPLIED CLAIMS TO THE VALIDITY OF THIS INFORMATION.
  31. -----------------------------------------------------------------
  32.  
  33. TRACE FILE FORMATS
  34.  
  35. The packets collected by LANalyzer may be stored in binary form in trace
  36. files.  This appendix describes the naming conventions used for these files
  37. and explains how to interpret their contents.
  38.  
  39. Filename Conventions
  40. LANalyzer trace files are split into subfiles.  A trace file can contain up to
  41. 35 subfiles.  The filename convention for the trace subfiles is the same: you
  42. provide the main filename and the LANalyzer software provides the extension. 
  43. For trace files the extension is TRn.  n indicates the subfile within the
  44. file; n has a range of 1 to 9 and then A to Z, for a total of 35 subfiles.  
  45.  
  46. A trace subfile can contain as many as 32,000 Kbytes.  This means that if
  47. several large files are to be used, multiple drives may be required.  
  48.  
  49. Record Formats
  50. The trace files consist of a collection of records. The records are stored in
  51. binary form, with no end-of-record character.  
  52.  
  53. All records in trace files have the same general format.  The first two words
  54. of each record have a fixed definition.  The first word (16 bits) is the
  55. record type.  The second word is the length of the data portion of the record,
  56. in bytes (the length does not include the "record type" and the "record
  57. length" fields).  Following the length field is the data field.  The format of
  58. the data depends on the record type.  
  59.  
  60. All data are stored in Intel 8086 format.  Hence, on other processors it might
  61. be necessary to byte-swap the data and word-swap within the doubleword fields.
  62.  
  63. Data Formats
  64. Table E-1 describes the various data formats used in the trace files.  
  65.  
  66. Table E-1
  67. Trace File Data Formats
  68.  
  69. DATA FORMAT       EXPLANATION
  70. BYTE              8-bit ASCII or integer field
  71. WORD              16-bit unsigned integer in Intel 8086 format
  72. DWORD             32-bit unsigned integer in Intel 8086 format 
  73.                   (doubleword)
  74. NADR              Network address.  This type is 6 bytes long and
  75.                   is in the order specified by the IEEE 802.3 
  76.                   specification.
  77. DATE              4-byte field consisting of the following types:
  78.  
  79.                     Type     Field Name    Description
  80.                     BYTE     day           Date
  81.                     BYTE     mon           Month
  82.                     WORD     year          Year
  83.  
  84. TIME              6-byte field consisting of the following types:
  85.  
  86.                     Type     Field Name    Description
  87.                     BYTE     second        Second
  88.                     BYTE     minute        Minute
  89.                     BYTE     hour          Hour
  90.                     BYTE     day           Day
  91.                     WORD     (blank)       Reserved
  92.  
  93. TIMESTAMP         Each trace record is timestamped.
  94.                   The timestamp is a three-word integer
  95.                   in units of 0.5 microsecond that gives the
  96.                   amount of time elapsed since 00:00:00 of the 
  97.                   day during which the test was started.  When a
  98.                   LANalyzer test is started, the TIMESTAMP timer
  99.                   is set to the current time of day.  The time- 
  100.                   stamp always increases, even when the time
  101.                   crosses midnight. To display the timestamp, the
  102.                   hours field should be displayed in mod 24.
  103.  
  104.                   The following example shows the timestamp in a 
  105.                   file, the actual timestamp and the timestamp
  106.                   reported on the LANalyzer screen:
  107.                     Timestamp in File:  F2 36 8D 0D 16 00
  108.                     Actual Timestamp:   0016 0D8D 36F2
  109.                     Time of Day:        13:09:18.319.481
  110.  
  111.  
  112. Trace File Format
  113. Each trace subfile consists of 10 unique records followed by multiple trace
  114. packet data records in the following order:
  115.  
  116. Trace header record (regular or cyclic)
  117. Trace receive channel name record
  118. Trace transmit channel name record
  119. Trace filter name record
  120. Trace receive template name record
  121. Trace transmit template name record
  122. Trace display options record
  123. Trace summary record
  124. Trace subfile summary record
  125. Trace cyclic information record
  126. Trace index record
  127. Trace packet data records
  128.  
  129. Each of these records is described in the following subsections.
  130.  
  131. Trace Header Record
  132. The trace header record identifies the trace file and its type.  A value of
  133. 1001H in the type code field indicates a regular trace file and a value of
  134. 1007H indicates a cyclic trace file.  The data portion of this record contains
  135. the fields listed in Table E-2.
  136.  
  137. Table E-2
  138. Trace Header Record Fields
  139.  
  140. Field             Description
  141. Major version     One byte identifying the trace file's major
  142. number            version number
  143. Minor version     One byte identifying the trace file's minor
  144. number            version number
  145. File type name    An ASCII string identifying the type of file
  146.  
  147.  
  148. Trace Receive-Channel Name Record
  149. The trace receive-channel name record contains the user-defined names for the
  150. eight receive channels.  Each channel name is a null-terminated, eight-byte
  151. ASCII string.  The starting character of the nth channel name is located at
  152. offset ((n-1)*9) in the data portion of the trace channel name record.
  153.  
  154. The type code for this record is 1006H.
  155.  
  156. Trace Transmit-Channel Name Record
  157. The trace transmit-channel name record contains the user-defined names for the
  158. six transmit channels.  Each channel name is a null-terminated, eight-byte
  159. ASCII string.  The starting character of the nth channel name is located at
  160. offset ((n-1)*9) in the data portion of the trace transmit channel name
  161. record.
  162.  
  163. The type code for this record is 100BH.
  164.  
  165. Trace Filter Name Record
  166. The Trace Filter name record contains the user-defined names for the 16
  167. filters used in the Enhanced Filter mode.  This record is present only when
  168. the trace file contains packets collected by running an Enhanced Filter mode
  169. application.
  170.  
  171. The type code for this record is 1032H.
  172.  
  173. Trace Receive-Template Name Record
  174. The trace receive-template name record contains the user-defined names for the
  175. eight templates for the eight receive channels.  Each template name is a
  176. null-terminated, eight-byte ASCII string.  The starting character of the nth
  177. template name is located at offset ((n-1)*9) in the data portion of the trace
  178. receive template name record.
  179.  
  180. The type code for this record is 1035H.
  181.  
  182. Trace Transmit-Template Name Record
  183. The trace transmit-template name record contains the user-defined names for
  184. the six templates for the six transmit channels.  Each template name is a
  185. null-terminated, eight-byte ASCII string.  The starting character of the nth
  186. template name is located at offset ((n-1)*9) in the data portion of the trace
  187. transmit template name record.
  188.  
  189. The type code for this record is 1036H.
  190.  
  191. Trace Display Options Record
  192. This record contains the trace display options record.
  193.  
  194. The type code for this record is 100AH.
  195.  
  196. Trace Summary Record
  197. The trace summary record contains global information about the test that
  198. generated this trace.  The type code for this record is 1002H.  The data of
  199. the trace summary records contain the fields listed in Table E-3.
  200.  
  201. Trace Subfile Summary Record
  202. The trace subfile record contain information about this subfile only.  The
  203. type code for this record is 1003H.  The data portion of the trace subfile
  204. records contains the fields listed in Table E-4.
  205.  
  206. Trace Cyclic Information Record
  207. This record contains information about the cyclic trace files.
  208.  
  209. The type code for this record is 1009H.  The data portion of this record
  210. contains the fields described in Table E-5.  
  211.  
  212. Table E-3
  213. Trace Summary Record Fields
  214.  
  215. Type     Field Name      Description
  216. DATE     datcre          The date the trace file was created
  217. DATE     datclo          The date the trace file was closed
  218. TIME     timeopn         The time the trace file was created
  219. TIME     timeclo         The time the trace file was closed
  220. EADR     statadr         Network address for the LANalyzer 325
  221.                          board on which the test was run
  222. WORD     mxseqno         Number of subfiles in trace file
  223. WORD     slcoff          Trace slice offset.  This is the value
  224.                          given in the Trace Slice Offset field
  225.                          when defining a test.
  226. WORD     mxslc           Maximum slice size of all subfiles in 
  227.                          the trace file.  This value can be used 
  228.                          for dynamically alloating memory for the
  229.                          packet slices.
  230. DWORD    totpktt         Total number of packet slices in the 
  231.                          trace file (all subfiles)
  232. DWORD    statrg          Number of the packet that fired the 
  233.                          start trigger, if any (refer to Table 
  234.                          6-2).  If there was none, this field is
  235.                          set to -1.
  236. DWORD    stptrg          Number of the packet that fired the stop 
  237.                          trigger, if any (refer to Table 6-2).
  238.                          If there was none, this field is set to
  239.                          -1.
  240. DWORD    mxpkta[36]      Ending packet number for all subfiles.  
  241.                          This is an array of ending packet
  242.                          numbers for all the trace subfiles.
  243.                          mxpkta[0]=0, mxpkta[1]=last packet 
  244.                          number in file_name.TR1, mxpkta[2]=last 
  245.                          packet number in file_name.TR2, etc.
  246. WORD     board type      A value of 226 indicates an LANalyzer
  247.                          325 board; a value of 227 indicates an 
  248.                          LANalyzer 325TR board.
  249. WORD     board version   Hardware version number
  250. BYTE     reserved [18]   Reserved
  251.  
  252.  
  253. Table E-4
  254. Trace Subfile Record Formats
  255.  
  256. Type     Field Name      Description
  257. WORD     seqno           Sequence number of this subfile in the
  258.                          trace file
  259. DWORD    totpktf         Total number of packets in this subfile
  260.  
  261.  
  262. Table E-5
  263. Trace Cyclic Information Record Fields
  264.  
  265. Type     Field Name      Description
  266. DWORD    cycpkts         Number of packets
  267. DWORD    staoffset       Start offset
  268. DWORD    stpoffset       Stop offset
  269. DWORD    startbuf        Start buffer offset
  270. DWORD    readstop        Read stop buffer offset
  271. DWORD    strtpkt         Start packet in second segment
  272. WORD     strtidx         Start index for second segment
  273.  
  274.  
  275. Trace Index Record
  276. The trace index record contains the file position for certain packet numbers
  277. in this subfile.  This information can be used to speed the retrieval of
  278. random traces.  This record is created when the subfile is created, but no
  279. information is placed into it until the first time the trace file is read by
  280. the LANalyzer  software. A field in the record indicates that the index
  281. information has been placed in the record.
  282.  
  283. The trace index record has a type code of 1004H.
  284.  
  285. The data within the trace index records contain the fields listed in Table
  286. E-6.
  287.  
  288. The space for the trace index record is pre-allocated.  The pre-allocated
  289. record contains space for the number of index entries specified by the field
  290. "idxsp."  When the index entries have been made, the field "idxct" is updated
  291. to reflect this.
  292.  
  293. Table E-6
  294. Trace Index Record Fields
  295.  
  296. Type     Field Name      Description
  297. WORD     idxsp           Total number of index entries
  298. WORD     idxct           Number of index spaces used
  299. BYTE     idxgranu        Index granularity-the number of packets
  300.                          between each index entry.  If the 
  301.                          granularity is d and the first packet in
  302.                          the subfile is packet number y, then the
  303.                          starting byte position of packet y is
  304.                          trcidx[0], the starting byte position of
  305.                          packet y + d is trcidx[1], and the 
  306.                          starting byte position for packet 
  307.                          y + (n*d) is trcidx[n].
  308. BYTE     idxvd           A value of 1 in the first bit of this
  309.                          field indicates the presence of indexes;
  310.                          a value of 0 indicates that no indexes 
  311.                          have been built yet.  If the first bit 
  312.                          is 1, then the remaining 7 bits show the
  313.                          index major granularity.  If the first 
  314.                          bit is 0, the remaining 7 bits are not
  315.                          meaningful.
  316. DWORD    trcidx[idxsp]   Array of indexes
  317.  
  318.  
  319. Trace Packet Data Record
  320. The trace packet data record contains a descriptor and a slice of the trace
  321. packet.
  322.  
  323. This record has a type code of 1005H.
  324.  
  325. This record consists of a descriptor data block followed by the packet slice
  326. data block.  The fields of the descriptor data block are listed in Table E-7. 
  327. The packet slice data block contains the packet slice data.
  328.  
  329. Table E-7
  330. Trace Packet Data Record Fields
  331.  
  332. Type      Field Name       Description
  333. WORD      rx_channels      Bit array of receive channels
  334.                            satisfied by this packet.  The least
  335.                            significant bit of the word (bit 0) is
  336.                            set to 1 if channel 1 was satisfied,  
  337.                            bit 1 is set to 1 if channel 2 was 
  338.                            satisfied, and so forth.
  339. WORD      rx_errors        Bit array of errors this packet 
  340.                            contains.  The bit array can contain 
  341.                            the following values:
  342.                              0001H-CRC/Alignment error
  343.                              0002H-Local Collision error
  344.                              0004H-Remote Collision error
  345.                              0008H-No error
  346.                              000FH-Number of collisions (mask of
  347.                                    the last four bits, which 
  348.                                    represent the values 0 to 15)
  349.                                    (transmitted packet)
  350.                              0010H-Frame activated the start 
  351.                                    trigger
  352.                              0020H-Frame activated the stop 
  353.                                    trigger
  354.                              0040H-Hardware problem when saving 
  355.                                    frame (received packet)
  356.                              0080H-At least one frame is missing
  357.                                    before this frame (received 
  358.                                    packet)
  359.                              0100H-Frame shorter than 64 bytes
  360.                              0200H-Frame longer than 1518 bytes
  361.                              1000H-Transmitted packet had a CRC 
  362.                                    error
  363.                              2000H-Deferred during transmission
  364.                              4000H-Excessive collisions 
  365.                                    (transmitted packet)
  366.                              8000H-Transmitted packet
  367. WORD      rx_frm_len       Length of the packet in bytes
  368. WORD      rx_frm_sln       Length of packet slice in bytes
  369. TIMESTAMP rx_time          Timestamp for this packet
  370. DWORD     pktno            Packet number
  371. WORD      prvlen           Previous record length
  372. WORD      offset           Offset of slice
  373. WORD      tx_errs          Transmit errors
  374. WORD      rx_filters       Filter mask
  375. BYTE      reserved[2]      Reserved
  376. WORD      hwcolls          Number of collisions in preamble(s)
  377. WORD      hwcollschans     Channels satisfied by preamble 
  378.                            collisions
  379. BYTE      data[tx_frm_sln] Packet data
  380.  
  381.  
  382. Self-Extracting File Name:  TRACE.EXE     Revision:  A
  383.  
  384. Files Included     Size     Date      Time
  385.  
  386. \
  387.    TRACE.TXT         (This File)
  388.  
  389.  
  390. -----------------------------------------------------------------
  391. Any trademarks referenced in this document are the property of their
  392. respective owners.  Consult your product manuals for complete trademark
  393. information.
  394. -----------------------------------------------------------------
  395.  
  396.  
  397.