|
|
|
SystemLog
Manipulate a log of system events in a c-tree format file.
Short Name
SYSLOG()
Type
Low-Level function
Declaration
COUNT SystemLog(COUNT evclass, LONG event, pTEXT buffer, VRLEN buflen)
Description
Use SystemLog() to add your own entries to the log. evclass must be ctSYSLOGapi or higher. buflen should not exceed SYSLOGvar, 8100 bytes. The contents pointed to by buffer do NOT need to be actual text. No assumptions are made about the contents of buffer.
Each entry in the system log, SYSLOGDT.FCS, is a variable-length record using the SYSLOGrec structure defined in ctport.h. Typically, the SYSLOGrec structure overlays a buffer capable of holding an entire record. A buffer of SYSLOGmax bytes will hold any entry in the system log. A DODA with the record layout below is added to SYSLOGDT.FCS when it is created:
typedef struct ctslog {
LONG evclass; /* overall type of entry */
LONG event; /* the particular event code */
LONG date; /* date measured in days: r-tree compatible */
LONG time; /* seconds past midnight */
LONG rsvrd; /* for future use */
LONG seqnm; /* sequence number */
LONG error; /* uerr_cod at time of entry */
TEXT userid[SYSLOGidz]; /* logon user ID */
TEXT nodnam[SYSLOGidz]; /* logon node name */
UCOUNT vlen; /* length of variable region */
TEXT vfld[2]; /* beginning of variable region */
} SYSLOGrec, ctMEM * pSYSLOGrec;
The FairCom-defined evclass codes are:
Value (Long) |
Symbolic Constant |
Explanation |
|---|---|---|
0x001 |
ctSYSLOGuser |
User logon information |
0x002 |
ctSYSLOGddmp |
Dynamic dump information |
0x003 |
ctSYSLOGstat |
CTSTATUS entries |
0x004 |
ctSYSLOGtmpuser |
Temp user logon info |
0x005 |
ctSYSLOGdelfil |
File delete information |
0x006 |
ctSYSLOGanl |
Abort node list |
0x007 |
ctSYSLOGsnap |
Snapshot |
0x008 |
ctSYSLOGrstpnt |
Restore points |
0x010 |
ctSYSLOGsql |
SQL info |
0x0400 |
ctSYSLOGpurge |
Special purge request |
0x0401 |
ctSYSLOGapi |
Beginning of vendor defined event classes |
It is anticipated that additional evclass codes will be defined, with appropriate event codes, as additional types of FairCom Server operations are added to the system log facility.
The user logon info event codes are:
Value (Long) |
Symbolic Constant |
Explanation |
|---|---|---|
0x001 |
ctSYSLOGuserLOGON |
Successful logon |
0x002 |
ctSYSLOGuserLOGOFF |
Logoff |
0x003 |
ctSYSLOGuserLOGFAIL |
Failed logon |
0x004 |
ctSYSLOGuserADDUSER |
Add new user |
0x005 |
ctSYSLOGuserCHGUSER |
Modify user profile |
0x006 |
ctSYSLOGuserDELUSER |
Delete user |
0x007 |
ctSYSLOGuserSQLLOGON |
Successful SQL logon |
0x008 |
ctSYSLOGuserSQLLOGOFF |
SQL logoff |
0x009 |
ctSYSLOGuserSQLLOGFAIL |
Failed SQL logon |
On the ADDUSER, CHGUSER, and DELUSER entries, the variable buffer portion of the entry contains the user ID and a brief description of the type of activity. The actual details of the user profile information are not in the log.
The dynamic dump event codes are:
Value (Long) |
Symbolic Constant |
Explanation |
|---|---|---|
0x001 |
ctSYSLOGddmpBEGIN |
Begin dynamic dump |
0x002 |
ctSYSLOGddmpTRAN |
Transaction controlled file |
0x003 |
ctSYSLOGddmpCLEAN |
Clean non-transaction file |
0x004 |
ctSYSLOGddmpDIRTY |
Dirty non-transaction file |
0x005 |
ctSYSLOGddmpINFO |
Dump information |
0x006 |
ctSYSLOGddmpWARN |
Dump warning |
0x007 |
ctSYSLOGddmpERR |
Fatal dump error |
0x010 |
ctSYSLOGddmpEND |
End dynamic dump |
The TRAN, CLEAN, and DIRTY log entries contain the name of the file dumped in the variable buffer portion of the log record.
There are no event codes for CTSTATUS entries. They are all event zero.
The file delete event codes are:
Value (Long) |
Symbolic Constant |
Explanation |
|---|---|---|
0x001 |
ctSYSLOGdelfRSTR |
Restore of deleted file. (12-byte File ID, Original Name, Copy Name) |
0x002 |
ctSYSLOGdelfTRAN |
Transaction-dependent delete. (12-byte File ID, Original Name, Copy Name) |
0x003 |
ctSYSLOGdelfNOTRAN |
Non-transaction-dependent delete. (12-byte File ID, Original Name) |
The abort node list event codes are:
Value (Long) |
Symbolic Constant |
Explanation |
|---|---|---|
0x001 |
ctSYSLOGanlADDDEL |
Add / delete pair |
The snapshot event codes are:
Value (Long) |
Symbolic Constant |
Explanation |
|---|---|---|
0x001 |
ctSYSLOGsnapSYSTEM |
System snapshot |
0x002 |
ctSYSLOGsnapFILE |
File snapshot |
0x003 |
ctSYSLOGsnapUSER |
User snapshot |
The restore point info event codes are:
Value (Long) |
Symbolic Constant |
Explanation |
|---|---|---|
0x001 |
ctSYSLOGrstpntCREATE |
Create restore point |
0x002 |
ctSYSLOGrstpntRECOVERY |
Recovery results |
0x003 |
ctSYSLOGrstpntTRANBAK |
TRANBAK results |
0x004 |
ctSYSLOGrstpntNOKEEP |
Create restore point but no keep |
The SQL info event codes are:
Value (Long) |
Symbolic Constant |
Explanation |
|---|---|---|
0x001 |
ctSYSLOGsqlSTMT |
SQL statement |
The developer of the calling application assigns the user-defined event codes.
The maximum length for the variable-length portion of the log entry is given by the constant SYSLOGvar, which defaults to 8100. The fixed length user ID and node name fields are SYSLOGidz bytes, which defaults to 32.
Purging entries from the log uses a special form of the SystemLog() call: evclass is set as ctSYSLOGpurge, and event is set to zero to purge all classes, or to a particular evclass code to only purge entries from that class. The number of days of entries to keep is specified by placing the number of days to keep in an integer and passing the address of the integer in buffer and the length of the integer in buflen.
Return
SystemLog() returns an error code, NO_ERROR (0) on success.
Note: The actual writing of the log is performed by a dedicated FairCom Server thread which reads a queue fed by SystemLog() calls and internal server calls. The successful return of the SystemLog() call does not guarantee that the entry has been made in the log.
Value |
Symbolic Constant |
Explanation |
|---|---|---|
0 |
NO_ERROR |
No error. |
458 |
SWRT_ERR |
Attempt to write directly to system log files. |
See c-tree Error Codes for a complete listing of valid c-tree error values.
This example shows how to keep the last seven days of user logon information, as well as all other entries regardless of date.
Example
NINT days_to_keep = 7, retval;
retval = SystemLog(ctSYSLOGpurge,(LONG) ctSYSLOGuser,
(pTEXT) &days_to_keep,
(VRLEN) sizeof(NINT));
Limitations
Server configuration entries control which users, if any, can call SystemLog(). Review the FairCom Server Administrator’s Guide for complete details on server configuration and operation.
