Exception Processing

When a program executes, a number of abnormal conditions and errors called "exceptions" can occur. These may include running out of memory, resource allocation errors, and failure to find files.

The Microsoft Foundation Class Library uses an exception-handling scheme that is modeled closely after the one proposed by the ANSI standards committee for C++. An exception handler must be set up before calling a function that may encounter an abnormal situation. If the function encounters an abnormal condition, it throws an exception and control is passed to the exception handler.

Several macros included with the Microsoft Foundation Class Library will set up exception handlers. A number of other global functions help to throw specialized exceptions and terminate programs, if necessary. These macros and global functions fall into the following categories:

• Exception macros, which structure your exception handler.

• Exception-throwing functions), which generate exceptions of specific types.

• Termination functions, which cause program termination.

For examples and more details, see the article Exceptions.

Exception Macros

Name	Description
TRY	Designates a block of code for exception processing.
CATCH	Designates a block of code for catching an exception from the preceding TRY block.
CATCH_ALL	Designates a block of code for catching all exceptions from the preceding TRY block.
AND_CATCH	Designates a block of code for catching additional exception types from the preceding TRY block.
AND_CATCH_ALL	Designates a block of code for catching all other additional exception types thrown in a preceding TRY block.
END_CATCH	Ends the last CATCH or AND_CATCH code block.
END_CATCH_ALL	Ends the last CATCH_ALL code block.
THROW	Throws a specified exception.
THROW_LAST	Throws the currently handled exception to the next outer handler.

Exception-Throwing Functions

Name	Description
AfxThrowArchiveException	Throws an archive exception.
AfxThrowFileException	Throws a file exception.
AfxThrowInvalidArgException	Throws an invalid argument exception.
AfxThrowMemoryException	Throws a memory exception.
AfxThrowNotSupportedException	Throws a not-supported exception.
AfxThrowResourceException	Throws a Windows resource-not-found exception.
AfxThrowUserException	Throws an exception in a user-initiated program action.

MFC provides two exception-throwing functions specifically for OLE exceptions:

OLE Exception Functions

Name	Description
AfxThrowOleDispatchException	Throws an exception within an OLE automation function.
AfxThrowOleException	Throws an OLE exception.

To support database exceptions, the database classes provide two exception classes, CDBException and CDaoException, and global functions to support the exception types:

DAO Exception Functions

Name	Description
AfxThrowDAOException	Throws a CDaoException from your own code.
AfxThrowDBException	Throws a CDBException from your own code.

MFC provides the following termination function:

Termination Functions

Name	Description
AfxAbort	Called to terminate an application when a fatal error occurs.

TRY

Sets up a TRY block.

TRY

Remarks

A TRY block identifies a block of code that might throw exceptions. Those exceptions are handled in the following CATCH and AND_CATCH blocks. Recursion is allowed: exceptions may be passed to an outer TRY block, either by ignoring them or by using the THROW_LAST macro. End the TRY block with an END_CATCH or END_CATCH_ALL macro.

For more information, see the article Exceptions.

Example

See the example for CATCH.

Requirements

Header: afx.h

CATCH

Defines a block of code that catches the first exception type thrown in the preceding TRY block.

CATCH(exception_class, exception_object_pointer_name)

Parameters

exception_class
Specifies the exception type to test for. For a list of standard exception classes, see class CException.

exception_object_pointer_name
Specifies a name for an exception-object pointer that will be created by the macro. You can use the pointer name to access the exception object within the CATCH block. This variable is declared for you.

Remarks

The exception-processing code can interrogate the exception object, if appropriate, to get more information about the specific cause of the exception. Invoke the THROW_LAST macro to shift processing to the next outer exception frame. End the TRY block with an END_CATCH macro.

If exception_class is the class CException, then all exception types will be caught. You can use the CObject::IsKindOf member function to determine which specific exception was thrown. A better way to catch several kinds of exceptions is to use sequential AND_CATCH statements, each with a different exception type.

The exception object pointer is created by the macro. You do not need to declare it yourself.

