The Solar-Stellar Spectrograph

[ Home | About | Tech Info & Data | Publications | References ]      [ Site by Jeffrey Hall | Research funded by NSF ]

ARTICLE

Root

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.

Version History

2008 July 07 - Documentation written.

 

Data Members

long logCodes

bool sysMsg

struct pointer[ ] history { tm:0D, code:0L, msg:' ', prev:Ptr_New() }

 

Method List

add_history

cleanup

clear_history

count_log_entries( )

define

dump_history

dump_stat

get_creation_time( )

get_history( )

init( )

is_valid( )

set_history

set_sys_msg

show_sys_msg

 

Method Descriptions

 

PRO add_history

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.

 

PRO cleanup

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.

 

PRO clear_history

Removes all items from the object's history list and reinitializes it with a message that the history has been cleared.

 

FUNCTION count_log_entries

Return integer tot

Returns the number of items in the event history list.

 

PRO define

Structure definition. Specifies the contents of the IDL structure instantiated by the Root class. Used by Obj_New; do not invoke directly.

 

PRO dump_history

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.

 

PRO dump_stat

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.

 

FUNCTION get_creation_time

Return double tm

Returns the Julian date the object was created.

 

FUNCTION get_history

Return pointer history

Returns a pointer to the object's event history list.

 

FUNCTION init

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.

 

FUNCTION is_valid

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.

 

PRO set_history

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.

 

PRO set_sys_msg

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.

 

PRO show_sys_msg

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.

 

Sample Usage

obj = Obj_New( 'Root', logCodes = !OIL_ALL, sysMsg = !TRUE )

Obj_Destroy( obj )

 


[Back to contents]

Supported by grants from the National Science Foundation.
[ Back to my home page | Email me: jch [at] lowell [dot] edu ]
The SSS is publicly funded. Unless explicitly noted otherwise, everything on this site is in the public domain.
If you use or quote our results or images, we appreciate an acknowledgment.
This site is best viewed with Mozilla Firefox.