Length

The length is the length of the data in bytes. It is useful only for variable-length data. For fixed-length data, the length is always the size of the data type. For example, the length of the ANSI string "Johnson" is 7, the length of the Unicode string "Lopez" is 10 (five two-byte characters), and the length of any value stored as a two-byte integer is 2.

The length gives the length of the data as it is stored by the consumer. That is, when getting data, it is the length of the data after it is converted from the provider type to the consumer type. When setting data, it is the length of the data before it is converted from the consumer type to the provider type.

Data Length and Buffer Length

It is important not to confuse the length of the data value with the length of the buffer in which the data value is stored. For example, in the following figure, the length of the buffer is 14 and the length of the data value stored in the buffer is 10.

An example of data length in relation to buffer length

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

Length Values

The length value itself is a ULONG data type. 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 supersedes the null-termination character in determining the end of the string. Embedding null characters is not encouraged. If the length is not bound, the string is assumed to be null terminated.
  
  
• Fixed-length data types—When getting data, the returned length of a fixed-length data type is the size of the data type. For DBTYPE_BSTR, this is sizeof(void *), not the length of the BSTR. When setting data, the provider ignores the length of fixed-length data types.
  
  
• DBTYPE_IUNKNOWN, DBTYPE_IDISPATCH—When setting or getting data through ISequentialStream, the length is used to specify the total number of bytes (which does not include space for a null since data returned through ISequentialStream is not null-terminated) that will be sent or 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 to an object other than ISequentialStream as DBTYPE_IUNKNOWN or DBTYPE_IDISPATCH.
  
  
• 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—When getting data, the returned length is zero. The reason is that there is only a single length, while a vector or array can contain multiple values. When setting data, the provider ignores the length.