Type Indicators

DBTYPE_EMPTY

No value was specified. This indicator is valid only in a VARIANT structure and exists only to match the VT_EMPTY value in the VARENUM enumerated type in OLE. It does not correspond to any C data type.

DBTYPE_I2

A two-byte, signed integer:

SHORT

DBTYPE_R4

A single-precision floating-point value:

Float

DBTYPE_CY

A currency value:

LARGE_INTEGER

Currency is a fixed-point number with four digits to the right of the decimal point. It is stored in an eight-byte signed integer, scaled by 10,000.

DBTYPE_BSTR

A pointer to a BSTR, as in Automation:

Typedef WCHAR * BSTR;

A BSTR is a pointer to a null-terminated character string in which the string length is stored with the string. Because the length is stored with the string, BSTR variables can contain embedded null characters. To determine the length of the BSTR in characters, call SysStringLen. To determine the length of the BSTR in bytes, call SysStringByteLen. In either case, the length does not include the null-termination character.

In Microsoft Win32? (the environment for OLE DB), a BSTR contains Unicode.

Consumers are responsible for freeing the memory used by BSTRs. Failure to free such memory is a common cause of memory leaks. For example, if a consumer calls IRowset::GetData to retrieve a BSTR, the provider allocates memory for the BSTR and returns a pointer to it in the memory pointed to by pData. A memory leak occurs when the consumer calls IRowset::GetData again with the same value of pData without first freeing the memory for the BSTR. In this case, the provider allocates new memory for the BSTR and overwrites the pointer to the old BSTR with the pointer to the new BSTR. The old BSTR is still allocated, but the pointer to it is lost. For more information, see Responsibility for Freeing Memory.

DBTYPE_ERROR

A 32-bit error code:

SCODE

DBTYPE_VARIANT

An Automation VARIANT:

VARIANT

The DBTYPE values that do not match Automation VARENUM values represent data types that cannot be stored in a VARIANT. If the VARIANT structure contains a pointer to the data, the buffer for that data is allocated separately.

DBTYPE_DECIMAL

An exact numeric value with a fixed precision and fixed scale, stored in the same way as in Automation:

Typedef struct tagDEC {
   USHORT wReserved;
   union {
      struct {
         BYTE scale;
         BYTE sign;
      };
      USHORT signscale;
   };
   ULONG Hi32;
   union {
      struct {
         ULONG Lo32;
         ULONG Mid32;
      };
      ULONGLONG Lo64;
   };
} DECIMAL;

The elements of this structure are used as follows:

• WReserved ? Reserved. Should be 0.

• scale ? The scale specifies the number of digits to the right of the decimal point and ranges from 0 to 28.

• sign ? The sign: 0 if positive, 0x80 if negative.

• Hi32 ? The high part of the integer (32-bit aligned).

• Mid32 ? The middle part of the integer (32-bit aligned).

• Lo32 ? The low part of the integer (32-bit aligned).

For example, to specify the number 12.345, the scale is 3, the sign is 0, and the number stored in the 12-byte integer is 12345.

For information about what precision and scale the provider uses when accessing DBTYPE_DECIMAL structures, see Conversions Involving DBTYPE_NUMERIC or DBTYPE_DECIMAL, in this Appendix.

DBTYPE_ARRAY

A pointer to a SAFEARRAY:

SAFEARRAY *

DBTYPE_ARRAY must be combined with another type indicator. This indicates that the data in the consumer's buffer is a pointer to a SAFEARRAY of the other type. For example, DBTYPE_I2 | DBTYPE_ARRAY means that the data is a pointer to a SAFEARRAY of two-byte integers.

When DBTYPE_ARRAY is used, the data in the consumer's buffer can be a null pointer only when the corresponding status value is DBSTATUS_S_ISNULL. When setting a column value, if the data in the consumer's buffer is a null pointer and the status is not DBSTATUS_S_ISNULL, the provider returns a conversion error.

DBTYPE_ARRAY is mutually exclusive with the DBTYPE_BYREF and DBTYPE_VECTOR modifiers and cannot be combined with indicators for variable-length data types because there is no way to determine the length of each element of the array. DBTYPE_ARRAY can be combined with DBTYPE_BSTR because DBTYPE_BSTR is a fixed-length data type: A BSTR is a pointer to a separately allocated string that contains its own length.

For information about how SAFEARRAYs are allocated, see Responsibility for Freeing Memory.