Note

The CATCH block is defined as a C++ scope delineated by braces. If you declare variables in this scope, they are accessible only within that scope. This also applies to exception_object_pointer_name.

For more information on exceptions and the CATCH macro, see the article Exceptions.

Example

CFile* pFile = NULL;
// Constructing a CFile object with this override may throw
// a CFile exception and won't throw any other exceptions.
// Calling CString::Format() may throw a CMemoryException,
// so we have a catch block for such exceptions, too. Any
// other exception types this function throws will be
// routed to the calling function.
TRY
{
   pFile = new CFile(_T("C:\\WINDOWS\\SYSTEM.INI"),
      CFile::modeRead | CFile::shareDenyNone);
   ULONGLONG dwLength = pFile->GetLength();
   CString str;
   str.Format(_T("Your SYSTEM.INI file is %I64u bytes long.") , dwLength);
   AfxMessageBox(str);
}
CATCH(CFileException, pEx)
{
   // Simply show an error message to the user.
   pEx->ReportError();
}
AND_CATCH(CMemoryException, pEx)
{
   // We can't recover from this memory exception, so we'll
   // just terminate the app without any cleanup. Normally, 
   // an application should do everything it possibly can to
   // clean up properly and not call AfxAbort().
   AfxAbort();
}
END_CATCH
// If an exception occurs in the CFile constructor,
// the language will free the memory allocated by new
// and will not complete the assignment to pFile.
// Thus, our cleanup code needs to test for NULL.
if (pFile != NULL)
{
   pFile->Close();
   delete pFile;
}

CATCH_ALL

Defines a block of code that catches all exception types thrown in the preceding TRY block.

CATCH_ALL(exception_object_pointer_name)

Parameters

exception_object_pointer_name
Specifies a name for an exception-object pointer that will be created by the macro. You can use the pointer name to access the exception object within the CATCH_ALL block. This variable is declared for you.

Remarks

The exception-processing code can interrogate the exception object, if appropriate, to get more information about the specific cause of the exception. Invoke the THROW_LAST macro to shift processing to the next outer exception frame. If you use CATCH_ALL, end the TRY block with an END_CATCH_ALL macro.

Note

The CATCH_ALL block is defined as a C++ scope delineated by braces. If you declare variables in this scope, they are accessible only within that scope.

For more information on exceptions, see the article Exceptions.

Example

See the example for CFile::Abort.

Requirements

Header afx.h

AND_CATCH

Defines a block of code for catching additional exception types thrown in a preceding TRY block.

AND_CATCH(exception_class, exception_object_pointer_name)

Parameters

exception_class
Specifies the exception type to test for. For a list of standard exception classes, see class CException.

exception_object_pointer_name
A name for an exception-object pointer that will be created by the macro. You can use the pointer name to access the exception object within the AND_CATCH block. This variable is declared for you.

Remarks

Use the CATCH macro to catch one exception type, then the AND_CATCH macro to catch each subsequent type. End the TRY block with an END_CATCH macro.

The exception-processing code can interrogate the exception object, if appropriate, to get more information about the specific cause of the exception. Call the THROW_LAST macro within the AND_CATCH block to shift processing to the next outer exception frame. AND_CATCH marks the end of the preceding CATCH or AND_CATCH block.

Note

The AND_CATCH block is defined as a C++ scope (delineated by curly braces). If you declare variables in this scope, remember that they are accessible only within that scope. This also applies to the exception_object_pointer_name variable.

Example

See the example for CATCH.

Requirements

Header afx.h

AND_CATCH_ALL

Defines a block of code for catching additional exception types thrown in a preceding TRY block.

AND_CATCH_ALL(exception_object_pointer_name)

Parameters

exception_object_pointer_name
A name for an exception-object pointer that will be created by the macro. You can use the pointer name to access the exception object within the AND_CATCH_ALL block. This variable is declared for you.

Remarks

Use the CATCH macro to catch one exception type, then the AND_CATCH_ALL macro to catch all other subsequent types. If you use AND_CATCH_ALL, end the TRY block with an END_CATCH_ALL macro.

