NAME

CQCC::IOBase - Base class for user and system interaction methods


CLASS DESCRIPTION

This class provides user interactors (dialog boxes, menus, etc) and system interactors to manage file input and output. It acts both as a functioning class that provides text interactors and as a base class that more advanced interactor classes are built upon.

This class is not accessed directly but rather through a set of interface functions which hide the object implementation, and handle initializing the IOBase object automatically if it hasn't already been created. Clients call IODebugPrint(), IOPathname(), IOPrompt(), IOMessage(), IOFileRead(), and IOFileWrite() rather than the corresponding methods. This allows many different classes to use IOBase without having to directly manage it's creation.

SUPPORT POLICY: See TriggerCQCC.pm for the Rational Support Policy.


METHODS

ClassInit()
This class function is automatically invoked to define class parameters using CQCC::Parm objects. Current parameters include:
CQCC_DEBUG
Controls level of debugging output reported thru the IODebugPrint function. Currently three levels are supported: 0 - no output; 1 - basic output (high level operations); and 2 - detailed output.

CQCC_JOURNAL_MODE
Controls internal test journaling capability to handle user input. Values are 'OFF' (default), 'RECORD' (outputs user input as special tags) and 'PLAYBACK' (expects to find tags in journal file input).

CQCC_JOURNAL_FILE
File used for input when CQCC_JOURNAL_MODE is set to 'PLAYBACK'.

CQCC_LOG_OUTPUT
Controls recording all warning, error and fatal messages to a log file for convenience later during problem diagnosis. Values are 'OFF' which disables log file output; 'OVERWRITE' (default) which overwrites the log file each trigger session; and 'APPEND', which will add to the log file (only recommended during debugging).

IOBaseInterface
Name of IOBase subclass to be instanced by IOClassFactory().

CQCC_CTRL_C
Enables the control-C handler that tries to recognize when an end user has hit control C to terminate the trigger, allowing the trigger to report this as if the user had canceled the operation. Values are 'TRUE' (default) which enables the handler and 'FALSE' which disables it.

ClassTest(@args)
This class function uses sets up a local environment for testing; automatically creates an instance of the selected IOBase subclass; and invokes the object's SelfTest method for testing.

new CQCC::IOBase()
This method initializes the object attributes used in translating pathname prefixes, determining which operating system/platform is in use, initializing message catalogs and managing general status information.

IOClassFactory(classInterface)
This function supports the ClassFactory methods in all classes by trying to make an instance of the classInterface, confirm that a valid object is created and report errors if necessary.

IODebugPrint($type, $message)
This accessor function optionally prints out debugging information. Its output is controlled by the value of CQCC_DEBUG class parameter which enables zero or more types to be enabled for printing: if 0, no debug information is displayed; if 1, then Basic information is shown; if 2, then detailed information is shown.

The type parameter is a string in the list ``ALWAYS'', ``BASIC'', and ``DETAILED''. The intention is to allow multiple ``types'' that may later be split out into more debug levels if warranted.

The message parameter is currently a single string not a message catalog tag set.

IOExitHandler(status)
This accessor function handles fatal errors, aborts, and normal exits from the application. If a cleanup handler is defined that is called before the program exits.

Status codes include the following: 0 = successful operation 1 = abort/canceled operation 2 = fatal error

IOFileRead(filename, delete-flag)
This accessor function will open, read from and close the requested filename, returning its contents in a list of scalar values. It will optionally delete it when complete if delete-flag is 1.

(item1,item2,...) = $obj->FileRead(filename, delete-flag);

Each value being returned is a single line in the file. While not a broad purpose file reader, it is intended to work in tandem with FileWrite which writes one item to a line.

IOFileWrite(filename, item(s))
This accessor function will open, write its arguments to, and close the requested filename.Each value is written out as a single line in the file. While not a broad purpose file writer, it is intended to work in tandem with FileRead which reads one item to a line.

IOInterruptHandler()
When enabled by the CQCC_CTRL_C configuration parameter, this function catches Contrl-C interrupts and calls IOExitHandler to force an operation cancel.

