Type Indicators

signed char

SHORT

LONG

LARGE_INTEGER

BYTE

unsigned short

unsigned int

ULARGE_INTEGER

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.

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

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

typedef struct tagDB_NUMERIC {
 BYTE precision;
 BYTE scale;
 BYTE sign;
 BYTE val[16];
} DBTYPE_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.

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.

VARIANT_BOOL

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

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.

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.

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 both cases, 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 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 "Memory Management" in Chapter 6 and the OLE Programmer's Reference, Volume 2.

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, or if none is available then by table metadata, or if none is available then 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. Note that the maximum length of the string is the number of allocated bytes divided by sizeof(wchar_t) and truncated to the nearest integer.

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, then the buffer for that data is allocated separately.

IDispatch *

For more information, see the OLE Programmer's Reference, Volume 2.

IUnknown *

For columns containing OLE 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.

GUID

GUIDs are also known as universally unique identifiers (UUIDs) and are used as class identifiers (CLSIDs) and interface identifiers (IIDs). For more information, see the OLE documentation.

SCODE

For more information, see the OLE documentation.

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 "Memory Management" in Chapter 6.

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 "Memory Management" in Chapter 6. For more information about SAFEARRAYs, see the OLE documentation.

typedef struct tagDBVECTOR {
 void * ptr;
 ULONG  size;
} 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 a pointer to an array of the other type. 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 "Memory Management" in Chapter 6.

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;

• 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, then 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;