The exception-processing code can interrogate the exception object, if appropriate, to get more information about the specific cause of the exception. Call the THROW_LAST macro within the AND_CATCH_ALL block to shift processing to the next outer exception frame. AND_CATCH_ALL marks the end of the preceding CATCH or AND_CATCH_ALL block.

Note

The AND_CATCH_ALL block is defined as a C++ scope (delineated by braces). If you declare variables in this scope, remember that they are accessible only within that scope.

Requirements

Header afx.h

END_CATCH

Marks the end of the last CATCH or AND_CATCH block.

END_CATCH

Remarks

For more information on the END_CATCH macro, see the article Exceptions.

Requirements

Header afx.h

END_CATCH_ALL

Marks the end of the last CATCH_ALL88 or AND_CATCH_ALL block.

END_CATCH_ALL

Requirements

Header afx.h

THROW (MFC)

Throws the specified exception.

THROW(exception_object_pointer)

Parameters

exception_object_pointer
Points to an exception object derived from CException.

Remarks

THROW interrupts program execution, passing control to the associated CATCH block in your program. If you have not provided the CATCH block, then control is passed to a Microsoft Foundation Class Library module that prints an error message and exits.

For more information, see the article Exceptions.

Requirements

Header afx.h

THROW_LAST

Throws the exception back to the next outer CATCH block.

THROW_LAST()

Remarks

This macro allows you to throw a locally created exception. If you try to throw an exception that you have just caught, it will normally go out of scope and be deleted. With THROW_LAST, the exception is passed correctly to the next CATCH handler.

For more information, see the article Exceptions.

Example

See the example for CFile::Abort.

Requirements

Header afx.h

AfxThrowArchiveException

Throws an archive exception.

void  AfxThrowArchiveException(int cause, LPCTSTR lpszArchiveName);

Parameters

cause
Specifies an integer that indicates the reason for the exception. For a list of the possible values, see CArchiveException::m_cause.

lpszArchiveName
Points to a string containing the name of the CArchive object that caused the exception (if available).

Requirements

Header afx.h

AfxThrowFileException

Throws a file exception.

void AfxThrowFileException(
    int cause,
    LONG lOsError = -1,
    LPCTSTR lpszFileName = NULL);

Parameters

cause
Specifies an integer that indicates the reason for the exception. For a list of the possible values, see CFileException::m_cause.

lOsError
Contains the operating-system error number (if available) that states the reason for the exception. See your operating-system manual for a listing of error codes.

lpszFileName
Points to a string containing the name of the file that caused the exception (if available).

Remarks

You are responsible for determining the cause based on the operating-system error code.

Requirements

Header afx.h

AfxThrowInvalidArgException

Throws an invalid argument exception.

Syntax

void AfxThrowInvalidArgException( );

Remarks

This function is called when invalid arguments are used.

Requirements

Header: afx.h

AfxThrowMemoryException

Throws a memory exception.

void AfxThrowMemoryException();

Remarks

Call this function if calls to underlying system memory allocators (such as malloc and the GlobalAlloc Windows function) fail. You do not need to call it for new because new will throw a memory exception automatically if the memory allocation fails.

Requirements

Header afx.h

AfxThrowNotSupportedException

Throws an exception that is the result of a request for an unsupported feature.

void AfxThrowNotSupportedException();

Requirements

Header afx.h

AfxThrowResourceException

Throws a resource exception.

void  AfxThrowResourceException();

Remarks

This function is normally called when a Windows resource cannot be loaded.

Requirements

Header afx.h

AfxThrowUserException

Throws an exception to stop an end-user operation.

void AfxThrowUserException();

Remarks

This function is normally called immediately after AfxMessageBox has reported an error to the user.

Requirements

Header afx.h

AfxThrowOleDispatchException

Use this function to throw an exception within an OLE automation function.

void AFXAPI AfxThrowOleDispatchException(
    WORD wCode ,
    LPCSTR lpszDescription,
    UINT nHelpID = 0);