IOListSelect(multiChoice, titleMsgTag, choiceMsgTagList...)
This accessor function presents a menu with a title described by ``titleMsgTag'' and one or more options to select from described by the remaining arguments. If multiChoice is 1 then multiple choices are allowed, otherwise only one choice is provided.

In the text implementation, the choices are numbered on the left margin and the user is expected to type one or more numbers separated by any combination of spaces or commas.

The selected items will be returned as a list to the caller, using the original choiceMsgTag items in their entirety for the caller to match to expectations.

The return value consists of a list containing the a flag to abort (1 for abort, 0 for continue) and the answer(s).

IOListTreeSelect(multiChoice,separator,titleMsgTag, choiceMsgTagList...)
Variant on IOListSelect which presents the list as a folding tree structure based on the choice list, assuming that each choice is a pathname separated by the separator character.

If the IOBase class does not provide support for the IOListTreeSelect method, it will default to using the standard IOListSelect method instead and present the information as a normal list.

For more details see the IOListSelect function documentation.

IOMessage(type, abort, [msgtag, args])
This accessor function will display its message to the user, after translating the msgtag and its arguments into the corresponding message catalog entry. Display is handled by calling the Prompt() method.

The type value may be ``INFO'', ``WARN'', ``ERROR'', or ``FATAL'' and is intended to qualify how the message is to be shown and whether or not the message affects the overall trigger status. If ``FATAL'' the status will be set to failed and the trigger will try to cleanly unwind and report failure back to the original caller, usually ClearCase.

The abort flag is also used to signal general failure for terminal conditions and will be combined with the type information shortly.

IOParseListString();
This utility function takes a string with embedded commas and white space and parses it into a list.

IOPathname($type, $filename)
This accessor function is used to convert platform independent filenames into platform specific pathname strings.

The type field may be ``TEMP'', ``PARM'', or ``ATRIA'' and references a platform-specific filename prefix in the temporary directory, users home (parameter) directory, or the Rational home directory respectively. Based on the operating system the prefixes are initialized by the Initialize() function and the remaining pathname is modified to adjust the slash (/ or \) conventions appropriately.

IOPrint(print-args)
This accessor function handles informational print operations, allowing prints to be redirected to a log as well as stdout.

IOPrompt(keys)
This accessor function will display its message to the user, after translating the msgtag and its arguments into the corresponding message catalog entry.

The return value consists of a list containing the a flag to abort (1 for abort, 0 for continue) and the answer(s).

($abort, $answer) = $obj->Prompt(keys);

IOSetCleanupHandler(object, method)
This function stores (or clears) the command string to be evaluated during exits processed by IOExitHandler(). The object is a pointer to the object whose method will be called. The method string should be either ``Method()'' or ``Method(args)''. On exit the command ``object->method'' will be invoked as a cleanup handler.

IOTraceBack()
This is a generic method to print out the calling stack back to N levels. It should be moved to a more generic base class for all objects when time permits.

new CQCC::IOBase()
This method creates the basic object instance and presets its attribute values, then it calls the Initialize() method for more extensive initialization.

SelfTest(@args)
This method runs basic unit testing on the object instance which currently includes debug print, platform pathname support, prompt and dialog box support, and file read/write operations.

_LogEntry(caller, msgtag)
Depending on the current mode, this method will either record a log entry noting which IO routine is being called or playback the log, confirming that the caller/msgtag entry is the next one expected.

_LogRead()
When playback is enabled this method reads the log file up until it gets to the next journaling tag <<anything>> and returns that line.

_ReadSTDIN(sequence, promptMsgTag, {user_answer})
Depending on the current mode, this method will either prompt the user for new input or get input from a playback log, then record the input to a log if in recording mode.

The sequence argument is used to differentiate between a single-call approach (``DURING'') when reading from STDIN and a two-call approach when a GUI widget is active: ``BEFORE'' checks for an available answer from the journal log that would avoid the need to display the widget, and ``AFTER'' is called after the user has provided an answer to the widget that should be recorded to the journal if we are recording. In the latter case, the optional user_answer is the widget's user input that needs to be written to the log.