scScript Log Package

scScript provides a simple and convenient logging mechanism. A running script can open a single log file, create time-stamped (#Zulu or #Local time) entries as necessary, then close the log when done. There can only be a single log file at a given time and any sub-scripts (subordinate scripts being run by another script) that log entries will automatically get redirected to the same log file. While the sub-script will seem to open and close its own log file normally, these actions will just add entries to the superior script's file, leaving it intact and operational without the sub-script being any the wiser. (The superior script sets the operational log flags, sub-script flags are ignored.)

The default name for the log file is simply Log.txt and it will be placed in the same directory as the (.sc or .bsc) script itself. But the script may provide a new filename or path for the log file. It can also specify the #Unique flag (as opposed to the default #Common flag) to append an additional time/date string to the filename, rendering it different and distinct from all other log files that may exist in the same directory.

Since a script is typically run many times, the default behavior is to re-use (#Use flag) the existing log file, if found (this can only work with #Common naming), and simply add entries to it. But it can zap the old file and create a fresh new one each time if the #Fresh flag is set.

While the log is conceptually opened (Log.Open) just once, the default entry mode is to close the actual data file (and flush it) after each entry. But the #KeepOpen flag will direct scScript to keep the data file open for the duration of the executing script, running faster at the expense of fault-tolerance. The default behavior is also to create a new header in the log file each time it is conceptually opened (not for every entry). But the #NoHead flag can be used if a header is not required.

In the case of long-running scripts, the user may remove the log file (assuming it is not #KeepOpen) without interrupting the script. Should the script thus find its log missing mid-stream, the default behavior (#Remake) is to create a new data file and continue logging. But this can be altered with the #Require flag, forcing the script to terminate with an error (as a failsafe mechanism).

It is generally good form for any script that opens a log to create one or more initial entries announcing what the script is and what it does. This will make the stand-alone log files more readable, especially if loading multiple sub-scripts. For example:

        Log.Open();
        Log.Entry("Widget HQ Simulation: V2.0 with CoR");
                .... normal operations and logging...
        Log.Close();
      

Functions:
Open X = Log.Open(FStr, F);	Open the Log file and return 1 if successful, 0 if fail. If already opened by superior: succeed but record entry for new open. If already opened by this script: fail with error. FStr can be missing, "", path, filename, or full path+filename. Flags (F) are optional.
Close X = Log.Close();	Closes the open Log. Will return 1 if it was open, 0 otherwise. If the log was opened by a superior: do not close, just record an entry for attempt to close and return 1.
Entry X = Log.Entry(U, V, W...);	Strings args together (like Writeln) and timestamps to create an entry. If no args, makes a "No Entry" log entry. Will open the Log file if not already open. Returns byte count written.
EntryE X = Log.EntryE(U, V, W...);	Creates an extended entry. Follows previous entry without a timestamp. Otherwise works exactly like Log.Entry.

Defs:
Time	#Zulu (default) or #Local Use global (UTC) or local time for Log.Entry timestamp.
Naming	#Common (default) or #Unique Use given/default filename as is or append UTC to make filename #Unique.
Creation	#Use (default) or #Fresh Create file if missing, but use existing or replace with fresh one.
Entry	#OpenClose (default, safer) or #KeepOpen (faster) Re-open/close on each entry or keep open until script ends.
Header	#Header (default) or #NoHead Write a header with each explicit Log.Open or do not.
Mid-stream	#Remake (default) or #Require Create log file if missing mid-stream or just fail!