Функция SQLBindCol

Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92

Сводка
SQLBindCol связывает буферы данных приложений с столбцами в наборе результатов.

Syntax

  
SQLRETURN SQLBindCol(  
      SQLHSTMT       StatementHandle,  
      SQLUSMALLINT   ColumnNumber,  
      SQLSMALLINT    TargetType,  
      SQLPOINTER     TargetValuePtr,  
      SQLLEN         BufferLength,  
      SQLLEN *       StrLen_or_IndPtr);  

Arguments

ОператорHandle
[Входные данные] Дескриптор инструкции.

ColumnNumber
[Ввод] Количество столбца с набором результатов для привязки. Столбцы нумеруются в порядке возрастающих столбцов, начиная с 0, где столбец 0 — это столбец закладок. Если закладки не используются — то есть атрибут SQL_ATTR_USE_BOOKMARKS оператора установлен в SQL_UB_OFF — тогда номера столбцов начинаются с 1.

ТипЦели
[Ввод] Идентификатор типа данных C буфера *TargetValuePtr . При извлечении данных из источника данных с помощью SQLFetch, SQLFetchScroll, SQLBulkOperations или SQLSetPos драйвер преобразует данные в этот тип; когда данные отправляются в источник данных с помощью SQLBulkOperations или SQLSetPos, драйвер преобразует данные из этого типа. Для списка действительных типов данных C и идентификаторов типов см. раздел C Data Types в Приложении D: Типы данных.

Если аргумент TargetType является типом интервальных данных, для данных используются стандартная точность интервала (2) и стандартная точность интервала секунд (6), установленные в полях SQL_DESC_DATETIME_INTERVAL_PRECISION и SQL_DESC_PRECISION ARD соответственно. Если аргумент TargetType — SQL_C_NUMERIC, для данных используются стандартная точность (определяемая драйвером) и масштаб по умолчанию (0), установленные в полях SQL_DESC_PRECISION и SQL_DESC_SCALE ARD. Если какая-либо стандартная точность или масштаб не подходят, приложение должно явно установить соответствующее поле дескриптора с помощью вызова SQLSetDescField или SQLSetDescRec.

Можно также указать расширенный тип данных C. Дополнительные сведения см. в разделе "Типы данных C" в ODBC.

TargetValuePtr
[Отложенный ввод/вывод] Указатель на буфер данных для привязки к столбцу. SQLFetch и SQLFetchScroll возвращают данные в этом буфере. SQLBulkOperations возвращает данные в этом буфере, когда операция SQL_FETCH_BY_BOOKMARK; он извлекает данные из этого буфера, когда операция SQL_ADD или SQL_UPDATE_BY_BOOKMARK. SQLSetPos возвращает данные в этом буфере при SQL_REFRESH операции ; он получает данные из этого буфера, когда операция SQL_UPDATE.

Если TargetValuePtr является нулевой указателем, драйвер развязывает буфер данных для столбца. Приложение может развязать все столбцы, вызвав SQLFreeStmt с помощью опции SQL_UNBIND. Приложение может развязать буфер данных для столбца, но при этом сохранить границу длины/индикатора для столбца, если аргумент TargetValuePtr в вызове SQLBindCol является нулевым указателем, а аргумент StrLen_or_IndPtr — действительным значением.

BufferLength
[Ввод] Длина буфера *TargetValuePtr в байтах.

Драйвер использует BufferLength , чтобы избежать записи за пределами буфера *TargetValuePtr при возврате данных переменной длины, таких как символьные или двоичные данные. Обратите внимание, что драйвер считает символ null-termination, когда возвращает данные символа в *TargetValuePtr. * Таким образом, TargetValuePtr должен содержать место для символа нулевой терминации, иначе драйвер усечит данные.

Когда драйвер возвращает данные фиксированной длины, такие как целое число или структура даты, драйвер игнорирует BufferLength и предполагает, что буфер достаточно велик для хранения данных. Поэтому важно, чтобы приложение выделило достаточно большой буфер для данных фиксированной длины, иначе драйвер будет записывать данные дальше конца буфера.

