NAME

Clearquest - Object oriented interface to Clearquest.

VERSION

Author: Andrew DeFaria <Andrew@DeFaria.com>
Revision: $Revision: 2.23 $
Created: Fri Sep 22 09:21:18 CDT 2006
Modified: 2013/03/28 22:48:07

SYNOPSIS

Provides access to Clearquest database in an object oriented manner.

# Create Clearquest object
my $cq = Clearquest->new;

# Connect to database (using all the defaults in cq.conf)
$cq->connect;

# Connect as non standard user;

$cq->connect (CQ_USERNAME => 'me', CQ_PASSWORD => 'mypassword');

# Get record (Default: all fields)
my %record = $cq->get ($recordName, $key);

# Get record with specific field list
my %record =$cq->get ($recordName, $key, qw(field1 field2))

# Modify a record
my %update = (
  Description => 'This is a new description',
  Active      => 1,
);
$cq->modify ($recordName, $key, 'Modify', \%update);

# Change state using modify with an alternate action. Note the use of @ordering
my %fieldsToUpdate = (
  Project  => 'Carrier',
  Category => 'New Functionality',
  Groups   => [ 'Group1', 'Group2' ],
);

my @ordering qw(Project Category);

$cq->modify ($recordName, $key, 'Open', \%fieldsToUpdate, @ordering);

if ($cq->error) {
  error "Unable to update $key to Opened state\n"
      . $cq->errmsg;
} # if

DESCRIPTION

This module provides a simple interface to Clearquest in a Perl like fashion. There are three modes of talking to Clearquest using this module - api, rest and client.

With module = 'api' you must have Clearquest installed locally and you must use cqperl to execute your script. This mode of operation has the benefit of speed - note that initial connection to the Clearquest database is not very speedy, but all subsequent calls will operate at full speed. The 'api' module is free to use. For the other modules contact Andrew DeFaria <Andrew@DeFaria.com>.

With module = 'rest' you can access Clearquest by using a RESTFull interface. You can use any Perl which has the required CPAN modules (REST, XML::Simple - see Clearquest::REST for a list of required CPAN modules). The REST interface is a slower than the native api and requires the setup of Clearquest Web (cqweb) on your network. To use the REST interface set CQ_MODULE to 'rest'.

With module = 'client' you access Clearquest through the companion Clearquest::Server module and the cqd.pl server script. The server process is started on a machine that has Clearquest installed locally. It uses the api interface for speed and can operate in a multithreaded manner, spawning processes which open and handle requests from Clearquest::Client requests. To use the Client interface set CQ_MODULE to 'client'.

Other than setting CQ_MODULE to one of the three modes described above, the rest of your script's usage of the Clearquest module should be exactly the same.

CONFIGURATION

This module reads configuration data from a file (../etc/cq.conf) which sets default values described below. Or you can export the option name to the env(1) to override the defaults in cq.conf. Finally you can programmatically set the options when you call new by passing in a %parms hash. To specify the %parms hash key remove the CQ_ portion and lc the rest.

CQ_SERVER: Clearquest server to talk to. Also used for rest server (Default: From cq.conf)
CQ_PORT: Port to connect to (Default: From cq.conf)
CQ_WEBHOST: The web host to contact with leading http:// (Default: From cq.conf)
CQ_DATABASE: Name of database to connect to (Default: From cq.conf)
CQ_USERNAME: User name to connect as (Default: From cq.conf)
CQ_PASSWORD: Password for CQREST_USERNAME (Default: From cq.conf)
CQ_DBSET: Database Set name (Default: From cq.conf)
CQ_MODULE: One of 'api', 'rest' or 'client' (Default: From cq.conf)

METHODS

The following methods are available:

add ($$;@)

Insert a new record into the database

Parameters:

$table

The name of the table to insert into

$values

Hash reference of name/value pairs for the insertion

@ordering

Array containing field names that need to be processed in order. Not all fields mentioned in the $values hash need be mentioned here. If you have fields that must be set in a particular order you can mention them here. So, if you're adding the Defect record, but you need Project set before Platform, you need only pass in an @ordering of qw(Project Platform). They will be done first, then all of the rest of the fields in the $values hash. If you have no ordering dependencies then you can simply omit @ordering.

Note that the best way to determine if you have an ordering dependency try using a Clearquest client and note the order that you set fields in. If at anytime setting one field negates another field via action hook code then you have just figured out that this field needs to be set before the file that just got negated.

Returns:

$dbid: The DBID of the newly added record or undef if error.

connect (;$$$$)

Connect to the Clearquest database. You can supply parameters such as username, password, etc and they will override any passed to Clearquest::new (or those coming from ../etc/cq.conf)

Parameters:

$username: Username to use to connect to the database
$password: Password to use to connect to the database
$database: Clearquest database to connect to
$dbset: Database set to connect to (Default: Connect to the default dbset)

