NAME

CQCC::CQWeb - Subclass of CQCC::CQuest used to manage communications with ClearQuest using the CQWeb ASP-based interface.


CLASS DESCRIPTION

This class implements the necessary methods to logon to ClearQuest, perform queries, and modify records over the CQWeb interface. Command strings are built up and encoded by the CCintCmd() method to identify the user, password and database; the operation to be performed; and the arguments needed such as the list of request numbers to have associations created. The commands are then sent using PostCommand() to establish a connection to the web server and handle communications.

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


METHODS

BasicCommand(keys)
This function presets a command to the shared clauses covering logon information, debug information and session management parameters.

CCintCmd(keyList)
Encodes pairs to a CQWeb command string and encodes strings so that ``Cmd''=>``ASS OC'' produces ``CCIntCmd=ASS%20OC'' with &'s in between Even though the arguments represent hash pairs they will be processed as a list to maintain the original order

If the key in the pair is ``'' then it is handled as a raw ``append'' request with the value being appended to the command without being touched. This allows a precomputed string like basic_cmd to be added on at the end.

ClassInit()
This class function is automatically invoked to define class parameters using CQCC::Parm objects. Current parameters include:
CQCC_URL
The full URL needed to locate the ClearQuest web server. If not provided directly it will be built up from the CQCC_SERVER and CQCC_SERVERROOT class parameters.

CQCC_SERVER
Name of the ClearQuest web server host. Used to build up the CQCC_URL string along with CQCC_SERVERROOT.

CQCC_SERVERROOT
Main folder on web server where ASP server will be located. Used to build up the CQCC_URL string along with CQCC_SERVER.

CQCC_WEB_DATABASE_SET
Similar to CQCC_DATABASE_SET but only used by the CQWeb interface. May or may not be set to the same value. No default value.

CQWEB_KEEPSESSION
The CQWeb interface performance is greatly improved when the same communications session is kept open and reused as long as it can be (CQWEB_SESSION_TIMEOUT). This parameter enables reusing sessions and is TRUE by default.

CQWEB_SESSION_TIMEOUT
CQWeb communications sessions can be kept open for up to two minutes depending on the ClearQuest release (60 seconds for 4.1, 120 seconds for 4.2). Default is 55 seconds; bounded between 0 and 120.

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.

ClearCookie()
This method clears the persistent session cookie and timestamp, and deletes the session id file so future sessions won't attempt to use it.

ExecCommand(cmdlist)
This method opens up a fresh communications pipeline to ClearQuest for each command; uses the Cookie management routines to restore or save the session information between trigger invocations; sends the command to ClearQuest and processes and packages the output for consumption by PostCommand(), its' only expected caller.

LoadCookie()
This subroutine will load or validate the persisten session ``cookie''. If not keeping session then cookie should already be empty. If cookie not set then read it from session file if available. If stale cookie, then clear it and return no cookie.

Logon()
This method attempts to actively logon to the target ClearQuest database. Once established the class will try to use the same session id as long as possible.

new CQCC::CQWeb()
This method initializes the object's attributes including the URL, name of the session file to store session information between trigger invocations and the session id (cookie) used.

PostCommand($cmd)
This method completes preparation of the command being sent, sends it to ClearQuest using the ExecCommand() method, then interprets the result codes returned from ClearQuest.

The return values are (0) - Failed; (1) Succeeded; and 2(Succeeded and more data is available.

SaveCookie()
This method will save the persistent session cookie along with a timestamp to ensure the session information is not used after it has expired.

URLencode($value)
Internal function used to encode the commands and arguments being sent of the pipe. Originally from CGI.PM.

_EditAssocs($dbname,$entity,$VOList,$addAssocs,$delAssocs)
This internal 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. If the system fails to successfully make the new additions, they are all deleted to prepare for the trigger failing gracefully.

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.

Returns 1 for success, 0 for failure.

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

Queries are the only type of request where we may have to generate more than one command to get the entire result back; if the query status returns 'PARTIAL' we need to send a 'FETCH' command to obtain more result rows. Also, session status remains ACTIVE if more rows are to be fetched, regardless of the 'KeepSession' setting.