153 lines
5.6 KiB
HTML
153 lines
5.6 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
|
|
<META NAME="GENERATOR" CONTENT="Mozilla/4.03 [en] (X11; U; SunOS 5.5.1 sun4u) [Netscape]">
|
|
</HEAD>
|
|
<BODY>
|
|
|
|
<H1>
|
|
Error Logging System</H1>
|
|
The error logging system provides:
|
|
<UL>
|
|
<LI>
|
|
Error message routines that can be called by ioc code.</LI>
|
|
|
|
<LI>
|
|
Provision for multiple system wide error loggers..</LI>
|
|
|
|
<LI>
|
|
A task (errlog) that handles the messages generated by the client routines.
|
|
It displays messages on the target console and also gives them to any registered
|
|
system wide error loggers.</LI>
|
|
|
|
<LI>
|
|
iocLog: A system wide error logger that writes all error message to a file.</LI>
|
|
</UL>
|
|
|
|
<H2>
|
|
Overview</H2>
|
|
|
|
<UL>
|
|
<LI>
|
|
The error message routines can be called by any non-interrupt level code.</LI>
|
|
|
|
<LI>
|
|
Task errlog manages the messages. Messages are placed in a message queue,
|
|
which is read by the errlog task. The message queue uses a fixed block
|
|
of memory to hold all messages. When the message queue is full additional
|
|
messages are rejected but a count of missed messages is kept. The next
|
|
time the message queue empties an extra message about the missed messages
|
|
is generated.</LI>
|
|
|
|
<LI>
|
|
The maximum message size is 256 characters. If a message is
|
|
longer, the message is truncated and a message explaining that it was truncated
|
|
is appended. There is a chance that long messages corrupt memory. This
|
|
only happens if client code is defective. Long messages most likely result
|
|
from "%s" formats with a bad string argument.</LI>
|
|
|
|
<LI>
|
|
The error message routines are partially implemented on the host. The host
|
|
version just calls fprintf or vfprintf instead of using a separate task
|
|
and a message queue. Thus host messages are NOT sent to a system wide error
|
|
logger.</LI>
|
|
</UL>
|
|
|
|
<H2>
|
|
Client Routines</H2>
|
|
<I>Basic Routines</I>
|
|
<UL>
|
|
<PRE>typedef enum {
|
|
errlogInfo,errlogMinor,errlogMajor,errlogFatal
|
|
}errlogSevEnum;
|
|
|
|
int errlogPrintf(const char *pformat, ...);
|
|
int errlogVprintf(const char *pformat,va_list pvar);
|
|
|
|
int errlogSevPrintf(const errlogSevEnum severity,
|
|
const char *pformat, ...);
|
|
int errlogSevVprintf(const errlogSevEnum severity,
|
|
const char *pformat,va_list pvar);
|
|
|
|
int errlogMessage( const char *message);
|
|
|
|
char * errlogGetSevEnumString(const errlogSevEnum severity);
|
|
|
|
void errlogSetSevToLog(const errlogSevEnum severity );
|
|
errlogSevEnum errlogGetSevToLog(void);</PRE>
|
|
These are the basic client routines.
|
|
|
|
<P>errlogPrintf and errlogVprintf act just like printf and vprintf.
|
|
|
|
<P>errlogSevPrintf and errlogSevVprintf are similar except that they also
|
|
add the severity to the beginning of the message in the form "sevr=<value>"
|
|
where value is on of "info, minor, major, fatal". Also the message is suppressed
|
|
if severity is less than the current severity to suppress.
|
|
|
|
<P>errlogMessage just logs message.
|
|
|
|
<P>errlogGetSevEnumString gets the string value of severity.
|
|
|
|
<P>errlogSetSevToLog sets the severity to log. errlogGetSevToLog gets the
|
|
current severity to log.</UL>
|
|
<I>Status Routines</I>
|
|
<BR>
|
|
<UL>
|
|
<PRE>void errMessage(long status, char *message);</PRE>
|
|
|
|
<PRE>void errPrintf(long status, const char *pFileName,
|
|
int lineno, const char *pformat, ...);</PRE>
|
|
errMessage is just a macro that calls errPrintf. errPrintf is meant to
|
|
be called as follows:
|
|
<PRE> errPrintf(status,__FILE__, __LINE__,"<format>",...)</PRE>
|
|
The argument status is described in the Application Developer's guide.
|
|
The arguments __FILE__ and __LINE__ are standard C preprocessor variables.
|
|
<BR> </UL>
|
|
<I>Obsolete Routines</I>
|
|
<UL>
|
|
<PRE>int epicsPrintf(const char *pformat, ...);
|
|
int epicsVprintf(const char *pformat,va_list pvar);</PRE>
|
|
These are exactly like errlogPrintf and errlogVprintf. They are provided
|
|
because a lot of existing code calls them,. </UL>
|
|
<I>Add and Remove Log Listener</I>
|
|
<UL>
|
|
<PRE>typedef void(*errlogListener) (const char *message);
|
|
void errlogAddListener(errlogListener listener);
|
|
void errlogRemoveListener(errlogListener listener);</PRE>
|
|
These routines add/remove a callback that receives each error message.
|
|
<BR> </UL>
|
|
<I>target console routines</I>
|
|
<UL>
|
|
<PRE>void eltc(int yesno); /* error log to console (0 or 1) */
|
|
void errlogInit(int bufsize);</PRE>
|
|
</UL>
|
|
eltc determines if errlog task writes message to the console. If error
|
|
messages storms are occuring the command can be used to suppress the messages.
|
|
A argument of 0 suppresses the messages and any other value lets the message
|
|
go to the console.
|
|
|
|
<P>errlogInit can be used to initialize the error logging system with a
|
|
larger buffer. The default is 1280 bytes. An extra MAX_MESSAGE_SIZE (currently
|
|
256) bytes are allocated but never used. This is a small extra protection
|
|
against long error messages.
|
|
<H1>
|
|
iocLog</H1>
|
|
This consists of two modules: iocLogServer and iocLogClient. The client
|
|
code runs on each ioc and listens for the messages generated by the errlog
|
|
system. It also reports the messages from vxWorks logMsg.
|
|
<H3>
|
|
iocLogServer</H3>
|
|
This runs on a host. It receives messages for all enabled iocLogClients
|
|
in the local area network. The messages are written to a file. Epics base
|
|
provides a startup file "base/src/util/rc2.logServer", which is a shell
|
|
script to start the server. Consult this script for details.
|
|
<H3>
|
|
iocLogClient</H3>
|
|
This runs on each ioc. It is started by default when iocInit runs. The
|
|
global variable iocLogDisable can be used to enable/disable the messages
|
|
from being sent to the server. Setting this variable to (0,1) (enables,disables)
|
|
the messages generation. If iocLogDisable<TT> </TT>is set to 1 immediately
|
|
after iocCore is loaded then iocLogClient will not even initialize itself.
|
|
</BODY>
|
|
</HTML>
|