Returns:

connected ()

Returns 1 if we are currently connected to Clearquest

Parameters:

none

Returns:

1 if logged in - 0 if not

connection ()

Returns a connection string that describes the current connection

Parameters:

$fullyQualify: If true the connection string will be fully qualified

Returns:

$connectionStr: A string describing the current connection. Generally <username>@<database>[/<dbset>]. Note that <dbset> is only displayed if it is not the default DBSet as defined in cq.conf.

checkErr (;$$)

Checks for error in the last Clearquest method call and prints error to STDERR. Optionally prints a user message if $msg is specified. Dies if $die is true

Parameters:

$msg: User error message
$die: Causes caller to croak if set to true

Returns:

$error: Returns 0 for no error, non-zero if error.

database

Returns the current database (or the database that would be used)

Parameters:

none

Returns:

database

dbset

Returns the current dbset (or the dbset that would be used)

Parameters:

none

Returns:

dbset

dbsets ()

Return the installed DBSets for this schema

Parameters:

none

Returns:

@dbsets: An array of dbsets

delete ($;$)

Deletes records from the database

Parameters:

$table: Table to delete records from
$key: Key of the record to delete

Returns:

$errmsg: Error message or blank if no error

disconnect ()

Disconnect from Clearquest

Parameters:

none

Returns:

nothing

errmsg ()

Returns the last error message. Optionally sets the error message if specified.

Parameters:

$errmsg

Returns:

$errmsg: Last $errmsg

error ($error)

Returns the last error number. Optional set the error number if specified

Parameters:

$error: Error number to set

Returns:

$error: Last error

fieldType ($table, $fieldname)

Returns the field type for the $table, $fieldname combination.

Parameters:

$table: Table to return field type from.
$fieldname: Fieldname to return the field type from.

Returns:

$fieldType: Fieldtype enum

fieldTypeName ($table, $fieldname)

Returns the field type name for the $table, $fieldname combination.

Parameters:

$table: Table to return field type from.
$fieldname: Fieldname to return the field type from.

Returns:

$fieldTypeName: Fieldtype name

find ($;$@)

Find records in $table. You can specify a $condition and which fields you wish to retrieve. Specifying a smaller set of fields means less data transfered and quicker retrieval so only retrieve the fields you really need.

Parameters:

$table

Name of the table to search

$condition

Condition to use. If you want all records then pass in undef. Only simple conditions are supported. You can specify compound conditions (e.g. field1 == 'foo' and field1 == 'bar' or field2 is not null). No parenthesizing is supported (yet).

The following conditionals are supported

Equal (==|=)
Not Equal (!=|<>)
Less than (<)
Greater than (>)
Less than or equal (<=)
Greater than or equal (>=)
Like
Is null
Is not null
In

Note that "is not null" is currently not working in the REST module (it works in the api and thus also in the client/server model). This because the OLSC spec V1.0 does not support it.

As for "Like"", you'll need to specify "<fieldname> like '%var%'" for the condition.

"In" is only available in the REST interface as that's what OLSC supports. It's syntax would be "<fieldname> In 'value1', 'value2', 'value3'..."

Also conditions can be combined with (and|or) so in the api you could do "in" as "<fieldname> = 'value1 or <fieldname> = 'value2" or <fieldname> = 'value3'".

Complicated expressions with parenthesis like "(Project = 'Athena' or Project = 'Hawaii') and Category = 'Aspen'" are not supported.

@fields

An array of fieldnames to retrieve

Returns:

$result or ($result, $nbrRecs): Internal structure to be used with getNext. If in an array context then $nbrRecs is also returned.

findIDs ($)

Given a $str or a reference to an array of strings, this function returns a list of Clearquest IDs found in the $str. If called in a scalar context this function returns a comma separated string of IDs found. Note that duplicate IDs are eliminated. Also, the lists of IDs may refer to different Clearquest databases.

Parameters:

$str: String or reference to an array of strings to search

Returns:

@IDs or $strIDs: Either an array of CQ IDs or a comma separated list of CQ IDs.

get ($$)

Return a record that you have the id or key of.

Parameters:

$table: The $table to get the record from
$id: The $id or key to use to retrieve the record

Returns:

%record: Hash of name/value pairs for all the fields in $table

getDBID ($$;@)

Return a record that you have the dbid

Parameters:

$table

The $table to get the record from

$dbid

The $dbid to use to retrieve the record

@fields

Array of field names to retrieve (Default: All fields)

Note: Avoid getting all fields for large records. It will be slow and bloat your script's memory usage.

Returns:

%record: Hash of name/value pairs for all the fields in $table

getDynamicList ($)

Return the entries of a dynamic list

Parameters:

$list: The name of the dynamic list

