OLE DB Core Components

OLE DB

Universal Data Access for Microsoft® Windows® and Windows NT® Operating Systems

White Paper

Abstract

This White Paper describes three redistributable components that ship with the Microsoft® OLE DB SDK: the OLE DB Data Conversion Library (MSDADC.DLL), the OLE DB Root Enumerator Object (MSDAENUM.DLL), and the OLE DB Error Object (MSDAER.DLL). The IDataConvert and IRowPosition interfaces are also documented here.

© 1997 Microsoft Corporation. All rights reserved.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS OR IMPLIED, IN THIS DOCUMENT.

Microsoft, Visual Basic, Windows, and Windows NT are registered trademarks of Microsoft Corporation.

Other product or company names mentioned herein may be the trademarks of their respective owners.

Microsoft Corporation · One Microsoft Way · Redmond, WA 98052-6399 · USA

0997

Data Conversion Library

The Microsoft® OLE DB Data Conversion Library manages data type conversions for OLE DB consumers and providers. The OLE DB Data Conversion Library uses the IDataConvert interface to expose data conversion methods to consumers.

IDataConvert

IDataConvert provides methods for data conversion using the OLE DB Data Conversion Library (MSDADC.DLL). Consumers requiring data conversion services from the OLE DB Data Conversion Library should include the MSDADC.H header file in their project. IDataConvert includes the following methods.

IDataConvert::CanConvert

Returns information about whether the conversion from the specified source type to the specified destination type is supported.

HRESULT CanConvert (
DBTYPEwSrcType,
DBTYPEwDstType);

Parameters

wSrcType [in]
The source type of the conversion to be verified.

wDstType [in]
The destination type of the conversion to be verified.

Return Code

S_OK
The method succeeded and the conversion is supported.

S_FALSE
The requested conversion is not supported.

E_INVALIDARG
One or more of the DBTYPE values specified was invalid.

IDataConvert::DataConvert

Converts the data from the source type to the destination type.

HRESULT DataConvert (
DBTYPEwSrcType,
DBTYPEwDstType,
ULONGcbSrcLength,
ULONG *pcbDstLength,
void *pSrc,
void *pDst,
ULONGcbDstMaxLength,
DBSTATUSdbsSrcStatus,
DBSTATUS *pdbsStatus,
BYTEbPrecision,
BYTEbScale,
DBDATACONVERTdwFlags);

Parameters

wSrcType [in]
The source type of the data to be converted.

wDstType [in]
The destination type of the data to be converted.

cbSrcLength [in]
The length of the source data in bytes.

pcbDstLength [out]
A pointer to memory in which to return the length in bytes of the output data after conversion.

pSrc [in]
A pointer to the source data. Note that this is a pointer to the underlying data type, based upon the value of wSrcType. For example, this would be the address of the BSTR pointer if wSrcType is DBTYPE_BSTR, not the BSTR pointer itself.

pDst [out]
A pointer to memory in which to return the destination data. As in the case of pSrc, this is a pointer to the underlying data type, based upon the value of wDstType.

cbDstMaxLength [in]
The maximum allowable length of the destination data in bytes. This is only used for variable length destination data types.

dbsSrcStatus [in]
The status value for the source data.

pdbsStatus [out]
A pointer to the status for the conversion.

bPrecision [in]
The precision of the output data in bytes, if applicable. This argument is used when converting to DBTYPE_NUMERIC data only.

bScale [in]
The scale of the output data in bytes, if applicable. This argument is used when converting to DBTYPE_NUMERIC data only.

dwFlags [in]
The data conversion flag indicating the requested conversion behavior. These flags can be combined.

The following flags are available:

typedef DWORD DBDATACONVERT;
enum DBDATACONVERTENUM{
   DBDATACONVERT_DEFAULT         = 0,
   DBDATACONVERT_SETDATABEHAVIOR = 1,
   DBDATACONVERT_LENGTHFROMNTS= 2
};

