LOG(OPCS)		Optical Printer Control System		LOG(OPCS)

    NAME
        log - logs manually entered commands to a file or device

    USAGE
        log [-r] <filename.log>
	log -f <filename> <format string>

    EXAMPLES
	log myfile        # Start logging commands to MYFILE.LOG
	log off           # Turn off logging.
	log -f foo.log Camera Feet=%1cF Camera Frames=%1cp%n
                          # Append a message to 'foo.log'

    DESCRIPTION
        The 'log <file>' and 'log off' usage of this command will log 
	all the commands you enter from the keyboard to a file. 
	Commands in RUN(OPCS) scripts will not be logged.

	The 'log -f <file> <message>' usage of this command will append
	a message to <file>, where <message> may contain formatting
	characters (see LOGFORMAT(OPCSDEFS)) that lets you embed
	counter values in the message.

    'LOG <FILENAME>' AND 'LOG OFF'
	When you quit the software, or enter LOG OFF, the file will 
	be closed, and can be saved or edited for later use.

	Optionally, the counters can also be logged to the file. See the
	LOGCOUNTERS(OPCSDEFS) man page for more on this.

	To enable logging, specify some filename as an argument. You may
	use LPT3:, COM1:, or other such IBM device names to log directly
	to line printers, etc. 

	-r can be specified before the filename to include commands
	in executing RUN(OPCS) scripts to also be logged to the file. 
	If -r isn't specified, only commands typed at the keyboard 
	will be logged. (-r in OPCS K1.13b+)

	To disable logging, type log off.

    'LOG -F <FILENAME> <MESSAGE>'
	With the -f flag, you can log a single message to a file
	with embedded counter values. For instance, if you want
	to append a message to a log file that includes the current
	camera counter:

	                                               Replaced with
	                                              Cam's position
	                                                 counter
	                                Replaced with cam   |
	                                feet/frms counter   |
	                                |                   |
	                               ----               ----
	    log -f foo.log Camera Feet=%1cF Camera Frames=%1cp%n
	           ------- -------------------------------------
	           |       |
	           File    Message text

        The above example would append the following text to 'foo.log',
	based on what the camera counter reads at the time:

	     Camera Feet=16(1'0) Camera Frames=16
	                 -------               --
	                    |                  |
	                 Cam's feet/frms      Cam's position
    NOTES
	If a file already exists, and you start logging to it, data will
	be APPENDED to the existing file. If you want to clean out the file 
	before logging to it:

	    ! del mylog.log  ! log myfile.log

	The LOGCOUNTERS(OPCSDEFS) command controls whether the log records
	the current counter positions or not. If you do not want this 
	information in your log file, you can specify the preference to have 
	it off in your OPCSDEFS.OPC file:

	    logcounters off

	..or as an OPCS command for scripts:

	    ! echo logcounters off > foo  ! ldefs foo

	Counter information lines are always preceded by a '#' comment
	delimiter, so that the log file can be executed directly as a run 
	script, should the user want to do so.

	It is advisable to use the '.LOG' extension on all files created
	by the log command so you can differentiate them from .OPC (motor 
	definition) and .POS (position files).

    CARRIAGE RETURNS IN 'log -f'
        You must include a '%n' at the end of your <message> for the
	message to have a CRLF at the end. Otherwise, the line will
	remain unterminated, letting you concatenate to a single line 
	using separate LOG(OPCS) commands, eg:

	    log -f foo.log Camera=%1cF,
	    log -f foo.log Projector=%1bF%n

	..results in appending the following to 'foo.log'

	    Camera=16(1'0),Projector=0(0'0)

	To have them appear on separate lines, make sure both commands
	have %n on the end:

	    log -f foo.log Camera=%1cF%n
	    log -f foo.log Projector=%1bF%n

	..which results in appending the following to 'foo.log':

	    Camera=16(1'0)
	    Projector=0(0'0)

    LINE PRINTERS
	You can use LOG(OPCS) to maintain a continuous hardcopy printout as 
	the user enters commands. EXAMPLE:

	    log lpt3		# log commands to the LPT3 line printer

	Keep in mind that some of the parallel ports may be being used to
	control the motors, and it is definatly 'not advised' to try to send
	a file to a port that is controlling motors.

    GOTCHYAS
        OPCS log files should not be edited by word processors that introduce
	non-ASCII characters. This is no fault of the OPCS software. Most
	word processors have a mode for editing ASCII files. Consult your
	word processor manual.

    BUGS
	If the operator uses ALLSTOP during command logging, it would be
	unwise to later execute the log file as a run script without making 
	the proper modifications to the commands that were interrupted. Here 
	is a sample log with a command that was interrupted:

	    #  1:1   0(0'0)         20(1'4)       CLOSED 0   
	    cam -120

	    # ### OPERATOR HIT ALLSTOP KEY
	    #  1:1   0(0'0)         18(1'2)       CLOSED 0   

	Note the camera counter now reads 18 instead of -100. Because the
	command was interrupted, it never got to finish shooting. This
	could cause confusion later if this log were executed as a RUN script,
	and commands that followed used absolute positioning (cam >134).
	The command cam -120 should then modified by hand:
	
	    cam >10    or   cam -10

	...to reflect the command as it was actually executed.

    SEE ALSO
        LOG(OPCS)		- log all commands entered by the user
        RUN(OPCS)		- run a log file
        LOGCOUNTERS(OPCSDEFS)	- enable/disable logging counters to logfiles
        LOGFORMAT(OPCSDEFS)	- formats how values are printed to logfile

    ORIGIN
	Gregory Ercolano, Los Feliz California 11/29/89

© Copyright 1997 Greg Ercolano. All rights reserved.