CDataSource Class

  • Article

Corresponds to an OLE DB data source object, which represents a connection through a provider to a data source.

Syntax

class CDataSource

Requirements

Header: atldbcli.h

Members

Methods

Name Description
Close Closes the connection.
GetInitializationString Retrieves the initialization string of the data source that is currently open.
GetProperties Gets the values of properties currently set for the connected data source.
GetProperty Gets the value of a single property currently set for the connected data source.
Open Creates a connection to a provider (data source) using either a CLSID, ProgID, or a CEnumerator moniker provided by the caller.
OpenFromFileName Opens a data source from a file specified by the user-supplied file name.
OpenFromInitializationString Opens the data source specified by an initialization string.
OpenWithPromptFileName Allows the user to select a previously created data link file to open the corresponding data source.
OpenWithServiceComponents Opens a data source object using the Data Link dialog box.

Remarks

One or more database sessions can be created for a single connection. These sessions are represented by CSession. You must call CDataSource::Open to open the connection before creating a session with CSession::Open.

For an example of how to use CDataSource, see the CatDB sample.

CDataSource::Close

Closes the connection by releasing the m_spInit pointer.

Syntax

void Close() throw();

CDataSource::GetInitializationString

Retrieves the initialization string of a data source that is currently open.

Syntax

HRESULT GetInitializationString(BSTR* pInitializationString,
   bool bIncludePassword = false) throw();

Parameters

pInitializationString
[out] A pointer to the initialization string.

bIncludePassword
[in] true if string includes a password; otherwise false.

Return Value

A standard HRESULT.

Remarks

The resulting initialization string can be used to later reopen this data source connection.

CDataSource::GetProperties

Returns the property information requested for the connected data source object.

Syntax

HRESULT GetProperties(ULONG ulPropIDSets,
   constDBPROPIDSET* pPropIDSet,
   ULONG* pulPropertySets,
   DBPROPSET** ppPropsets) const throw();

Parameters

See IDBProperties::GetProperties in the OLE DB Programmer's Reference in the Windows SDK.

Return Value

A standard HRESULT.

Remarks

To get a single property, use GetProperty.

CDataSource::GetProperty

Returns the value of a specified property for the connected data source object.

Syntax

HRESULT GetProperty(const GUID& guid,
   DBPROPID propid,
   VARIANT* pVariant) const throw();

Parameters

guid
[in] A GUID identifying the property set for which to return the property.

propid
[in] Property ID for the property to return.

pVariant
[out] A pointer to the variant where GetProperty returns the value of the property.

Return Value

A standard HRESULT.

Remarks

To get multiple properties, use GetProperties.

CDataSource::Open

Opens a connection to a data source using a CLSID, ProgID, or CEnumerator moniker or prompts the user with a locator dialog box.

Syntax

