Поделиться через


Функция SQLGetData

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

Сводка
SQLGetData извлекает данные для одного столбца в результирующем наборе или для одного параметра после того, как SQLParamData возвращает SQL_PARAM_DATA_AVAILABLE. Его можно вызывать несколько раз, чтобы получить данные переменной длины в частях.

Синтаксис

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

Аргументы

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

Col_or_Param_Num
[Входные данные] Для получения данных столбца это число столбцов, для которого будут возвращены данные. Столбцы результирующего набора нумеруются в увеличении порядка столбцов, начиная с 1. Столбец закладки имеет номер 0; это можно указать только в том случае, если включены закладки.

Для получения данных параметров это порядковый номер параметра, который начинается с 1.

TargetType
[Входные данные] Идентификатор типа данных C для буфера *TargetValuePtr . Список допустимых типов данных C и идентификаторов типов см . в разделе "Типы данных C" в приложении D: Типы данных.

Если TargetType SQL_ARD_TYPE, драйвер использует идентификатор типа, указанный в поле SQL_DESC_CONCISE_TYPE ARD. Если TargetType SQL_APD_TYPE, SQLGetData будет использовать тот же тип данных C, который был указан в SQLBindParameter. В противном случае тип данных C, указанный в SQLGetData , переопределяет тип данных C, указанный в SQLBindParameter. Если это SQL_C_DEFAULT, драйвер выбирает тип данных C по умолчанию на основе типа данных SQL источника.

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

TargetValuePtr
[Выходные данные] Указатель на буфер, в котором возвращаются данные.

TargetValuePtr не может иметь значение NULL.

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

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

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

SQLGetData возвращает SQLSTATE HY090 (недопустимая строка или длина буфера), если BufferLength меньше 0, но не когда BufferLength равно 0.

StrLen_or_IndPtr
[Выходные данные] Указатель на буфер, в котором возвращается значение длины или индикатора. Если это пустой указатель, длина или значение индикатора не возвращается. При получении данных значение NULL возвращает ошибку.

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

  • Длина возвращаемых данных

  • SQL_NO_TOTAL

  • SQL_NULL_DATA

Дополнительные сведения см. в разделе "Использование значений длины или индикатора" и "Примечания" в этом разделе.

Возвраты

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.

Диагностика

Когда SQLGetData возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLGetData и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное.

SQLSTATE Error Description
01000 Общее предупреждение Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.)
01004 Строковые данные, усеченные справа Не все данные для указанного столбца, Col_or_Param_Num, можно получить в одном вызове функции. SQL_NO_TOTAL или длину данных, оставшихся в указанном столбце до текущего вызова SQLGetData , возвращаются в *StrLen_or_IndPtr. (Функция возвращает SQL_SUCCESS_WITH_INFO.)

Дополнительные сведения об использовании нескольких вызовов SQLGetData для одного столбца см. в разделе "Комментарии".
01S07 Дробное усечение Данные, возвращаемые для одного или нескольких столбцов, усечены. Для числовых типов данных дробная часть числа была усечена. Для времени, метки времени и типы данных интервала, содержащие компонент времени, дробная часть времени была усечена.

(Функция возвращает SQL_SUCCESS_WITH_INFO.)
07006 Нарушение атрибута ограниченного типа данных Значение данных столбца в результирующем наборе нельзя преобразовать в тип данных C, указанный аргументом TargetType.
07009 Недопустимый индекс дескриптора Для аргумента Col_or_Param_Num задано значение 0, а для атрибута оператора SQL_ATTR_USE_BOOKMARKS задано значение SQL_UB_OFF.

Значение, указанное для аргумента Col_or_Param_Num , больше количества столбцов в результирующем наборе.

Значение Col_or_Param_Num не равно порядковой номеру параметра, доступного.

(DM) Указанный столбец привязан. Это описание не относится к драйверам, возвращающим битовую маску SQL_GD_BOUND для параметра SQL_GETDATA_EXTENSIONS в SQLGetInfo.