void AFXAPI AfxThrowOleDispatchException(
    WORD wCode,
    UINT nDescriptionID,
    UINT nHelpID = -1);

Parameters

wCode
An error code specific to your application.

lpszDescription
Verbal description of the error.

nDescriptionID
Resource ID for the verbal error description.

nHelpID
A help context for your application's help (.HLP) file.

Remarks

The information provided to this function can be displayed by the driving application (Microsoft Visual Basic or another OLE automation client application).

Example

// Sort is method of automation class CStrArrayDoc
long CStrArrayDoc::Sort(VARIANT* vArray)
{
   USES_CONVERSION;

   // Type check VARIANT parameter. It should contain a BSTR array
   // passed by reference. The array must be passed by reference; it is
   // an in-out-parameter.

   // throwing COleDispatchException allows the EXCEPINFO structure of 
   // IDispatch::Invoke() to set
   if (V_VT(vArray) != (VT_ARRAY | VT_BSTR))
      AfxThrowOleDispatchException(1001,
         _T("Type Mismatch in Parameter. Pass a string array by reference"));

   // ...
   // ...

   return 0;
}

Requirements

Header afx.h

AfxThrowOleException

Creates an object of type COleException and throws an exception.

void AFXAPI AfxThrowOleException(SCODE sc);
void AFXAPI AfxThrowOleException(HRESULT hr);

Parameters

sc
An OLE status code that indicates the reason for the exception.

hr
Handle to a result code that indicates the reason for the exception.

Remarks

The version that takes an HRESULT as an argument converts that result code into the corresponding SCODE. For more information on HRESULT and SCODE, see Structure of COM Error Codes in the Windows SDK.

Requirements

Header afxdao.h

AfxThrowDaoException

Call this function to throw an exception of type CDaoException from your own code.

void AFXAPI AfxThrowDaoException(
    int nAfxDaoError = NO_AFX_DAO_ERROR,
    SCODE scode = S_OK);

Parameters

nAfxDaoError
An integer value representing a DAO extended error code, which can be one of the values listed under CDaoException::m_nAfxDaoError.

scode
An OLE error code from DAO, of type SCODE. For information, see CDaoException::m_scode.

Remarks

The framework also calls AfxThrowDaoException. In your call, you can pass one of the parameters or both. For example, if you want to raise one of the errors defined in CDaoException::nAfxDaoError but you do not care about the scode parameter, pass a valid code in the nAfxDaoError parameter and accept the default value for scode.

For information about exceptions related to the MFC DAO classes, see class CDaoException in this book and the article Exceptions: Database Exceptions.

Requirements

Header afxdb.h

AfxThrowDBException

Call this function to throw an exception of type CDBException from your own code.

void AfxThrowDBException(
    RETCODE nRetCode,
    CDatabase* pdb,
    HSTMT hstmt);

Parameters

nRetCode
A value of type RETCODE, defining the type of error that caused the exception to be thrown.

pdb
A pointer to the CDatabase object that represents the data source connection with which the exception is associated.

hstmt
An ODBC HSTMT handle that specifies the statement handle with which the exception is associated.

Remarks

The framework calls AfxThrowDBException when it receives an ODBC RETCODE from a call to an ODBC API function and interprets the RETCODE as an exceptional condition rather than an expectable error. For example, a data access operation might fail because of a disk read error.

For information about the RETCODE values defined by ODBC, see Chapter 8, "Retrieving Status and Error Information," in the Windows SDK. For information about MFC extensions to these codes, see class CDBException.

Requirements

Header afx.h

AfxAbort

The default termination function supplied by MFC.

void  AfxAbort();

Remarks

AfxAbort is called internally by MFC member functions when there is a fatal error, such as an uncaught exception that cannot be handled. You can call AfxAbort in the rare case when you encounter a catastrophic error from which you cannot recover.

Example

See the example for CATCH.

Requirements

Header afx.h

See also

Macros and Globals
CException Class
CInvalidArgException Class