                  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_incrEQendtime_resfnEQyes.c, 
ts_incrEQendtime_resfnEQno.c and ts_incrEQstarttime.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 pair-wise association support of the interval records is provided 
   through use of off-diagonal interval record which is like an an interval
   with different begin processID and end processID

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

3, 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 slogfile
   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.  The current implmemtation predefined record type
   for variable and fixed size interval records and arrow records.
   Check slog.h for the predetermined value, SLOG_RECTYPE_XXXXX.

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

.....


Platform tested :
---------------
AIX ( SP2 ), Linux( Redhat 5.2-6.2 ), IRIX64( O2K ), Solaris, Sun4.


COMPILER FLAGS :
--------------
There are several compiler flags predefined, check CFLAGS.txt.  Some are
for the debugging, diagnostic and self-consistency checking code.  
The flag ! WORDS_BIGENDIAN is used to byteswap all the binary
data written to slogfile and read from the slogfile, the flag is useful
for intel iX86 box.  WORDS_BIGENDIAN is used by autoconf.  The NOCPUID 
flag turns off reading and writing the interval record's cpu_ID field to
the slogfile.  The NOINSTRUCTION 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().  
The flag CHECKPROFILE checks the consistency of the Display Profile and 
Record Definition Table.

All these options, XXXX, can be turned on by using -DXXXX as the compiler
flags.  But the most useful ones have been set in the configure.in.
So user does NOT need to worry about them in the normal circumstances.


BUILDING :
--------
Since SLOG-API has VPATH support, so the build directory can be chosen to
be different from the source directory.  In the following paragraphs, 
assume the source of SLOG-API is located at $(SLOG_API) which is different 
from the directory where SLOG-API is going to be built.  And the SLOG-API
library, include files, manpage & html documentation are going to be at 
/home/chan/slog_install

1, configure :
   To create all the necessary Makefiles, at the top level build directory, do 
       $(SLOG_API)/configure
   or
       $(SLOG_API)/configure --prefix=/home/chan/slog_install

   For adding optimization flags, do 
       $(SLOG_API)/configure --with-cflags="-O3"

   For choosing specify C compiler, do
       $(SLOG_API)/configure --with-cc="xlC"
   or
       setenv CC xlc; $(SLOG_API)/configure

   For further details, do
   $(SLOG_API)/configure --help

2, make : 
   At the top level build directory, do
         make

3, install :
   At the top level build directory, do 
         make install PREFIX=/home/chan/slog_install
   If $prefix has been set during configure, do 
         make install

4, uninstall :
   To remove files installed, at the top level build directory, do
         make uninstall



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