(DM) Число указанного столбца было меньше или равно числу самого высокого привязанного столбца. Это описание не относится к драйверам, возвращающим битовую маску SQL_GD_ANY_COLUMN для параметра SQL_GETDATA_EXTENSIONS в SQLGetInfo.

(DM) Приложение уже назвало SQLGetData для текущей строки; число столбцов, указанных в текущем вызове, было меньше числа столбцов, указанных в предыдущем вызове; драйвер не возвращает SQL_GD_ANY_ORDER битовую маску для параметра SQL_GETDATA_EXTENSIONS в SQLGetInfo.

(DM) Аргумент TargetType был SQL_ARD_TYPE, а запись дескриптора Col_or_Param_Num в ARD завершилась ошибкой проверки согласованности.

(DM) Аргумент TargetType был SQL_ARD_TYPE, а значение в поле SQL_DESC_COUNT ARD было меньше Col_or_Param_Num аргумента.
08S01 Сбой связи Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции.
22002 Переменная индикатора, требуемая, но не указанная StrLen_or_IndPtr был указателем NULL, а данные NULL были извлечены.
22003 Числовое значение вне диапазона Возвращая числовое значение (как числовое или строковое) для столбца, было бы вызвано усечением всей части (в отличие от дробной) части числа.

Дополнительные сведения см. в приложении D: Типы данных.
22007 Недопустимый формат datetime Столбец символов в результирующем наборе привязан к структуре даты, времени или метки времени C, а значение в столбце было недопустимой датой, временем или меткой времени соответственно. Дополнительные сведения см. в приложении D: Типы данных.
22012 Деление по нулю Значение из арифметического выражения, которое привело к делении на ноль, было возвращено.
22015 Переполнение поля интервала Назначение от точного числового или интервалного типа SQL к типу интервала C привело к потере значительных цифр в начале поля.

При возврате данных в тип C интервала не было представления значения типа SQL в типе интервала C.
22018 Недопустимое значение символа для спецификации приведения Столбец символов в результирующем наборе был возвращен в буфер C символов, а столбец содержал символ, для которого в наборе символов буфера не было представления.

Тип C был точным или приблизительным числом, датой и временем или типом данных интервала; Тип SQL столбца — символьный тип данных; значение в столбце не является допустимым литералом привязанного типа C.
24000 Недопустимое состояние курсора (DM) Функция была вызвана без первого вызова SQLFetch или SQLFetchScroll для размещения курсора в строке необходимых данных.

(DM) ОператорHandle находился в состоянии выполнения, но с оператором StatementHandle не было связано никакого результированного набора.

Курсор был открыт в операторе StatementHandle и SQLFetch или SQLFetchScroll, но курсор был размещен до начала результирующий набор или после окончания результирующий набор.
HY000 Общая ошибка Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере MessageText , описывает ошибку и ее причину.
HY001 Ошибка выделения памяти Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции.
HY003 Тип программы вне диапазона (DM) Аргумент TargetType не был допустимым типом данных, SQL_C_DEFAULT, SQL_ARD_TYPE (в случае получения данных столбца) или SQL_APD_TYPE (в случае получения данных параметров).

(DM) Аргумент Col_or_Param_Num был 0, и аргумент TargetType не был SQL_C_BOOKMARK для закладки фиксированной длины или SQL_C_VARBOOKMARK для закладки переменной длины.
HY008 Операция отменена Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана в операторе StatementHandle, а затем функция была вызвана снова на ОператорHandle.

Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана на ОператорHandle из другого потока в многопотоковом приложении, а затем функция была вызвана еще раз в StatementHandle.
HY009 Недопустимое использование указателя NULL (DM) Аргумент TargetValuePtr был пустым указателем.
HY010 Ошибка последовательности функций (DM) Указанный оператор StatementHandle не находился в состоянии выполнения. Функция была вызвана без первого вызова SQLExecDirect, SQLExecute или функции каталога.

(DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLGetData .

(DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов.

(DM) ОператорHandle находился в состоянии выполнения, но с оператором StatementHandle не было связано никакого результированного набора.

Вызов SQLExeceute, SQLExecDirect или SQLMoreResults вернулся SQL_PARAM_DATA_AVAILABLE, но SQLGetData был вызван вместо SQLParamData.
HY013 Ошибка управления памятью Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти.
HY090 Недопустимая длина строки или буфера (DM) Значение, указанное для аргумента BufferLength , было меньше 0.

Значение, указанное для аргумента BufferLength , было меньше 4, аргумент Col_or_Param_Num был задан как 0, а драйвером был драйвер ODBC 2*.x*.
HY109 Недопустимое положение курсора Курсор был размещен (SQLSetPos, SQLFetch, SQLFetchScroll или SQLBulkOperations) в строке, которая была удалена или не удалось получить.

Курсор был курсором только для пересылки, и размер набора строк был больше одного.
HY117 Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function.
HYC00 Необязательный компонент не реализован Драйвер или источник данных не поддерживает использование SQLGetData с несколькими строками в SQLFetchScroll. Это описание не относится к драйверам, возвращающим битовую маску SQL_GD_BLOCK для параметра SQL_GETDATA_EXTENSIONS в SQLGetInfo.

Драйвер или источник данных не поддерживает преобразование, указанное в сочетании аргумента TargetType и типа данных SQL соответствующего столбца. Эта ошибка применяется только в том случае, если тип данных SQL столбца сопоставлен с типом данных SQL для конкретного драйвера.

Драйвер поддерживает только 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) Драйвер, соответствующий ОператорHandle , не поддерживает функцию.
IM017 Опрос отключен в асинхронном режиме уведомлений При использовании модели уведомлений опрос отключается.
IM018 SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции.

Комментарии

SQLGetData возвращает данные в указанном столбце. SQLGetData можно вызывать только после получения одной или нескольких строк из результирующих наборов SQLFetch, SQLFetchScroll или SQLExtendedFetchFetch. Если данные переменной длины слишком большие для возврата в одном вызове SQLGetData (из-за ограничения в приложении), SQLGetData может получить его в частях. Можно привязать некоторые столбцы в строке и вызвать SQLGetData для других, хотя это связано с некоторыми ограничениями. Дополнительные сведения см. в разделе "Получение длинных данных".

Сведения об использовании SQLGetData с потоковыми выходными параметрами см. в разделе "Получение выходных параметров с помощью SQLGetData".

Использование SQLGetData

Если драйвер не поддерживает расширения в SQLGetData, функция может возвращать данные только для несвязанных столбцов с числом больше, чем последний привязанный столбец. Кроме того, в строке данных значение аргумента Col_or_Param_Num в каждом вызове SQLGetData должно быть больше или равно значению Col_or_Param_Num в предыдущем вызове; то есть данные должны быть получены в растущем порядке числа столбцов. Наконец, если расширения не поддерживаются, SQLGetData не может вызываться, если размер набора строк превышает 1.

Водители могут расслабить любой из этих ограничений. Чтобы определить, какие ограничения ослабляет драйвер, приложение вызывает SQLGetInfo с любым из следующих SQL_GETDATA_EXTENSIONS параметров:

  • SQL_GD_OUTPUT_PARAMS = SQLGetData можно вызывать для возврата значений выходных параметров. Дополнительные сведения см. в разделе Получение выходных параметров с помощью метода SQLGetData.

  • SQL_GD_ANY_COLUMN. Если этот параметр возвращается, SQLGetData можно вызывать для любого несвязанного столбца, в том числе до последнего привязанного столбца.

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

  • SQL_GD_BLOCK. Если этот параметр возвращается SQLGetInfo для SQL_GETDATA_EXTENSIONS InfoType, драйвер поддерживает вызовы SQLGetData , если размер набора строк превышает 1, а приложение может вызывать SQLSetPos с параметром SQL_POSITION, чтобы разместить курсор в правильной строке перед вызовом SQLGetData.

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

Существует два исключения этих ограничений и способность водителя расслабить их. Во-первых, SQLGetData никогда не следует вызывать для курсора только для пересылки, если размер набора строк превышает 1. Во-вторых, если драйвер поддерживает закладки, он всегда должен поддерживать возможность вызова SQLGetData для столбца 0, даже если приложения не позволяют приложениям вызывать SQLGetData для других столбцов до последнего привязанного столбца. (Если приложение работает с драйвером ODBC 2*.x*, SQLGetData успешно возвращает закладку при вызове с Col_or_Param_Num равно 0 после вызова SQLFetch. поскольку диспетчер драйверов ODBC 3*.x* сопоставляется с диспетчером драйверов SQLExtendedFetch с FetchOrientation SQL_FETCH_NEXT, а SQLGetData с Col_or_Param_Num 0 сопоставляется диспетчером драйверов ODBC 3*.x* с sqlGetStmtOption с fOption SQL_GET_BOOKMARK.)

SQLGetData нельзя использовать для извлечения закладки для строки, просто вставленной путем вызова SQLBulkOperations с параметром SQL_ADD, так как курсор не расположен в строке. Приложение может получить закладку для такой строки путем привязки столбца 0 перед вызовом SQLBulkOperations с SQL_ADD, в этом случае SQLBulkOperations возвращает закладку в связанном буфере. Затем SQLFetchScroll можно вызвать с помощью SQL_FETCH_BOOKMARK, чтобы изменить положение курсора в этой строке.

Если аргумент 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. Оно может задать для поля SQL_DESC_CONCISE_TYPE значение SQL_C_NUMERIC и вызвать SQLGetData с аргументом TargetType SQL_ARD_TYPE, что приведет к использованию значений точности и масштабирования в полях дескриптора.

Заметка

В ODBC 2*.x* приложения задают TargetType для SQL_C_DATE, SQL_C_TIME или SQL_C_TIMESTAMP, чтобы указать, что *TargetValuePtr — это структура даты, времени или метки времени. В ODBC 3*.x*приложения задают TargetType для SQL_C_TYPE_DATE, SQL_C_TYPE_TIME или SQL_C_TYPE_TIMESTAMP. При необходимости диспетчер драйверов создает соответствующие сопоставления на основе версии приложения и драйвера.

Получение данных переменной длины в частях

SQLGetData можно использовать для получения данных из столбца, содержащего данные переменной длины в частях, то есть если идентификатор типа данных SQL столбца SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_WCHAR, SQL_WVARCHAR, SQL_WLONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY или идентификатор драйвера для типа переменной длины.

Чтобы получить данные из столбца в частях, приложение вызывает SQLGetData несколько раз в последовательности для одного столбца. При каждом вызове SQLGetData возвращает следующую часть данных. Приложение выполняет повторное удаление частей, заботясь о том, чтобы удалить символ завершения null из промежуточных частей символов. Если для конца символа выделено больше данных для возврата или недостаточно буфера, SQLGetData возвращает SQL_SUCCESS_WITH_INFO и SQLSTATE 01004 (усеченные данные). При возвращении последней части данных SQLGetData возвращает SQL_SUCCESS. Ни SQL_NO_TOTAL, ни нулю не могут быть возвращены при последнем допустимом вызове для получения данных из столбца, так как приложение не сможет знать, сколько данных в буфере приложения допустимо. Если sqlGetData вызывается после этого, он возвращает SQL_NO_DATA. Дополнительные сведения см. в следующем разделе "Получение данных с помощью SQLGetData".

Закладки переменной длины можно возвращать в частях SQLGetData. Как и в случае с другими данными, вызов SQLGetData для возврата закладок переменной длины в частях вернет SQLSTATE 01004 (строковые данные, усеченные по правому краю) и SQL_SUCCESS_WITH_INFO при получении дополнительных данных. Это отличается от случая, когда закладка переменной длины усечена вызовом SQLFetch или SQLFetchScroll, который возвращает SQL_ERROR и SQLSTATE 22001 (строковые данные, усекаются право).

SQLGetData нельзя использовать для возврата данных фиксированной длины в частях. Если SQLGetData вызывается несколько раз в строке для столбца, содержащего данные фиксированной длины, он возвращает SQL_NO_DATA для всех вызовов после первого вызова.

Получение потоковых выходных параметров

Если драйвер поддерживает потоковые выходные параметры, приложение может вызывать SQLGetData с небольшим буфером много раз, чтобы получить большое значение параметра. Дополнительные сведения о потоковых выходных параметрах см. в разделе "Получение выходных параметров с помощью SQLGetData".

Получение данных с помощью SQLGetData

Чтобы вернуть данные для указанного столбца, SQLGetData выполняет следующую последовательность действий:

  1. Возвращает SQL_NO_DATA, если он уже вернул все данные для столбца.

  2. Задает значение *StrLen_or_IndPtr значение SQL_NULL_DATA , если данные равно NULL. Если данные равно NULL и StrLen_or_IndPtr был указателем NULL, SQLGetData возвращает SQLSTATE 22002 (переменная индикатора, требуемая, но не указана).

    Если данные для столбца не равно NULL, SQLGetData переходит к шагу 3.

  3. Если атрибут инструкции SQL_ATTR_MAX_LENGTH имеет значение, отличное от нуля, если столбец содержит символьные или двоичные данные, а если SQLGetData не был вызван для столбца, данные усечены до SQL_ATTR_MAX_LENGTH байтов.

    Заметка

    Атрибут оператора SQL_ATTR_MAX_LENGTH предназначен для уменьшения сетевого трафика. Обычно он реализуется источником данных, который усечение данных перед возвратом данных через сеть. Для поддержки драйверов и источников данных не требуется. Таким образом, чтобы гарантировать усечение данных до определенного размера, приложение должно выделить буфер этого размера и указать размер в аргументе BufferLength .

  4. Преобразует данные в тип, указанный в TargetType. Данные получают точность и масштаб по умолчанию для этого типа данных. Если TargetType SQL_ARD_TYPE, используется тип данных в поле SQL_DESC_CONCISE_TYPE ARD. Если targetType SQL_ARD_TYPE, данные получают точность и масштаб в полях SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION и SQL_DESC_SCALE ARD в зависимости от типа данных в поле SQL_DESC_CONCISE_TYPE. Если какая-либо точность или масштаб по умолчанию не подходит, приложение должно явно задать соответствующее поле дескриптора вызовом SQLSetDescField или SQLSetDescRec.

  5. Если данные были преобразованы в тип данных переменной длины, например символ или двоичный файл, SQLGetData проверяет, превышает ли длина данных BufferLength. Если длина символьных данных (включая символ завершения null) превышает BufferLength, SQLGetData усечает данные в BufferLength меньше длины символа завершения null. Затем он завершает данные с пустым значением. Если длина двоичных данных превышает длину буфера данных, SQLGetData усечает его до байтов BufferLength .

    Если предоставленный буфер данных слишком мал для хранения символа завершения null, SQLGetData возвращает SQL_SUCCESS_WITH_INFO и SQLSTATE 01004.

    SQLGetData никогда не усечение данных, преобразованных в типы данных фиксированной длины; всегда предполагается, что длина *TargetValuePtr — это размер типа данных.

  6. Помещает преобразованные (и, возможно, усеченные) данные в *TargetValuePtr. Обратите внимание, что SQLGetData не может возвращать данные из строки.

  7. Помещает длину данных в *StrLen_or_IndPtr. Если StrLen_or_IndPtr был указателем null, SQLGetData не возвращает длину.

    • Для символьных или двоичных данных это длина данных после преобразования и перед усечением из-за BufferLength. Если драйвер не может определить длину данных после преобразования, как и в некоторых случаях с длинными данными, он возвращает SQL_SUCCESS_WITH_INFO и задает длину SQL_NO_TOTAL. (Последний вызов SQLGetData всегда должен возвращать длину данных, а не ноль или SQL_NO_TOTAL.) Если данные были усечены из-за атрибута оператора SQL_ATTR_MAX_LENGTH, значение этого атрибута ( в отличие от фактической длины) помещается в *StrLen_or_IndPtr. Это связано с тем, что этот атрибут предназначен для усечения данных на сервере перед преобразованием, поэтому драйвер не может определить фактическую длину. Если SQLGetData вызывается несколько раз в последовательности для одного столбца, это длина данных, доступных в начале текущего вызова, то есть длина уменьшается при каждом последующем вызове.

    • Для всех других типов данных это длина данных после преобразования; То есть это размер типа, в который были преобразованы данные.

  8. Если данные усечены без потери значения во время преобразования (например, реальное число 1.234 усечено при преобразовании в целочисленное число 1) или так как BufferLength слишком мал (например, строка abcdef помещается в буфер 4-байтов), SQLGetData возвращает SQLSTATE 01004 (усеченные данные) и SQL_SUCCESS_WITH_INFO. Если данные усечены без потери значения из-за атрибута инструкции SQL_ATTR_MAX_LENGTH, SQLGetData возвращает SQL_SUCCESS и не возвращает SQLSTATE 01004 (усечено данных).

Содержимое связанного буфера данных (если SQLGetData вызывается в привязанном столбце) и буфер длины или индикатора не определен, если SQLGetData не возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO.

Последовательные вызовы SQLGetData извлекают данные из последнего запрошенного столбца. Предыдущие смещения становятся недопустимыми. Например, при выполнении следующей последовательности:

SQLGetData(icol=n), SQLGetData(icol=m), SQLGetData(icol=n)  

Второй вызов SQLGetData(icol=n) извлекает данные из начала n столбца. Любое смещение в данных из-за более ранних вызовов SQLGetData для столбца больше не является допустимым.

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

SQLGetData не взаимодействует напрямую с полями дескриптора.

Если TargetType SQL_ARD_TYPE, используется тип данных в поле SQL_DESC_CONCISE_TYPE ARD. Если TargetType имеет значение SQL_ARD_TYPE или SQL_C_DEFAULT, данные получают точность и масштаб в полях SQL_DESC_DATETIME_INTERVAL_PRECISION, SQL_DESC_PRECISION и SQL_DESC_SCALE ARD в зависимости от типа данных в поле SQL_DESC_CONCISE_TYPE.

Пример кода

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

#define NAME_LEN 50  
#define PHONE_LEN 50  
  
SQLCHAR      szName[NAME_LEN], szPhone[PHONE_LEN];  
SQLINTEGER   sCustID, cbName, cbAge, cbBirthday;  
SQLRETURN    retcode;  
SQLHSTMT     hstmt;  
  
retcode = SQLExecDirect(hstmt,  
   "SELECT CUSTID, NAME, PHONE FROM CUSTOMERS ORDER BY 2, 1, 3",  
   SQL_NTS);  
  
if (retcode == SQL_SUCCESS) {  
   while (TRUE) {  
      retcode = SQLFetch(hstmt);  
      if (retcode == SQL_ERROR || retcode == SQL_SUCCESS_WITH_INFO) {  
         show_error();  
      }  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO){  
  
         /* Get data for columns 1, 2, and 3 */  
  
         SQLGetData(hstmt, 1, SQL_C_ULONG, &sCustID, 0, &cbCustID);  
         SQLGetData(hstmt, 2, SQL_C_CHAR, szName, NAME_LEN, &cbName);  
         SQLGetData(hstmt, 3, SQL_C_CHAR, szPhone, PHONE_LEN,  
            &cbPhone);  
  
         /* Print the row of data */  
  
         fprintf(out, "%-5d %-*s %*s", sCustID, NAME_LEN-1, szName,   
            PHONE_LEN-1, szPhone);  
      } else {  
         break;  
      }  
   }  
}  
Сведения Раздел
Назначение хранилища столбца в результирующем наборе SQLBindCol
Выполнение массовых операций, не связанных с положением курсора блока SQLBulkOperations
Отмена обработки инструкций SQLCancel
Выполнение инструкции SQL SQLExecDirect
Выполнение подготовленной инструкции SQL SQLExecute
Получение блока данных или прокрутка результирующий набор SQLFetchScroll
Получение одной строки данных или блока данных в направлении только для пересылки SQLFetch
Отправка данных параметров во время выполнения SQLPutData
Размещение курсора, обновление данных в наборе строк или обновление или удаление данных в наборе строк Sqlsetpos

См. также

Справочник по API ODBC
Файлы заголовков ODBC
Получение выходных параметров с помощью метода SQLGetData