< Previous | Next >

Building a query

You build a query by creating a QueryDef object by calling the BuildQuery method of the Session object.

About this task

A Query consists of a list of fields for a given record type for which you want to retrieve the values. The records are returned in a ResultSet object. The query returns the requested fields for all records of a given type. You can then iterate over the results sets and process the data.

Creating a query may involve the creation of at least three separate objects: a QueryDef object, a QueryFilterNode object, and a ResultSet object. More complex queries might also involve the creation of additional QueryFilterNode objects.

To create a simple query, follow these steps:

Procedure

  1. Build a query by using the QueryDef object to specify the data to retrieve. The QueryDef object contains the definition of a query for a Rational® ClearQuest® database. After a QueryDef is created, you can use it to get information from the database. To create this object, you use the BuildQuery method of the Session object.
  2. Use the methods of QueryDef to add search criteria and to specify the fields of each record you want the query to return.
  3. Create a ResultSet object to hold the returned data. To create this object, call the BuildResultSet method of the Session object. On creation, the ResultSet object creates a set of internal data structures using the information in the QueryDef object as a template. When the query is run, the ResultSet object fills these data structures with data from the query.
  4. Run the query by calling the Execute or ExecuteAndCountRecords method of the ResultSet object. Calling either of these methods populates a result set with the data it fetches from the database.
  5. Access the data by iterating through the ResultSet object and using other methods of the object ResultSet to obtain information about the fields of a record.

Results

Rather than returning the entire record, a query returns only those fields of the record that you specify by calling the BuildField method of the QueryDef object. The Execute method returns results in no particular order. Therefore, the ResultSet object uses a cursor-based system to allow your code to move through the records one by one.
< Previous | Next >