Lab 8

ClearQuest® Customization – API Functions

The purpose of this Laboratory is to give you gain hands-on experience with the process
of calling Rational ® ClearQuest® API functions in external programs.

Important Notes
In order to do the exercises in this Lab, the computer that you are using must have the
following settings:
1. You must have a designated location for developing your external programs.
The recommended location is C:\temp\. However, you can select any available
folder on your local drive as the development location.
2. You need to make the CQPerl application available to your system. You will
use CQPerl as the Perl interpreter. Generally, the CQPerl application is available in
a location such as C:\Program Files\Rational\ClearQuest\. You must add the
path of the CQPerl application to your system environment variable PATH.
3. You need to make the MS-DOS Command Shell available. In this Lab, all
external programs will be executed in the MS-DOS Command Shell. Normally, the
MS-DOS Command application, CMD.EXE, is located in C:\WINNT\system32\.
You can make a shortcut for the application and place it in your desktop. For your
convenience, you can configure the properties of the CMD shortcut to your
preference, for example, you can set the height of the screen buffer size to be 1000
on the Layout tab of the CMD Properties dialog box.

Objectives
In this Lab, you will perform the following tasks:
 Develop a Perl script as an external program to submit a defect record.
 Develop a Perl script as an external program to list all the defect records in the
SAMPL database, and modify the value of the Description field in one of the
records, SAMPL00000012.
 Develop a Perl script as an external program to generate a chart.

© Copyright IBM Corp. 2003 8 - 1

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Student Workbook

Exercise 8.1: Develop an external program to submit a defect.

The purpose of this exercise is to develop a Perl script as an external program that calls
ClearQuest API functions to submit a defect.

Here are the tasks that you will perform:

1. Create a Perl script that calls ClearQuest API functions to submit a defect to the
SAMPL database with the following content:

 Headline – Using API functions to submit defects does work

 Severity – 1-Critical

 Priority – 1-Resolve Immediately

 Owner – admin

 Description – We can use external programs to submit defects.

2. Execute the developed Perl script as an external program to actually submit a

defect.

3. Review the submitted defect in the ClearQuest Windows client.

8 - 2 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 SCM490 Mastering Rational ClearQuest Administration

Solution for Exercise 8.1

The following set of steps is one of the ways to approach the above tasks. You can use
these steps to accomplish the tasks listed in this exercise, or create your own.

TASK 1 – Create a Perl script that calls ClearQuest API functions to submit a
defect.

1. Open the Windows Explorer. Click View > Explorer Bar > Folders. The Folders
tree appears.

2. In the Folders tree, locate and select the designated development folder, for
example, C:\Temp.

3. Click File > New > Text Document. A file named New Text Document.txt is
created.

4. Double-click the New Text Document.txt icon to open the file in Notepad.

5. Type the following code. Alternatively, you can copy this code from the file
lab8.1Perl on the CD included with this Student Workbook.
#!perl -w
use CQPerlExt;

#get the ClearQuest session

my $session = CQSession::Build() or die "$!";
CQSession::UserLogon ($session, "admin", "", "SAMPL", "2003.06.00");

#create the new entity object

my $newDefect = $session -> BuildEntity ("defect");

#Setting up the content of the new entity

