CDaoException Class

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at CDaoException Class.

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

Syntax

class CDaoException : public CException  

Members

Public Constructors

Public Methods

Public Data Members

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.

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 are using an ODBC data source, you are 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 are 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 are 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 the 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.

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 did not 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 does not exist or is invalid (the address was not 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 was not 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:

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 will 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
CException Class