Type Indicators

SHORT

LONG

Float

Double

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.

DATE

A DATE is a double, the whole part of which is the number of days since December 30, 1899, and the fractional part of which is the fraction of a day. For example, the number 2.25 represents the datetime January 1, 1900 6:00 AM.

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 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" in Chapter 6, "Getting and Setting Data."

IDispatch *

SCODE

VARIANT_BOOL

0 means false and ~0 (bitwise, the value is not 0; that is, all bits are set to 1) means true.

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.

IUnknown *

For columns containing COM objects, the provider reports the data type as DBTYPE_IUNKNOWN. The consumer specifies the interface to use through the pObject element of the DBBINDING structure. For more information, see "IPersist* Objects" in Chapter 7, "Blobs and COM Objects."

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," later in this appendix.

BYTE

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" in Chapter 6, "Getting and Setting Data."

Void *

DBTYPE_BYREF must be combined with another type indicator. This indicates that the data in the consumer's buffer is a pointer to the other type. For example, DBTYPE_STR | DBTYPE_BYREF means that the data is a pointer to an ANSI string, and DBTYPE_I2 | DBTYPE_BYREF means that the data is a pointer to a two-byte integer. DBTYPE_BYREF is commonly used to return pointers to variable-length data. It is used with provider-owned bindings to return pointers to the data in the rowset's copy of a row.

When DBTYPE_BYREF 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_BYREF is mutually exclusive with the DBTYPE_ARRAY and DBTYPE_VECTOR modifiers and cannot be combined with the following values:

DBTYPE_EMPTY
DBTYPE_NULL
DBTYPE_RESERVED

For information about how DBTYPE_BYREF values are allocated, see "Responsibility for Freeing Memory" in Chapter 6, "Getting and Setting Data."

signed char

USHORT

ULONG

LARGE_INTEGER

ULARGE_INTEGER

GUID

GUIDs are also known as universally unique identifiers (UUIDs) and are used as class identifiers (CLSIDs) and interface identifiers (IIDs).

typedef struct tagDBVECTOR {
   ULONG    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" in Chapter 6, "Getting and Setting Data."

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" in Chapter 7, "Blobs and COM Objects."

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.

Char[length]

If DBTYPE_STR 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_STR 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 one. In either case, the actual length of the string is determined from the bound length value.

If a locale is applicable, it is indicated first by the column metadata; if no column metadata is available, it is indicated by table metadata or by the database locale.

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.

Typedef struct tagDB_NUMERIC {
   BYTE precision;
   BYTE scale;
   BYTE sign;
   BYTE val[16];
} DB_NUMERIC;

The elements of this structure are used as follows:

Precision—The maximum number of digits in base 10.

Scale—The number of digits to the right of the decimal point.

Sign—The sign: 1 for positive numbers, 0 for negative numbers.

Val—A number stored as a 16-byte scaled integer, with the least-significant byte on the left.

For example, to specify the base 10 number 20.003 with a scale of 4, the number is scaled to an integer of 200030 (20.003 shifted by four tens digits), which is 30D5E in hexadecimal. The value stored in the 16-byte integer is 5E 0D 03 00 00 00 00 00 00 00 00 00 00 00 00 00, the precision is the maximum precision, the scale is 4, and the sign is 1.

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

Typedef struct tagDBDATE {
   SHORT      year;
   USHORT     month;
   USHORT     day;
} DBDATE;

The elements of this structure are used as follows:

Year—The year: 0–9999 measured from 0 A.D.

month—The month: 1–12.

Day—1–n, where n is the number of days in the month.

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.

Typedef struct tagDBTIMESTAMP {
   SHORT   year;
   USHORT  month;
   USHORT  day;
   USHORT  hour;
   USHORT  minute;
   USHORT  second;
   ULONG   fraction;
} DBTIMESTAMP;

The elements of this structure are used as follows:

Year—The year: 0–9999 measured from 0 A.D.

month—The month: 1–12.

Day—1–n, where n is the number of days in the month.

Hour—The hour: 0–23.

minute—The minute: 0–59.

Second—The second: 0–61.

Fraction—Billionths of a second: 0–999,999,999.

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

Typedef struct tagFILETIME {
   DWORD   dwLowDateTime;
   DWORD   dwHighDateTime;
} FILETIME;

The elements of the structure are used as follows:

DwLowDateTime—The lower 32 bits of the Win32 date/time value.

DwHighDateTime—The upper 32 bits of the Win32 date/time value.

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

Typedef struct tagDB_VARNUMERIC {
   BYTE      precision;
   SBYTE     scale;
   BYTE      sign;
   BYTE      val[ 1 ];
} DB_VARNUMERIC;

The elements of the structure are used as follows:

Precision—The maximum number of digits in base 10.

Scale—The number of digits to the right of the decimal point. The scale can be negative to support the storage of very large numbers without using exponential notation; for example, "12000" could be stored as "12" with a scale of -3. Also, the scale can be greater than precision to represent very small numbers without using exponential notation; for example, "0.00012" could be stored as "12" with precision=2 and scale = 5.

Sign—The sign: 1 for positive numbers, 0 for negative numbers.

Val—A number stored as a variable-byte length scaled integer, with the least significant byte on the left.

For example, to specify the base 10 number "6553E+50" with 5 digits of precision, the number is scaled to "65530", which is 0xFFFA in hexadecimal. The value can be stored in two bytes as FA FF (val[0] = 0xFA and val[1] = 0xFF), the precision is 5, the scale is –49, and the sign is 1.