Infrasctucture Trc Function Reference
Trc
The Trace layer allows reporting from process functions at run-time.   The output of all processes are placed in a single file which is time stamped, the process' logical name is added then the desired text.   This is combined from all processes in a system so that the troubleshooter may see the sequence of events as it happened in all processes.   The amount of tracing is set by comparing a mask and trace level value from the original program statement with a dynamically set mask and level.  

A trcLog may be viewed using the "extr" tool.   If extr is called with no argument, the "trcLog" is assumed to be in the current directory.   If it is called with the letter 'e', only errors are extracted from the log ("trcLog") in the current directory is displayed.   You may also use '-E' to extract errors only.   It may also be called with a specific "path/file".   The command ":extr -?" displays a usage message listing all options.

Inf System Trace Levels: TRC_IO, TRC_INF, TRC_SYS, TRC_CFG, TRC_CTL, TRC_MSG, TRC_IN, TRC_OUT, TRC_SRC, TRC_SRV, TRC_SER

Inf User Application Trace Levels: TRC_APP1, TRC_APP2, TRC_APP3, TRC_APP4, TRC_APP5, TRC_APP6, TRC_APP7, TRC_APP8

Configuration file keywords for tracing:

TRACECTL	
	Used to enable tracing at startup.  Format: Mask,Level, where Mask may
	be IO,INF,SYS,CFG,APP1,APP2,APP3,UTIL,HTML,HTTP,MSG1 or MSG2, and Level
	is an integer from 0 to 255.  The mask selects the system layer.  The 
	Level selects the granularity of the tracing (higher level = more trace info).
	LOGDIR	Directory path to write the trace and error logs.
	ROTMONTH
	Number the rotated log files based on the day of the month (1-31)
	instead of the Unix day of the week (0-6).


trc trcDmp trcErr trcFatal trcInit trcIsMsk
trcIsOk trcMsg trcNow trcOff trcOn trcReOpn
trcSetLev trcSetMsk trcSrv

int trc( int lev, char* fmt, elipsis )
Capture trace information if the trace level "lev" is appropriate.   nbsp; If the process level and mask permit (below) the data is formatted and either written to a file or sent as a message to the trace daemon (trcd).   nbsp; Tracing is controlled by the "lev" argument and the process' TrcMsk (trace mask) and TrcLev (trace level).   nbsp; The "lev" argument consists of two parts, the mask (ie. TRC_APP1), which determines what layer in the system should be enabled to trace, and the level number (integer less than 255).   nbsp; If the process' mask bit is set and matches the trc() statement's mask and the trc() statement's level number is greater than or equal to the process's tracing is enabled for this statement.


int trcDmp( int level, char* loc, int len, char* fmt, ... elipsis )
If the level is above the process' tace level and correct mask, trace a hex dump of the location "loc" for "len" bytes.   Preceed the dump with the formatted ascii string.


int trcErr( char* fmt, ... elipsis )
Log a formatted error statement to both the trace and error logs.


int trcFatal( char* fmt, ... elipsis )
Log the formatted error and exit the process.


int trcInit( int argc, char* argv[] )
Initialize the trace layer prior to reading the config file.


int trcIsMsk( int msk )
Apply the supplied trace layer mask to the process' trace mask, returning the logical and of them.


int trcIsOk( int lev )
Using the supplied trace level "lev", test it against the process' current trace mask and level.   nbsp; Returns OK if tracing will occur, else FALSE.


int trcMsg( char* mp, char* peer, int trcTypeFlg )
Trace a message object pointed to by "mp".   The message's peer is "peer".   I think the "trcTypeFlg" indicates the direction of the message (in or out).


int trcNow( int mask )
Force tracing until turned off. The argument "mask" is compared against the MASK in the trc() call and if it matches, tracing is forced, ignoring the LEVEL in the trc() call.   The argument "mask" is logically anded with the MASK in the trc() call and if it is non-zero tracing is forced ignoring the LEVEL in the trc() call.   If "mask" is FALSE tracing is controlled by normal trace level and mask settings.   This allow an error routing to call general usage reports that use trc() calls and force the output.
trcNow( TRC_APP1 ); // FORCE TRACING OF APP1 trc( TRC_APP1+???,"a report"); CALLS.
printReport(); // PRINT A REPORT USING NORMAL APP1 TRACING.
trcNow( FALSE ); // TURN FORCED TRACING OFF.


int trcOff( )
Temporarily disable (turn off) tracing.


int trcOn( )
Temporarily enable (turn on) tracing back to the original mask and level.


int trcReOpn( )
Reopen the current trace logs.


int trcSetLev( char* lev )
Set the process' trace level to the value of "lev".


int trcSetMsk( char* lev )
Set the process' trace mask and level to the value of "lev" ("APP1+MSGO,20").


int trcSrv( int typ, char* mp, int len )
Used by trcd, it announces that this process is the trace daemon.