Функция 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 выполняет следующую последовательность действий:
Возвращает SQL_NO_DATA, если он уже вернул все данные для столбца.
Задает значение *StrLen_or_IndPtr значение SQL_NULL_DATA , если данные равно NULL. Если данные равно NULL и StrLen_or_IndPtr был указателем NULL, SQLGetData возвращает SQLSTATE 22002 (переменная индикатора, требуемая, но не указана).
Если данные для столбца не равно NULL, SQLGetData переходит к шагу 3.
Если атрибут инструкции SQL_ATTR_MAX_LENGTH имеет значение, отличное от нуля, если столбец содержит символьные или двоичные данные, а если SQLGetData не был вызван для столбца, данные усечены до SQL_ATTR_MAX_LENGTH байтов.
Заметка
Атрибут оператора SQL_ATTR_MAX_LENGTH предназначен для уменьшения сетевого трафика. Обычно он реализуется источником данных, который усечение данных перед возвратом данных через сеть. Для поддержки драйверов и источников данных не требуется. Таким образом, чтобы гарантировать усечение данных до определенного размера, приложение должно выделить буфер этого размера и указать размер в аргументе BufferLength .
Преобразует данные в тип, указанный в 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.
Если данные были преобразованы в тип данных переменной длины, например символ или двоичный файл, SQLGetData проверяет, превышает ли длина данных BufferLength. Если длина символьных данных (включая символ завершения null) превышает BufferLength, SQLGetData усечает данные в BufferLength меньше длины символа завершения null. Затем он завершает данные с пустым значением. Если длина двоичных данных превышает длину буфера данных, SQLGetData усечает его до байтов BufferLength .
Если предоставленный буфер данных слишком мал для хранения символа завершения null, SQLGetData возвращает SQL_SUCCESS_WITH_INFO и SQLSTATE 01004.
SQLGetData никогда не усечение данных, преобразованных в типы данных фиксированной длины; всегда предполагается, что длина *TargetValuePtr — это размер типа данных.
Помещает преобразованные (и, возможно, усеченные) данные в *TargetValuePtr. Обратите внимание, что SQLGetData не может возвращать данные из строки.
Помещает длину данных в *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 вызывается несколько раз в последовательности для одного столбца, это длина данных, доступных в начале текущего вызова, то есть длина уменьшается при каждом последующем вызове.
Для всех других типов данных это длина данных после преобразования; То есть это размер типа, в который были преобразованы данные.
Если данные усечены без потери значения во время преобразования (например, реальное число 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