CDataConnection class

  • Article

Manages the connection with the data source.

Syntax

class CDataConnection

Requirements

Header: atldbcli.h

Members

Methods

Name Description
CDataConnection::CDataConnection Constructor. Instantiates and initializes a CDataConnection object.
CDataConnection::Copy Creates a copy of an existing data connection.
CDataConnection::Open Opens a connection to a data source using an initialization string.
CDataConnection::OpenNewSession Opens a new session on the current connection.

Operators

Name Description
CDataConnection::operator BOOL Determines whether the current session is open or not.
CDataConnection::operator bool Determines whether the current session is open or not.
CDataConnection::operator CDataSource& Returns a reference to the contained CDataSource object.
CDataConnection::operator CDataSource* Returns a pointer to the contained CDataSource object.
CDataConnection::operator CSession& Returns a reference to the contained CSession object.
CDataConnection::operator CSession* Returns a pointer to the contained CSession object.

Remarks

CDataConnection is a useful class for creating clients because it encapsulates necessary objects (data source and session) and some of the work you need to do when connecting to a data source

Without CDataConnection, you have to create a CDataSource object, call its OpenFromInitializationString method, then create an instance of a CSession object, call its Open method, then create a CCommand object and call its Open* methods.

With CDataConnection, you only need to create a connection object, pass it an initialization string, then use that connection to open commands. If you plan on using your connection to the database repeatedly, it's a good idea to keep the connection open, and CDataConnection provides a convenient way to do that.

Note

If you are creating a database application that needs to handle multiple sessions, you will need to use OpenNewSession.

CDataConnection::CDataConnection

Instantiates and initializes a CDataConnection object.

Syntax

CDataConnection();
CDataConnection(const CDataConnection &ds);

Parameters

ds
[in] A reference to an existing data connection.

Remarks

The first override creates a new CDataConnection object with default settings.

The second override creates a new CDataConnection object with settings equivalent to the data connection object you specify.

CDataConnection::Copy

Creates a copy of an existing data connection.

Syntax

CDataConnection& Copy(const CDataConnection & ds) throw();

Parameters

ds
[in] A reference to an existing data connection to copy.

CDataConnection::Open

Opens a connection to a data source using an initialization string.

Syntax

HRESULT Open(LPCOLESTR szInitString) throw();

Parameters

szInitString
[in] The initialization string for the data source.

Return value

A standard HRESULT.

CDataConnection::OpenNewSession

Opens a new session using the current connection object's data source.

Syntax

HRESULT OpenNewSession(CSession & session) throw();

Parameters

session
[in/out] A reference to the new session object.

Remarks

The new session uses the current connection object's contained data source object as its parent, and can access all of the same information as the data source.

Return value

A standard HRESULT.

CDataConnection::operator BOOL

Determines whether the current session is open or not.

Syntax

operator BOOL() throw();

Remarks

Returns BOOL (MFC typedef) value. TRUE means the current session is open; FALSE means the current session is closed.

CDataConnection::operator bool (OLE DB)

Determines whether the current session is open or not.

Syntax

operator bool() throw();

Remarks

Returns a bool (C++ data type) value. true means the current session is open; false means the current session is closed.

CDataConnection::operator CDataSource&

Returns a reference to the contained CDataSource object.

Syntax

operator const CDataSource&() throw();

Remarks

This operator returns a reference to the contained CDataSource object, allowing you to pass a CDataConnection object where a CDataSource reference is expected.

Example

If you have a function (such as func below) that takes a CDataSource reference, you can use CDataSource& to pass a CDataConnection object instead.

void SourceFunc(const CDataSource& theSource)
{
   CComVariant var;
   theSource.GetProperty(DBPROPSET_DATASOURCEINFO, DBPROP_DATASOURCENAME, &var);
}

 

CDataConnection dc;
dc.Open(szInit);
SourceFunc(dc);

CDataConnection::operator CDataSource*

Returns a pointer to the contained CDataSource object.

Syntax

operator const CDataSource*() throw();

Remarks

This operator returns a pointer to the contained CDataSource object, allowing you to pass a CDataConnection object where a CDataSource pointer is expected.

See operator CDataSource& for a usage example.

CDataConnection::operator CSession&

Returns a reference to the contained CSession object.

Syntax

operator const CSession&();

Remarks

This operator returns a reference to the contained CSession object, allowing you to pass a CDataConnection object where a CSession reference is expected.

Example

If you have a function (such as func below) that takes a CSession reference, you can use CSession& to pass a CDataConnection object instead.

void SessionFunc(const CSession& theSession)
{
   XACTTRANSINFO info = {0};
   HRESULT hr = theSession.GetTransactionInfo(&info);
   wprintf_s(_T("GetTransactionInfo returned %x\n"), hr);
}

 

CDataConnection dc;
dc.Open(szInit);
SessionFunc(dc);

CDataConnection::operator CSession*

Returns a pointer to the contained CSession object.

Syntax

operator const CSession*() throw();

Remarks

This operator returns a pointer to the contained CSession object, allowing you to pass a CDataConnection object where a CSession pointer is expected.

Example

See operator CSession& for a usage example.

See also

OLE DB consumer templates
OLE DB consumer templates reference