DBBINDING Structures

  • Artículo

A binding associates a single column or parameter to the consumer's buffer and contains information about the buffer.

The DBBINDING structure describes a single binding:

typedef struct tagDBBINDING {
   DBORDINAL      iOrdinal;
   DBBYTEOFFSET   obValue;
   DBBYTEOFFSET   obLength;
   DBBYTEOFFSET   obStatus;
   ITypeInfo     *pTypeInfo;
   DBOBJECT      *pObject;
   DBBINDEXT     *pBindExt;
   DBPART         dwPart;
   DBMEMOWNER     dwMemOwner;
   DBPARAMIO      eParamIO;
   DBLENGTH       cbMaxLen;
   DWORD          dwFlags;
   DBTYPE         wType;
   BYTE           bPrecision;
   BYTE           bScale;
} DBBINDING;

Remarks

The elements of this structure are used as described in the following table.

Element

Description

iOrdinal

The ordinal of the column or parameter to which the binding applies.

Column ordinals are fixed for the lifetime of the rowset. The self bookmark column is column 0, and other columns have values greater than or equal to 1. Rowset column ordinals start at 1 and are numbered sequentially in increasing order (for example, 1, 2, 3, and so on). When a row object is derived from a rowset, the row-specific column ordinals must come after the rowset column ordinals.

To retrieve column ordinals, consumers call IColumnsInfo::GetColumnInfo, IColumnsRowset::GetColumnsRowset, or IColumnsInfo::MapColumnIDs. If the rowset is generated from a command, the column ordinals returned by GetColumnInfo or GetColumnsRowset on the rowset must match the column ordinals returned by the same methods on the command.

To retrieve parameter ordinals, consumers call ICommandWithParameters::GetParameterInfo on the command object.

obValue

The offset in bytes in the consumer's buffer to the value part. The value of obValue is ignored unless the DBPART_VALUE bit is set in dwPart. For more information about the value part, see Value.

This offset must be properly aligned for the processor architecture of the consumer's machine. If data is improperly aligned, consumers can expect alignment faults to occur when getting and setting data values. Consumers should use addresses that are multiples of the size of the data type. For example, if wType is DBTYPE_I4, the value part should be LONG aligned.

obLength

The offset in bytes in the consumer's buffer to the length part. The value of obLength is ignored unless the DBPART_LENGTH bit is set in dwPart. For more information about the length part, see Length.

The length itself is a DBLENGTH. This offset must be properly aligned for the processor architecture of the consumer's machine. That is, it should be a multiple of sizeof(DBLENGTH). If it is improperly aligned, consumers can expect alignment faults when getting and setting length values.

obStatus

The offset in bytes in the consumer's buffer to the status part. The value of obStatus is ignored unless the DBPART_STATUS bit is set in dwPart. For more information about the status part, see Status.

The status part itself is a DBSTATUS value, which is a DWORD. This offset must be properly aligned for the processor architecture of the consumer's machine. That is, it should be a multiple of sizeof(DWORD). If it is improperly aligned, consumers can expect alignment faults when getting and setting status values.

pTypeInfo

Reserved for future use. Consumers should set pTypeInfo to a null pointer.

pObject

Pointer to a DBOBJECT structure. For columns or parameters that can hold BLOBs or COM objects, this structure gives information needed to access the object:

typedef struct tagDBOBJECT {
   DWORD   dwFlags;
   IID     iid;
} DBOBJECT;

The elements of this structure are used as follows:

  • dwFlags ? The combined storage mode flags to use when creating an instance of the COM object.

  • iid ? The interface to be exposed on the COM object.

The storage mode flags apply only to IRowset::GetData; IRowsetChange::SetData ignores dwFlags.

The storage mode flags are defined by the Structured Storage model in COM. They are as follows:

STGM_READ

Requests a storage object from the provider that can be used only to read the current contents of the column.

STGM_WRITE

Requests a writable storage object from the provider that contains the current contents of the column. The consumer can use this storage object to modify or append to the current contents of the column.

STGM_READWRITE

Combination of STGM_READ and STGM_WRITE.

STGM_SHARE_DENY_NONE

Requests others subsequently opening the object not be denied read or write access.

STGM_SHARE_DENY_READ

Requests that others subsequently opening the object be denied read access.

STGM_SHARE_DENY_WRITE

Requests that others subsequently opening the object be denied write access.

STGM_SHARE_EXCLUSIVE

Combination of STGM_SHARE_DENY_READ and STGM_SHARE_DENY_WRITE.

STGM_DIRECT

Requests a direct (nontransacted) storage object over the column.

STGM_TRANSACTED

Requests a transacted storage object over the column.

STGM_CREATE

Requests a new storage object with which to write data to the column. The current contents of the column are replaced by the new storage object.

STGM_CONVERT

(Generally not used in OLE DB.)

STGM_FAILIFTHERE

Requests for a storage object should fail if the column already contains data.

STGM_PRIORITY

