CDaoQueryDef Class

Article
01/08/2013

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:

In all cases, first construct a CDaoQueryDef object, supplying a pointer to the CDaoDatabase object to which the query belongs.
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