DBBINDING Structures

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.

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.

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

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.

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 are defined by the Structured Storage model in COM. These are as follows:

• STGM_READ = OF_READ
  
  
• STGM_WRITE = OF_WRITE
  
  
• STGM_READWRITE = OF_READWRITE
  
  
• STGM_SHARE_DENY_NONE = OF_SHARE_DENY_NONE
  
  
• STGM_SHARE_DENY_READ = OF_SHARE_DENY_READ
  
  
• STGM_SHARE_DENY_WRITE = OF_SHARE_DENY_WRITE
  
  
• STGM_SHARE_EXCLUSIVE = OF_SHARE_EXCLUSIVE
  
  
• STGM_DIRECT
  
  
• STGM_TRANSACTED
  
  
• STGM_CREATE = OF_CREATE
  
  
• STGM_CONVERT
  
  
• STGM_FAILIFTHERE
  
  
• STGM_PRIORITY
  
  
• STGM_DELETEONRELEASE

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.

Note   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

Note   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.

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

• DBPART_VALUE—The binding includes a value part.
  
  
• DBPART_LENGTH—The binding includes a length part.
  
  
• DBPART_STATUS—The binding includes a status part.

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 by         Might be invalidated by

  GetData                               DeleteRows^[1]
                                                RefreshVisibleData
                                                SetData
                                                Update
                                                Undo

  GetLastVisibleData            GetLastVisibleData

  GetOriginalData                  RefreshVisibleData
                                                SetData
                                                Update

  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.

• 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.

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    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.

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.

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" in Chapter 13, "Data Types in OLE DB."