The DBDATACONVERT_SETDATABEHAVIOR flag indicates that data truncation is an error and that the memory pointed to by pDst will not be changed if any error occurs.

The DBDATACONVERT_LENGTHFROMNTS flag indicates that the data conversion library should calculate cbSrcLength for string (DBTYPE_STR, DBTYPE_WSTR) source data.

Return Code

S_OK
The conversion succeeded.

E_FAIL
pSrc was a null pointer.

E_OUTOFMEMORY
The data conversion object was unable to allocate memory.

DB_E_BADBINDINFO
The source or destination data type was invalid.

DB_E_DATAOVERFLOW
The requested conversion resulted in an overflow.

DB_E_ERRORSOCCURRED
Errors occurred while converting data. The requested conversion can fail for a number of reasons, including:

• The source data was unavailable.
  
  
• Data truncation occurred.
  
  
• The precision and scale arguments did not make sense for the data type.
  
  
• There was an invalid character or second decimal point in the source data.

DB_E_UNSUPPORTEDCONVERSION
The requested conversion was not supported.

IDataConvert::
GetConversionSize

Calculates the size of the buffer needed by the destination data type to support a conversion.

HRESULT GetConversionSize (
DB\TYPEwSrcType,
DBTYPEwDstType,
ULONG *pcbSrcLength,
ULONG *pcbDstLength,
void *pSrc);

Parameters

wSrcType [in]
The source type of the data.

wDstType [in]
The destination type of the data.

pcbSrcLength [in]
A pointer to the length of the source data, in bytes. This value can be a null pointer.

pcbDstLength [out]
A pointer to memory in which to return the size of the destination buffer required for the conversion, in bytes.

pSrc [in]
A pointer to the source data.

Return Code

S_OK
The method succeeded.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
pcbDstLength was a null pointer or the information supplied by the consumer was insufficient to determine the appropriate buffer size.

1. pcbSrcLength was a null pointer and the conversion size was requested for a conversion from a variable-length data type to DBTYPE_STR, DBTYPE_WSTR, DBTYPE_BSTR, or DBTYPE_VARIANT.

DB_E_UNSUPPORTEDCONVERSION
The requested conversion was not supported.

Data Type Conversions Supported by MSDA]DC.DLL

The Data Conversion Library supports a limited set of conversions. The DBTYPE_BYREF modifier is only supported on the destination type for variable length data types (DBTYPE_BYTES, DBTYPE_STR, and DBTYPE_WSTR).

In the conversion tables, an X indicates that the conversion is supported by MSDADC.DLL. All data types can be converted to the same data type.

Note Supported data conversions can be determined through the IConvertType interface.

Conversions Supported from Data Type I1

Conversions Supported from Data Type I2

Conversions Supported from Data Type I4

Conversions Supported from Data Type I8

Conversions Supported from Data Type UI1

Conversions Supported from Data Type UI2

Conversions Supported from Data Type UI4

Conversions Supported from Data Type UI8

Conversions Supported from Data Type R4

Conversions Supported from Data Type R8

Conversions Supported from Data Type CY

Conversions Supported from Data Type DECIMAL

Conversions Supported from Data Type NUMERIC

Conversions Supported from Data Type DATE

Conversions Supported from Data Type DBDATE

Conversions Supported from Data Type DBTIME

Conversions Supported from Data Type DBTIMESTAMP

Conversions Supported from Data Type BOOL

Conversions Supported from Data Type BSTR

Conversions Supported from Data Type BYTES

Conversions Supported from Data Type Empty

Conversions Supported from Data Type ERROR

Conversions Supported from Data Type GUID

Conversions Supported from Data Type IDISPATCH

Conversions Supported from Data Type IUNKNOWN

Conversions Supported from Data Type NULL

Conversions Supported from Data Type STR

Conversions Supported from Data Type VARIANT

Conversions Supported from Data Type WSTR

Row Position Object

