CQCC::IOBase - Base class for user and system interaction methods
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.
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.