String Data

  • Article

The term string is used collectively to refer to ANSI strings, Unicode strings, and BSTRs. When used as metadata ? for example, 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 as an in-memory string rather than through a storage object, the provider always returns a null-terminated string to the consumer. If the consumer's buffer is smaller than the sum of the length of the character data plus the length of the null-termination character, the provider truncates the data and adds a null-termination character to the truncated data. String data retrieved through a storage object is not null-terminated.

Note

Consumers cannot assume that multibyte character set (MBCS) string data was truncated at a character boundary.

To ensure that strings returned by the provider are not truncated, consumers should allocate space for a 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 5-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 6-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 space for the null-termination character, 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.

Note

It is an error to set cbMaxLen to less than the size of the null-termination character.

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 can be obtained by calling SysStringLength. For more information, see Type Indicators in Appendix A: Data Types.