Database Macros and Globals

 

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 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

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

AfxGetHENV

Retrieves a handle to the ODBC environment currently in use by MFC. You can use this handle in direct ODBC calls.

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"));
   }

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.

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);

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.

See Also

Macros and Globals