SQLBindCol возвращает SQLSTATE HY090 (Неверная строка или длина буфера), когда BufferLength меньше 0, но не при 0. Однако если TargetType указывает тип символа, приложение не должно устанавливать BufferLength в 0, поскольку драйверы, совместимые с ISO CLI, возвращают SQLSTATE HY090 (Недопустимая длина строки или длины буфера).

StrLen_or_IndPtr
[Отложенный ввод/вывод] Указатель на буфер длины/индикатора для привязки к столбцу. SQLFetch и SQLFetchScroll возвращают значение в этом буфере. SQLBulkOperations извлекает значение из этого буфера, когда операция SQL_ADD, SQL_UPDATE_BY_BOOKMARK или SQL_DELETE_BY_BOOKMARK. SQLBulkOperations возвращает значение в этом буфере, когда операция SQL_FETCH_BY_BOOKMARK. SQLSetPos возвращает значение в этом буфере, когда операция SQL_REFRESH; он получает значение из этого буфера, когда операция SQL_UPDATE.

SQLFetch, SQLFetchScroll, SQLBulkOperations и SQLSetPos могут возвращать следующие значения в буфере длины/индикатора:

• Длина данных, доступных для возврата

• SQL_NO_TOTAL

• SQL_NULL_DATA

Приложение может вводить следующие значения в буфер длины/индикатора для использования с SQLBulkOperations или SQLSetPos:

• Длина передаваемых данных

• SQL_NTS

• SQL_NULL_DATA

• SQL_DATA_AT_EXEC

• Результат макро SQL_LEN_DATA_AT_EXEC

• SQL_COLUMN_IGNORE

Если индикаторный буфер и длинный буфер являются отдельными буферами, индикаторный буфер может возвращать только SQL_NULL_DATA, тогда как длинный буфер может возвращать все остальные значения.

Для получения дополнительной информации см. SQLBulkOperations Function, SQLFetch Function, SQLSetPos Function и Using Length/Indicator Values.

Если StrLen_or_IndPtr — нулевой указатель, то значение длины или индикатора не используются. Это ошибка при извлечении данных, и данные имеют NULL.

См. сведения о 64-разрядной версии ODBC, если приложение будет работать в 64-разрядной операционной системе.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR или SQL_INVALID_HANDLE.

Diagnostics