Returns:

@entries: An array of entries from the dynamic list

getNext ($)

Return the next record that qualifies from a preceeding call to the find method.

Parameters:

$result: The $result returned from find.

Returns:

%record: Hash of name/value pairs for the @fields specified to find.

id2db ($)

This function returns the database name given an ID.

Parameters:

$ID: The ID to extract the database name from

Returns:

$database: Returns the name of the database the ID is part of or undef if not found.

key ($$)

Return the key of the record given a $dbid

Parameters:

$table: Name of the table to lookup
$dbid: Database ID of the record to retrieve

Returns:

key

modify ($$$$;@)

Update record(s)

Parameters:

$table

The $table to get the record from

$key

The $key identifying the record to modify

$action

Action to perform the modification under. Default is 'Modify'.

$values

Hash reference containing name/value that have the new values for the fields

@ordering

Array containing field names that need to be processed in order. Not all fields mentioned in the $values hash need be mentioned here. If you have fields that must be set in a particular order you can mention them here. So, if you're modifying the Defect record, but you need Project set before Platform, you need only pass in an @ordering of qw(Project Platform). They will be done first, then all of the rest of the fields in the $values hash. If you have no ordering dependencies then you can simply omit @ordering.

Returns:

$errmsg: The $errmsg, if any, when performing the update (empty string for success)

modifyDBID ($$$%)

Update a unique record (by DBID)

Parameters:

$table: The $table to get the record from
$dbid: The $dbid of the record to update. Note that the find method always includes the dbid of a record in the hash that it returns.
$action: Action to perform the modification under. Default is 'Modify'.
%update: Hash containing name/value that have the new values for the fields

Returns:

$errmsg: The $errmsg, if any, when performing the update (empty string for success)

module

Returns the current back end module we are using

Parameters:

none

Returns:

module

new ()

Construct a new Clearquest object.

Parameters:

Below are the key values for the %parms hash.

CQ_SERVER: Webhost for REST module
CQ_USERNAME: Username to use to connect to the database
CQ_PASSWORD: Password to use to connect to the database
CQ_DATABASE: Clearquest database to connect to
CQ_DBSET: Database set to connect to
CQ_MODULE: One of 'rest', 'api' or 'client' (Default: From cq.conf). This determines which backend module will be used.

Returns:

Clearquest object

server

Returns the current server if applicable

Parameters:

none

Returns:

$server: For api this will return ''. For REST and client/server this will return the server name that we are talking to.

setOpts

Set options for operating

Parameters:

%opts

Options to set. The only options currently supported are emptyStringForUndef and returnSystemFields. If set emptyStringForUndef will return empty strings for empty fields instead of undef. Default: Empty fields are represented with undef.

System-owned fields are used internally by IBM Rational ClearQuest to maintain information about the database. You should never modify system fields directly as it could corrupt the database. If returnSystemFields is set then system fields will be returned. Default: System fields will not be returned unless explicitly stated in the @fields parameter. This means that if you do not specify any fields in @fields, all fields will be returned except system fields, unless you set returnSystemFields via this method or you explicitly mention the system field in your @fields parameter.

Returns:

Nothing

getOpt

Get option

Parameters:

$option

Option to retrieve. If non-existant then undef is returned.

Returns:

$option or undef if option doesn't exist

username

Returns the current username (or the username that would be used)

Parameters:

none

Returns:

username

DEPENDENCIES

Perl Modules

File::Basename

BUGS AND LIMITATIONS

There are no known bugs in this module

Multithreading causes the database to be reopened for each thread. This can cause performance issues if the database is large or if the database is accessed by multiple threads.

Please report problems to Andrew DeFaria <Andrew@DeFaria.com>.

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone else, you are strictly prohibited from removing any copyright notice from that Modified Version.

Copyright Holder makes no, and expressly disclaims any, representation or warranty, should the Package be used for any purpose. The liability of the Copyright Holder is limited to the maximum extent permitted by law.

To install Clearquest, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Clearquest

CPAN shell

perl -MCPAN -e shell
install Clearquest

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

CONFIGURATION

METHODS

add ($$;@)

connect (;$$$$)

connected ()

connection ()

checkErr (;$$)

database

dbset

dbsets ()

delete ($;$)

disconnect ()

errmsg ()

error ($error)

fieldType ($table, $fieldname)

fieldTypeName ($table, $fieldname)

find ($;$@)

findIDs ($)

get ($$)

getDBID ($$;@)

getDynamicList ($)

getNext ($)

id2db ($)

key ($$)

modify ($$$$;@)

modifyDBID ($$$%)

module

new ()

server

setOpts

getOpt

username

DEPENDENCIES

Perl Modules

BUGS AND LIMITATIONS

LICENSE AND COPYRIGHT

Module Install Instructions