# coyote: ERRORLOGGER__DEFINE

- coyote/Utilities
- [Source code]

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.