[ Home | About | Tech Info & Data | Publications | References ] [ Site by Jeffrey Hall | Research funded by NSF ]
The Root class is the OIL base class. It provides services for logging object events through a linked list of pointers.
Derive a class from Root to provide filtered event logging services for the objects of that class. The logCodes data member controls the filter, and you should set it to one of the system variable values defined in the startup file. Typically one would set this to !OIL_ALL to log every message, but if you only want to log messages (including any of your user-defined ones), just create your object with logCodes set to !OIL_MSG, and then pass !OIL_MSG to add_history whenever you add a message.
You can also have the object print messages begin inserted into its history list at runtime by setting the sysMsg data member to !TRUE; in this case, calls to show_sys_msg will print the events to stdio, as well as adding them to the event list. You can use this to see problems as they happen, rather than using the history list exclusively as a post-runtime diagnostic.
Note that messages are supposed to be rather terse; if you add your own, keep them to 45 characters or less.
2008 July 07 - Documentation written.
long logCodes
bool sysMsg
struct pointer[ ] history { tm:0D, code:0L, msg:' ', prev:Ptr_New() }
argument long logCode
argument long msgCode
argument char(45) msg
argument bool added
Calls show_sys_msg
Adds an item to the object's history list. If the logical AND of logCode and Self.logCodes is false, the routine exits without adding the item. Otherwise, the text in msg is logged with a timestamp and the msgCode. added will be set to !TRUE or !FALSE depending on whether the message was added or not.
Calls clear_history
Destructor. It first invokes clear_history to free up all the heap variables associated with events in the history list. It then frees the pointer to the history data member itself. Never call this procedure directly; it is invoked by IDL's Obj_Destroy function.
Removes all items from the object's history list and reinitializes it with a message that the history has been cleared.
Return integer tot
Returns the number of items in the event history list.
Structure definition. Specifies the contents of the IDL structure instantiated by the Root class. Used by Obj_New; do not invoke directly.
keyword long u
Dumps the object's history list. If the u keyword is not sent, the history dumps to stdio. Otherwise, u should give the LUN of an open file; the history will be dumped to the file in a formatted table, with times given in familiar text-based formatting rather than Julian date.
Calls count_log_entries
This is a standard OIL class method. It dumps the current state of the object's data members to the command output window. The dump will look best if the output font is fixed rather than proportional width.
Return double tm
Returns the Julian date the object was created.
Return pointer history
Returns a pointer to the object's event history list.
keyword long logCodes
keyword bool sysMsg
Return bool !TRUE
Constructor. If keywords are not set, they will be initialized to 0L and 0B, respectively. It initializes the linked list of pointers that comprises the history data member and places a message in the list containing the object's creation time. This timestamp is added regardless of the value of the logCodes data member. Never call this function directly; it is invoked by IDL's Obj_New function.
Calls add_history
Return long valid
Each OIL class has an is_valid function that performs class-specific tests on its data members. If all members are found to be valid, however validity is defined for that class, this funtion returns 1. Otherwise, a negative number is returned that contains a bitwise combination of all errors detected. In the case of Root, the error codes are: -1 (invalid event list pointer), -2 (logCodes < 0 or > 2^32), -4 (sysMsg not a valid boolean). An event is written to the log giving the validity state of the object.
argument long logCodes
Calls add_history
Sets the object's logCodes data member to the value given in the argument and adds an !OIL_MSG to the event list noting the change.
argument bool sysMsg
Calls add_history
Sets the object's sysMsg data member to the value given in the argument and adds an !OIL_MSG to the event list noting the change.
Prints the most recent message on added to the event history list while the sysMsg data member is !TRUE. The message will appear automatically whenever a method adds an event to the history list.
obj = Obj_New( 'Root', logCodes = !OIL_ALL, sysMsg = !TRUE )
Obj_Destroy( obj )