Когда SQLBindCol возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить, вызвав SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и Handle-аStatementHandle. В следующей таблице перечислены значения SQLSTATE, обычно возвращаемые SQLBindCol , и каждое из них объясняется в контексте этой функции; обозначение «(DM)» предшествует описаниям SQLSTATE, возвращаемым менеджером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE	Error	Description
01000	Общее предупреждение	Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
07006	Нарушение атрибута ограниченного типа данных	(DM) Аргумент ColumnNumber был равен 0, а аргумент TargetType не был SQL_C_BOOKMARK или SQL_C_VARBOOKMARK.
07009	Индекс некорректного дескриптора	Значение для аргумента ColumnNumber превышало максимальное количество столбцов в наборе результатов.
HY000	Общая ошибка	Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину.
HY001	Ошибка выделения памяти	Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY003	Недопустимый тип буфера приложения	Аргумент TargetType не был ни допустимым типом данных, ни SQL_C_DEFAULT.
HY010	Ошибка последовательности функций	(DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция всё ещё выполнялась, когда был вызван SQLBindCol . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) асинхронно выполняющаяся функция была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов.
HY013	Ошибка управления памятью	Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090	Недопустимая длина строки или буфера	(DM) Значение для аргумента BufferLength было меньше 0. (ДМ) Водитель был ODBC 2. x driver, аргумент ColumnNumber был установлен в 0, а значение для аргумента BufferLength не было равным 4.
HY117	Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения.	(DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00	Необязательный компонент не реализован	Драйвер или источник данных не поддерживает преобразование, заданное комбинацией аргумента TargetType и специфичного для драйвера типа данных SQL в соответствующем столбце. Аргумент ColumnNumber равен 0, и драйвер не поддерживает закладки. Драйвер поддерживает только ODBC 2. x и аргумент TargetType был одним из следующих: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT и любой из типов данных интервала C, перечисленных в C Типах данных в Приложении D: Типы данных. Драйвер поддерживает только версии ODBC до 3.50, и аргумент TargetType был SQL_C_GUID.
HYT01	Время ожидания для подключения истекло	Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Драйвер не поддерживает эту функцию	(DM) Драйвер, связанный с StatementHandle , не поддерживает функцию.

Comments

SQLBindCol используется для связывания столбцов в наборе результатов с буферами данных и буферами длины/индикаторов в приложении. Когда приложение вызывает SQLFetch, SQLFetchScroll или SQLSetPos для получения данных, драйвер возвращает данные для связанных столбцов в указанных буферах; для получения дополнительной информации см. Функция SQLFetch. Когда приложение вызывает SQLBulkOperations для обновления или вставки строки, или SQLSetPos для обновления строки, драйвер получает данные для связанных столбцов из указанных буферов; для получения дополнительной информации см. SQLBulkOperations Function или SQLSetPos Function. Для получения дополнительной информации о привязке см. раздел «Получение результатов (Basic)».

Обратите внимание, что столбцы не обязаны быть связаны для получения данных из них. Приложение также может вызывать SQLGetData для извлечения данных из столбцов. Хотя возможно привязать некоторые столбцы в строку и вызывать SQLGetData для других, это имеет определённые ограничения. Для получения дополнительной информации см. SQLGetData.

Колонки для привязки, снятия и перевязки

Столбец может быть связан, развязан или отскок в любой момент, даже после того, как данные были извлечены из набора результатов. Новое привязывание вступает в силу при следующем вызове функции, использующей привязки. Например, предположим, что приложение связывает столбцы в наборе результатов и вызывает SQLFetch. Драйвер возвращает данные из связанных буферов. Теперь предположим, что приложение связывает столбцы с другим набором буферов. Драйвер не помещает данные для только что выбранной строки в новые связанные буферы. Вместо этого он ждёт повторного вызова SQLFetch и затем помещает данные для следующей строки в новые связанные буферы.

Замечание

Атрибут оператора SQL_ATTR_USE_BOOKMARKS всегда должен быть установлен перед привязкой столбца к столбцу 0. Это не обязательно, но настоятельно рекомендуется.

Привязка столбцов

Для привязки столбца приложение вызывает SQLBindCol и передаёт номер столбца, тип, адрес и длину буфера данных, а также адрес буфера длины/индикатора. Для получения информации о том, как используются эти адреса, см. раздел «Буферные адреса» позже в этом разделе. Для получения дополнительной информации о колонках привязки см. раздел «Использование SQLBindCol».

Использование этих буферов отложено; то есть приложение связывает их в SQLBindCol , но драйвер получает доступ к ним из других функций — а именно SQLBulkOperations, SQLFetch, SQLFetchScroll или SQLSetPos. Ответственность приложения лежит за тем, чтобы указатели, указанные в SQLBindCol , оставались действительными до тех пор, пока связывание действует. Если приложение позволяет этим указателям становиться недействительными — например, освобождает буфер — а затем вызывает функцию, ожидающую их валидности, последствия остаются неопределёнными. Для получения дополнительной информации см. раздел «Отложенные буферы».

Привязка действует до тех пор, пока его не заменят на новое, колонка не освободится или оператор не освободится.

Развязывающие колонны

Чтобы развязать один столбец, приложение вызывает SQLBindCol с ColumnNumber с номером этого столбца, а TargetValuePtr — на нулевой указатель. Если ColumnNumber относится к несвязанному столбцу, SQLBindCol всё равно возвращает SQL_SUCCESS.

Чтобы развязать все столбцы, приложение вызывает SQLFreeStmt с fOption , установленным в SQL_UNBIND. Это также можно реализовать, установив SQL_DESC_COUNT поле ARD равным нулю.

Колонны перевязки

Приложение может выполнить одно из двух операций, чтобы изменить привязку:

• Вызовите SQLBindCol , чтобы указать новую связку для уже связанного столбца. Драйвер перезаписывает старую привязку новым.

• Укажите смещение, которое должно быть добавлено к адресу буфера, указанного вызовом связывания SQLBindCol. Для получения дополнительной информации см. следующий раздел «Смещение связи».

Смещение связей

Смещение связывания — это значение добавляется к адресам буферов данных и длины/индикатора (как указано в аргументе TargetValuePtr и StrLen_or_IndPtr ) до их деэпирации. Когда используются смещения, эти привязки служат «шаблоном» того, как расположены буферы приложения, и приложение может перемещать этот «шаблон» в разные области памяти, изменяя смещение. Поскольку одно и то же смещение добавляется к каждому адресу в каждом привязке, относительные смещения между буферами для разных столбцов должны быть одинаковыми внутри каждого набора буферов. Это всегда верно, когда используется переплет по строкам; Приложение должно тщательно распределять свои буферы, чтобы это было верно при использовании перевязки по колонкам.

Использование смещения связки даёт практически тот же эффект, что и повторное перевязывание столбца с вызовом SQLBindCol. Разница в том, что новый вызов SQLBindCol указывает новые адреса для буфера данных и буфера длины/индикатора, тогда как использование смещения связывания не меняет адреса, а лишь добавляет к ним смещение. Приложение может указывать новый смещение в любое время, и это смещение всегда добавляется к исходно связанным адресам. В частности, если смещение установлено на 0 или атрибут оператора установлен на нулевой указатель, драйвер использует изначально связанные адреса.

Для указания смещения связывания приложение устанавливает атрибут оператора SQL_ATTR_ROW_BIND_OFFSET_PTR адресом буфера SQLINTEGER. Перед тем как приложение вызовет функцию, использующую привязки, оно помещает смещение в байтах в этом буфере. Чтобы определить адрес используемого буфера, драйвер добавляет смещение к адресу в привязке. Сумма адреса и смещения должна быть действительным, но адрес, к которому добавлено смещение, не обязательно должен быть действительным. Для получения дополнительной информации о том, как используются смещения связи, см. раздел «Адреса буфера» ниже в этом разделе.

Связывающие массивы

Если размер рядового набора (значение атрибута оператора SQL_ATTR_ROW_ARRAY_SIZE) больше 1, приложение связывает массивы буферов вместо отдельных буферов. Для получения дополнительной информации см. Блок-курсоры.

Приложение может связывать массивы двумя способами:

• Привязка массива к каждому столбцу. Это называется связыванием по столбцам , поскольку каждая структура данных (массив) содержит данные для одного столбца.

• Определите структуру, которая хранит данные для целой строки, и свяжите массив этих структур. Это называется построковым связыванием , поскольку каждая структура данных содержит данные для одной строки.

Каждый массив буферов должен содержать как минимум столько элементов, сколько размер множества строк.

Замечание

Приложение должно проверить, что выравнивание действительно. Для получения дополнительной информации о соображениях выравнивания см. раздел «Выравнивание».

Column-Wise привязка

В поколончном привязке приложение привязывает отдельные массивы данных и длины/индикаторов к каждому столбцу.

Для использования привязки по столбцам приложение сначала устанавливает атрибут оператора SQL_ATTR_ROW_BIND_TYPE в SQL_BIND_BY_COLUMN. (Это значение по умолчанию.) Для привязки каждого столбца приложение выполняет следующие действия:

1. Выделяет массив буфера данных.

2. Выделяет массив буферов длины или индикатора.

   Замечание

   Если приложение записывает непосредственно в дескрипторы при использовании привязки со столбцами, отдельные массивы можно использовать для данных длины и индикатора.

3. Вызывает SQLBindCol следующими аргументами:

   • TargetType — это тип одного элемента в массиве буфера данных.

   • TargetValuePtr — это адрес массива буфера данных.

   • BufferLength — это размер одного элемента в массиве буфера данных. Аргумент BufferLength игнорируется, если данные являются данными фиксированной длины.

   • StrLen_or_IndPtr — это адрес массива длины или индикатора.

Для получения дополнительной информации о том, как используется эта информация, см. раздел «Буферные адреса» ниже в этом разделе. Для получения дополнительной информации о переплете по колонкам см. Column-Wise раздел Binding.

Row-Wise привязка

При построчном привязке приложение определяет структуру, содержащую данные и буферы длины/индикаторов для каждого столбца, который подлежит ограничению.

Чтобы использовать привязку по строкам, приложение выполняет следующие действия.

1. Определяет структуру для хранения одной строки данных (включая данные и буферы длины/индикаторов) и выделяет массив этих структур.

   Замечание

   Если приложение записывает непосредственно в дескрипторы при использовании привязки по строкам, отдельные поля можно использовать для данных длины и индикатора.

2. Устанавливает атрибут оператора SQL_ATTR_ROW_BIND_TYPE размеру структуры, содержащей одну строку данных, или размеру экземпляра буфера, в который будут связаны столбцы результатов. Длина должна включать пространство для всех связанных столбцов и любого дополнения структуры или буфера, чтобы при увеличении адреса связанного столбца с указанной длиной результат указывал на начало того же столбца в следующей строке. При использовании оператора sizeof в ANSI C это поведение гарантируется.

3. Вызывает SQLBindCol со следующими аргументами для каждого столбца, который должен быть связан:

   • TargetType — это тип элемента буфера данных, который должен быть привязан к столбцу.

   • TargetValuePtr — это адрес члена буфера данных в первом элементе массива.

   • BufferLength — это размер элемента буфера данных.

   • StrLen_or_IndPtr — это адрес привязанного элемента длины или индикатора.

Для получения дополнительной информации о том, как используется эта информация, см. раздел «Буферные адреса» ниже в этом разделе. Для получения дополнительной информации о переплете по колонкам см. Row-Wise раздел Binding.

Буферные адреса

Адрес буфера — это фактический адрес данных или буфера длины/индикатора. Драйвер вычисляет адрес буфера непосредственно перед записью в буферы (например, во время выборки). Он вычисляется по следующей формуле, которая использует адреса, указанные в аргументах TargetValuePtr и StrLen_or_IndPtr , смещение связывания и номер строки:

Связанный адрес + Смещение связки + ((номер строки - 1) x размер элемента)

где переменные формулы определены, как описано в следующей таблице.

Variable	Description
Связанный адрес	Для буферов данных адрес, указанный аргументом TargetValuePtr в SQLBindCol. Для буферов длины/индикатора адрес, указанный с аргументом StrLen_or_IndPtr в SQLBindCol. Для получения дополнительной информации смотрите раздел «Дополнительные комментарии» в разделе «Дескрипторы и SQLBindCol». Если связанный адрес равен 0, значение данных не возвращается, даже если адрес, вычисленный по предыдущей формуле, не равен нулю.
Смещение связывания	Если используется построчное привязывание, значение, хранящееся по адресу, указанному с атрибутом оператора SQL_ATTR_ROW_BIND_OFFSET_PTR. Если используется связывание по столбцам или если значение атрибута оператора SQL_ATTR_ROW_BIND_OFFSET_PTR является нулевым указателем, смещение связывания равно 0.
Номер строки	Число строки в наборе строк, основанное на 1. Для однострочных выборов, которые являются по умолчанию, это 1.
Размер элемента	Размер элемента в связанном массиве. Если используется перевязка по столбцам, это sizeof(SQLINTEGER) для буферов длины/индикатора. Для буферов данных это значение аргумента BufferLength в SQLBindCol , если тип данных имеет переменную длину, и размер типа данных, если тип данных фиксирован. Если используется привязка по строкам, это значение атрибута оператора SQL_ATTR_ROW_BIND_TYPE как для данных, так и для буферов длины/индикатора.

Дескрипторы и SQLBindCol

В следующих разделах описывается, как SQLBindCol взаимодействует с дескрипторами.

Предостережение

Вызов SQLBindCol для одного оператора может повлиять на другие операторы. Это происходит при явном выделении ARD, связанном с инструкцией, и также связана с другими операторами. Поскольку SQLBindCol модифицирует дескриптор, эти изменения применяются ко всем операторам, с которыми этот дескриптор ассоциируется. Если это не требуемое поведение, приложение должно отделить этот дескриптор от других операторов перед вызовом SQLBindCol.

Аргументы

Концептуально SQLBindCol выполняет следующие шаги последовательно:

1. Вызывает SQLGetStmtAttr для получения ARD-дея.

2. Вызывает SQLGetDescField для получения SQL_DESC_COUNT поля этого дескриптора, и если значение в аргументе ColumnNumber превышает значение SQL_DESC_COUNT, вызывает SQLSetDescField , чтобы увеличить значение SQL_DESC_COUNT до ColumnNumber.

3. Многократно вызывает SQLSetDescField для присвоения значений следующим полям ARD:

   • Устанавливает SQL_DESC_TYPE и SQL_DESC_CONCISE_TYPE на значение TargetType, за исключением того, что если TargetType является одним из кратких идентификаторов подтипа datetime или interval (дата-тайм) или интервала, то SQL_DESC_TYPE устанавливается соответственно в SQL_DATETIME или SQL_INTERVAL; задаёт SQL_DESC_CONCISE_TYPE в лаконичный идентификатор; и задаёт SQL_DESC_DATETIME_INTERVAL_CODE соответствующему подкоду datetime или интервала.

   • Устанавливает один или несколько SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE и SQL_DESC_DATETIME_INTERVAL_PRECISION, в зависимости от TargetType.

   • Задает поле SQL_DESC_OCTET_LENGTH значение BufferLength.

   • Устанавливает поле SQL_DESC_DATA_PTR в значение TargetValuePtr.

   • Устанавливает поле SQL_DESC_INDICATOR_PTR в значение StrLen_or_IndPtr. (См. следующий абзац.)

   • Задаёт поле SQL_DESC_OCTET_LENGTH_PTR равно StrLen_or_IndPtr. (См. следующий абзац.)

Переменная, на которую относится аргумент StrLen_or_IndPtr , используется как для информации об индикаторе, так и для информации. Если выборка встречает нулевое значение столбца, она сохраняет SQL_NULL_DATA в этой переменной; в противном случае длина данных сохраняется в этой переменной. Передача нулевого указателя в виде StrLen_or_IndPtr не позволяет операции выбора вернуть длину данных, но приводит к неудаче, если оно встречает нулевое значение и не имеет возможности вернуть SQL_NULL_DATA.

Если вызов SQLBindCol не выполняется, содержимое дескрипторных полей в ARD не определённо, и значение поля SQL_DESC_COUNT ARD не меняется.

Неявное сброс поля COUNT

SQLBindCol устанавливает SQL_DESC_COUNT в значение аргумента ColumnNumber только тогда, когда это увеличивает значение SQL_DESC_COUNT. Если значение в аргументе TargetValuePtr является нулевым указателем, а значение в аргументе ColumnNumber равно SQL_DESC_COUNT (то есть при развязке столбца с наивысшей границей), то SQL_DESC_COUNT устанавливается на число самого оставшегося связанного столбца.

Осторожности относительно SQL_DEFAULT

Для успешного извлечения данных столбцов приложение должно правильно определить длину и начальную точку данных в буфере приложения. Когда приложение указывает явный TargetType, ошибочные представления в приложении легко выявляются. Однако, когда приложение указывает TargetType SQL_DEFAULT, SQLBindCol может быть применён к столбцу другого типа данных, отличного от того, который предназначен приложению, либо из-за изменений в метаданных, либо при применении кода к другому столбцу. В этом случае приложение не всегда определяет начало или длину данных из полученных столбцов. Это может привести к незарегистрированным ошибкам в данных или нарушениям памяти.

Пример кода

В следующем примере приложение выполняет оператор SELECT в таблице Customers, чтобы вернуть набор результатов с идентификаторами клиентов, именами и номерами телефонов, отсортированными по имени. Затем он вызывает SQLBindCol для связки столбцов данных с локальными буферами. Наконец, приложение получает каждую строку данных с помощью SQLFetch и печатает имя, ID и номер телефона каждого клиента.

Для дополнительных примеров кода см. SQLBulkOperations Function, SQLColumns Function, SQLFetchScroll Function и SQLSetPos Function.

// SQLBindCol_ref.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <stdio.h>  
  
#define UNICODE  
#include <sqlext.h>  
  
#define NAME_LEN 50  
#define PHONE_LEN 60
  
void show_error() {  
   printf("error\n");  
}  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt = 0;  
   SQLRETURN retcode;  
   SQLWCHAR szName[NAME_LEN], szPhone[PHONE_LEN], sCustID[NAME_LEN];  
   SQLLEN cbName = 0, cbCustID = 0, cbPhone = 0;  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);  
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            // Connect to data source  
            retcode = SQLConnect(hdbc, (SQLWCHAR*) L"NorthWind", SQL_NTS, (SQLWCHAR*) NULL, 0, NULL, 0);  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {   
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               retcode = SQLExecDirect(hstmt, (SQLWCHAR *) L"SELECT CustomerID, ContactName, Phone FROM CUSTOMERS ORDER BY 2, 1, 3", SQL_NTS);  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
  
                  // Bind columns 1, 2, and 3  
                  retcode = SQLBindCol(hstmt, 1, SQL_C_WCHAR, &sCustID, 100, &cbCustID);  
                  retcode = SQLBindCol(hstmt, 2, SQL_C_WCHAR, szName, NAME_LEN, &cbName);  
                  retcode = SQLBindCol(hstmt, 3, SQL_C_WCHAR, szPhone, PHONE_LEN, &cbPhone);   
  
                  // Fetch and print each row of data. On an error, display a message and exit.  
                  for (int i=0 ; ; i++) {  
                     retcode = SQLFetch(hstmt);  
                     if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO)  
                        show_error();  
                     if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO)  
                     {
                        //replace wprintf with printf
                        //%S with %ls
                        //warning C4477: 'wprintf' : format string '%S' requires an argument of type 'char *'
                        //but variadic argument 2 has type 'SQLWCHAR *'
                        //wprintf(L"%d: %S %S %S\n", i + 1, sCustID, szName, szPhone);  
                        printf("%d: %ls %ls %ls\n", i + 1, sCustID, szName, szPhone);  
                    }    
                     else  
                        break;  
                  }  
               }  
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLCancel(hstmt);  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}  

Также см. Пример программы ODBC.

Связанные функции

Сведения о	Смотри
Возврат сведений о столбце в результирующем наборе	Функция SQLDescribeCol
Получение блока данных или прокрутка результирующий набор	Функция SQLFetchScroll
Получение нескольких строк данных	Функция SQLFetch
Освобождение буферов столбцов на операторе	Функция SQLFreeStmt
Извлечение части или всех столбцов данных	Функция SQLGetData
Возврат количества столбцов результатов	Функция SQLNumResultCols

Связанные материалы

• Ссылка на ODBC API
• Файлы заголовков ODBC