                  SLOG file Writing and Reading API
                  *********************************

The highest level API routines are documented in UNIX manpage and HTML 
format under directory ~slog_api/doc/.  Be sure to read those page for
each API to understand the limitation of each routine.  The example 
programs which show usage of the write API are ts_incr=endtime_resfn=Y.c, 
ts_incr=endtime_resfn=N.c and ts_incr=starttime.c.  Here "ts" stands 
for "test", and "incr" means "increasing time order" and "resfn" refers 
to "reserve space function" which will be explained later.  And the 
example programs for Read API which show the usage of the read API are 
slog_printframes.c, slog_printbbufs.c and slog_readtest.c in 
directory ~slog_api/src/.

test/slog_echofile     : Read in the binary SLOG Record Definition Table 
                         and Print the content of SLOG Record Definition 
                         Table to the stdout( for verification purpose )

test/slog_writetest    : Generate the SLOG binary file.  The 1st command line
                         argument specifies the number of fixed interval 
                         records in SLOG binary file.  Used all the top
                         level Write API.

test/slog_printbbufs   : Read the SLOG binary file and print the content of 
                         all the internal sectors of each frame of the SLOG
                         file to the stdout( for verification purpose ).  
                         It does NOT ued all the top level Read API.
                     
test/slog_printframes  : Functions almost the same as test/slog_printbbufs,
                         except it use all the top level Read API. 


CODE USAGE/ORGANIZATION :
-----------------------

The code employs object oriented design and is implmemted in C.
For those who would like to know the code structure, read src/README.OOP

There are basically 2 parts of the API, one for the writing of slogfile 
and the other one is for reading of slogfile.  The Write API is 
significantly more complicated than the Read API.  There are basically
API calls which create the Display Profile Table of the slogfile are
named as SLOG_PROF_XXXX().  And there are also API calls to generate
The Record Definition Table which defines the number of associations 
and number of related MPI arguments of the given interval record type.
The Table is generated by SLOG_RDEF_XXXX().   Then SLOG_TTAB_XXX()
are API calls to generate the Thread Table Information for the
mapping from thread to application display ID.  The run time API 
SLOG_Irec_ToOutputStream() uses the infomation in record definition 
to create a runtime database and to check the number of the association
and call arguments in the interval record.  And there are various
API call to set the various properties of the logfiles and are named
as SLOG_SetXXXXXXX().

The SLOG __write__ API are SLOG_OpenOutputStream(), 
SLOG_Irec_ToOutputStream(), and SLOG_CloseOutputStream().  And then
there is the optional SLOG_Irec_ReserveSpace which is meant to be
used in event based system.  And the SLOG __read__ API are 
SLOG_OpenInputStream(), SLOG_Irec_FromInputStream() and 
SLOG_CloseInputStream().  In the Read API, the user may need to 
manipulate runtime interval record data structure.  The rountine 
provided for the typical operation of Interval record are named 
like SLOG_Irec_xxx().  And SLOG_Irec is a acroym for (SLOG_intvlrec_t *irec).

The various primitive datatypes for run time interval record data structure,
SLOG_intvlrec_t, are renamed as SLOG_xxx_t which are defined in slog.h
with its corrponding printing formats called fmt_xxx.  This aims to provide
flexibility if one chooses to change the byte width of each basic datatype 
later for optimization purpose.

Be sure to check out the example/testing programs in src.  They are
ts_*.c and slog_print*.c


ALGORITHM :
---------
Check slog_api/src/Algorithm-SLOG.txt.


KNOWN LIMITATIONS :
-----------------
1, The association support of the interval records has NOT been added

2, The multiple directory hierarchy of the code has NOT been implemented.

3, The endtime of the each frame is determined by the endtime of the
   last interval record in the current Bbuf in the frame buffer.  So
   the very last interval record of the slogfile should have the latest
   endtime of all the interval records.  If it is NOT the case, the code 
   still run and without any warning.  If the input interval record to
   the SLOG API is arranged with accending end timestamp.  Then incoming
   pseudo-records of each frame will be empty.

4, The datatypes for SLOG_intvlrec_t's components have NOT been implmented 
   in the most memory efficient manner.   Namely bit is NOT used yet.
   But the 2 bebits are encoded into 1 byte when writing to slogile
   and it is decoded back to 2 bebits when reading back from the slogfile.

5, The variable vector arguments of the variable interval record has been 
   implmented in the API code.  The number of associations in the variable
   interval record is assumed to be defined in the Record Definition Table
   just like the fixed interval records.  So the code looks up the number 
   of associations of all records in the record definition table.  There 
   must be a mechanism to define which record definition entries are for
   variable records.  For testing purpose, the current implmemtation
   hardwires the range of irectype for variable records by defining
   the two end indexes of the range.  They are in src/slog_impl.c as
   SLOG_global.RecDefs_MinIdx4VarIrec = 0 and
   SLOG_global.RecDefs_MaxIdx4VarIrec = 0. 

6, The current implmentation does NOT make use of bebits in joining
   the disconnected intervals of a state.  This part of code May
   be done in Jumpshot.

.....


Platform tested :
---------------
AIX ( SP2 ), Linux( Redhat 5.2 ), IRIX64( O2K )


Built: One just simply type "make" at the top level directory.  If the 
       symbolic link of Make.conf."OS type" to Make.conf is NOT created 
       successfully, one can do it by hand.


COMPILER FLAGS :
--------------
There are 5 compiler flags used in Make.conf.  They are DEBUG which turns on
all the debugging, diagnostic and self-consistency checking code.  
The other one is BYTESWAP which is used to byteswap all the binary
data written to slogfile and read from the slogfile, the flag is useful
for intel iX86 box.   The NOCPUID flag turns off reading and writing 
the interval record's cpu_ID field to the slogfile.  The NOWHERE flag
turns off the reading and writing the record's where field to the slogfile.
The CHECKTIMEORDER flag turns on the code that checks the time order of
either starttime or endtime stamps supplied in SLOG_Irec_ReserveSpace()
and SLOG_Irec_ToOutputStream().

All these options, XXXX, can be turned on by using -DXXXX as the compiler
flags in Make.conf


If you have any question, please feel free to contact me at chan@mcs.anl.gov

A.Chan