The OLE DB Row Position Object keeps track of a current hRow so that multiple components can coordinate on the concept of a current row. Consumers create a Row Position Object and set or retrieve the current row position using the IRowPosition interface.

IRowPosition

IRowPosition allows multiple components to share the concept of a current row over a rowset.

When to Implement

IRowPosition is not implemented by the provider. It is implemented by a common service provider component which works over any rowset.

When to Call

Components create a row position object in order to manage operations involving a current position within a rowset. Components call SetRowPosition in order to specify that the hRow be considered the current row, and GetRowPosition in order to retrieve the hRow specified as the current row. Changing the current row generates notifications for any listeners of the row position object, but makes no change to the position or state of the rowset itself.

IRowPosition:
ClearRowPosition

Clears the value of the current hRow.

HRESULT ClearRowPosition ();

Parameters

None.

Return Code

S_OK
The method succeeded. Calling GetRowPosition returns a phRow value of DB_NULL_ROW and a pdwPositionFlag value of DBPOSITION_NOROW.

E_FAIL
A provider-specific error occurred. The row position is unchanged.

DB_E_CANCELED
The operation was canceled by a client during notification. The row position is unchanged.

E_UNEXPECTED
ClearRowPosition was called twice in a row.

1. There is no current rowset.

Comments

ClearRowPosition fires the following notification phases with the reason DBREASON_ROWPOSITION_CLEARED:

• DBEVENTPHASE_OKTODO
  
  
• DBEVENTPHASE_ABOUTTODO
  
  
• DBEVENTPHASE_FAILEDTODO (if either of the above events are canceled)

Calling SetRowPosition fires the remaining phases.

ClearRowPosition must be called prior to the first and any subsequent SetRowPosition calls.

IRowPosition::
GetRowPosition

Returns the hRow of the current row position.

HRESULT GetRowPosition (
HCHAPTER *phChapter,
HROW *phRow
DBPOSITIONFLAGS *pdwPositionFlags);

Parameters

phChapter [out]
A pointer to memory in which to return the chapter associated with the current row. If the rowset is not chaptered, phChapter is set to DB_NULL_HCHAPTER. If phChapter is a null pointer on input, no chapter value is returned.

phRow [out]
A pointer to memory in which to return the hRow of the current row position, or DB_NULL_HROW if there is no current row position.

pdwPositionFlags [out]
A pointer to memory in which to return additional information about the row position. If pdwPositionFlags is a null pointer on input, no additional information is returned for the row position. pdwPositionFlags may indicate one of the following conditions:

1. Value	Meaning
   DBPOSITION_OK	hRow specifies the current row position.
   DBPOSITION_NOROW	hRow is DB_NULL_HROW, and the current row position is undefined.
   DBPOSITION_BOF	hRow is DB_NULL_HROW, and the row position is before the beginning of the rowset.
   DBPOSITION_EOF	hRow is DB_NULL_HROW, and the row position is off the end of the rowset.

Additional values for this flag may be defined in the future. Consumers should be prepared to handle other values for this flag by relying only on the value of phRow for undefined values of pdwPositionFlags.

Return Code

S_OK
The method succeeded.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
phRow was a null pointer.

E_UNEXPECTED
IRowPosition::Initialize has not been called; the row position object is in an uninitialized state.

1. There is no current rowset.

Comments

Before returning, the row position object calls AddRefRows to increment the hRow’s reference count and, if the chapter is non-null, AddRefChapter to increment the phChapter’s reference count.

Code Example

The following code fragment shows how a consumer might use IRowPosition when traversing a rowset.

// Code to generate a pRowset
…

IRowPosition * pRowPosition = NULL;
HRESULT hr;

hr = CoCreateInstance(CLSID_OLEDB_ROWPOSITIONOBJECT, NULL, CLSCTX_INPROC_SERVER,  IID_IRowPosition,
(LPVOID *)&pRowPosition)

