From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 pkg/language/doc/logging.hlp | 82 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 pkg/language/doc/logging.hlp

(limited to 'pkg/language/doc/logging.hlp')

diff --git a/pkg/language/doc/logging.hlp b/pkg/language/doc/logging.hlp
new file mode 100644
index 00000000..06a3bdaf
--- /dev/null
+++ b/pkg/language/doc/logging.hlp
@@ -0,0 +1,82 @@
+.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
-- 
cgit