Share via


CDaoQueryDef Class

Represents a query definition, or "querydef," usually one saved in a database.

class CDaoQueryDef : public CObject

Members

Public Constructors

Name

Description

CDaoQueryDef::CDaoQueryDef

Constructs a CDaoQueryDef object. Next call Open or Create, depending on your needs.

Public Methods

Name

Description

CDaoQueryDef::Append

Appends the querydef to the database's QueryDefs collection as a saved query.

CDaoQueryDef::CanUpdate

Returns nonzero if the query can update the database.

CDaoQueryDef::Close

Closes the querydef object. Destroy the C++ object when you finish with it.

CDaoQueryDef::Create

Creates the underlying DAO querydef object. Use the querydef as a temporary query, or call Append to save it in the database.

CDaoQueryDef::Execute

Executes the query defined by the querydef object.

CDaoQueryDef::GetConnect

Returns the connection string associated with the querydef. The connection string identifies the data source. (For SQL pass-through queries only; otherwise an empty string.)

CDaoQueryDef::GetDateCreated

Returns the date the saved query was created.

CDaoQueryDef::GetDateLastUpdated

Returns the date the saved query was last updated.

CDaoQueryDef::GetFieldCount

Returns the number of fields defined by the querydef.

CDaoQueryDef::GetFieldInfo

Returns information about a specified field defined in the query.

CDaoQueryDef::GetName

Returns the name of the querydef.

CDaoQueryDef::GetODBCTimeout

Returns the timeout value used by ODBC (for an ODBC query) when the querydef is executed. This determines how long to allow for the query's action to complete.

CDaoQueryDef::GetParameterCount

Returns the number of parameters defined for the query.

CDaoQueryDef::GetParameterInfo

Returns information about a specified parameter to the query.

CDaoQueryDef::GetParamValue

Returns the value of a specified parameter to the query.

CDaoQueryDef::GetRecordsAffected

Returns the number of records affected by an action query.

CDaoQueryDef::GetReturnsRecords

Returns nonzero if the query defined by the querydef returns records.

CDaoQueryDef::GetSQL

Returns the SQL string that specifies the query defined by the querydef.

CDaoQueryDef::GetType

Returns the query type: delete, update, append, make-table, and so on.

CDaoQueryDef::IsOpen

Returns nonzero if the querydef is open and can be executed.

CDaoQueryDef::Open

Opens an existing querydef stored in the database's QueryDefs collection.

CDaoQueryDef::SetConnect

Sets the connection string for a SQL pass-through query on an ODBC data source.

CDaoQueryDef::SetName

Sets the name of the saved query, replacing the name in use when the querydef was created.

CDaoQueryDef::SetODBCTimeout

Sets the timeout value used by ODBC (for an ODBC query) when the querydef is executed.

CDaoQueryDef::SetParamValue

Sets the value of a specified parameter to the query.

CDaoQueryDef::SetReturnsRecords

Specifies whether the querydef returns records. Setting this attribute to TRUE is only valid for SQL pass-through queries.

CDaoQueryDef::SetSQL

Sets the SQL string that specifies the query defined by the querydef.

Public Data Members

Name

Description

CDaoQueryDef::m_pDAOQueryDef

A pointer to the OLE interface for the underlying DAO querydef object.

CDaoQueryDef::m_pDatabase

A pointer to the CDaoDatabase object with which the querydef is associated. The querydef might be saved in the database or not.

Remarks

A querydef is a data access object that contains the SQL statement that describes a query, and its properties, such as "Date Created" and "ODBC Timeout." You can also create temporary querydef objects without saving them, but it is convenient — and much more efficient — to save commonly reused queries in a database. A CDaoDatabase object maintains a collection, called the QueryDefs collection, that contains its saved querydefs.

Note

The DAO database classes are distinct from the MFC database classes based on Open Database Connectivity (ODBC). All DAO database class names have the "CDao" prefix. You can still access ODBC data sources with the DAO classes. In general, the MFC classes based on DAO are more capable than the MFC classes based on ODBC; the DAO-based classes can access data, including through ODBC drivers, via their own database engine. The DAO-based classes also support Data Definition Language (DDL) operations, such as adding tables via the classes, without having to call DAO directly.

Usage

Use querydef objects either to work with an existing saved query or to create a new saved query or temporary query:

  1. In all cases, first construct a CDaoQueryDef object, supplying a pointer to the CDaoDatabase object to which the query belongs.

  2. Then do the following, depending on what you want:

    • To use an existing saved query, call the querydef object's Open member function, supplying the name of the saved query.

    • To create a new saved query, call the querydef object's Create member function, supplying the name of the query. Then call Append to save the query by appending it to the database's QueryDefs collection. Create puts the querydef into an open state, so after calling Create you do not call Open.

    • To create a temporary querydef, call Create. Pass an empty string for the query name. Do not call Append.

When you finish using a querydef object, call its Close member function; then destroy the querydef object.

Tip

The easiest way to create saved queries is to create them and store them in your database using Microsoft Access. Then you can open and use them in your MFC code.

Purposes

You can use a querydef object for any of the following purposes:

  • To create a CDaoRecordset object

  • To call the object's Execute member function to directly execute an action query or a SQL pass-through query

You can use a querydef object for any type of query, including select, action, crosstab, delete, update, append, make-table, data definition, SQL pass-through, union, and bulk queries. The query's type is determined by the content of the SQL statement that you supply. For information about query types, see the Execute and GetType member functions. Recordsets are commonly used for row-returning queries, usually those using the SELECT ... FROM keywords. Execute is most commonly used for bulk operations. For more information, see Execute and CDaoRecordset.

Querydefs and Recordsets

To use a querydef object to create a CDaoRecordset object, you typically create or open a querydef as described above. Then construct a recordset object, passing a pointer to your querydef object when you call CDaoRecordset::Open. The querydef you pass must be in an open state. For more information, see class CDaoRecordset.

You cannot use a querydef to create a recordset (the most common use for a querydef) unless it is in an open state. Put the querydef into an open state by calling either Open or Create.

External Databases

Querydef objects are the preferred way to use the native SQL dialect of an external database engine. For example, you can create a Transact SQL query (as used on Microsoft SQL Server) and store it in a querydef object. When you need to use a SQL query not based on the Microsoft Jet database engine, you must provide a connection string that points to the external data source. Queries with valid connection strings bypass the database engine and pass the query directly to the external database server for processing.

Tip

The preferred way to work with ODBC tables is to attach them to a Microsoft Jet (.MDB) database.

For related information, see the topics "QueryDef Object", "QueryDefs Collection", and "CdbDatabase Object" in the DAO SDK.

Inheritance Hierarchy

CObject

CDaoQueryDef

Requirements

Header: afxdao.h

See Also

Reference

CObject Class

Hierarchy Chart

CDaoRecordset Class

CDaoDatabase Class

CDaoTableDef Class

CDaoException Class