NAME

logging -- Using the CL logging features

DESCRIPTION

The CL has some simple logging features to allow the recording of events of interactive sessions. From these saved event logs, one can trace a particular data analysis sequence, track errors in programs, and create new CL scripts. Other uses for the logfile exist as well.

There are currently five types of logging messages, with a parameter to control what is actually logged. These include:

       commands - commands and keystrokes of an interactive session
     background - messages about and from background jobs
         errors - logging of error messages
          trace - start/stop trace of script and executable tasks
           user - user messages, via the \fIputlog\fR builtin

All of these types of messages except the interactive commands will show up as comments (i.e., starting with a #) in the logfile. This facilitates using a previous logfile as input to the CL or as the basis for a script task.

The CL parameters discussed below are used to control the logging features. These parameters can be set on the command line, in the "login.cl" file, or with the command "eparam cl".

PARAMETERS

keeplog = no

The overall on/off switch for the CL logging. When set to `yes', the logfile will be opened and logging will commence. If the named logfile does not exist, it will be created, otherwise log messages will be appended to the existing file.

logfile = "home$logfile"

The name of the logfile.

logmode = "commands nobackground noerrors notrace"

Logmode controls what goes into the logfile. The following options are currently available:

[no]commands

Enables or disables logging of interactive commands. (This is usually always enabled.)

[no]background

Enables or disables background logging. This includes start/stop messages when background jobs are submitted and complete, as well as log messages from the background job itself.

[no]errors

Enables or disables error logging within script and executable tasks. If enabled, error messages printed on the terminal will also be logged.

[no]trace

Enables or disables tracing of script and executable tasks. If enabled, start and stop messages are logged, which include the package and task names, and the time. The start message also includes the filename of the task (.cl or .e).

EXAMPLES

1. Turn all the logging features on except for background logging:

cl> logmode = "commands nobackground errors trace"

BUGS

Background logging to the same logfile can cause problems. The environment variable filewait should be set to `no' to avoid file access conflicts. Even with this, reliability is not guaranteed and some messages will not get into the logfile.

SEE ALSO

cl, putlog