if (SUCCEEDED(hr))
{
hr = pRowPosition->Initialize(pRowset);// init with pRowset

if (FAILED(hr))
      pRowPosition->Release();
}

return hr;

// Read the rows; 100 rows at a time into the rowset.
While(SUCCEEDED(hr = pRowset->GetNextRows(NULL, 0, 100, &cRowsObtained, &rghRows)) &&
      cRowsObtained) {
   for(irow = 0; irow < cRowsObtained; irow++) {
      // GetData copies the rows into the local buffers, performing the type
      // conversions specified in the binding structures associated with the accessor.
      pRowset->GetData(rghRows[irow], hAccessor, (void*) rgData);

     // Set currently read row as “current row”
     // Note: other clients will choose different notions of current row.
     If (pIRowPosition->ClearRowPosition () == S_OK)
pIRowPosition->SetRowPosition (NULL, rghRows[irow], DBPOSITION_OK);

     // Convenience function to print the data.
     PrintData(rgData);
   }

   // Release the rows just printed from the rowset.
   PRowset->ReleaseRows(cRowsObtained, rghRows, NULL, NULL, NULL);

}

IRowPosition::
GetRowset

Returns a pointer to the underlying rowset.

HRESULT GetRowset (
REFIID riid,
IUnknown **ppRowset);

Parameters

riid [in]
The requested IID for the rowset returned in *ppRowset.

ppRowset [out]
A pointer to memory in which to return the interface pointer of the underlying rowset.

Return Code

S_OK
The method succeeded.

E_INVALIDARG
ppRowset was a null pointer.

E_NOINTERFACE
riid referenced IID_NULL.

1. ppRowset did not support the interface specified in riid.

E_UNEXPECTED
There is no current rowset.

Comments

Before ppRowset is returned, it is AddReferenced by the row position object.

IRowPosition::
Initialize

Initializes the row position object by setting the source rowset.

HRESULT Initialize (
IUnknown * pRowset);

Parameters

pRowset [in]
Pointer to an interface on the source Rowset.

Return Code

S_OK
The method succeeded.

E_FAIL
A provider-specific error occurred.

E_INVALIDARG
pRowset was a null pointer.

E_NOINTERFACE
pRowset does not support the IRowset interface.

DB_E_ALREADYINITIALIZED
The row position object has already been initialized.

IRowPosition::
SetRowPosition

Sets the current row position to a new hRow.

HRESULT SetRowPosition (
HCHAPTERhChapter,
HROWhRow,
DBPOSITIONFLAGSdwPositionFlags);

Parameters

hChapter [in]
The chapter associated with the current row, or DB_NULL_HCHAPTER if the rowset is not chaptered.

hRow [in]
The new current row.

dwPositionFlags [in]
A flag indicating additional information about the new row position. One of the following:

Return Code

S_OK
The method succeeded.

E_FAIL
A provider-specific error occurred.

DB_E_BADCHAPTER
hChapter was invalid.

DB_E_BADROWHANDLE
hRow was invalid.

DB_E_CANCELED
The operation was canceled by a client during notification. The current row is set to DB_NULL_ROW with a position flag indicating DBPOSITION_NOROW.

E_UNEXPECTED
SetRowPosition was called without first calling ClearRowPosition.

1. There is no current rowset.

Comments

ClearRowPosition must be called prior to the first and any subsequent SetRowPosition calls.

SetRowPosition fires the following notification phases with either DBREASON_ROWPOSITION_CHANGED or DBREASON_ROWPOSITION_CHAPTERCHANGED:

• DBEVENTPHASE_SYNCHAFTER
  
  
• DBEVENTPHASE_DIDEVENT or DBEVENTPHASE_FAILEDTODO

The RowPostion object maintains a reference count on the both the hRow and the hChapter by respectively calling AddRefRows for the hRow and AddRefChapter for the hChapter when SetRowPosition is called.

IRowPositionChange

IRowPositionChange is the callback interface that a consumer must support in order to be notified when the current row position is changed.

