# $EPIC: log_command.txt,v 1.4 2010/01/10 01:08:22 jnelson Exp $
======Synopsis:======
[[log]] //<refnum>// //<operation> [<arguments> ...]//

======Description:======
The [[log]] command is the interface to the client's generalized logfiles.
A logfile writes a copy to a file of everything that appears in your display.

^ Operation ^ What it does ^
| [[log activity|ACTIVITY]] | Reset the logfile's activity timer |
| [[log add|ADD]] | Add a target or refnum this logfile will log |
| [[log describe|DESCRIBE]] | Detailed information about the logfile |
| [[log filename|FILENAME]] //filename// | Change the filename the logfile uses |
| [[log kill|KILL]] | Close and kill (delete) the logfile |
| [[log level|LEVEL]] //[[levels]]// | Change the levels the logfile accepts|
| [[log list|LIST]]| List all currently registered logfiles (briefly) |
| [[log mangle|MANGLE]] //[[mangle types]]// | Change how the output will be mangled before written to the logfile|
| [[log name|NAME]] //logical name// | Change the logfile's name|
| [[log new|NEW]] | Create a new logfile which becomes the current logfile|
| [[log off|OFF]] | Stop logging.  A timestamp line is added to the log |
| [[log on|ON]] | Start logging. A timestamp line is added to the log|
| [[log refnum|REFNUM]] //logfile refnum or logfile name// | Change the logfile's refnum |
| [[log remove|REMOVE]] //target or window refnum or server refnum// | Remove a target or refnum from this logfile |
| [[log rewrite|REWRITE]] //expando string// | Change how the output will be rewritten before written to the logfile|
| [[log server|SERVER]] //server refnum// | Change which server the logfile thinks it is associated with.  The magic server refnum -2 means "every server"|
| [[log type|TYPE]] //server// or //window// or //target// | Changes the domain of the targets of the logfile.  This deletes all previously added targets, so you should set the TYPE first. |

======Syntax:======
The [[log]] command breaks down into a stream of operations of the form:
> [[LOG]] //<refnum>// //<operation>// //<operation-arguments>//
The <refnum> is the target of the <operation>.  The <refnum> is optional.
There is no default <refnum> for the first operation, so it is an error if
you don't specify a logfile first.

If any //<operation>// fails, the current logfile is unset; further operations
are performed, but since there is no logfile, most further operations will 
also fail.

The default operation is [[log list|LIST]].

======About domains and targets:======
Each logfile belongs to a "domain" type, either WINDOW, SERVER, or TARGET.
A WINDOW logfile logs all of the windows whose refnums you have added using
[[LOG ADD]].
A SERVER logfile logs all of the servers whose refnums you have added using
[[LOG ADD]].  The SERVER logfile type ignores the associated SERVER.  To log
a SERVER you have to ADD the server's refnum.
A TARGET logfile logs all of the targets (channels or nicknames) whose names
you have added using [[LOG ADD]].

Please note that a logfile does not log anything by default until you add
targets to it.  This is especially true with server refnums, where it is
not just enough to change the server association, you have to add it as a
target:
	LOG NEW TYPE server ADD 0
If you omitted the "ADD 0" operation, it wouldn't log anything.

======Logfiles are separate and overlappable:======
Each logfile is fully separate and independant of all other logfiles.
This means that any line of output may appear in multiple logfiles.
Specifically, a server logfile will log all channels and all nicknames
on that server.

======History:======
The LOG command first appeared in EPIC4-1.1.8