Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Applies to: WG3.x

Editor's note: this chapter is new in the WG3 layer. It is from section 8 ("Audit Trail API") of the Developer's Addendum for Worldgroup 3.12 (wg312dev; the earlier 3.10 edition, devad3, is the same text apart from "3.10" for "3.12", BC5 for BC50, InstallShield V5.0 for V5.1 and spelling). The addendum has no figures. Prose is unrewritten; "Header check" notes record where the printed text disagrees with the WG3.2 headers. It extends the one-line audit() call of chapter 8 (Operator Services) into a file API.

...

Below is a code example that opens an audit trail file, adds a record, reads and displays the last ten records, and then closes the file.

Code Block
#include "gcomm.h"
Code Block
/* create online context required for audit trail */
INT usrnum;
INT errcod;
INT nterms=1;
INT channel[1]={0};
Code Block
INT
main(VOID)
{
     HAUDFILE haud;                /* audit trail file handle              */
     INT rc;                       /* return from audit trail functions    */
     ULONG nRecs;                  /* total number of records in file      */
     ULONG iStart;                 /* record at which to start printing    */
     ULONG iRec;                   /* record index for printing            */
     struct audEntry recBuf;       /* buffer for reading audit trail       */
     INT year;                     /* year part of time stamp              */
     INT month;                    /* month part of time stamp             */
     INT day;                      /* day part of time stamp               */
     INT hour;                     /* hour part of time stamp              */
     INT minute;                   /* minute part of time stamp            */
     INT second;                   /* second part of time stamp            */
     CHAR dateBuf[sizeof("September 31, 1999")]; /* buf for date string    */
     CHAR timeBuf[sizeof("11:59:59 PM")]; /* buffer for time string        */
Code Block
     /* open the audit trail file */
     rc=audfOpen(&haud,"myfile.adt",AUDMODE_READWRITE);
Code Block
     /* check for error opening */
     if (rc < AUDERR_OK) {
          fprintf(stderr,"Error opening file: %d\n",rc);
          return(1);
     }
Code Block
     /* check for damaged file */
     if (rc == AUDERR_DAMAGED) {
Code Block
          /* attempt to recover */
          rc=audfRecover(haud);
Code Block
          /* check for error in recovery */
          if (rc < AUDERR_OK) {
               audfClose(haud);
               fprintf(stderr,"Error recovering file: %d\n",rc);
               return(1);
          }
     }
Code Block
     /* prepare online context (for Console) */
     usrnum=AUDCHAN_CONSOLE;
     errcod=0;
Code Block
     /* add a record */
     rc=audfAddEntry(haud
                    ,"AUDIT TRAIL TEST"
                    ,"Testing the new Audit Trail API");
Code Block
     /* check for error */
     if (rc < AUDERR_OK) {
          audfClose(haud);
          fprintf(stderr,"Error writing to file: %d\n",rc);
          return(1);
     }
Code Block
     /* print the last ten entries */
     nRecs=audfNumRecs(haud);
     if (nRecs < 10) {
          iStart=0;
     }
     else {
          iStart=nRecs-10;
     }
     for (iRec=iStart ; iRec < nRecs ; ++iRec) {
Code Block
          /* read the current entry */
          rc=audfReadEntry(haud,iRec,&recBuf,sizeof(recBuf));
Code Block
          /* check for error */
          if (rc < AUDERR_OK) {
               audfClose(haud);
               fprintf(stderr,"Error reading from file: %d\n",rc);
               return(1);
          }
Code Block
          /* decode the time stamp */
          sDecodeDT(recBuf.stamp,&year,&month,&day,&hour,&minute,&second);
          prnDate(year,month,day,dateBuf,sizeof(dateBuf),PRND_MMMDYY,'\0');
          prnTime(hour,minute,second,timeBuf,sizeof(timeBuf),PRNT_HMS_PMC);
Code Block
          /* print the entry */
          fprintf(stdout,"Entry 
#%lu
#%lu\n",iRec);
          fprintf(stdout,"Time Stamp:   %s  %s\n",dateBuf,timeBuf);
          fprintf(stdout,"Channel:      %s\n",recBuf.channel);
          fprintf(stdout,"Description:  %s\n",recBuf.brief);
          fprintf(stdout,"Details:      %s\n",recBuf.detail);
          fprintf(stdout,"\n");
     }
Code Block
     /* close and exit */
     audfClose(haud);
     return(0);
}

Result Codes

Most Audit Trail API functions return a code that describes the result of the operation. In general, a negative code indicates failure while a zero or positive code indicates success. The following is a list of all

...

The following is a list of structures defined by the Audit Trail API.

Code Block
struct audEntry {                  /* audit trail record format            */
     CHAR stamp[AUDSTAMPSIZ];      /*   time stamp ("YYYYMMDD HHMMSS")     */
     CHAR brief[AUDBRIEFSIZ];      /*   brief description                  */
     CHAR channel[AUDCHANSIZ];     /*   channel/console/event/cleanup      */
     CHAR detail[AUDDETSIZ];       /*   detailed description               */
};
Code Block
#define AUDSTAMPSIZ sizeof("YYYYMMDD HHMMSS")
#define AUDBRIEFSIZ (32+1)
#define AUDCHANSIZ  (16+1)
#define AUDDETSIZ   128

This is the standard structure for reading and writing audit trail records. The fields have the following uses:

...

detail: Details on the event. This field may contain information specific to the particular event (e.g., "SMTP MAIL RECEIVED", "From: user@company.com To: Local User"). If the information to be placed in this field exceeded the maximum length, the last character before the terminating nul character will be an asterisk ('*').

Code Block
struct audOldStyle {               /* old-style audit trail record format  */
     CHAR stamp[AUDOLDSTAMPSIZ];   /*   time stamp (not nul-terminated)    */
     CHAR brief[AUDOLDBRIEFSIZ];   /*   brief description (32 chars + sp)  */
     CHAR channel[AUDOLDCHANSIZ];  /*   chan/console/event (nul-terminated)*/
     CHAR unused[12];              /*   unused space (filled with nuls)    */
     CHAR detail[AUDOLDDETSIZ];    /*   long desc (63 chars + 2 nuls)      */
};
Code Block
#define AUDOLDSTAMPSIZ   14
#define AUDOLDBRIEFSIZ   33
#define AUDOLDCHANSIZ    8
#define AUDOLDDETSIZ     65

This is a formalized representation of the pre-Worldgroup 3.12 Audit Trail record format. It is defined so that the API can provide backward compatibility with add-ons that read from the Audit Trail. In general,

...

Applies to: WG3.x

Header check: the function is audfAddEntry() (AUDAPI.h:92); the prototype printed below already shows that name.

Code Block
INT                                /*   returns result code                */
audfAddEntry(                      /* add an entry to audit trail file     */
HAUDFILE haud,                     /*   audit trail file to use            */
const CHAR *brief,                 /*   brief description                  */
const CHAR *detail,                /*   detailed description/format string */
...);                              /*   arguments to be formatted          */

Adds a record to an audit trail file, with variable arguments. It requires an online context as discussed above.

...

Applies to: WG3.x

Header check: the function is audfAddLowLevel() (AUDAPI.h:174).

Code Block
INT                                /*   returns result code                */
audfAddLowLevel(                   /* low-level add entry                  */
HAUDFILE haud,                     /*   audit trail file to use            */
struct audEntry *src,              /*   formatted record to add            */
size_t srcSiz);                    /*   size of source buffer              */

Adds an already-formatted entry to an audit trail file.

...

Applies to: WG3.x

Header check: the function is audfChannelStr() (AUDAPI.h:140); audAddfChannelStr appears nowhere in WGDEV/INC.

Code Block
CHAR *                             /*   returns pointer to buffer          */
audfChannelStr(                    /* generate channel description string  */
CHAR *buf,                         /*   buffer (must be AUDCHANSIZ long)   */
size_t bufSiz);                    /*   size of buffer                     */
                                   /*   (implicit inputs: usrnum, nterms,  */
                                   /*    channel[], errcod)                */

Create a channel description string based on the current online context.

...

Applies to: WG3.x

Header check: C identifiers are case-sensitive: the function is audfClose() (AUDAPI.h:80).

Code Block
VOID
audfClose(                         /* close an audit trail file            */
HAUDFILE haud);                    /*   handle to close                    */

Closes an audit trail file. The handle is no longer valid once this function has been called.

...

The handle of the file to close. This handle must have been gotten from a successful call to audfOpen().

audfCvtEntryToOld()

Code Block
struct audOldStyle *               /*   returns pointer to buffer          */
audfCvtEntryToOld(                 /* convert an entry to old-style        */
const struct audEntry *src,        /*   new-style audit trail entry        */
struct audOldStyle *buf,           /*   buffer to receive converted entry  */
size_t bufSiz);                    /*   size of destination buffer         */

Converts a new (Worldgroup 3.12) audit trail entry to the old (Worldgroup 3.0 and earlier) format.

...

A pointer to the buf argument.

audfCvtRawToEntry ()

Code Block
struct audEntry *                  /*   returns pointer to buffer          */
audfCvtRawToEntry(                 /* convert raw file data to entry       */
const CHAR *src,                   /*   raw file data                      */
struct audEntry *buf,              /*   buffer to receive converted entry  */
size_t bufSiz);                    /*   size of destination buffer         */

Converts raw audit trail file data to an audit trail entry structure.

...

A pointer to the buf argument.

audfFindEntryDOS()

Code Block
INT                                /*   returns result code                */
audfFindEntryDOS(                  /* find an entry by DOS date and time   */
HAUDFILE haud,                     /*   audit trail file to use            */
USHORT dosDate,                    /*   DOS-style date to search for       */
USHORT dosTime,                    /*   DOS-style time to search for       */
ULONG *pRecNum,                    /*   buf for rec # (NULL if don't want) */
struct audEntry *buf,              /*   buf for entry (NULL if don't want) */
size_t bufSiz);                    /*   size of destination buffer         */

Finds a specific audit trail record given a time and date stamp in DOS packed format. If an exact match is not found, the next highest record will be returned. If the target time is greater than the last record in the file, the last record will be returned. If there is more than one record with the same time stamp, the first one will be returned.

...

AUDERR_OKThe operation completed successfully.
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe file is empty.

audfFindEntryStr()

Code Block
INT                                /*   returns result code                */
audfFindEntryStr(                  /* find an entry by string date & time  */
HAUDFILE haud,                     /*   audit trail file to use            */
const CHAR *strDate,               /*   YYYYMMDD date to search for        */
const CHAR *strTime,               /*   HHMMSS time to search for          */
ULONG *pRecNum,                    /*   buf for rec # (NULL if don't want) */
struct audEntry *buf,              /*   buf for entry (NULL if don't want) */
size_t bufSiz);                    /*   size of destination buffer         */

Finds a specific audit trail record given a time and date stamp in DOS packed format. If an exact match is not found, the next highest record will be returned. If the target time is greater than the last record in the file, the last record will be returned. If there is more than one record with the same time stamp, the first one will be returned.

...

AUDERR_OKThe operation completed successfully.
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe file is empty.

audfFormatEntry ()

Code Block
struct audEntry *                  /*   returns pointer to destination     */
audfFormatEntry(                   /* create properly-formatted entry      */
struct audEntry *buf,              /*   buffer to receive entry            */
size_t bufSiz,                     /*   size of destination buffer         */
const CHAR *brief,                 /*   brief description                  */
const CHAR *chanStr,               /*   channel description string         */
const CHAR *detail,                /*   detailed description/format string */
va_list argList);                  /*   argument list                      */

Creates a properly-formatted audit trail record given its component parts.

...

A pointer to the buf argument.

audfNumRecs ()

Code Block
ULONG
audfNumRecs(                       /* get number of records in file        */
HAUDFILE haud);                    /*   audit trail file to use            */

Gets the number of records in an audit trail file.

...

The number of records in the file.

audfOpen()

Code Block
INT                                /*   returns result code                */
audfOpen(                          /* open an audit trail file             */
HAUDFILE *phaud,                   /*   buffer to receive opened handle    */
const CHAR *fileName,              /*   name of file to open               */
AUDMODE mode);                     /*   mode in which to open              */

Opens an audit trail file. The file may be opened in one of the following modes:

...

AUDERR_OKThe operation completed successfully.
AUDERR_NEWThe specified file was not found, so a new file was created.
AUDERR_DAMAGEDThe file is damaged. You must recover the file before proceeding.
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error. This response will be returned if you try to open a non-existent file in read-only mode.
AUDERR_MEMORYThere was not enough memory to open the file.

audfReadEntry()

Code Block
INT                                /*   returns result code                */
audfReadEntry(                     /* read an entry by record number       */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
struct audEntry *buf,              /*   buffer to receive data             */
size_t bufSiz);                    /*   size of destination buffer         */

Reads a record from an audit trail file.

...

AUDERR_OKThe record was read successfully.
AUDERR_FIOAn I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe requested record was not found (the record number was out of range).

audfReadLowLevel()

Code Block
INT                                /*   returns result code                */
audfReadLowLevel(                  /* low-level read an entry utility      */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
CHAR *buf,                         /*   buffer (must be AUDRECLEN+1 long)  */
size_t bufSiz);                    /*   size of buffer                     */

Reads a raw data record from an audit trail file but does not convert it into the standard entry structure. The raw data can be converted into an entry structure using audfCvtRawToEntry().

...

AUDERR_OKThe record was read successfully.
AUDERR_FIOAn I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe requested record was not found (the record number was out of range).

audfReadOldStyle()

Code Block
INT                                /*   returns result code                */
audfReadOldStyle(                  /* read an old-style entry              */
HAUDFILE haud,                     /*   audit trail file to use            */
ULONG recNum,                      /*   record number to read              */
struct audOldStyle *buf,           /*   buffer to receive data             */
size_t bufSiz);                    /*   size of destination buffer         */

Reads a record from an audit trail file and converts to the old style (pre-Worldgroup 3.1).

...

AUDERR_OKThe record was read successfully.
AUDERR_FIOAn I/O error occurred while reading the record. Check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_NOTFOUNDThe requested record was not found (the record number was out of range).

audfRecover()

Code Block
INT                                /*   returns result code                */
audfRecover(                       /* recover a damaged audit trail file   */
HAUDFILE haud);                    /*   handle to file to recover          */

Recovers a damaged audit trail file.

...

AUDERR_OKThe operation completed successfully.
AUDERR_NEWThe specified file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGEDThe file is still damaged. (This code will not be returned under normal conditions.)
AUDERR_FIOAn I/O error occurred while recovering the file; check the global variable errno for the specific error.

audfVAddEntry()

Code Block
INT                                /*   returns result code                */
audfVAddEntry(                     /* add entry with variable argument list*/
HAUDFILE haud,                     /*   audit trail file to use            */
const CHAR *brief,                 /*   brief description                  */
const CHAR *detail,                /*   detailed description/format string */
va_list argList);                  /*   argument list                      */

Adds a record to an audit trail file; does not take variable arguments. It requires an online context as discussed above.

...

AUDERR_OKThe operation completed successfully.
AUDERR_NEWThe file was not found, so a new file was created. (This code will not be returned under normal conditions.)
AUDERR_DAMAGEDThe file is damaged; you must recover the file before continuing. (This code will not be returned under normal conditions.)
AUDERR_FIOAn I/O error occurred while performing an operation; check the global variable errno for the specific error.
AUDERR_NOTOPENThe file is not open, you must close and reopen it before you can use it.
AUDERR_MODEThe requested operation was not valid for the mode used when opening the file (e.g., attempting to write to a read-only file).

...

Previous: Major BBS v10: 25 Searchable Memory Blocks  |  Contents  |  Next: Major BBS v10: 27 Date and Time API