 --------------------------------------------------------------------
 | README (Summary documentation for the ALOG Tracing package)      |
 |                                                                  |
 | This file briefly describes the functionality  and the user      |
 | interface for the ALOG system.                                   |
 |                                                                  |
 | Written by:  Arun Nanda    (08/15/91)                            |
 |                                                                  |
 --------------------------------------------------------------------

This directory contains the source file for the tracing system.
The code presented here can be transported to any of the following 
computers:

                ALLIANT
                BALANCE
                BFLY1
                BFLY2
                BFLY2_TCMP
                DELTA
                IBM3090
                RS6000
                IPSC860_HOST
                IPSC860_NODE
                MULTIMAX
                NEXT
                SGI
                SUN
                SYMMETRY
                TITAN

To add more configurations, follow the examples of ifdefs for the Machine
dependent code sections.  The microsecond clock provided by the USC
package is used by ALOG to obtain the event timestamps.  Hence, all
timestamps appearing in the log files are expressed in microseconds.


ALOG TRACING INTERFACE
======================

The package comprises of the following macros/functions that are
provided via the include file "alog.h" and the library "libalog.a".


	ALOG_DEC:	

		no parameters 

		This macro is now redundant, but retained only for 
		backward compatibility.


	ALOG_SETUP(pid,flag):	

		pid  -  (integer) process id of callee
		flag -  (integer) either ALOG_WRAP or ALOG_TRUNCATE  

		This macros initializes the tracing area for a slave 
		process and MUST be called once before any event is 
		logged.  If the value of 'flag' is set to ALOG_WRAP, 
		then in the event of no more space for logging events 
		the system will only report the latest n events.  If 
		the 'flag' is set to ALOG_TRUNCATE the system will stop 
		logging events as soon as there is no more memory for 
		the events to be logged.


	ALOG_MASTER(pid,flag):

		pid  -  (integer) process id of the callee
		flag -  (integer) either 0 or 1  (see above)

		This macro has the same effect over its parameters as
		ALOG_SETUP with the difference that this macro should be 
		referenced by the master process only.


	ALOG_DEFINE(event,strdef,format):

		event  - (integer) id of event being defined
		strdef - (string) description of 'event'
		format - (string) control string in "printf" format to

		This macro expands to an event definition code.


	ALOG_LOG(pid,event,intdata,strdata):

		pid     - (integer) process id of callee
		event   - (integer) event id to be logged
		intdata - (integer) any integer data for this event
		strdata - (string) any string data (can be the null string)

		This macro provides the event logging service.


	ALOG_OUTPUT:
		no parameters  

		This macro dumps the events logged into a log file with
		the name "alogfile.pxx" where 'xx' is the logical PID
		of the callee process.  The log file is created in the
		current directory unless specified otherwise through
		the macro ALOG_SETDIR.


	ALOG_SETDIR(dir):

		dir - (string) directory where log file is created

		This macro sets the output directory for the log file.
		The default directory for the creation of the log file
		is the current directory of the process.  If used, then
		this macro MUST be invoked before ALOG_MASTER/ALOG_SETUP.


	ALOG_STATUS(status):

		status - (integer) either ALOG_ON or ALOG_OFF

		This macro controls the logging status of ALOG as follows.
		Setting 'status' to ALOG_ON enables logging until it is
		turned off.  Setting 'status' to ALOG_OFF disables logging 
		until it is turned on again.  Logging is enabled at the 
		outset by default.


	ALOG_ENABLE:

		no parameters

		This macro enables event logging; same as calling
		ALOG_STATUS(ALOG_ON).


	ALOG_DISABLE:

		no parameters

		This macro disables event logging; same as calling
		ALOG_STATUS(ALOG_OFF).

An application that uses the ALOG tracing facility must do the
following:

 1) Include the file "alog.h" at the beginning of the program.
 2) Link the application with the library file "libalog.a" and the
    machine-specific library mentioned below.


INCLUDE FILE
============

        alog.h


LIBRARY FILE
============

        libalog.a


ADDITIONAL MACHINE DEPENDENT LIBRARIES
======================================

The application will also have to be linked with the following machine
dependent libraries in order to enable the microsecond clock to function
properly:

                 MULTIMAX        -lpp
                 BALANCE         -lseq
                 SYMMETRY        -lseq

