String Data

The term string is used collectively to refer to ANSI strings, Unicode strings, and  BSTRs. Where a specific type is intended, that type can be determined from looking at the data type of the programming construct that contains the string. When used as metadata, such as in a schema rowset, a metadata interface such as IColumnsInfo, or a data definition interface such as ITableDefinition, string lengths are always measured in characters. When passing data, such as with IRowset::GetData, string lengths are always measured in bytes.

When a consumer gets string data from a provider, the provider generally returns a null-terminated string to the consumer. If the consumer's buffer is smaller than the length in bytes of the character data plus the null-termination character (that is, cbMaxLen in the DBBINDING structure is less than the length in bytes), the provider truncates the data and adds a null-termination character to the truncated data. String data retrieved through ISequentialStream is not null-terminated.

To ensure that strings returned by the provider are not truncated, consumers should allocate an additional byte for ANSI strings, or two bytes for Unicode strings, in their buffer to allow for the null-termination character. The following examples illustrate three cases where the buffer size determines whether all significant data is copied into the consumer's buffer:

• When the size of the buffer is less than the size in bytes of the string (that is, cbMaxLen is less than the length in bytes), the string is truncated and a null-termination character is added. For example, the ANSI string ABCDEF\0 is stored in a five-byte buffer as ABCD\0.
  
  
• When the size of the buffer is equal to the size in bytes of the character data but no allowance has been made for the null-termination character (that is, cbMaxLen equals the length in bytes), the string is truncated and a null-termination character is added. One character of data is lost, even though the size of the buffer is equal to the size in bytes of the character data. For example, the ANSI string ABCDEF\0 is stored in a six-byte buffer as ABCDE\0.
  
  
• When the size of the buffer is greater than or equal to the size in bytes of the character data plus the null-termination character (that is, cbMaxLen is greater than or equal to the length in bytes plus one for ANSI strings, or two for Unicode strings), the complete string is copied into the consumer's buffer. For example, the ANSI string ABCDEF\0 is stored in a 7-byte buffer as ABCDEF\0.

Whether character data is stored in the provider with a null-termination character is specific to each provider. If the consumer binds the character as another type, such as binary, the character data is returned without a null-termination character.

For ANSI strings and Unicode strings, the length returned in the length part of the binding is the actual length of the data in bytes. The null-termination character is not counted. For BSTRs, the length returned in the length part of the binding is sizeof(BSTR), not the length of the actual string. The length of the actual string is stored in a DWORD value preceding the string. For more information, see "Type Indicators" in Appendix A.