DBTYPE_I1

A one-byte, signed integer:

signed char

DBTYPE_UI4

A four-byte, unsigned integer:

ULONG

DBTYPE_UI8

An eight-byte, unsigned integer:

ULARGE_INTEGER

DBTYPE_VECTOR

A DBVECTOR structure:

typedef struct tagDBVECTOR {
   DBLENGTH   size;
   void      *ptr;
} DBVECTOR;

DBTYPE_VECTOR must be combined with another type indicator. This indicates that the data in the consumer's buffer is a DBVECTOR structure, which contains ptr, a pointer to an array of the other type, and size, the number of elements in this array. For example, DBTYPE_I2 | DBTYPE_VECTOR means that the data is a DBVECTOR structure that contains a pointer to an array of two-byte integers.

When DBTYPE_VECTOR is used, the pointer in the DBVECTOR structure can be a null pointer only when the corresponding status value is DBSTATUS_S_ISNULL. When setting a column value, if the pointer is a null pointer and the status is not DBSTATUS_S_ISNULL, the provider returns a conversion error.

DBTYPE_VECTOR is mutually exclusive with the DBTYPE_BYREF and DBTYPE_ARRAY modifiers and cannot be combined with indicators for variable-length data types because there is no way to determine the length of each element of the array.

For information about how the memory pointed to by DBVECTOR structures is allocated, see Responsibility for Freeing Memory.

DBTYPE_BYTES

A binary data value. That is, an array of bytes:

BYTE[length]

The length of the array is specified by cbMaxLen in the DBBINDING structure if DBTYPE_BYTES is used by itself. It is specified by the bound length value if DBTYPE_BYTES is combined with DBTYPE_BYREF.

For columns containing binary data, the provider reports the data type as DBTYPE_BYTES and the maximum length as the true maximum length of the binary data (assuming there is one). For small, fixed-length binary data, such as a column in an SQL database of type BINARY(1000), the consumer generally binds the column as DBTYPE_BYTES. For small, variable-length binary data, such as a column in an SQL database of type VARBINARY(1000), the consumer generally binds the column as DBTYPE_BYTES | DBTYPE_BYREF, so no space is wasted and no data is truncated. For long binary data, the consumer generally binds the column as DBTYPE_IUNKNOWN and uses a storage interface such as IsequentialStream to manipulate the data. For more information, see Accessing BLOB Data.

When null-terminated string data is converted to or from DBTYPE_BYTES, the null termination character is not included in the length count or the data transferred.

DBTYPE_WSTR

A null-terminated Unicode character string:

wchar_t[length]

If DBTYPE_WSTR is used by itself, the number of bytes allocated for the string, including the null-termination character, is specified by cbMaxLen in the DBBINDING structure. If DBTYPE_WSTR is combined with DBTYPE_BYREF, the number of bytes allocated for the string, including the null-termination character, is at least the length of the string plus two. In either case, the actual length of the string is determined from the bound length value. The maximum length of the string is the number of allocated bytes divided by sizeof(wchar_t) and truncated to the nearest integer.

DBTYPE_UDT

A user-defined data type of variable length. The format of the data type is defined by the data source and the provider. Converting to and from DBTYPE_UDT is provider specific.

DBTYPE_DBTIME

A time structure:

Typedef struct tagDBTIME {
   USHORT hour;
   USHORT minute;
   USHORT second;
} DBTIME;

The elements of this structure are used as follows:

• Hour ? The hour: 0?23.

• minute ? The minute: 0?59.

• Second ? The second: 0?61.

The range of seconds allows as many as two leap seconds to maintain synchronization with sidereal time.

DBTYPE_HCHAPTER

A four-byte chapter value that can be used to identify rows in a child rowset.

DBTYPE_PROPVARIANT

An Automation PROPVARIANT:

PROPVARIANT

If the VARIANT structure contains a pointer to the data, the buffer for the data is allocated separately.

DBTYPE_PROPVARIANT should support the same set of conversions as DBTYPE_VARIANT (including conversions to/from DBTYPE_VARIANT).

DBTYPE_XML

An XML document fragment with a single element root. The fragment is preceded by an XML declaration, and by optional comments and processing instructions as siblings to the element root. All other forms (multiple roots or a single root without an XML declaration) are considered fragments.

The data stored in a XML type is retrieved as a string or by using the SAX reader.