/*
 *  (C) 2001 by Argonne National Laboratory
 *      See COPYRIGHT in top-level directory.
 */

/*
 *  @author  Anthony Chan
 */

   *********************************************************************
   *  Prefered reference for slog2sdk tools including Jumpshot-4 for   *
   *  publications:                                                    *
   *                                                                   *
   *     An Efficient Format for Nearly Constant-Time Access to        *
   *        Arbitrary Time Intervals in Large Trace Files.             *
   *     Anthony Chan, William Gropp, and Ewing Lusk.                  *
   *     Scientific Programming, Volume 16, Number 2-3,                *
   *     pages 155-165, 2008.                                          *
   *                                                                   *
   *     Bibtex entry:                                                 *
   *     @article{slog2,                                               *
   *     author    = {Anthony Chan and William Gropp and Ewing Lusk},  *
   *     title     = {An Efficient Format for Nearly Constant-Time     *
   *                  Access to Arbitrary Time Intervals in Large      *
   *                  Trace Files},                                    *
   *     journal   = {Scientific Programming},                         *
   *     volume    = {16},                                             *
   *     number    = {2-3},                                            *
   *     year      = {2008},                                           *
   *     issn      = {1058-9244},                                      *
   *     pages     = {155--165},                                       *
   *     publisher = {IOS Press},                                      *
   *     address   = {Amsterdam, The Netherlands, The Netherlands},    *
   *     }                                                             *
   *********************************************************************

This is an ASCII text file format to slog2 convertor.

The ASCII text file format is described as follows:
It basically contains 3 types of records, Category, Primitive or Composite,
and YCoordMap.

1) Category defines the name, color and shape of the drawable
   as well the sprintf style format string for the byteinfo array.
   For example, below is a line that defines a Category.

Category[ index=0 name=message topo=Arrow color=(255,255,255,255,true) width=3 <msg_tag=%d, msg_size=%d> ]
Category[ index=10 name=Project_A topo=State color=(160,32,240,127,true) width=1 <jobID=%d\n account=%s user=%s> ]
   
   where
   index="the category index", positive integer.
   name="the name of category", any ASCII string.
   topo="shape of drawables".  The supported topologies are
                               Arrow, Event, and State.
   color="(Red, Green, Blue, Transparency, isModifiableIdentifier)",
   width="width of drawables", usually 1.
   The last entry is bounded by angle brackets "<" and ">".  
   The % conversion specifier supported are listed as follows:
   %d 4-byte signed integer in Java (network) byte order.
   %h 2-byte signed integer in Java (network) byte order.
   %l 8-byte signed integer in Java (network) byte order.
   %x 4-byte unsigned byte hex in Java (network) byte order.
   %X 8-byte unsigned byte hex in Java (network) byte order.
   %e 4-byte float pointing number in Java (network) byte order.
   %E 8-byte float pointing number in Java (network) byte order.
   %s string with length specified by a 2-byte network byte ordered integer.
   Also, "\n" the newline character will be interpreted by Jumpshot to
   split the long lines into multiple ones in popup info dialog box.

2) YCoordMap defines the mapping between lineID in each drawable to
   the actual row in Jumpshot's screen.  YCoordMap is optional because
   the default mapping called Identity Map is alway present.  Identity
   Map is a one-to-one map where RowID = LineID.

3) Primitive and Composite are drawable types.  Composite drawable
   is a collection of Primitive drawables.  Each Primitive is marked
   by TimeBoundingBox between 2 timestamps, followed by Category index
   and then actual coordinates of the drawables.
   The last entry is the optional byteinfo array which is a passthrough
   array in network byte order that supplies the arguments for the
   sprintf style format string defined in Category.
   Composite drawables ain't meaningful unless methods are specified to
   define how Primitives should be displayed.  Currently only one predefined
   method, connect, is predefined in Jumpshot.
   e.g.

Primitive[ TimeBBox(0.000500,0.0010000) Category=10 (0.000500, 2) (0.0010000, 2) <12345;;Google_com;;tom> ]

   TimeBBox("started timestamp","ended timestamp")
   Category=<Category index defined in Category section> 
   (timestamp, lineID) is coordinate of a vertex of each drawable.
       Event has one vertex, State and Arrow both have 2 vertices.
   <....;;...> specifies the byteinfo array with delimiter ";;" that
       separates number of byteinfo array values.
       The number of byteinfo array values must match the number of
       % conversion specifier defined in the corresponding Category.
