CdbQueryDef Object

See Also    Example    Methods    Properties

A CdbQueryDef object is a stored definition of a query in a Microsoft Jet database or a temporary definition of a query in an ODBCDirect workspace.

Remarks

You can use the CdbQueryDef object to define a query. For example, you can:

• Use the SQL property to set or return the query definition.
  
  
• Use the CdbQueryDef object's Parameters collection to set or return query parameters.
  
  
• Use the Type property to return a value indicating whether the query selects records from an existing table, makes a new table, inserts records from one table into another table, deletes records, or updates records.
  
  
• Use the MaxRecords property to limit the number of records returned from a query.
  
  
• Use the ODBCTimeout property to indicate how long to wait before the query returns records. The ODBCTimeout property applies to any query that accesses ODBC data.

In a Microsoft Jet workspace, you can also:

• Use the ReturnsRecords property to indicate that the query returns records. The ReturnsRecords property is only valid on SQL pass-through queries.
  
  
• Use the Connect property to make an SQL pass-through query to an ODBC database.

In an ODBCDirect workspace, you can also:

• Use the Prepare property to determine whether to invoke the ODBC SQLPrepare API when the query is executed.
  
  
• Use the CacheSize property to cache records returned from a query.

You can also create temporary CdbQueryDef objects. Unlike permanent CdbQueryDef objects, temporary CdbQueryDef objects are not saved to disk or appended to the QueryDefs collection. Temporary CdbQueryDef objects are useful for queries that you must run repeatedly during run time, but do not not need to save to disk, particularly if you create their SQL statements during run time.

You can think of a permanent CdbQueryDef object in a Microsoft Jet workspace as a compiled SQL statement. If you execute a query from a permanent CdbQueryDef object, the query will run faster than if you run the equivalent SQL statement from the OpenRecordset method. This is because the Microsoft Jet database engine doesn't need to compile the query before executing it.

The preferred way to use the native SQL dialect of an external database engine accessed through the Microsoft Jet database engine is through CdbQueryDef objects. For example, you can create a Microsoft SQL Server query and store it in a CdbQueryDef object. When you need to use a non-Microsoft Jet database engine SQL query, you must provide a Connect property string that points to the external data source. Queries with valid Connect properties bypass the Microsoft Jet database engine and pass the query directly to the external database server for processing.

To create a new CdbQueryDef object, use the CreateQueryDef method. In a Microsoft Jet workspace, if you supply a string for the name argument or, if you explicitly set the Name property of the new CdbQueryDef object to a non–zero-length string, you will create a permanent CdbQueryDef that will automatically be appended to the QueryDefs collection and saved to disk. Supplying a zero-length string as the name argument or explicitly setting the Name property to a zero-length string will result in a temporary CdbQueryDef object.

In an ODBCDirect workspace, a CdbQueryDef is always temporary. The QueryDefs collection contains all open CdbQueryDef objects. When a CdbQueryDef is closed, it is automatically removed from the QueryDefs collection.

To refer to a CdbQueryDef object in a collection by its ordinal number or by its Name property setting, use either of the following syntax forms:

QueryDefs[0]

QueryDefs["name"]

You can refer to temporary CdbQueryDef objects only by the object variables that you have assigned to them.

CdbQueryDef Constructor Syntax

Use any one of the following three constructors. The qualifier 'CONSTRUCTOR' in the syntax models is provided to help readability. It has no syntactic value.

CONSTRUCTORCdbQueryDef(VOID);

This constructor creates an instance of the class. There are no parameters.

CONSTRUCTORCdbQueryDef(const CdbQueryDef &);

This constructor creates a copy of the object referenced in the parameter.

CONSTRUCTORCdbQueryDef(DAOQueryDef *pqd,

BOOL bAddRef = FALSE);

DAO functionality is presented through pointers to DAO Automation interfaces. This constructor makes a DAO interface available in the form of a DAO class object that provides additional functionality.

This constructor is not required for typical use. It is provided to enable you to easily create a DAO class object if you have access to the corresponding DAO interface.

When the destructor for the DAO object is invoked, the underlying Automation interface's Release member is called. If Release decrements the interface's reference count to zero, the pointer to the Automation interface can be deleted. If you don't want this to happen (for example, because you want to discard the DAO object, but continue using the Automation interface), specify TRUE for the second parameter. The underlying Automation interface's AddRef member is called, which counterbalances the eventual call to Release.

Note In DAO the default collection for the CdbQueryDef object is Parameters. However, in the DAO SDK the default collection for the CdbQueryDef object is Fields. The default collection is accessed by applying the subscript ([ ]) operator to the CdbQueryDef object.