MDAC 2.5 SDK - OLE DB Programmer's Reference
Chapter 6: Getting and Setting Data

Length

The length of a data value is its size in bytes as it is stored in the consumer's data buffer. When the consumer gets data, length is the size of the data after it is converted from the provider type to the consumer type. When the consumer sets data, length is the size of the data before it is converted from the consumer type to the provider type.

The consumer specifies the buffer length with the cbMaxLen element of the DBBINDING structure. For information about how the provider uses the buffer length in conjunction with the data length, see cbMaxLen in "DBBINDING Structures," later in this chapter.

Length Values

The length value itself is a ULONG. The value stored in this ULONG depends on the data type as follows:

• Variable-length data types—The length of variable-length data types is the actual length of the untruncated data value in bytes. For string data, the length does not include the length of the null-termination character. If the length is bound, the string can include embedded null characters; that is, the length, rather than the null-termination character, is used in determining the end of the string. Consumers are encouraged not to use embedded null characters. Nevertheless, providers must support them. If the length is not bound, the string is assumed to be null-terminated.
  
  
• Fixed-length data types—When the consumer gets data, the returned length of a fixed-length data value is the size of its data type. When the consumer sets data, the provider ignores the length of fixed-length data types.
  
  
• DBTYPE_IUNKNOWN, DBTYPE_IDISPATCH—When setting data through ISequentialStream, the length is used to specify the total number of bytes that will be sent through ISequentialStream (which does not include space for a null because data returned through ISequentialStream is not null-terminated). When getting data through ISequentialStream, the length is either sizeof(IUnknown *) or the total number of bytes that will be returned through ISequentialStream. When binding to any other object as DBTYPE_IUNKNOWN or DBTYPE_IDISPATCH, the returned length is sizeof(IUnknown*), not the size of the object itself. If there is a way to determine the length of the object, it is through a method on the object itself. The provider ignores the length field when binding as DBTYPE_IUNKNOWN or DBTYPE_IDISPATCH to an object other than ISequentialStream.
  
  
• DBTYPE_BYREF—The length is the same as if DBTYPE_BYREF is not used; that is, it is the length of the data being pointed to. For example, if the type indicator is DBTYPE_STR | DBTYPE_BYREF, the length is the length of the string in bytes, not the length of the pointer.
  
  
• DBTYPE_VECTOR, DBTYPE_ARRAY—These types are considered fixed-length types. If the type indicator is joined in a logical OR with DBTYPE_ARRAY or DBTYPE_VECTOR, the returned length when getting or setting data is sizeof(SAFEARRAY*) and sizeof(DBVECTOR), respectively.