The Logging Agent

SMT
Version 2.81

The Logging Agent - SMTLOG

Creates log files, and writes data to the log files. Can handle multiple log files in parallel; each open log file is managed by one thread. Sends errors to the operator console agent.

To use, call smtlog init(). This does not create any threads. Create an unnamed thread using the thread_create() function. Send an OPEN or APPEND event to create the log file and PUT events to write to the log file. Finally, send a CLOSE event to close the log file and terminate the log file thread. SMTLOG does not reply - errors are sent to the console, not the requesting program. It supports these methods:

CYCLE - cycle log file if it already exists.
OPEN - create new, empty log file.
APPEND - open log file in append mode.
PUT - write line of data to log file.
PLAIN - do not timestamp logged data.
STAMP - timestamp logged data (default).
CLOSE - close log file and destroy log file thread.

Example of initialising SMTLOG:

/*  Static data                                                 */
static QID
    logq;                       /*  Logging agent event queue   */

    /*  In agent initialisation code                            */
    THREAD  *thread;            /*  Handle to various threads   */
    /*  Ensure that logging agent is running, else start it     */
    smtlog init ();
    if ((thread = thread create (SMT_LOGGING, "")) != NULL)
        logq = thread-> queue-> qid;   /*  Get logging queue id */
    else
        return (-1);

The CYCLE Method

If the specified log file already exists, renames it to a file whose name consists of the first letter of the log file name, followed by the date in 7 positions (YYYYDDD). If that file name already exists, generates a unique filename. Takes the event body to supply the log file name; if the event body is empty, uses the thread name instead. If the log file name is empty ("") or the 4-letter string "NULL", nothing is done.

The OPEN Method

Creates a new, empty log file. Takes the event body to supply the log file name; if the event body is empty, uses the thread name instead. If the log file name is "" or "NULL", no file is created, and SMTLOG discards all output.

The APPEND Method

Opens an existing log file for additional output. If the log file does not already exist, acts like OPEN. Takes the event body to supply the log file name; if the event body is empty, uses the thread name instead.

The PUT Method

Takes the event body as a string, prefixes the date and time, and writes it to the log file.

The PLAIN Method

Disables time-stamping of the logged data. Use this when you do not want the default SMTLOG time-stamping.

The STAMP Method

Enables time-stamping of the logged data.

The CLOSE Method

Closes the log file and destroys the thread used to manage it. You normally send this event when you end your program.

Example Of Use

The SMTECHO agent shows an example of using the Logging agent.

SMTLOG Implementation

The hypertext view of SMTLOG's dialog and source code may help to understand how SMTLOG works.

| << | < | > | >>