Database Macros and Globals
The macros and globals listed below apply to ODBC-based database applications. They are not used with DAO-based applications.
Before MFC 4.2, the macros AFX_SQL_ASYNC and AFX_SQL_SYNC gave asynchronous operations an opportunity to yield time to other processes. Beginning with MFC 4.2, the implementation of these macros changed because the MFC ODBC classes used only synchronous operations. The macro AFX_ODBC_CALL was new to MFC 4.2.
Database Macros
| Name | Description |
|---|---|
| AFX_ODBC_CALL | Calls an ODBC API function that returns SQL_STILL_EXECUTING. AFX_ODBC_CALL will repeatedly call the function until it no longer returns SQL_STILL_EXECUTING. |
| AFX_SQL_ASYNC | Calls AFX_ODBC_CALL. |
| AFX_SQL_SYNC | Calls an ODBC API function that does not return SQL_STILL_EXECUTING. |
Database Globals
| Name | Description |
|---|---|
| AfxDbInitModule | Adds database support for a regular MFC DLL that is dynamically linked to MFC. |
| AfxGetHENV | Retrieves a handle to the ODBC environment currently in use by MFC. You can use this handle in direct ODBC calls. |
AfxDbInitModule
For MFC database (or DAO) support from a regular MFC DLL that is dynamically linked to MFC, add a call to this function in your regular MFC DLL's CWinApp::InitInstance function to initialize the MFC database DLL.
Syntax
void AFXAPI AfxDbInitModule( );
Remarks
Make sure this call occurs before any base-class call or any added code which accesses the MFC database DLL. The MFC database DLL is an MFC extension DLL; in order for an MFC extension DLL to get wired into a CDynLinkLibrary chain, it must create a CDynLinkLibrary object in the context of every module that will be using it. AfxDbInitModule creates the CDynLinkLibrary object in your regular MFC DLL's context so that it gets wired into the CDynLinkLibrary object chain of the regular MFC DLL.
Requirements
Header: <afxdll_.h>
AFX_ODBC_CALL
Use this macro to call any ODBC API function that may return SQL_STILL_EXECUTING.
AFX_ODBC_CALL(SQLFunc)
Parameters
SQLFunc
An ODBC API function. For more information about ODBC API functions, see the Windows SDK.
Remarks
AFX_ODBC_CALL repeatedly calls the function until it no longer returns SQL_STILL_EXECUTING.
Before invoking AFX_ODBC_CALL, you must declare a variable, nRetCode, of type RETCODE.
Note that the MFC ODBC classes now use only synchronous processing. In order to perform an asynchronous operation, you must call the ODBC API function SQLSetConnectOption. For more information, see the topic "Executing Functions Asynchronously" in the Windows SDK.
Example
This example uses AFX_ODBC_CALL to call the SQLColumns ODBC API function, which returns a list of the columns in the table named by strTableName. Note the declaration of nRetCode and the use of recordset data members to pass parameters to the function. The example also illustrates checking the results of the call with Check, a member function of class CRecordset. The variable prs is a pointer to a CRecordset object, declared elsewhere.
RETCODE nRetCode;
AFX_ODBC_CALL(::SQLColumns(prs->m_hstmt, (SQLTCHAR*)NULL, SQL_NTS, (SQLTCHAR*)NULL,
SQL_NTS, (SQLTCHAR*)strTableName.GetBuffer(), SQL_NTS, (SQLTCHAR*)NULL, SQL_NTS));
if (!prs->Check(nRetCode))
{
AfxThrowDBException(nRetCode, prs->m_pDatabase, prs->m_hstmt);
TRACE(_T("SQLColumns failed\n"));
}
Requirements
Header: afxdb.h
AFX_SQL_ASYNC
The implementation of this macro changed in MFC 4.2.
AFX_SQL_ASYNC(prs, SQLFunc)
Parameters
prs
A pointer to a CRecordset object or a CDatabase object. Beginning with MFC 4.2, this parameter value is ignored.
SQLFunc
An ODBC API function. For more information about ODBC API functions, see the Windows SDK.
Remarks
AFX_SQL_ASYNC simply calls the macro AFX_ODBC_CALL and ignores the prs parameter. In versions of MFC prior to 4.2, AFX_SQL_ASYNC was used to call ODBC API functions that might return SQL_STILL_EXECUTING. If an ODBC API function did return SQL_STILL_EXECUTING, then AFX_SQL_ASYNC would call prs->OnWaitForDataSource.
Note
The MFC ODBC classes now use only synchronous processing. In order to perform an asynchronous operation, you must call the ODBC API function SQLSetConnectOption. For more information, see the topic "Executing Functions Asynchronously" in the Windows SDK.
Requirements
Header afxdb.h
AFX_SQL_SYNC
The AFX_SQL_SYNC macro simply calls the function SQLFunc.
AFX_SQL_SYNC(SQLFunc)
Parameters
SQLFunc
An ODBC API function. For more information about these functions, see the Windows SDK.
Remarks
Use this macro to call ODBC API functions that will not return SQL_STILL_EXECUTING.
Before calling AFX_SQL_SYNC, you must declare a variable, nRetCode, of type RETCODE. You can check the value of nRetCode after the macro call.
Note that the implementation of AFX_SQL_SYNC changed in MFC 4.2. Because checking the server status was no longer required, AFX_SQL_SYNC simply assigns a value to nRetCode. For example, instead of making the call
AFX_SQL_SYNC(::SQLGetInfo(m_dbCust.m_hdbc, SQL_ODBC_SQL_CONFORMANCE,
&nValue, sizeof(nValue), &cbValue));
you can simply make the assignment
nRetCode = ::SQLGetInfo(m_dbCust.m_hdbc, SQL_ODBC_SQL_CONFORMANCE,
&nValue, sizeof(nValue), &cbValue);
Requirements
Header afxdb.h
AfxGetHENV
You can use the returned handle in direct ODBC calls, but you must not close the handle or assume that the handle is still valid and available after any existing CDatabase- or CRecordset-derived objects have been destroyed.
HENV AFXAPI AfxGetHENV();
Return Value
The handle to the ODBC environment currently in use by MFC. Can be SQL_HENV_NULL if there are no CDatabase objects and no CRecordset objects in use.
Requirements
Header afxdb.h