< Previous | Next >

Result sets

You move through the ResultSet returned by a query to retrieve the data for each record it includes.

About this task

Here are the steps to follow when using a ResultSet object:

Procedure

  1. Create the ResultSet object. To create a ResultSet object, you use either the BuildResultSet method or the BuildSQLQuery method of the Session object. Both of these methods return a ResultSet object that is ready to run the query but which contains no data.
  2. Run the query to fill the ResultSet with data. To run the query, you call the Execute or ExecuteAndCountRecords method of the ResultSet object. These methods fill the ResultSet with data from the database.
  3. Navigate through the resulting data until you find the record you want. To move to the first record in the result set, call the MoveNext method, which initializes the cursor and moves it to the first record. You can then use the methods of ResultSet to obtain information about the fields of first record. To move to subsequent records, use the MoveNext method again. You can then use the methods of ResultSet to obtain information about the fields of the current record.
  4. Retrieve the values from the fields of the record. Use methods of the ResultSet object to obtain information about the fields of the record.

Example

The following code example illustrates how to use methods of the ResultSet object to move through the data returned by your query: 

use CQPerlExt; 
#Start a Rational
ClearQuest session 
$SessionObj = CQSession::Build(); 
$dbsetname = "CQMS.SAMPL.HOME"; 

#Refresh list of accessible databases 
$databases = $SessionObj->GetAccessibleDatabases("MASTR", "", $dbsetname); 

#Log into a database 
$SessionObj->UserLogon("admin","","SAMPL",$dbsetname); 

#Create a Query by calling the BuildQuery(record_type) method, You specify a record type as the argument
$querydef = $SessionObj->BuildQuery("defect"); 
#  You use the BuildField (field_name) method for each field value that you want included for each record 
#  returned in the result set for the query:
$querydef->BuildField("id"); 
$querydef->BuildField("headline"); 
$querydef->BuildField("owner.login_name"); 
$querydef->BuildField("submit_date"); 

# The BuildResultSet(query_def_name) you build will contain the records returned by the query: 
$resultset = $SessionObj->BuildResultSet($querydef); 

# The following command runs the query and counts the number of records in the result set.
$ct = $resultset->ExecuteAndCountRecords(); 

for ($i = 0; $i < $ct; $i++) { 
#  You use the MoveNext method to iterate through the records in the ResultSet:
$resultset->MoveNext(); 
# You can also loop through ResultSet without using the count, like this:
# while ( $resultset->MoveNext == $CQPerlExt::CQ_SUCCESS ) {

#  You use the GetColumnValue(column_number) method to get the field values that you specified to be returned 
# for each record (by calling the BuildField method for each field to include):
   print $resultset->GetColumnValue(1); 
   print " "; 
   print $resultset->GetColumnValue(2); 
   print " "; 
   print $resultset->GetColumnValue(3); 
   print " "; 
   print $resultset->GetColumnValue(4); 
   print "\n"; 
   } 

# There are also methods to discover column properties such as these methods: 
# ResultSet:GetNumberOfColumns 
# ResultSet:GetColumnType (all values are returned as strings, but you may wish to format them) 
#ResultSet:GetColumnLabel

CQSession::Unbuild($SessionObj);

What to do next

The most useful queries includes filters that you define to retrieve specific records that meet certain criteria. The next lesson describes how to define search criteria.
< Previous | Next >