Функция SQLFetch
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: ISO 92
Сводка
SQLFetch получает следующий набор строк данных из результирующего набора и возвращает данные для всех привязанных столбцов.
Синтаксис
SQLRETURN SQLFetch(
SQLHSTMT StatementHandle);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
При возврате sqlFetch SQL_ERROR или SQL_SUCCESS_WITH_INFO связанное значение SQLSTATE можно получить путем вызова функции SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и дескриптора инструкцииHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLFetch и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное. Если ошибка возникает в одном столбце, sqlGetDiagField можно вызвать с помощью DiagIdentifier SQL_DIAG_COLUMN_NUMBER, чтобы определить столбец, в котором произошла ошибка; и SQLGetDiagField можно вызвать с помощью DiagIdentifier SQL_DIAG_ROW_NUMBER, чтобы определить строку, содержащую этот столбец.
Для всех этих SQLSTATEs, которые могут возвращать SQL_SUCCESS_WITH_INFO или SQL_ERROR (кроме 01xxx SQLSTATEs), SQL_SUCCESS_WITH_INFO возвращается, если ошибка возникает в одной или нескольких строках многострочных операций и SQL_ERROR возвращается, если ошибка возникает при однострочной операции.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01004 | Строковые данные, усеченные справа | Строковые или двоичные данные, возвращаемые для столбца, привели к усечению небланковых символов или двоичных данных, отличных от NULL. Если это строковое значение, оно было усечено по правому краю. |
| 01S01 | Ошибка в строке | Произошла ошибка при выборе одной или нескольких строк. (Если этот SQLSTATE возвращается, когда приложение ODBC 3*.x* работает с драйвером ODBC 2*.x*, его можно игнорировать.) |
| 01S07 | Дробное усечение | Данные, возвращаемые для столбца, были усечены. Для числовых типов данных дробная часть числа была усечена. Для времени, метки времени и типы данных интервала, содержащие компонент времени, дробная часть времени была усечена. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 07006 | Нарушение атрибута ограниченного типа данных | Не удалось преобразовать значение данных столбца в результирующем наборе в тип данных, указанный TargetType в SQLBindCol. Столбец 0 привязан к типу данных SQL_C_BOOKMARK, а для атрибута оператора SQL_ATTR_USE_BOOKMARKS задано значение SQL_UB_VARIABLE. Столбец 0 привязан к типу данных SQL_C_VARBOOKMARK, а атрибут инструкции SQL_ATTR_USE_BOOKMARKS не был задан для SQL_UB_VARIABLE. |
| 07009 | Недопустимый индекс дескриптора | Драйвером был драйвер ODBC 2*.x*, который не поддерживает SQLExtendedFetch, а номер столбца, указанный в привязке для столбца, был 0. Столбец 0 привязан, а для атрибута оператора SQL_ATTR_USE_BOOKMARKS задано значение SQL_UB_OFF. |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции. |
| 22001 | Строковые данные, усеченные справа | Закладка переменной длины, возвращенная для столбца, была усечена. |
| 22002 | Переменная индикатора, требуемая, но не указанная | Данные NULL извлеклись в столбец, StrLen_or_IndPtr заданный SQLBindCol (или SQL_DESC_INDICATOR_PTR заданный SQLSetDescField или SQLSetDescRec) был указателем null. |
| 22003 | Числовое значение вне диапазона | Возвращая числовое значение как числовое или строковое для одного или нескольких ограничивающих столбцов, было бы вызвано усечением всей части (в отличие от дробной) части числа. Дополнительные сведения см. в разделе "Преобразование данных из SQL в типы данных C" в приложении D: Типы данных. |
| 22007 | Недопустимый формат datetime | Столбец символов в результирующем наборе привязан к структуре даты, времени или метки времени, а значение в столбце было, соответственно, недопустимой датой, временем или меткой времени. |
| 22012 | Деление по нулю | Значение из арифметического выражения было возвращено, что привело к делении на нулю. |
| 22015 | Переполнение поля интервала | Назначение от точного числового или интервалного типа SQL к типу интервала C привело к потере значительных цифр в начале поля. При получении данных в тип C интервала не было представления значения типа SQL в типе C интервала. |
| 22018 | Недопустимое значение символа для спецификации приведения | Столбец символов в результирующем наборе привязан к буферу C символов, а столбец содержит символ, для которого не было представления в наборе символов буфера. Тип C был точным или приблизительным числом, датой и временем или типом данных интервала; Тип SQL столбца — символьный тип данных; значение в столбце не является допустимым литералом привязанного типа C. |
| 24000 | Недопустимое состояние курсора | Оператор StatementHandle находился в состоянии выполнения, но результирующий набор не был связан с оператором StatementHandle. |
| 40001 | Сбой сериализации | Транзакция, в которой была выполнена выборка, была прекращена, чтобы предотвратить взаимоблокировку. |
| 40003 | Неизвестное завершение инструкции | Связанное соединение завершилось сбоем во время выполнения этой функции, и состояние транзакции невозможно определить. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLGetDiagRec в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ОператораHandle. Функция SQLFetch была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция SQLFetch снова была вызвана на ОператорHandle. Или функция SQLFetch была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана на ОператорHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLFetch . (DM) SQLExecute, SQLExecDirect или SQLMoreResults был вызван для ОператораHandle и возвращен SQL_PARAM_DATA_AVAILABLE. Эта функция была вызвана до получения данных для всех потоковых параметров. (DM) Указанный оператор StatementHandle не находился в состоянии выполнения. Функция была вызвана без первого вызова SQLExecDirect, SQLExecute или функции каталога. (DM) асинхронно выполняющаяся функция (не эта) была вызвана для StatementHandle и по-прежнему выполнялась при вызове этой функции. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations или SQLSetPos были вызваны для ОператораHandle и возвращены SQL_NEED_DATA. Эта функция была вызвана до отправки данных для всех параметров выполнения или столбцов. (DM) SQLFetch был вызван для ОператораHandle после вызова SQLExtendedFetch и до вызова SQLFreeStmt с параметром SQL_CLOSE. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY090 | Недопустимая длина строки или буфера | Для атрибута оператора SQL_ATTR_USE_BOOKMARK задано значение SQL_UB_VARIABLE, а столбец 0 привязан к буферу, длина которого не равна максимальной длине закладки для этого результирующий набор. (Эта длина доступна в поле SQL_DESC_OCTET_LENGTH IRD и может быть получена путем вызова.SQLDescribeCol, SQLColAttribute или SQLGetDescField.) |
| HY107 | Значение строки вне диапазона | Значение, указанное атрибутом инструкции SQL_ATTR_CURSOR_TYPE, было SQL_CURSOR_KEYSET_DRIVEN, но значение, указанное с атрибутом инструкции SQL_ATTR_KEYSET_SIZE, было больше 0 и меньше значения, указанного атрибутом оператора SQL_ATTR_ROW_ARRAY_SIZE. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYC00 | Необязательный компонент не реализован | Драйвер или источник данных не поддерживает преобразование, указанное сочетанием TargetType в SQLBindCol и типом данных SQL соответствующего столбца. |
| HYT00 | Время ожидания истекло. | Срок ожидания запроса истек до того, как источник данных вернул запрошенный результирующий набор. Период времени ожидания задается через SQLSetStmtAttr, SQL_ATTR_QUERY_TIMEOUT. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
| IM017 | Опрос отключен в асинхронном режиме уведомлений | При использовании модели уведомлений опрос отключается. |
| IM018 | SQLCompleteAsync не был вызван для выполнения предыдущей асинхронной операции с этим дескриптором. | Если предыдущий вызов функции дескриптора возвращает SQL_STILL_EXECUTING и если включен режим уведомлений, sqlCompleteAsync должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Комментарии
SQLFetch возвращает следующий набор строк в результирующем наборе. Его можно вызывать только в то время, когда результирующий набор существует: то есть после вызова, создающего результирующий набор, и до закрытия курсора над результирующий набор. Если какие-либо столбцы привязаны, он возвращает данные в этих столбцах. Если приложение указало указатель на массив состояния строки или буфер, в котором возвращается количество строк, извлекаемых, SQLFetch также возвращает эти сведения. Вызовы SQLFetch могут быть смешанными с вызовами SQLFetchScroll, но не могут быть смешанными с вызовами SQLExtendedFetch. Дополнительные сведения см. в разделе "Получение строки данных".
Если приложение ODBC 3*.x* работает с драйвером ODBC 2*.x*, диспетчер драйверов сопоставляет вызовы SQLFetch с SQLExtendedFetch для драйвера ODBC 2*.x*, поддерживающего SQLExtendedFetch. Если драйвер ODBC 2*.x* не поддерживает SQLExtendedFetch, диспетчер драйверов сопоставляет вызовы SQLFetch к SQLFetch в драйвере ODBC 2*.x*, который может получить только одну строку.
Дополнительные сведения см. в разделе "Блокировать курсоры", "Прокручиваемые курсоры" и "Обратная совместимость " в приложении G. Рекомендации по драйверам для обеспечения обратной совместимости.
Размещение курсора
При создании результирующий набор курсор размещается перед началом результирующий набор. SQLFetch извлекает следующий набор строк. Это эквивалентно вызову SQLFetchScroll с набором FetchOrientation , равным SQL_FETCH_NEXT. Дополнительные сведения о курсорах см. в разделе "Курсоры " и "Блокировать курсоры".
Атрибут оператора SQL_ATTR_ROW_ARRAY_SIZE указывает количество строк в наборе строк. Если набор строк, извлекаемый SQLFetch , перекрывает конец результируемого набора, SQLFetch возвращает частичный набор строк. То есть, если S + R - 1 больше L, где S является начальной строкой набора строк, R — это размер набора строк, а L — последняя строка в результирующем наборе, то допустимы только первые строки - S + 1 набора строк. Остальные строки пусты и имеют состояние SQL_ROW_NOROW.
После возврата SQLFetch текущая строка является первой строкой набора строк.
Правила, перечисленные в следующей таблице, описывают расположение курсора после вызова SQLFetch на основе условий, перечисленных во второй таблице в этом разделе.
| Condition | Первая строка нового набора строк |
|---|---|
| Перед началом работы | 1 |
| CurrRowsetStart<= LastResultRow — RowsetSize[1] | CurrRowsetStart + RowsetSize[2] |
| CurrRowsetStart>LastResultRow — RowsetSize[1] | После окончания |
| После окончания | После окончания |
[1] Если размер набора строк изменяется между выборками, это размер набора строк, который использовался с предыдущим получением.
[2] Если размер набора строк изменяется между выборками, это размер набора строк, который использовался с новым получением.
| Представление | Значение |
|---|---|
| Перед началом работы | Курсор блока размещается перед началом результирующий набор. Если первая строка нового набора строк находится перед началом результирующий набор, SQLFetch возвращает SQL_NO_DATA. |
| После окончания | Курсор блока размещается после окончания результирующий набор. Если первая строка нового набора строк после окончания результирующий набор, SQLFetch возвращает SQL_NO_DATA. |
| CurrRowsetStart | Число первой строки в текущем наборе строк. |
| LastResultRow | Число последней строки в результирующем наборе. |
| RowsetSize | Размер набора строк. |
Например, предположим, что результирующий набор содержит 100 строк, а размер набора строк — 5. В следующей таблице показаны набор строк и код возврата, возвращаемый SQLFetch для разных начальных позиций.
| Текущий набор строк | Код возврата | Новый набор строк | # строк, извлекаемых |
|---|---|---|---|
| Перед началом работы | SQL_SUCCESS | От 1 до 5 | 5 |
| От 1 до 5 | SQL_SUCCESS | От 6 до 10 | 5 |
| 52–56 | SQL_SUCCESS | 57–61 | 5 |
| От 91 до 95 | SQL_SUCCESS | От 96 до 100 | 5 |
| 93–97 | SQL_SUCCESS | От 98 до 100. Строки 4 и 5 массива состояния строки имеют значение SQL_ROW_NOROW. | 3 |
| От 96 до 100 | SQL_NO_DATA | Нет. | 0 |
| От 99 до 100 | SQL_NO_DATA | Нет. | 0 |
| После окончания | SQL_NO_DATA | Нет. | 0 |
Возврат данных в привязанных столбцах
Так как SQLFetch возвращает каждую строку, она помещает данные для каждого привязанного столбца в буфере, привязанном к нему. Если столбцы не привязаны, SQLFetch не возвращает данные, но перемещает курсор блока вперед. Данные по-прежнему можно получить с помощью SQLGetData. Если курсор является многороувным курсором (т. е. SQL_ATTR_ROW_ARRAY_SIZE больше 1), sqlGetData можно вызывать только в том случае, если SQL_GD_BLOCK возвращается при вызове SQLGetInfo с SQL_GETDATA_EXTENSIONS InfoType. (Дополнительные сведения см. в разделе SQLGetData.)
Для каждого связанного столбца в строке SQLFetch выполняет следующие действия:
Задает буфер длины или индикатора для SQL_NULL_DATA и переходит к следующему столбцу, если данные равно NULL. Если данные не привязаны, а буфер длины или индикатора не привязан, SQLFetch возвращает SQLSTATE 22002 (переменная индикатора, требуемая, но не указана) для строки и переходит к следующей строке. Сведения о том, как определить адрес буфера длины или индикатора, см. в разделе "Буферные адреса" в SQLBindCol.
Если данные для столбца не являются NULL, SQLFetch переходит к шагу 2.
Если атрибут инструкции SQL_ATTR_MAX_LENGTH имеет значение, отличное от нуля, а столбец содержит символьные или двоичные данные, данные усечены до SQL_ATTR_MAX_LENGTH байтов.
Примечание.
Атрибут оператора SQL_ATTR_MAX_LENGTH предназначен для уменьшения сетевого трафика. Обычно он реализуется источником данных, который усечение данных перед возвратом данных по сети. Для поддержки драйверов и источников данных не требуется. Таким образом, чтобы гарантировать усечение данных до определенного размера, приложение должно выделить буфер этого размера и указать размер в аргументе cbValueMax в SQLBindCol.
Преобразует данные в тип, указанный TargetType в SQLBindCol.
Если данные были преобразованы в тип данных переменной длины, например символ или двоичный файл, SQLFetch проверяет, превышает ли длина буфера данных. Если длина символьных данных (включая символ завершения null) превышает длину буфера данных, SQLFetch усечает данные до длины буфера данных меньше длины символа завершения null. Затем он завершает данные с пустым значением. Если длина двоичных данных превышает длину буфера данных, SQLFetch усечет его до длины буфера данных. Длина буфера данных указывается с помощью BufferLength в SQLBindCol.
SQLFetch никогда не усечение данных, преобразованных в типы данных фиксированной длины; всегда предполагается, что длина буфера данных — это размер типа данных.
Помещает преобразованные (и, возможно, усеченные) данные в буфер данных. Сведения о том, как определить адрес буфера данных, см. в разделе "Буферные адреса" в SQLBindCol.
Помещает длину данных в буфер длины или индикатора. Если указатель индикатора и указатель длины были заданы для одного буфера (как вызов SQLBindCol ), длина записывается в буфер для допустимых данных и SQL_NULL_DATA записывается в буфер для данных NULL. Если буфер длины или индикатора не привязан, SQLFetch не возвращает длину.
Для символьных или двоичных данных это длина данных после преобразования и перед усечением из-за слишком малого буфера данных. Если драйвер не может определить длину данных после преобразования, как и в некоторых случаях с длинными данными, он задает длину для SQL_NO_TOTAL. Если данные были усечены из-за атрибута инструкции SQL_ATTR_MAX_LENGTH, значение этого атрибута помещается в буфер длины или индикатора вместо фактической длины. Это связано с тем, что этот атрибут предназначен для усечения данных на сервере перед преобразованием, поэтому драйвер не имеет способа выяснить, какая длина имеет фактическую длину.
Для всех других типов данных это длина данных после преобразования; То есть это размер типа, в который были преобразованы данные.
Сведения о том, как определить адрес буфера длины или индикатора, см. в разделе "Буферные адреса" в SQLBindCol.
Если данные усечены во время преобразования без потери значительных цифр (например, реальное число 1.234 усечено до целого числа 1 при преобразовании), SQLFetch возвращает SQLSTATE 01S07 (дробное усечение) и SQL_SUCCESS_WITH_INFO. Если данные усечены, так как длина буфера данных слишком мала (например, строка abcdef помещается в буфер 4-байтов), SQLFetch возвращает SQLSTATE 01004 (усеченные данные) и SQL_SUCCESS_WITH_INFO. Если данные усечены из-за атрибута инструкции SQL_ATTR_MAX_LENGTH, SQLFetch возвращает SQL_SUCCESS и не возвращает SQLSTATE 01S07 (дробное усечение) или SQLSTATE 01004 (усечение данных). Если данные усечены во время преобразования со значительными цифрами (например, если значение SQL_INTEGER больше 100 000 было преобразовано в SQL_C_TINYINT), SQLFetch возвращает SQLSTATE 22003 (числовое значение вне диапазона) и SQL_ERROR (если размер набора строк равен 1) или SQL_SUCCESS_WITH_INFO (если размер набора строк больше 1).
Содержимое связанного буфера данных и буфера длины или индикатора не определено, если SQLFetch или SQLFetchScroll не возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO.
Массив статусов строк
Массив состояния строки используется для возврата состояния каждой строки в наборе строк. Адрес этого массива указан атрибутом оператора SQL_ATTR_ROW_STATUS_PTR. Массив выделяется приложением и должен содержать столько элементов, сколько указано атрибутом инструкции SQL_ATTR_ROW_ARRAY_SIZE. Его значения задаются SQLFetch, SQLFetchScroll и SQLBulkOperations или SQLSetPos (за исключением случаев, когда они были вызваны после размещения курсора SQLExtendedFetch). Если значение атрибута инструкции SQL_ATTR_ROW_STATUS_PTR является пустым указателем, эти функции не возвращают состояние строки.
Содержимое буфера массива состояния строки не определено, если SQLFetch или SQLFetchScroll не возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO.
Следующие значения возвращаются в массиве состояния строки.
| Значение массива состояния строк | Description |
|---|---|
| SQL_ROW_SUCCESS | Строка была успешно получена и не изменилась с тех пор, как она была получена из этого результированного набора. |
| SQL_ROW_SUCCESS_WITH_INFO | Строка была успешно получена и не изменилась с тех пор, как она была получена из этого результированного набора. Однако предупреждение было возвращено о строке. |
| SQL_ROW_ERROR | Произошла ошибка при выборе строки. |
| SQL_ROW_UPDATED[1],[2], [3] | Строка была успешно получена и изменена с момента последнего получения из этого результированного набора. Если строка снова извлекается из этого результированного набора или обновляется SQLSetPos, состояние изменяется на новое состояние строки. |
| SQL_ROW_DELETED[3] | Строка была удалена с момента последнего получения из этого результированного набора. |
| SQL_ROW_ADDED[4] | Строка была вставлена SQLBulkOperations. Если строка снова извлекается из этого результированного набора или обновляется SQLSetPos, его состояние SQL_ROW_SUCCESS. |
| SQL_ROW_NOROW | Набор строк перекрывал конец результирующий набор, и строка не была возвращена, соответствующая этому элементу массива состояния строки. |
[1] Для набора ключей, смешанных и динамических курсоров, если значение ключа обновляется, строка данных считается удаленной и добавлена новая строка.
[2] Некоторые драйверы не могут обнаруживать обновления данных и поэтому не могут возвращать это значение. Чтобы определить, может ли драйвер обнаруживать обновления для ссылок на строки, приложение вызывает SQLGetInfo с параметром SQL_ROW_UPDATES.
[3] SQLFetch может возвращать это значение только в том случае, если оно перемешано с вызовами SQLFetchScroll. Это связано с тем, что SQLFetch перемещается вперед через результирующий набор и когда он используется исключительно, не получает никаких ссылок на строки. Так как строки не перенаправляются, SQLFetch не обнаруживает изменения, внесенные в ранее созданные строки. Однако если SQLFetchScroll помещает курсор перед любыми ранее извлекаемых строк и SQLFetch используется для получения этих строк, SQLFetch может обнаружить любые изменения этих строк.
[4] Возвращается только SQLBulkOperations. Не заданы SQLFetch или SQLFetchScroll.
Извлекаемый буфер строк
Извлекаемый буфер строк используется для возврата количества извлекаемых строк, включая строки, для которых данные не были возвращены, так как произошла ошибка при их выборке. Другими словами, это количество строк, для которых значение в массиве состояния строки не SQL_ROW_NOROW. Адрес этого буфера указывается с помощью атрибута инструкции SQL_ATTR_ROWS_FETCHED_PTR. Буфер выделяется приложением. Он устанавливается SQLFetch и SQLFetchScroll. Если значение атрибута оператора SQL_ATTR_ROWS_FETCHED_PTR является указателем null, эти функции не возвращают количество строк, извлекаемых. Чтобы определить количество текущей строки в результирующем наборе, приложение может вызвать SQLGetStmtAttr с атрибутом SQL_ATTR_ROW_NUMBER.
Содержимое буфера, извлекаемого строк, не определено, если SQLFetch или SQLFetchScroll не возвращает SQL_SUCCESS или SQL_SUCCESS_WITH_INFO, за исключением случаев, когда возвращается SQL_NO_DATA, в этом случае значение в буфере получения строк имеет значение 0.
Обработка ошибок
Ошибки и предупреждения могут применяться к отдельным строкам или ко всей функции. Дополнительные сведения о диагностических записях см. в разделе "Диагностика " и "SQLGetDiagField".
Ошибки и предупреждения для всей функции
Если ошибка применяется ко всей функции, например SQLSTATE HYT00 (истекло время ожидания) или SQLSTATE 24000 (недопустимое состояние курсора), SQLFetch возвращает SQL_ERROR и применимое значение SQLSTATE. Содержимое буферов набора строк не определено, а положение курсора не изменяется.
Если предупреждение применяется ко всей функции, SQLFetch возвращает SQL_SUCCESS_WITH_INFO и применимое значение SQLSTATE. Записи состояния для предупреждений, которые применяются ко всей функции, возвращаются до записей состояния, которые применяются к отдельным строкам.
Ошибки и предупреждения в отдельных строках
Если ошибка (например, SQLSTATE 22012 (деление по нулю)) или предупреждение (например, SQLSTATE 01004 (усечение данных)) применяется к одной строке, SQLFetchвыполняет следующее:
Задает соответствующий элемент массива состояния строки SQL_ROW_ERROR для ошибок или SQL_ROW_SUCCESS_WITH_INFO для предупреждений.
Добавляет ноль или больше записей состояния, содержащих SQLSTATEs для ошибки или предупреждения.
Задает поля строк и столбцов в записях состояния. Если sqlFetch не может определить номер строки или столбца, он задает это число для SQL_ROW_NUMBER_UNKNOWN или SQL_COLUMN_NUMBER_UNKNOWN соответственно. Если запись состояния не применяется к определенному столбцу, SQLFetch задает номер столбца для SQL_NO_COLUMN_NUMBER.
SQLFetch продолжает получение строк до тех пор, пока он не извлекает все строки в наборе строк. Он возвращает SQL_SUCCESS_WITH_INFO, если ошибка не возникает в каждой строке набора строк (не включая строки с состоянием SQL_ROW_NOROW), в этом случае возвращается SQL_ERROR. В частности, если размер набора строк равен 1, а ошибка возникает в этой строке, SQLFetch возвращает SQL_ERROR.
SQLFetch возвращает записи состояния в порядке номера строки. То есть возвращает все записи состояния для неизвестных строк (если таковые есть); далее он возвращает все записи состояния для первой строки (если есть), а затем возвращает все записи состояния для второй строки (если таковые есть) и т. д. Записи состояния для каждой строки упорядочены в соответствии с обычными правилами для упорядочивания записей состояния; Дополнительные сведения см. в разделе "Последовательность записей состояния" в SQLGetDiagField.
Дескрипторы и SQLFetch
В следующих разделах описывается взаимодействие SQLFetch с дескрипторами.
Сопоставления аргументов
Драйвер не задает поля дескриптора на основе аргументов SQLFetch.
Другие поля дескриптора
Следующие поля дескриптора используются SQLFetch.
| Поле дескриптора | Desc. | Поле в | Настройка с помощью |
|---|---|---|---|
| SQL_DESC_ARRAY_SIZE | ARD | авторизации | Атрибут оператора SQL_ATTR_ROW_ARRAY_SIZE |
| SQL_DESC_ARRAY_STATUS_PTR | IRD | авторизации | Атрибут инструкции SQL_ATTR_ROW_STATUS_PTR |
| SQL_DESC_BIND_OFFSET_PTR | ARD | авторизации | атрибут оператора SQL_ATTR_ROW_BIND_OFFSET_PTR |
| SQL_DESC_BIND_TYPE | ARD | авторизации | атрибут оператора SQL_ATTR_ROW_BIND_TYPE |
| SQL_DESC_COUNT | ARD | авторизации | Аргумент ColumnNumber sqlBindCol |
| SQL_DESC_DATA_PTR | ARD | записи | Аргумент TargetValuePtr sqlBindCol |
| SQL_DESC_INDICATOR_PTR | ARD | записи | аргумент StrLen_or_IndPtr в SQLBindCol |
| SQL_DESC_OCTET_LENGTH | ARD | записи | Аргумент BufferLength в SQLBindCol |
| SQL_DESC_OCTET_LENGTH_PTR | ARD | записи | аргумент StrLen_or_IndPtr в SQLBindCol |
| SQL_DESC_ROWS_PROCESSED_PTR | IRD | авторизации | атрибут оператора SQL_ATTR_ROWS_FETCHED_PTR |
| SQL_DESC_TYPE | ARD | записи | Аргумент TargetType в SQLBindCol |
Все поля дескриптора также можно задать с помощью SQLSetDescField.
Отдельные буферы длины и индикатора
Приложения могут привязать один буфер или два отдельных буфера, которые можно использовать для хранения значений длины и индикатора. Когда приложение вызывает SQLBindCol, драйвер задает поля SQL_DESC_OCTET_LENGTH_PTR и SQL_DESC_INDICATOR_PTR ARD на тот же адрес, который передается в аргументе StrLen_or_IndPtr . Когда приложение вызывает SQLSetDescField или SQLSetDescRec, оно может задать для этих двух полей разные адреса.
SQLFetch определяет, задано ли приложение отдельные буферы длины и индикатора. В этом случае, если данные не являются NULL, SQLFetch задает буфер индикатора значение 0 и возвращает длину в буфере длины. Если данные равно NULL, SQLFetch задает буфер индикатора для SQL_NULL_DATA и не изменяет буфер длины.
Пример кода
См. статью SQLBindCol, SQLColumns, SQLGetData и SQLProcedures.
Связанные функции
| Сведения | Смотрите |
|---|---|
| Привязка буфера к столбцу в результирующем наборе | Функция SQLBindCol |
| Отмена обработки инструкций | Функция SQLCancel |
| Возврат сведений о столбце в результирующем наборе | Функция SQLDescribeCol |
| Выполнение инструкции SQL | Функция SQLExecDirect |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |
| Получение блока данных или прокрутка результирующий набор | Функция SQLFetchScroll |
| Закрытие курсора в инструкции | Функция SQLFreeStmt |
| Извлечение части или всех столбцов данных | Функция SQLGetData |
| Возврат числа столбцов результирующего набора | Функция SQLNumResultCols |
| Подготовка инструкции для выполнения | Функция SQLPrepare |