How_to_use_L4N

How to use L4N - the logging framework for Natural

History and design

We wanted to develop a logging framework that can be used in a development enviroment, as well as in a production environment.

Before the development of L4N, most of our debugging output looked like this:

IF *USER EQ 'MWESSJOH'
    WRITE '=' #RCVALUE
END-IF

Before transferring the modules to the production enviroment the above lines were deleted. When searching for a bug, we inserted the lines again.

L4N was designed to be able to use the same source code for development and production. It can be turned on and off dynamically.

The secound big thing was, that we did not want to add L4N to all our existing modules at once, so L4N has the ability to work with modules that do not yet use L4N.

Using L4N

L4N PDAs

To be able to use L4N in a module you have to include the PDAs L4NPARAM and L4NCONST.

...
LOCAL USING L4NPARAM
LOCAL USING L4NCONST
...

L4N Enter/Leave

There is no way for L4N to find out on its own which module is currently running and add this information to its log entries. So in every module you want to use L4N in, it has to be told which module is currently executing. Therefore, the first few lines of the module should look like this:

L4N-LINENR := *LINE
INCLUDE L4NENTER

After that, you could (opionally) configure L4N like this:

L4N-LOGTYPES := C-LOGTYPE-FILE + C-LOGTYPE-MEMORY
L4N-DEBUGLEVEL :=  C-LOGLEVEL-DEBUG
L4N-DEBUGUSER :=  'MWESSJOH'
CALLNAT 'L4NCHGPA' L4NPARAM

Using L4N-LOGTYPES, you can set the log appenders simply by "adding" them (work file and memory in this example).

These log appenders are available at the moment:

• C-LOGTYPE-FILE - work file (Unix)
• C-LOGTYPE-WRITE - WRITE on console
• C-LOGTYPE-INPUT - INPUT on console
• C-LOGTYPE-MEMORY - log into memory (100 log entries)
• C-LOGTYPE-DATABASE - log into an Oracle DB

L4N-DEBUGLEVEL defines the debug level. Only log entries with a log level greater than or equal to the debug level will be processed.

The available log levels are:

• C-LOGLEVEL-DEBUG
• C-LOGLEVEL-INFO
• C-LOGLEVEL-WARNING
• C-LOGLEVEL-ERROR
• C-LOGLEVEL-FATAL
• (plus some internal log levels you should not use for your log entries)

L4N-DEBUGUSER sets the debug user. If a valid username is set, L4N will only log, if the current user equals the debug user.

Before leaving the module you have to tell L4N that the currently executed module will no longer be active. This will update the log stack accordingly.

L4N-LINENR := *LINE
INCLUDE L4NLEAVE

L4N Log

To write a single log entry you may use these lines:

COMPRESS 'Writing a log entry with log level DEBUG' INTO L4N-LOGTEXT
L4N-LINENR := *LINE; L4N-LOGLEVEL := C-LOGLEVEL-DEBUG
INCLUDE L4NLOGIT

Simply put the log text into L4N-LOGTEXT. L4N-LOGLEVEL defines the log level for the new log entry. L4N-LINENR defines the line number for the new log entry, so you can quickly find out where in your module a given log entry was created.

Example Logfile

12:39:40.9 L4N-INFO 0 NUNIT.SMLOG (00080): L4N initialized.
12:39:40.9 L4N-INFO 1 NUNIT.SMLOG (01730): Changing debug level to: INFO. Changing log types to: File.
12:39:40.9 INFO     1 NUNIT.SMLOG (00180): Test-Eentry on INFO
12:39:40.9 ENTRLEAV 1 NUNIT.SMLOG (00220): Leave SMLOG.SMLOG
12:39:40.9 L4N-INFO 0 NUNIT.SMLOG (00220): Stack size 0 reached. Closing L4N.
12:39:40.9 L4N-INFO 0 NUNIT.SMLOG (00220): L4N deinitialized.

The pattern for the logfile is:

<Time> <log level> <log stack level> <library>.<module> (<line number>): <log text>

Example Program

The program L4NTEST is a sample program, which write some logs with differnt loglevels.

By editing the following lines you can change the logtypes and loglevels ans see what happend:

 L4N-LOGTYPES := C-LOGTYPE-WRITE + C-LOGTYPE-MEMORY
 * L4N-LOGTYPES := C-LOGTYPE-INPUT + C-LOGTYPE-MEMORY
 * L4N-LOGTYPES := C-LOGTYPE-DATABASE + C-LOGTYPE-MEMORY
 * L4N-LOGTYPES := C-LOGTYPE-FILE + C-LOGTYPE-MEMORY
 L4N-DEBUGLEVEL :=  C-LOGLEVEL-DEBUG
 CALLNAT 'L4NCHGPA' L4NPARAM

Add-Ons

Here is a list of useful add-on programs:

• L4NBOOL - for logging boolean variables
• L4NFLSWF - flushes the log file
• L4NSTACK - logs the Natural program stack
• L4N-TURN-OFF - create no logs at all (for batch programs)
• L4N-LOG-FATAL-ERRORS - logs where a fatal error happened
• L4NERROR - catches fatal errors and logs them
• L4NSTATE - change log settings manually
• L4NSHWE - dialog showing the memory log