NAME

CQCC::CQSchema - Class used to manage ClearQuest schema descriptions


CLASS DESCRIPTION

This class manages schema descriptions to support different schemas across multiple entity record types. As used here a schema defines a generic record type consisting of a field map (mapping between the default names Rational ClearQuest initially uses and the local names for the same fields), one or more query descriptions (defining the search filters) and one or more results descriptions (defining the fields being returned and the desired display format string).

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


METHODS

ChangeFieldMap(key=value, ...)>
This method adds or overrides field mappings in the field map. The standard mappings will persist unless they are directly overwritten.

ClassInit()
This class function is automatically invoked to define class parameters using CQCC::Parm objects. Current parameters include:
CQCC_DATABASE_ENTITY_LIST
This parameter defines one or more databases and which entities they support. The format is

'dbname1: entity1,entity2; $dbname2: entity3,entity4'

i.e. 'SAMPL: defect,patch; SAMPL2: patch,defect'

ClassTest(@args)
This function will create schema samples, lookup schemas for entities, and return various values.

DefineCQSchema(key=value, ...)>
This function defines a new schema and adds it to the global list. It also defines the standard field_map, query_list, results_set and results_format information for a ClearQuery change request record.

EvalItem(item)
This method evaluates it's argument to process embedded references to the objects instance variables like <OWNER>.

GetCQSchemaByEntity(entityname)
This function looks up an existing schema that supports the specified entity name.

GetCQSchemaByName(schemaName)
This function looks up an existing schema with the given name.

GetEntityList()
This method retrieves the entity list from the object after parsing the original string.

GetQuery(name)
This method looks up the provided name and retrieves the matching query clauses as a list.

GetQueryList(name)
This method returns the list of queries defined for the current schema.

GetResultSet(name)
This method looks up the provided name and retrieves the matching resultSet string (comma delimited list) and the format string. If any field mappings are embedded in the resultSet list the substitutions are made before the result is returned.

($resultSet, $format) = $obj->GetResultSet(name);

If the name provided is an array it is treated as a one time result set of [ result_set, format ]. The result_set will be translated and returned.

GetRestrictionsQuery(entity)
This method retrieves the name of the restrictions query associated with the given entity if any.

new CQCC::CQSchema()
This method defines a new schema and adds it to the global list. It supports the following instance variables.
NAME
A name for the schema for easier reference.

ENTITY_LIST
A scalar string containing a comma delimited list of entity names supported by this schema. At least one name must be provided.

QUERY_NAME_PATTERN
A scalar string defining the public named queries that can be presented to the user. Example ``public queries\temp\'' would select all queries beginning with ``public queries\temp\''.

FIELD_MAP
A hash table of field name mappings, supporting local schema changes. Queries and results lists can use either explicit field names or references to the field map lists. For example if OWNER=>AssignedTo was in the field map, then <OWNER> would be translated to ``AssignedTo'' before it was used. This allows the application to generate additional queries on the fly. It will also facilitate taking advantage of ClearQuest schema aliases when that feature becomes available.

QUERY_LIST
A hash table containing named query strings allowing Schemas to support more than one standard query, i.e. ``Standard'' and ``Restriction''. Each query is an array of one or more clauses, each of which is in the form ``subject verb object''. Each clause will be processed to replace any <> references with the appropriate field mappings, allowing generic queries to be defined that work with different field mappings.

RESULTS_SET_LIST
A hash table containing named results set lists in the form of scalar strings delimited with commas. When a query is performed the results set defines which entity fields are to be retrieved. A matching format string with the same name is used to format the columns into a return string for each record being retrieved. The default results set, ``STANDARD'', is set to this string: ``<ID>, <STATE>, <PRIORITY>, <SEVERITY>, <HEADLINE>''

RESULTS_FORMAT_LIST
A hash table containing named format strings to match the results set with the same name. The default string is set to this string: ``%s %-9.9s %1.1s %1.1s %-45.45s''.

Print()
This method prints out the contents of the schema.

SetQuery(name, query_clauses...)
This method adds or overrides query definitions in the schema. Each query needs a name and an array of conditional clauses which may contain field aliases, i.e. ``<OWNER> eq <*USER*>''. The standard mappings will persist unless they are directly overwritten.

SetResultSet(name, resultSetList, resultFormat)
This method adds or overrides result set descriptions in the schema based on a comma delimited string with the desired fields and a matching format string. The resultSetList may contain field aliases, i.e. ``<OWNER> eq <*USER*>''. The standard mappings will persist unless they are directly overwritten.

SupportedDatabaseList()
This function returns a list of all supported databases supported by the defined schemas.

SupportedEntityList(databaseName)
This function gets entities supported by a specific database.

TranslateQuery(queryName or [ clauselist ] )
This method takes either the name of a defined query or a one-time query provided as a list of query clauses. In either case it will process the query clauses to substitute field mapping names in in place of the <NAME> tags. A special tag, <*USER*> is provided to reference the current USER name in the midst of the current trigger invocation.