OpenConnection Method

See Also      Applies To

Opens a CdbConnection object on an ODBC data source (ODBCDirect workspaces only).

Syntax

CdbConnectionOpenConnection(LPCTSTR pstrName,

LONG lOptions = -1L,

BOOL bReadOnly = FALSE,

LPCTSTR pstrConnect = NULL);

Parameters

Type Argument Description
LPCTSTR pstrName A pointer to a string that contains the name of a registered ODBC data source (DSN). If it doesn't refer to a valid ODBC data source name, an error occurs.
LONG lOptions Optional. A Long value that specifies how the ODBC driver manager should prompt the user for connection information such as DSN, user name, and password. Possible values are described in Remarks.
BOOL bReadOnly Optional.

TRUEOpens a CdbConnection object for read-only access.

FALSE(Default) Opens a CdbConnection object for read/write access.

LPCTSTR pstrConnect Optional. A pointer to a string that contains the ODBC connect string. See the Connect property for the specific elements and syntax of this string. A prepended "ODBC;" is required. If pstrConnect is omitted (default), the UID and/or PWD will be taken from the UserName and Password properties of the CdbWorkspace.

Settings

The lOptions argument determines if and when to prompt the user to establish the connection, and whether or not to open the connection asynchronously. You can use one of the following constants.

Constant Description
dbDriverNoPrompt The ODBC Driver Manager uses the connection string provided in pstrName and pstrConnect. If you don't provide sufficient information, a run-time error occurs.
dbDriverPrompt The ODBC Driver Manager displays the ODBC Data Sources dialog box, which displays any relevant information supplied in pstrNname or pstrConnect. The connection string is made up of the DSN that the user selects via the dialog boxes, or, if the user doesn't specify a DSN, the default DSN is used.
dbDriverComplete Default. If the pstrConnect argument includes all the necessary information to complete a connection, the ODBC Driver Manager uses the string in pstrConnect. Otherwise it behaves as it does when you specify dbDriverPrompt.
dbDriverCompleteRequired This option behaves like dbDriverComplete except the ODBC driver disables the prompts for any information not required to complete the connection.
dbRunAsync Execute the method asynchronously. This constant may be used with any of the other lOptions constants.

Remarks

Use the OpenConnection method to establish a connection to an ODBC data source from an ODBCDirect workspace. The OpenConnection method is similar but not equivalent to OpenDatabase. The main difference is that OpenConnection is available only in an ODBCDirect workspace.

If you specify a registered ODBC data source name (DSN) in the connect argument, then the pstrName argument can be any valid string, and will also provide the Name property for the CdbConnection object. If a valid DSN is not included in the pstrConnect argument, then pstrName must refer to a valid ODBC DSN, which will also be the Name property. If neither name nor pstrConnect contains a valid DSN, the ODBC driver manager can be set (via the lOptions argument) to prompt the user for the required connection information. The DSN supplied through the prompt then provides the Name property.

OpenConnection returns a CdbConnection object which contains information about the connection. The CdbConnection object is similar to a CdbDatabase object. The principal difference is that a CdbDatabase object usually represents a database, although it can be used to represent a connection to an ODBC data source from a Microsoft Jet workspace.

Usage

#include <afxole.h>
#include <dbdao.h>
CdbDBEngine      dben(..., dbUseODBC);
CdbConnection   conn;
CdbRecordset      rstX;
conn = dben.OpenConnection(_T("ODBC;..."), dbDriverNoPrompt,
                           FALSE, T("DATABASE=SomeDB..."));
rstX = conn.OpenRecordset(...);