Edit

Share via

CDaoException Class

  • Article

Represents an exception condition arising from the MFC database classes based on data access objects (DAO).

Note

Data Access Object (DAO) is supported through Office 2013. DAO 3.6 is the final version, and is obsolete.

Syntax

class CDaoException : public CException

Members

Public Constructors

Name Description
CDaoException::CDaoException Constructs a CDaoException object.

Public Methods

Name Description
CDaoException::GetErrorCount Returns the number of errors in the database engine's Errors collection.
CDaoException::GetErrorInfo Returns error information about a particular error object in the Errors collection.

Public Data Members

Name Description
CDaoException::m_nAfxDaoError Contains an extended error code for any error in the MFC DAO classes.
CDaoException::m_pErrorInfo A pointer to a CDaoErrorInfo object that contains information about one DAO error object.
CDaoException::m_scode The SCODE value associated with the error.

Remarks

The class includes public data members you can use to determine the cause of the exception. CDaoException objects are constructed and thrown by member functions of the DAO database classes.

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. For information on exceptions thrown by the ODBC classes, see CDBException.

You can access exception objects within the scope of a CATCH expression. You can also throw CDaoException objects from your own code with the AfxThrowDaoException global function.

In MFC, all DAO errors are expressed as exceptions, of type CDaoException. When you catch an exception of this type, you can use CDaoException member functions to retrieve information from any DAO error objects stored in the database engine's Errors collection. As each error occurs, one or more error objects are placed in the Errors collection. (Normally the collection contains only one error object; if you're using an ODBC data source, you're more likely to get multiple error objects.) When another DAO operation generates an error, the Errors collection is cleared, and the new error object is placed in the Errors collection. DAO operations that do not generate an error have no effect on the Errors collection.

For DAO error codes, see the file DAOERR.H. For related information, see the topic "Trappable Data Access Errors" in DAO Help.

For more information about exception handling in general, or about CDaoException objects, see the articles Exception Handling (MFC) and Exceptions: Database Exceptions. The second article contains example code that illustrates exception handling in DAO.

Inheritance Hierarchy

CObject

CException

CDaoException

Requirements

Header: afxdao.h

CDaoException::CDaoException

Constructs a CDaoException object.

CDaoException();

Remarks

Ordinarily, the framework creates exception objects when its code throws an exception. You seldom need to construct an exception object explicitly. If you want to throw a CDaoException from your own code, call the global function AfxThrowDaoException.

However, you might want to explicitly create an exception object if you're making direct calls to DAO via the DAO interface pointers that MFC classes encapsulate. In that case, you might need to retrieve error information from DAO. Suppose an error occurs in DAO when you call a DAO method via the DAODatabases interface to a workspace's Databases collection.

To retrieve the DAO error information

  1. Construct a CDaoException object.

  2. Call the exception object's GetErrorCount member function to determine how many error objects are in the database engine's Errors collection. (Normally only one, unless you're using an ODBC data source.)

  3. Call the exception object's GetErrorInfo member function to retrieve one specific error object at a time, by index in the collection, via the exception object. Think of the exception object as a proxy for one DAO error object.

  4. Examine the current CDaoErrorInfo structure that GetErrorInfo returns in the m_pErrorInfo data member. Its members provide information on the DAO error.

  5. In the case of an ODBC data source, repeat steps 3 and 4 as needed, for more error objects.

  6. If you constructed the exception object on the heap, delete it with the delete operator when you finish.

For more information about handling errors in the MFC DAO classes, see the article Exceptions: Database Exceptions.

CDaoException::GetErrorCount

Call this member function to retrieve the number of DAO error objects in the database engine's Errors collection.

short GetErrorCount();

Return Value

The number of DAO error objects in the database engine's Errors collection.

Remarks

This information is useful for looping through the Errors collection to retrieve each of one or more DAO error objects in the collection. To retrieve an error object by index or by DAO error number, call the GetErrorInfo member function.

Note

Normally there is only one error object in the Errors collection. If you're working with an ODBC data source, however, there could be more than one.

CDaoException::GetErrorInfo

Returns error information about a particular error object in the Errors collection.

void GetErrorInfo(int nIndex);

Parameters

nIndex
The index of the error information in the database engine's Errors collection, for lookup by index.

Remarks

Call this member function to obtain the following kinds of information about the exception:

  • Error code

  • Source

  • Description

  • Help file

  • Help context

GetErrorInfo stores the information in the exception object's m_pErrorInfo data member. For a brief description of the information returned, see m_pErrorInfo. If you catch an exception of type CDaoException thrown by MFC, the m_pErrorInfo member will already be filled in. If you choose to call DAO directly, you must call the exception object's GetErrorInfo member function yourself to fill m_pErrorInfo. For a more detailed description, see the CDaoErrorInfo structure.

For information about DAO exceptions, and example code, see the article Exceptions: Database Exceptions.

CDaoException::m_nAfxDaoError

Contains an MFC extended error code.

Remarks

This code is supplied in cases where a specific component of the MFC DAO classes has erred.

Possible values are:

  • NO_AFX_DAO_ERROR The most recent operation didn't result in an MFC extended error. However, the operation could have produced other errors from DAO or OLE, so you should check m_pErrorInfo and possibly m_scode.

  • AFX_DAO_ERROR_ENGINE_INITIALIZATION MFC could not initialize the Microsoft Jet database engine. OLE might have failed to initialize, or it might have been impossible to create an instance of the DAO database engine object. These problems usually suggest a bad installation of either DAO or OLE.

  • AFX_DAO_ERROR_DFX_BIND An address used in a DAO record field exchange (DFX) function call doesn't exist or is invalid (the address wasn't used to bind data). You might have passed a bad address in a DFX call, or the address might have become invalid between DFX operations.

  • AFX_DAO_ERROR_OBJECT_NOT_OPEN You attempted to open a recordset based on a querydef or a tabledef object that wasn't in an open state.

CDaoException::m_pErrorInfo

Contains a pointer to a CDaoErrorInfo structure that provides information on the DAO error object that you last retrieved by calling GetErrorInfo.

Remarks

This object contains the following information:

CDaoErrorInfo member Information Meaning
m_lErrorCode Error Code The DAO error code
m_strSource Source The name of the object or application that originally generated the error
m_strDescription Description A descriptive string associated with the error
m_strHelpFile Help File A path to a Windows Help file in which the user can get information about the problem
m_lHelpContext Help Context The context ID for a topic in the DAO Help file

For full details about the information contained in the CDaoErrorInfo object, see the CDaoErrorInfo structure.

CDaoException::m_scode

Contains a value of type SCODE that describes the error.

Remarks

This is an OLE code. You'll seldom need to use this value because, in almost all cases, more specific MFC or DAO error information is available in the other CDaoException data members.

For information about SCODE, see the topic Structure of OLE Error Codes in the Windows SDK. The SCODE data type maps to the HRESULT data type.

See also

CException Class
Hierarchy Chart