Share via

CDatabase::OpenEx

  • Article

virtual BOOL OpenEx( LPCTSTRlpszConnectString**, DWORDdwOptions= 0);**
throw( CDBException, CMemoryException );

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.

Parameters

lpszConnectString

Specifies an ODBC connect 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 connect 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.

Remarks

Call this member function to initialize a newly constructed CDatabase object. 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 connect 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 connect string you pass to OpenEx. Or you might want to save the connect string you pass so you can reuse it the next time your application calls OpenEx on a CDatabase object.

You can also use the connect 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 connect strings, see Chapter 5 in the ODBC SDK 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

// Embed a CDatabase object
// in your document class
CDatabase m_dbCust;

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

CDatabase Overview |  Class Members |  Hierarchy Chart

See Also   CDatabase::Open, CDatabase::CDatabase, CDatabase::Close, CDBException, CRecordset::Open