The RowPostion object supports IConnectionPointContainer and the consumer calls FindConnectionPoint for IID_IRowPostionChange to obtain the correct IConnectionPoint interface. The consumer then advises that connection point to connect and supplies a pointer to the consumer’s IRowPositionChange interface.

For more information about notifications, see Chapter 9, “Notifications.”

When to Implement

IRowPositionChange is implemented by consumers that require notification about changes to the current row position.

When to Call

IRowPositionChange is called by the row position object when a consumer attempts to change the current row position.

1. Method	Description
   OnRowPositionChange	Notifies the consumer of a row position object of a change to the current row position.

IRowPositionChange::
OnRowPositionChange

Notifies the consumer of a row position object of a change to the current row position..

HRESULT OnRowPositionChange (
DBREASON eReason,
DBEVENTPHASEePhase,
BOOLfCantDeny);

Parameters

eReason [in]
The reason of the event that caused this change. If this value is not recognized by the method, the method returns S_OK or DB_S_UNWANTEDREASON.

ePhase [in]
The phase of this notification.

fCantDeny [in]
When this flag is set to TRUE, the consumer cannot veto the event by returning S_FALSE because the provider cannot undo the event.

Return Code

S_OK
The method succeeded.

S_FALSE
The event or phase is vetoed by reason of logical objection or a failure to be able to implement.

DB_S_UNWANTEDPHASE
The consumer is not interested in receiving this phase for this reason. The provider can optimize by making no further calls with this reason and phase. The phases for other reasons are unaffected.

DB_S_UNWANTEDREASON
The consumer is not interested in receiving any phases for this reason. The provider can optimize by making no further calls with this reason.

E_FAIL
A consumer-specific error occurred. The row position object continues the operation.

Comments

Possible reasons are DBREASON_ROWPOSITION_CLEARED, DBREASON_ROWPOSITION_CHANGED, and DBREASON_ROWPOSITION_CHAPTERCHANGED.

DBREASON_ROWPOSITION_CLEARED generates DBEVENTPHASE_OKTODO and DBEVENTPHASE_ABOUTTODO, and DBEVENTPHASE_FAILEDTODO if the notification is canceled.

DBREASON_ROWPOSITION_CHANGED and DBREASON_ROWPOSITIONCHAPTERCHANGED generate DBEVENTPHASE_SYNCHAFTER and DBEVENTPHASE_DIDEVENT, or DBEVENTPHASE_FAILEDTODO if the notification is canceled.

Consumers are required to handle reasons that not defined in this interface by returning S_OK or DB_S_UNWANTEDREASON.

Root Enumerator Object

The OLE DB Root Enumerator Object enumerates OLE DB providers and enumerators on your system. The root enumerator traverses the registry searching for providers and enumerators listed in the registry. It has a class ID of CLSID_OLEDB_ENUMERATOR. In the rowset returned by ISourcesRowset::GetSourcesRowset, the root enumerator returns values from the registry as follows:

For more information, see “Enumerating Data Sources and Enumerators” in Chapter 2 and “Registry Entries” in Chapter 14 of the OLE DB Programmer’s Reference.To meet its goal of providing data access to all types of data in a COM (Component Object Model) environment, Microsoft® OLE DB is designed as a component technology. In OLE DB, data sources expose the interfaces that reflect their functionality, and common components can be built on top of those interfaces to expose more robust data models. To define a component architecture, OLE DB identifies common characteristics between different data providers and services, and defines common interfaces to expose those characteristics. So, for example, while a rowset may be obtained through a number of very different mechanisms, the end result is still a rowset, with well-defined interfaces, methods and characteristics. With OLE DB, navigating the result of a complex multi-table join is no different than navigating the results of an opened text file containing tabular data. Defining common interfaces in this manner allows components to more efficiently augment the individual data provider's native functionality.

For More Information

For the latest information on OLE DB, check out our World Wide Web site at http://www.microsoft.com/oledb.