Opens the storage object with exclusive access to the most recently committed version. Other users cannot commit changes to the object while it is open in this mode. STGM_DIRECT and STGM_READ must be specified with this mode.

STGM_DELETEONRELEASE

(Generally not used in OLE DB.)

To open a new, empty stream over the contents of the column, specify the STGM_CREATE flag. When the new stream is opened, the seek pointer is positioned at the beginning of the stream.

NoteNote
If STGM_CREATE or STGM_WRITE is specified when opening a stream over a null column, the provider always returns an empty stream, as opposed to returning a null pointer or setting the DBSTATUS_S_ISNULL flag.

The value of pObject is ignored unless the DBPART_VALUE bit is set in dwPart and wType is DBTYPE_IUNKNOWN. If neither of these conditions is true, pObject should be set to a null pointer.

A null value of pObject implies that both of the following statements are true:

  • pObject->iid is IID_IUnknown

  • pObject->dwFlags is at least STGM_READ

NoteNote
Consumers should not set wType to DBTYPE_IUNKNOWN and the DBPART_VALUE bit in dwPart without specifying a non-null value for pObject. However, providers can assume in this case that the interface to be bound is IID_IUnknown. If wType is DBTYPE_IUNKNOWN, the DBPART_VALUE bit in dwPart is set, and pObject is NULL, providers may assume when setting data or inserting rows that the consumer buffer contains a pointer to an object that supports at least IUnknown. Providers can then call IUnknown::QueryInterface for any interfaces they are interested in. If the call to QueryInterface succeeds, the provider uses the returned interface pointers to set the data for this column. If the object does not support one of these interfaces, the provider should return DBSTATUS_E_CANTCREATE.

pBindExt

The DBBINDEXT structure can be used for future extensions to the binding structure. The pBindExt value is reserved for future use, and consumers should set it to a null pointer:

typedef struct tagDBBINDEXT{
   BYTE         *pExtension;
   DBCOUNTITEM   ulExtension;
} DBBINDEXT;

dwPart

Specifies which buffer parts are to be bound to the column or parameter. It is one or more DBPARTENUM values combined. These values have the following meaning:

  • DBPART_VALUE ? The binding includes a value part.

  • DBPART_LENGTH ? The binding includes a length part.

  • DBPART_STATUS ? The binding includes a status part.

dwMemOwner

For bindings in row accessors, specifies memory allocated by the provider for a column and for which a pointer is returned to the consumer. For example, when wType is DBTYPE_BYREF | DBTYPE_STR, the provider allocates memory for the string and returns a pointer to the string to the consumer. The dwMemOwner value specifies whether the consumer or provider is responsible for freeing this memory. The provider ignores this when the consumer sets rowset data.

The following is a description of each of these values:

  • DBMEMOWNER_CLIENTOWNED ? The consumer owns the memory and is responsible for freeing it.

  • DBMEMOWNER_PROVIDEROWNED ? The provider owns the memory and is responsible for freeing it. When getting data, the provider returns a pointer into its copy of the row. When using provider-owned memory, the consumer's type must exactly match the provider's type, except that if wType is X | DBTYPE_BYREF, the provider's type can be X or X | DBTYPE_BYREF. If a column is NULL, the provider returns a null pointer for the data value.

    The consumer must not write to or free the memory to which the pointer points. The lifetime of the pointer is provider-specific. However, pointers to row data are guaranteed to be valid until IRowset::ReleaseRows is called for the row and its reference count falls to zero, the rowset is freed, or a method is called for the row that might invalidate the pointer. The methods that might invalidate the pointer depend on the method that returned it, as follows:

Pointer returned byMight be invalidated by
GetDataDeleteRows [1] RefreshVisibleDataSetDataUpdateUndo
GetLastVisibleDataGetLastVisibleData
GetOriginalDataRefreshVisibleDataSetDataUpdate

Although the consumer must not write to provider-owned memory, it can pass pointers to provider-owned memory when setting data. For example, suppose that the consumer wants to copy data efficiently from row A to row B. The consumer creates an accessor to the columns in row A in which wType is X | DBTYPE_BYREF and sets dwMemOwner to DBMEMOWNER_PROVIDEROWNED. When the consumer calls IRowset::GetData, the provider returns pointers to its copy of row A. The consumer then calls IRowsetChange::SetData for row B with the same accessor and a pointer to the memory passed to IRowset::GetData. The provider dereferences the pointers and copies the data from the rowset's copy of row A to the rowset's copy of row B.

For bindings in row accessors, consumer-owned memory must be used unless wType is DBTYPE_BSTR, X | DBTYPE_BYREF, X | DBTYPE_ARRAY, or X | DBTYPE_VECTOR, in which cases either consumer-owned or provider-owned memory can be used. However, the provider might not support using provider-owned memory to retrieve columns for which IColumnsInfo::GetColumnInfo returns DBCOLUMNFLAGS_ISLONG for the column. Consumers can mix bindings for provider-owned and consumer-owned memory in the same accessor.

