NAME

CQCC::CQuest - Base class to manage communications with ClearQuest


CLASS DESCRIPTION

This class provides an abstract base class for all ClearQuest interfaces. It handles user logon information and storage, defining class parameters such as query definitions, and provides standard unit tests. A subclass such as CQCC::CQWeb must implement methods to logon, post commands, format queries and modify entity data.

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:
USER
An internal parameter initialized during logon which can be referenced in other variables such as Query filters, etc.

REPLICA_NAME
An internal parameter initialized during queries which can be use to reference the replica name of a MultiSite database.

ClearQuestInterface
Name of CQuest subclass to use for this session, used by IOClassFactory(). Set to 'CQCC::CQWeb' by default.

CQCC_DATABASE
Name of default database.

CQCC_ENTITY
Name of default entity.

CQCC_MULTISITE
Switch to enable checking for ClearQuest Multisite mastership restrictions before making associations. Set to 'FALSE' by default; change to 'TRUE' to enable.

CQCC_REPLICA_NAME
Default value for ClearQuest database replica name. Only used when CQCC_MULTISITE is enabled and there is no way to automatically obtain the same information through the API.

ClassTest(@args)
This class function uses sets up a local environment for testing; calls IOClassFactory() to get an instance of the desired subclass; and invokes the object's SelfTest method for testing.

Connect($return)
This method repeatedly tries to logon to the ClearQuest database until the user succeeds or gives up trying. If the $return argument is non-zero, then instead of exiting on failure the method will return a zero.

EditAssocs($VOList, $addAssocs, $delAssocs)
This method takes information about the ClearCase version object being associated to and two AssocLists, one listing the new associations to be made, and the other, the list of associations to be deleted.

The VOList is expected to be a string with a comma separated list of pathname, vobid, objectID, and old objectID.

If the system fails to successfully make the new additions, they are all deleted to prepare for the trigger failing gracefully.

GetLogonParms()
Method that retrieves the user name and password to logon to ClearQuest from a file stored in the user's home directory. If the file doesn't exist, this method interacts with the user to get a ClearQuest user name and password and stores the information into a file for use in later sessions. This method also sets the internal parameter ``USER'' for access by filters and other parameters.

new CQCC::CQuest()
This method presets the object's attributes including the default entity to be used and the name of the file used to store logon information. During operation, additional attributes will be set as needed including the user name and password and the query filters once they have been parsed.

PerformQuery(db, entity, schema, query, results, AllowCache, {K=V,...})>
This method will query the ClearQuest database for records matching the caller's query and return them as a list of strings in the format requested by the results argument.

Note that one time queries and results lists are supported. The query can be either a named query in the schema or an array reference to one or more query clauses which will be translated using the schema information. The results argument can be either a named results set or an array containing a results list and a results format.

The AllowCache argument is either TRUE or FALSE - if enabled it will cache query results and return saved results when the same query is run.

The optional Key=>Value pairs allow for future expansion and include the following:

RETURN => STRING (default) or ARRAY: Controls the format of the data being returned.

If STRING, each record is returned as a formatted string based on the results format string and the results are sorted.

If ARRAY it is returned as an array reference for use with columnar output and the first record contains the column labels.

This frontend method will check and convert input before calling the interface specific _PerformQuery method to perform the query itself.

CheckRestrictions(AssocList)
This method takes the associations in the AssocList and tests them against the restrictions query specified for their respective schema to make sure they are permissible as new associations.

Returns 0 if any items fail.

PrintChangeSets(dbid, entityName, @defectIds)
This abstract method should be overridden by the subclass to actually print out the cc_change_set and cc_vob_objects associated with one or more defect records. If the information can't be obtained this default method will report that.

SelfTest(@args)
This method runs basic unit testing on the object instance which currently includes connecting to the ClearQuest database, performing a query and displaying the results. It makes new associations, queries for current associations and deletes the new associations to confirm operation.

SetDatabase(databaseName)
This method changes the database we are attached to and attempts to login to the new database. If that fails it will try to relogin to the original database it was logged into. If that fails it will exit because there is no valid database.

ValidateDatabaseEntity()
This method validates the current settings for CQCC_DATABASE and CQCC_ENTITY to ensure that the values are self consistent and are on the list of valid database/entity combinations. It is usually called after the main trigger loads any prior settings from the cache file and has read in command line arguments. It will not handle changing database logins.