SQLBindCol

Applies to: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

As a general rule, consider the implications of using SQLBindCol to cause data conversion. Binding conversions are client processes, so, for example, retrieving a floating-point value bound to a character column causes the driver to perform the float-to-character conversion locally when a row is fetched. The Transact-SQL CONVERT function can be used to place the cost of data conversion on the server.

An instance of SQL Server can return multiple sets of result rows on a single statement execution. Each result set must be bound separately. For more information about binding for multiple result sets, see SQLMoreResults.

The developer can bind columns to SQL Server-specific C data types using the TargetType value SQL_C_BINARY. Columns bound to SQL Server-specific types are not portable. The defined SQL Server-specific ODBC C data types match the type definitions for DB-Library, and DB-Library developers porting applications may want to take advantage of this feature.

Reporting data truncation is an expensive process for the SQL Server Native Client ODBC driver. You can avoid truncation by ensuring that all bound data buffers are wide enough to return data. For character data, the width should include space for a string terminator when the default driver behavior for string termination is used. For example, binding a SQL Server char(5) column to an array of five characters results in truncation for every value fetched. Binding the same column to an array of six characters avoids the truncation by providing a character element in which to store the null terminator. SQLGetData can be used to efficiently retrieve long character and binary data without truncation.

For large value data types, if the user supplied buffer isn't large enough to hold the entire value of the column, SQL_SUCCESS_WITH_INFO is returned and the "string data; right truncation" warning is issued. The StrLen_or_IndPtr argument will contain the number of chars/bytes stored in the buffer.

SQLBindCol Support for Enhanced Date and Time Features

Result column values of date/time types are converted as described in Conversions from SQL to C. Note that to retrieve time and datetimeoffset columns as their corresponding structures (SQL_SS_TIME2_STRUCT and SQL_SS_TIMESTAMPOFFSET_STRUCT), TargetType must be specified as SQL_C_DEFAULT or SQL_C_BINARY.

For more information, see Date and Time Improvements (ODBC).

SQLBindCol Support for Large CLR UDTs

SQLBindCol supports large CLR user-defined types (UDTs). For more information, see Large CLR User-Defined Types (ODBC).

See Also

SQLBindCol Function
ODBC API Implementation Details