For bindings in parameter accessors, consumer-owned memory must always be used.

The value of dwMemOwner is ignored in reference accessors.

All providers must support binding to client-owned memory. Providers support provider-owned memory only if they can efficiently return a pointer to a cached value. Providers are not required to support binding deferred columns to provider-owned memory.

eParamIO

For parameter accessors, eParamIO specifies whether the parameter with which the binding is associated is an input, input/output, or output parameter. Providers support only those parameter I/O types that are supported by their underlying data store. The value of eParamIO is one or more DBPARAMIOENUM values combined. These values have the following meaning:

  • DBPARAMIO_NOTPARAM ? The accessor is not used for parameters. In most cases, eParamIO is set to this value in row accessors to remind the programmer that it is ignored.

  • DBPARAMIO_INPUT ? The parameter is an input parameter.

  • DBPARAMIO_OUTPUT ? The parameter is an output parameter.

  • DBPARAMIO_INPUT | DBPARAMIO_OUTPUT ? The parameter is both an input and an output parameter.

For row accessors, the value of eParamIO is ignored.

cbMaxLen

The length in bytes of the consumer's data structure allocated for the data value. That is, it is the number of bytes allocated at offset obValue for the data value. The value of cbMaxLen is ignored unless the DBPART_VALUE bit is set in dwPart and the data value stored at that location is variable-length. For information about variable-length data types, see Fixed-Length and Variable-Length Data Types.

The value of cbMaxLen is used as follows:

  • Variable-length data types ? The provider checks the length in bytes of variable-length data types against cbMaxLen. If the length is greater than cbMaxLen, the provider truncates the data to cbMaxLen bytes.

    When getting string data, this is a warning and the provider sets the status to DBSTATUS_S_TRUNCATED and sets the length to the actual number of bytes of data available after conversion and before truncation. Thus, the consumer can determine the actual number of bytes of data available.

    When setting data, this is an error and the provider sets the status to DBSTATUS_E_CANTCONVERTVALUE. In most cases, this is a consumer programming error.

  • Fixed-length data types ? The provider ignores cbMaxLen for fixed-length data types and assumes that the number of bytes available in the consumer's buffer for the data is the size of the data type.

  • DBTYPE_BYREF, DBTYPE_VECTOR, DBTYPE_ARRAY ? The provider ignores cbMaxLen and assumes that the number of bytes available in the consumer's buffer is the size dictated by DBTYPE_BYREF, DBTYPE_VECTOR, or DBTYPE_ARRAY. For DBTYPE_BYREF and DBTYPE_ARRAY, this is sizeof(void *). For DBTYPE_VECTOR, this is sizeof(DBVECTOR).

    Important noteImportant
    If DBTYPE_BYREF is combined with the type indicator for a variable-length data type, the data is not truncated to cbMaxLen bytes. This is because the data is in separately allocated memory, not the consumer's buffer, and cbMaxLen does not apply to this memory. The provider allocates this memory based on the length of the data, as bound at the offset obLength, so consumers can guarantee that variable-length data is not truncated if it is retrieved in this manner.

dwFlags

The consumer can set dwFlags to specify information about how returned data is to be formatted. The following flags are recognized:

DBBINDFLAG_HTML

The provider should format the returned data in HTML. If the provider does not support HTML formatting, the bit is ignored and regular text is returned.

DBBINDFLAG_OBJECT

The provider should format the returned data as a COM object.

NoteNote
These two dwFlags values cannot be combined.

wType

The indicator of the data type of the value part of the buffer. For more information about type indicators, see Type Indicators in Appendix A: Data Types.

This type forms an implied conversion between the buffer type and the type of the column or parameter. For information about conversions that providers are required to support, see Data Type Conversion.

bPrecision

The maximum precision to use when getting data and wType is DBTYPE_NUMERIC or DBTYPE_VARNUMERIC. This is ignored in three cases: when setting data; when wType is not DBTYPE_NUMERIC or DBTYPE_VARNUMERIC; and when the DBPART_VALUE bit is not set in dwPart. For more information, see Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in Appendix A: Data Types.

bScale

The scale to use when getting data and wType is DBTYPE_NUMERIC, DBTYPE_VARNUMERIC, or DBTYPE_DECIMAL. This is ignored in three cases: when setting data; when wType is not DBTYPE_NUMERIC, DBTYPE_VARNUMERIC, or DBTYPE_DECIMAL; and when the DBPART_VALUE bit is not set in dwPart. For more information, see Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL in Appendix A: Data Types.

[1] Immediate update mode.

Note

The offsets specified in obValue, obLength, and obStatus must not point to overlapping areas of memory. The provider is not required to check for the occurrence of this condition. Consumers must be careful to avoid this condition when constructing bindings.

Note

The memory of a dbBindings structure should be initialized prior to setting any values. Use the syntax memset(rgBindings, 0, cColumns * sizeof(DBBINDING));, to perform this action. The syntax usage is shown in the example Binding and Accessor Example

This topic is a part of: