Custom modules - log reference

The log is the common mechanism for errors, warnings and debugging information to be reported to the user.

There are three functions, one for each of the above, all with the same arguments. The first argument is the logging level, a number between 1 and 9 indicating the severity of the condition - see below. The remaining arguments are interpreted as the arguments to a printf(3).

void plc_log_trcmsg(int min_debug_level, const char *format, ...);

Log debugging information ("trace message"). This indicates successful execution of a specific action.

void plc_log_wrnmsg(int min_debug_level, const char *format, ...);

Log a warning. Something has gone wrong, or unexpected result received, but an alternative/default/fallback action is available and will be tried (after this is logged). If all alternatives fail, only then log an error message.

void plc_log_errmsg(int min_debug_level, const char *format, ...);

Log an error. Something is seriously wrong, for which no (further) corrective action is known, and the only solution is to give up on that specific action.

Note that the PLC or the module that experienced the error does not necessarily have to stop executing (or crash), but may continue with other actions (e.g. modbus_tcp module cannot connect to a remote host 1 to read point A, but continues to connect to host 2 to get point B).

Logging levels

The default logging level is 1, which should be used by any part of the program to log messages that one would like to see by default. Typically, levels 2..5 will be used only by module specific code, while levels 6..9 will be used by the MatPLC libraries; however, it really depends on the severity of the event rather than its source.

Policy

The following table contains examples of the kinds of events that should be logged at each level.

	Debug	Warning	Error
1
2
3
4
5
6
7
8
9

FIXME fill in the table.

All messages logged by the library or by generic and specific modules (that is, anything included with MatPLC itself) should be listed in the Log messages appendix.

Real-time considerations

$Date: 2005/12/08 09:24:46 $