HRESULT Open(const CLSID& clsid,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(const CLSID& clsid,
   LPCTSTR pName,
   LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();HRESULT Open(LPCTSTR szProgID,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();HRESULT Open(LPCTSTR szProgID,
   LPCTSTR pName,  LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

HRESULT Open(const CEnumerator& enumerator,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(const CEnumerator& enumerator,
   LPCTSTR pName,
   LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

HRESULT Open(HWND hWnd = GetActiveWindow(),
   DBPROMPTOPTIONS dwPromptOptions = DBPROMPTOPTIONS_WIZARDSHEET) throw();

HRESULT Open(LPCWSTR szProgID,
   DBPROPSET* pPropSet = NULL,
   ULONG nPropertySets = 1) throw();

HRESULT Open(LPCSTR szProgID,
   LPCTSTR pName,LPCTSTR pUserName = NULL,
   LPCTSTR pPassword = NULL,
   long nInitMode = 0) throw();

Parameters

clsid
[in] The CLSID of the data provider.

pPropSet
[in] A pointer to an array of DBPROPSET structures containing properties and values to be set. See Property Sets and Property Groups in the OLE DB Programmer's Reference in the Windows SDK.

nPropertySets
[in] The number of DBPROPSET structures passed in the pPropSet argument.

pName
[in] The name of the database to which to connect.

pUserName
[in] The name of the user.

pPassword
[in] The user's password.

nInitMode
[in] Database initialization mode. See Initialization Propertiesin the OLE DB Programmer's Reference in the Windows SDK for a list of valid initialization modes. If nInitMode is zero, no initialization mode is included in the property set used to open the connection.

szProgID
[in] A program identifier.

enumerator
[in] A CEnumerator object used to obtain a moniker for opening the connection when the caller does not specify a CLSID.

hWnd
[in] Handle to the window that is to be the parent of the dialog box. Using the function overload that uses the hWnd parameter will automatically invoke Service Components; see Remarks for details.

dwPromptOptions
[in] Determines the style of locator dialog box to display. See Msdasc.h for possible values.

Return Value

A standard HRESULT.

Remarks

The method overload that uses the hWnd parameter opens a data source object with the service components in oledb32.dll; this DLL contains the implementation of Service Components features such as Resource Pooling, Automatic Transaction Enlistment, and so on. For more information, see the OLE DB reference in the OLE DB Programmer's Guide.

The method overloads that do not use the hWnd parameter open a data source object without using the service components in oledb32.dll. A CDataSource object opened with these function overloads will be unable to utilize any of the functionality of Service Components.

Example

The following code shows how to open a Jet 4.0 data source with OLE DB Templates. You treat the Jet data source as an OLE DB data source. However, your call to Open needs two property sets: one for DBPROPSET_DBINIT and the other for DBPROPSET_JETOLEDB_DBINIT, so that you can set DBPROP_JETOLEDB_DATABASEPASSWORD.

CDBPropSet rgDBPropSet[2];  // Declare two property sets;
                            // set properties elsewhere as appropriate.

hr = m_DataSource.Open(szProgId, rgDBPropSet, 2);

CDataSource::OpenFromFileName

Opens a data source from a file specified by the user-supplied file name.

Syntax

HRESULT OpenFromFileName(LPCOLESTR szFileName) throw();

Parameters

szFileName
[in] The name of a file, usually a data source connection (.UDL) file.

For more information about data link files (.udl files), see Data Link API Overview in the Windows SDK.

Return Value

A standard HRESULT.

Remarks

This method opens a data source object using the service components in oledb32.dll; this DLL contains the implementation of Service Components features such as Resource Pooling, Automatic Transaction Enlistment, and so on. For more information, see the OLE DB reference in the OLE DB Programmer's Guide.

CDataSource::OpenFromInitializationString

Opens a data source specified by the user-supplied initialization string.

Syntax

HRESULT OpenFromInitializationString(LPCOLESTR szInitializationString,
   bool fPromptForInfo= false) throw();

Parameters

szInitializationString
[in] The initialization string.

fPromptForInfo
[in] If this argument is set to true, then OpenFromInitializationString will set the DBPROP_INIT_PROMPT property to DBPROMPT_COMPLETEREQUIRED, which specifies that the user be prompted only if more information is needed. This is useful for situations in which the initialization string specifies a database that requires a password, but the string does not contain the password. The user will be prompted for a password (or any other missing information) when trying to connect to the database.

The default value is false, which specifies that the user never be prompted (sets DBPROP_INIT_PROMPT to DBPROMPT_NOPROMPT).

Return Value

A standard HRESULT.

Remarks

This method opens a data source object using the service components in oledb32.dll; this DLL contains the implementation of Service Components features such as Resource Pooling, Automatic Transaction Enlistment, and so on.

CDataSource::OpenWithPromptFileName

This method prompts the user with a dialog box, then opens a data source using the file specified by the user.

Syntax

HRESULT OpenWithPromptFileName(HWND hWnd = GetActiveWindow(   ),
   DBPROMPTOPTIONS dwPromptOptions = DBPROMPTOPTIONS_NONE,
   LPCOLESTR szInitialDirectory = NULL) throw();

Parameters

hWnd
[in] Handle to the window that is to be the parent of the dialog box.

dwPromptOptions
[in] Determines the style of locator dialog box to display. See Msdasc.h for possible values.

szInitialDirectory
[in] The initial directory to display in the locator dialog box.

Return Value

A standard HRESULT.

Remarks

This method opens a data source object using the service components in oledb32.dll; this DLL contains the implementation of Service Components features such as Resource Pooling, Automatic Transaction Enlistment, and so on. For more information, see the OLE DB reference in the OLE DB Programmer's Guide.

CDataSource::OpenWithServiceComponents

Opens a data source object using the service components in oledb32.dll.

Syntax

HRESULT OpenWithServiceComponents (const CLSID clsid,
   DBPROPSET* pPropset = NULL,
   ULONG ulPropSets = 1);

HRESULT OpenWithServiceComponents (LPCSTR szProgID,
   DBPROPSET* pPropset = NULL,
   ULONG ulPropSets = 1);

Parameters

clsid
[in] The CLSID of a data provider.

szProgID
[in] Program ID of a data provider.

pPropset
[in] A pointer to an array of DBPROPSET structures containing properties and values to be set. See Property Sets and Property Groups in the OLE DB Programmer's Reference in the Windows SDK. If the data source object is initialized, the properties must belong to the Data Source property group. If the same property is specified more than once in pPropset, then which value is used is provider-specific. If ulPropSets is zero, this parameter is ignored.

ulPropSets
[in] The number of DBPROPSET structures passed in the pPropSet argument. If this is zero, the provider ignores pPropset.

Return Value

A standard HRESULT.

Remarks

This method opens a data source object using the service components in oledb32.dll; this DLL contains the implementation of Service Components features such as Resource Pooling, Automatic Transaction Enlistment, and so on. For more information, see the OLE DB reference in the OLE DB Programmer's Guide.

See also

OLE DB Consumer Templates
OLE DB Consumer Templates Reference