CDatabase::OpenEx

CDatabase::OpenEx

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

MFC Library Reference

CDatabase::OpenEx

Call this member function to initialize a newly constructed CDatabase object.

virtual BOOL OpenEx( 
   LPCTSTR lpszConnectString, 
   DWORD dwOptions = 0  
);

Parameters

lpszConnectString

Specifies an ODBC connection string. This includes the data source name as well as other optional information, such as a user ID and password. For example, "DSN=SQLServer_Source;UID=SA;PWD=abc123" is a possible connection string. Note that if you pass NULL for lpszConnectString, a Data Source dialog box will prompt the user to select a data source.

dwOptions

A bitmask which specifies a combination of the following values. The default value is 0, meaning that the database will be opened as shared with write access, the ODBC Cursor Library DLL will not be loaded, and the ODBC connection dialog box will display only if there is not enough information to make the connection.

CDatabase::openExclusive Not supported in this version of the class library. A data source is always opened as shared (not exclusive). Currently, an assertion fails if you specify this option.
CDatabase::openReadOnly Open the data source as read-only.
CDatabase::useCursorLib Load the ODBC Cursor Library DLL. The cursor library masks some functionality of the underlying ODBC driver, effectively preventing the use of dynasets (if the driver supports them). The only cursors supported if the cursor library is loaded are static snapshots and forward-only cursors. If you plan to create a recordset object directly from CRecordset without deriving from it, you should not load the cursor library.
CDatabase::noOdbcDialog Do not display the ODBC connection dialog box, regardless of whether enough connection information is supplied.
CDatabase::forceOdbcDialog Always display the ODBC connection dialog box.

Return Value

Nonzero if the connection is successfully made; otherwise 0 if the user chooses Cancel when presented a dialog box asking for more connection information. In all other cases, the framework throws an exception.

Remarks

Your database object must be initialized before you can use it to construct a recordset object.

If the lpszConnectString parameter in your OpenEx call does not contain enough information to make the connection, the ODBC driver opens a dialog box to obtain the necessary information from the user, provided you have not set CDatabase::noOdbcDialog or CDatabase::forceOdbcDialog in the dwOptions parameter. When you call OpenEx, your connection string, lpszConnectString, is stored privately in the CDatabase object and is available by calling the GetConnect member function.

If you wish, you can open your own dialog box before you call OpenEx to get information from the user, such as a password, and then add that information to the connection string you pass to OpenEx. Or you might want to save the connection string you pass so you can reuse it the next time your application calls OpenEx on a CDatabase object.

You can also use the connection string for multiple levels of login authorization (each for a different CDatabase object) or to convey other data source-specific information. For more information about connection strings, see Chapter 6 in the ODBC Programmer's Reference.

It is possible for a connection attempt to time out if, for example, the DBMS host is unavailable. If the connection attempt fails, OpenEx throws a CDBException.

Example

Visual C++

// m_dbCust is a CDatabase object embedded in a CDocument class.

// Connect the object to a read-only data source where
// the ODBC connection dialog box will always remain hidden
m_dbCust.OpenEx(_T("DSN=MFC_ODBCTest;UID=JOES"),
   CDatabase::openReadOnly | CDatabase::noOdbcDialog);

Requirements

Header: afxdb.h

Reference

Other Resources

CDatabase Members