.help logging Mar86 language
.ih
NAME
.nf
logging -- Using the CL logging features
.fi
.ih 
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:

.ks
.nf
       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
.fi
.ke

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". 
.ih
PARAMETERS
.ls 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.
.le
.ls logfile = "home$logfile"
The name of the logfile.
.le
.ls logmode = "commands nobackground noerrors notrace"

\fILogmode\fR controls what goes into the logfile.  The following options
are currently available:
.ls [no]commands
Enables or disables logging of interactive commands.  (This is usually always
enabled.)
.le
.ls [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.
.le
.ls [no]errors
Enables or disables error logging within script and executable tasks.
If enabled, error messages printed on the terminal will also be logged.
.le
.ls [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). 
.le
.le
.ih
EXAMPLES
1. Turn all the logging features on except for background logging:

	cl> logmode = "commands nobackground errors trace"
.ih
BUGS
Background logging to the same logfile can cause problems.  The environment
variable \fIfilewait\fR 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.
.ih
SEE ALSO
cl, putlog
.endhelp
