Experimental Physics and
Industrial Control System

[email protected] (Marty Kraimer) · Mon, 23 Oct 1995 15:50:09 -0500

			EPICS status codes

The following discusses the use and also the limitations of
EPICS status codes. The following are the result of discussions between
Jim Kowalkowski, John Winans, and myself that we had as a result of the
proposal submitted by William Lupton.

	Review of Existing EPICS Status codes and error logging

The EPICS status codes are modeled closely on the vxWorks error status
values. Status values are encoded in 32 bit format with the lower
16 bits representing a error status associated with a system
and the upper 16 bits representing a subsystem. When the word system is
mentioned think of library.

Many library routines return error status codes with 0 meaning success and
non zero being one of the status values defined in header files.
In a few cases non zero status values are returned when no actual error
occured. This is overloading the use of error codes and is generally avoided.

EPICS supplys the routines errMessage and errPrintf which accept a status
argument. These routines are called to generate error messages that
are displayed on the IOC console. In addition the messages can be sent to 
a system wide log file.

In general only the code that detects an error knows how to supply
a meaningful error message. However that code often does not know the
context in which the code is used. Thus the caller has to supply the context
and the callee has to supply the error message. Lets assume that 
code calls a library routine which returns an error status.
The caller calls errMessage with the status argument and an additional string.
errMessage can supply the character string associated with the status value.
Thus status is used to obtain the error message and the additional argument
to errMessage describes context.

		Discussion of error status

Now let us state some things for which error status should NOT be used.

1)A replacement or addition to an alarm system.
In EPICS alarms are usually raised for one of two reasons:
	a) a hardware error is detected.
	b) a record raises alarms based on limits, etc specified by application
	developers.
In case 1) well written device support will also call errMessage or errPrintf.
It is the alarm system that should notify operators NOT the error
handling system.

2)A way to communicate error status codes across many layers of software.
Let me take the extreme of a channel access client and low level code in an ioc.
Status info should, at the most, be used to tell a client that it made an
invalid request. (For example an illegal put request). Status should not
be used to communicate that the request was successful.  Consider the following
example.
A put to a record causes a large number of records to process.
In addition it starts a complicated algorithm involving sequence programs, etc.
I dont think it is possible and certainly not desirable to use status
to indicate that the algorithm completed successfully. 
Only very simple cases could be handled. Developers MUST use other
methods to determine that commands produce valid results.

We dont think error status values should have an embeded severity
level. For EPICS S_ definitions the convention originally used was that
even numbers meant informational messages and odd numbers errors.
After several sets of status values were defined it was noticed that all
values were odd. I think that the reason is as follows: When defining
the S_ values the circumstances under which the value is used are not known.
Without this information it is impossible to determine severity. Contrast this
with raising alarms.  Existing device support generates alarms when it detectes
hardware errors. In all cases the alarm severity is INVALID.
Nothing else makes sense. Only application developers know how to
set alarm severities of MINOR or MAJOR. They do this by setting fields
in records.

What IS often desired is a verbosity level. vxWorks programmers often create
a global variable such as xxxDEBUG, and then have statements such as

   if(xxxDEBUG >= 3) epicsPrintf(...

Where 3 would be one of the verbosity levels

		Possible new log system interface

The following assumes that errMdef could be "grandfathered" and ultimately
completely removed from EPICS. New code would use the following.

Perhaps the biggest objection to the existing EPICS status encoding scheme
is that definitions have to be placed in errMdef.h and that a utility has
to be run to create the mapping from S_ values to string messages.
The following suggestion is really due to Jim Kowalkowski and John Winans.

Let libraries define their own status values as small integers.
The problem is to be able to generate error messages
that contain both a meaningful message and the context. In order to solve
this problem any library could make a call to the following routine:

 logPrintf(int verbosityLevel, char *system, char *subsystem, char *format,...)

In addition the library must supply a routine

   char *xxxGetSystem(void);

Then in a normal error situation the following happens:

1) A library routine detects an error.
2) The library routine makes the call:
   logPrintf(0,"xxx",NULL,"This is a bad error because I found it");
3) The library routine returns a value indicating an error occured.
4) The caller executes the code:

   if(!xxxRoutine(...)) {
	logPrintf(0,"yyy",xxxGetSystem(),"This shows context");
   }

It is important to note that this method gives a way to correlate messages
from several layers while still only making each layer know about itself
and the layer it calls. (There is still a problem if two different
tasks call xxx which each result in an error and a task switch occurs between
the two calls).

Since the system values are strings there is only a small chance that
two different systems will use the same system name. 

It is assummed that logPrintf would add taskid and hostid to messages
sent to a system wide  error handler.
The above scheme would allow a system wide error handler that lets a
user select messages from particular hosts, particular subsystems,
and particulay verbosity levels.

Marty Kraimer, Jim Kowalkowski, John Winans

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System