$newDefect->SetFieldValue("headline", "Using API functions to submit defects
does work");
$newDefect->SetFieldValue("severity", "1-Critical");
$newDefect->SetFieldValue("priority", "1-Resolve Immediately");
$newDefect->SetFieldValue("owner", "admin");
$newDefect->SetFieldValue("Description", "We can use external programs to
submit defects.");
$newDefect->Validate();
$newDefect->Commit();
CQSession::Unbuild($session);

6. Save the file as Exercise8_1.txt. Rename it Exercise8_1.pl.

TASK 2 – Execute the Perl script as an external program.

© Copyright IBM Corp. 2003 8 - 3

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Student Workbook

7. Open the MS-DOS Command Shell. Change the directory to the development
location, for example, C:\Temp.

8. Type “cqperl Exercise8_1.pl”. There will be no error message if the script is

executed successfully.

TASK 3 – Review the submitted defect in the ClearQuest Windows client.

9. Click Start > Programs > Rational Software> Rational ClearQuest.

10. If the Rational Schema Repository dialog box appears, select 2003.06.00 by
highlighting it and click Next. Otherwise, skip to step 11.

11. In the Rational ClearQuest Login dialog box, type “admin” as the user name, and
leave the Password field blank. Select SAMPL as the database. Click OK.

12. In the Workspace, double-click Public Queries/All Defects to execute the query.

13. Scroll down the Result Set table. The submitted defect is the last one in the table.

14. Select that entry to examine its content in the Record form.

15. Close the ClearQuest client. This concludes Exercise 8.1.

8 - 4 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 SCM490 Mastering Rational ClearQuest Administration

Exercise 8.2: Develop an external program to list all the defect records in a ClearQuest
user database. Use this program to modify one of the records.

Here are the tasks that you will perform:

1. Develop a Perl script that calls ClearQuest API functions to:

 List all the defect records in the SAMPL database, and select id,
Headline, and State as display fields.

 Modify the Description field of the defect record SAMPL00000012 to be

This defect has been modified.

2. Execute the developed Perl script as an external program to list all the defect
records in the SAMPL database, and modify the defect record SAMPL00000012.

3. Examine the modified defect in the ClearQuest Windows client.

© Copyright IBM Corp. 2003 8 - 5

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Student Workbook

Solution for Exercise 8.2

The following set of steps is one of the ways to approach the above tasks. You can use
these steps to accomplish the tasks listed in this exercise, or create your own.

TASK 1 – Create a Perl script that calls ClearQuest API functions to list all the
defect records in the SAMPL database, and modify the defect record
SAMPL00000012.

1. Open the Windows Explorer. Click View > Explorer Bar > Folders. The Folders
tree appears.

2. In the Folders tree, locate and select the desired development folder, for example,
C:\Temp.

3. Click File > New > Text Document. A file named New Text Document.txt is
created.

4. Double-click the New Text Document.txt icon to open the file in Notepad.

5. Type the following code. Alternatively, you can copy this code from the file
lab8.2Perl on the CD included with this Student Workbook.
#!perl -w
use CQPerlExt;

#Getting the session

my $session = CQSession::Build() or die "$!";
CQSession::UserLogon ($session, "admin", "", "SAMPL", "2003.06.00");

my $querydef = $session -> BuildQuery ("defect");

$querydef -> BuildField ("id");
$querydef -> BuildField ("headline");
my $resultset = $session -> BuildResultSet ($querydef);
$resultset -> Execute();

while (($resultset->MoveNext()) == 1)
{
$id = $resultset->GetColumnValue(1);
$rec = $session->GetEntity("Defect", $id);
$head = $rec->GetFieldValue("Headline")->GetValue();
$state= $rec->GetFieldValue("State")->GetValue();
print "$id, $head, $state. \n";

if ($id eq "SAMPL00000012") {
$session->EditEntity($rec, "Modify");
$rec->SetFieldValue("description", "This defect has been modified.");

8 - 6 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
 SCM490 Mastering Rational ClearQuest Administration

$rec->Validate();
$rec->Commit();
}
}

CQSession::Unbuild($session);
6. Save the file as Exercise8_2.txt. Rename it Exercise8_2.pl.
TASK 2 – Execute the Perl script as an external program.

7. Open the MS-DOS Command Shell. Change the directory to the development
location, for example, C:\Temp.

8. Type “cqperl Exercise8_2.pl”. There will be no error message if the script is

executed successfully. Also, a list of all of the defect records in the SAMPL
database appears.

TASK 3 – Examine the modified defect in the ClearQuest Windows client.

9. Click Start > Programs > Rational Software> Rational ClearQuest.

10. If the Rational Schema Repository dialog box appears, select 2003.06.00 by
highlighting it and click Next. Otherwise, skip to step 11.

11. In the Rational ClearQuest Login dialog box, type “admin” as the user name, and
leave the Password field blank. Select SAMPL as the database. Click OK.

12. In the Workspace, double-click Public Queries/All Defects to execute the query.

13. Scroll down the Result Set table to locate the defect with SAMPL00000012 as the
record ID in the table.

14. Select that entry to examine its content in the Record form. The Description field
should have the following value: This defect has been modified.

15. Close the ClearQuest client. This concludes Exercise 8.2.

© Copyright IBM Corp. 2003 8 - 7

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Student Workbook

8 - 8 © Copyright IBM Corp. 2003

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.