NAME

CQCC::CQPerlAPI - Subclass of CQCC::CQuest used to manage communications with ClearQuest using the CQPerl API interface.


CLASS DESCRIPTION

This class implements the necessary methods to logon to ClearQuest, perform queries, and modify records over the CQPerl interface.

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_MASTER_DB_NAME
The name of the master database in the data repository for ClearQuest.

CQCC_DATABASE_SET
Name of the database set if other than the release name, i.e. 2001.04.02.

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.

Logon()
This method attempts to actively logon to the target ClearQuest database.

new CQCC::CQPerlAPI()
This method initializes the object's attributes including the database and repository names and opens a ClearQuest CQPerl session.

PrintChangeSets(dbName, entityName, @defectIds)
This method prints out the cc_change_set and cc_vob_objects associated with one or more defect records.

GetDatabaseList()
This method returns the list of databases in the repository that the user is connecting to.

GetQueryList(type)
This method returns the list of queries in the repository that the user is connecting to. The type argument can be ``PUBLIC'' for only Public queries, ``USER'' for only user queries or ``BOTH'' for both.

SetEntityFields(dbid, schema, entityName, fieldValues)
This method creates a new entity of type ``entityName'' (if dbID is undefined) or modifies an existing one if dbID is provided. It sets the entity's field values to the paired list provided (mapping the names if needed), validates and commits the entry and returns the dbid and key of the new entity.

(dbid,k) = obj->SetEntityFields(dbid,schema,entityName,fieldValues);

For handling fields that take list values use SetEntityListField method below. The two methods can be used on the same entity if needed though this will make two separate editing passes.

SetEntityListField(dbid, schema, entityName, fieldName, operation, \@valueList)
This method creates a new entity of type ``entityName'' (if dbID is undefined) or modifies an existing one if dbID is provided. It only modifies a single field with the name ``fieldName'' based on the operation (``Add'', ``Remove'', ``Clear'') and the valueList provided. If the operation is ``Add'', the value list is appended to the existing value list; if ``Remove'', the value list is deleted from the existing list; and if ``Clear'', all existing values are deleted. If necessary the ``fieldName'' is mapped using the schema. The method then validates the changes and commits the entry and returns the dbid and key of the new entity.

(dbid,k) = $obj->SetEntityListField(dbid, schema, entityName, fieldName, operation, \@valueList)

Use the SetEntity method to modify non-list fields.

_EditAssocs(database,entity,$VOList,add,del)
This internal method implements the EditAssocs functionality for a single database and entity. The add and del association lists are expected to be homogeneous since we can only interact with one database and one entity type at a time. The EditAssocs method is responsible for splitting up associations into homogeneous lists.

It must be called thru the CQuest method, EditAssocs which will break up the association lists into unique database/entity combinations so that this method only handles one combination at a time.

This method calls _LoadCSetCache to speed up getting dbids for cc_change_set and cc_vob_object entities. This may be overkill in some situations but should scale up well for larger numbers of associations per changeset.

_PerformQuery(db,entity,schema,query,results,resultsFormat, returnType, queryType)
This internal method is called by PerformQuery to actually query the ClearQuest database for records matching the query description.

returnType controls the format of the results - STRING returns formatted strings and ARRAY returns each record as a list of fields.

queryType identifies what kind of query is being used - LOCAL means the query was defined in the config.pl file and CQ means it is a named query defined in the ClearQuest database.

_LoadCSetCache(DB, Schema, entity, @ids)
This method caches up change set information for the defect records of immediate interest. It runs two queries whose output is used to (1) build up a hash map from defects to their object (cc_change_set pointer) fields and (2) a hash map from change_sets to their lists of cc_vob_object keys. These hash tables are then used by EditAssocs to more efficiently make changes.

_GetEntity(dbid, schema, entityName)
This internal method creates a new entity of type ``entityName'' (if dbID is undefined) or modifies an existing one if dbID is provided. It is only used by other methods that make field changes then validate and commit the information.

(dbid,entity) = obj->_GetEntity(dbid, schema, entityName);