coyote: ERRORLOGGER__DEFINE

NAME
ErrorLogger__Define
PURPOSE
The purpose of this program is to log program errors or text messages during
program execution as an aid to debugging such a program at a later date. The
ErrorLogger program is written as an object so that it will persist in the IDL
session until it is destroyed.
AUTHOR
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: david@idlcoyote.com
Coyote's Guide to IDL Programming: http://www.idlcoyote.com
CATEGORY
Utilities
CALLING SEQUENCE
errorLogger = Obj_New("ErrorLogger")
ARGUMENTS
filename:    The name of the error log file. If not provided, a default name
             will be created, based on the current system time. (Optional)
KEYWORDS
ALERT:       The default behavior of the error logger is simply to write text to a file.
             But if the ALERT keyword is set, the program will alert the user via a
             message dialog that an error has occurred when using the AddError method. 
             Default is 0. (Input)
ELETE_ON_DESTROY: If this keyword is set, the error log file will be deleted when the
             ErrorLogger object is destroyed, but only if the ErrorLogger object is not
             in an error state at that time (error status = 2). Default is 0. (Input)
NOCLUTTER:   Believe it or not, some people who use an ErrorLogger prefer that an error log
             file is never left behind. (They prefer that the program act like cgErrorMsg.)
             For those people, the NOCLUTTER keyword provides a way for them to automatically
             set the ALERT and DESTROY_ON_DELETE keywords to 1. It also prevents the error 
             logger from ever setting the error status to 2. Thus, when the ErrorLogger is
             destroyed, the file is always deleted. Default is 0. When set, overrides ALERT
             and DELETE_ON_DESTROY settings. (Input)
NOTRACEBACK: Set this keyword to suppress traceback information in the error log output
             and in any alerts issued by the program. Default is 0. (Input)
TIMESTAMP:   Set this keyword if you wish a time stamp to be appended to the provided
             filename. Otherwise, the filename is used as defined. Default filenames
             always have a timestamp appended to the file name. (Input)
METHODS
AddError:   Adds an error text string or array to the error log file. By default,
            it will add the HELP, LAST_MESSAGE=1, /TRACEBACE traceback 
            information to the file. (Procedure)
AddText:    Adds a text string or array to the error log file. (Procedure)
ClearLog:   Erases all the text currently in the error log file. (Procedure)
CloseFile:  Closes the currently open error log file. (Procedure)
Flush:      Forces a write of any current information to the disk (Procedure)
GetProperty: Gets properties of the object. (Procedure)
LastMessage: Returns the last message text written into the error log file. (Function)
OpenFile:   Opens the error log file for writing. (Function)
PrintLastMessage: Writes the last message text written into the error log file to 
            standard output. (Procedure)
Status:     Returns the current status of the error logger. (0 - waiting for input, 
            1 - normal operation, 2 - error operation.) (Function)
SetProperty: Sets properties of the object. (Procedure)
SetStatus:  Sets the current status of the error logger. Normally not used by the
            user, but used internally. (Procedure)
MODIFICATION HISTORY
Written by David W. Fanning, November 2009.
Modified and expanded the way errors are written into the log file and displayed.
   Also made it possible to automatically delete the log file when the object is
   destroyed, if the error logger is not in an error state at the time. Added
   DELETE_ON_DESTROY and NOTRACEBACK keywords to the INIT and SetProperty
   methods. 28 Jan 2010. DWF.
 Modified default filenames so that I am now guaranteed to get unique file names 
    by using cgTimestamp program from the Coyote Library. 8 Feb 2010. DWF.
 Added NOCLUTTER keyword. 15 February 2010. DWF.
 Added PRINT keyword to AddText method to allow users to log statements that should
    also be printed easily to a file. 17 February 2010. DWF.
 Small documentation changes to the program. 22 June 2010. DWF.
 Made a change so that the file is not opened until something needs to be written 
     to it. 22 June 2010. DWF.
 Added FLUSH method and keyword IMMEDIATE to the INIT method (defaults to 1) which
     will immediately flush the log information to disk when log information is
     added to the object. This will prevent missing information that is buffered
     when a program crashes. Matt Savoie suggestion. DWF, 10 Sept 2010.
 Now calling cgTimeStamp rather than TimeStamp to avoid problems with IDL code. 6 Feb 2013. DWF.