Функция SQLExtendedFetch
Соответствие
Представлена версия: соответствие стандартам ODBC 1.0: не рекомендуется
Сводка
SQLExtendedFetch извлекает указанный набор строк данных из результирующего набора и возвращает данные для всех привязанных столбцов. Наборы строк можно указать в абсолютной или относительной позиции или по закладке.
Примечание.
В ODBC 3*.x*, SQLExtendedFetch заменен SQLFetchScroll. Приложения ODBC 3*.x* не должны вызывать SQLExtendedFetch. Вместо этого они должны вызывать SQLFetchScroll. Диспетчер драйверов сопоставляет SQLFetchScroll с SQLExtendedFetch при работе с драйвером ODBC 2*.x*. Драйверы ODBC 3*.x* должны поддерживать SQLExtendedFetch , если они хотят работать с приложениями ODBC 2*.x*, которые вызывают его. Дополнительные сведения см. в разделе "Комментарии" и "Блокируемые курсоры", "Прокручиваемые курсоры" и обратная совместимость в приложении G. Рекомендации по драйверам для обеспечения обратной совместимости.
Синтаксис
SQLRETURN SQLExtendedFetch(
SQLHSTMT StatementHandle,
SQLUSMALLINT FetchOrientation,
SQLLEN FetchOffset,
SQLULEN * RowCountPtr,
SQLUSMALLINT * RowStatusArray);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
FetchOrientation
[Входные данные] Тип получения. Это то же самое, что и FetchOrientation в SQLFetchScroll.
FetchOffset
[Входные данные] Число строк для получения. Это то же самое, что и FetchOffset в SQLFetchScroll, за исключением одного исключения. Если FetchOrientation SQL_FETCH_BOOKMARK, FetchOffset является закладкой фиксированной длины, а не смещением из закладки. Другими словами, SQLExtendedFetch извлекает закладку из этого аргумента, а не атрибут оператора SQL_ATTR_FETCH_BOOKMARK_PTR. Она не поддерживает закладки переменной длины и не поддерживает получение набора строк в смещение (кроме 0) из закладки.
RowCountPtr
[Выходные данные] Указатель на буфер, в котором возвращается количество строк, фактически извлекаемых. Этот буфер используется так же, как и буфер, указанный атрибутом инструкции SQL_ATTR_ROWS_FETCHED_PTR. Этот буфер используется только SQLExtendedFetch. Он не используется SQLFetch или SQLFetchScroll.
RowStatusArray
[Выходные данные] Указатель на массив, в котором возвращается состояние каждой строки. Этот массив используется так же, как массив, указанный атрибутом оператора SQL_ATTR_ROW_STATUS_PTR.
Однако адрес этого массива не хранится в поле SQL_DESC_STATUS_ARRAY_PTR в IRD. Кроме того, этот массив используется только SQLExtendedFetch и SQLBulkOperations с операцией SQL_ADD или SQLSetPos, когда он вызывается после SQLExtendedFetch. Он не используется SQLFetch или SQLFetchScroll, и он не используется SQLBulkOperations или SQLSetPos, когда они вызываются после SQLFetch или SQLFetchScroll. Он также не используется при вызове SQLBulkOperations с операцией SQL_ADD перед вызовом любой функции получения. Другими словами, он используется только в состоянии инструкции S7. Он не используется в инструкциях S5 или S6. Дополнительные сведения см. в разделе "Переходы инструкций " в приложении B: таблицы перехода состояния ODBC.
Приложения должны предоставлять допустимый указатель в аргументе RowStatusArray; если нет, поведение SQLExtendedFetch и поведение вызовов SQLBulkOperations или SQLSetPos после того, как курсор был размещен SQLExtendedFetch, не определены.
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Если SQLExtendedFetch возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLError. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLExtendedFetch и объясняются каждый из них в контексте этой функции. Нотация "(DM)" предшествует описаниям SQLSTATEs, возвращаемым диспетчером драйверов. Возвращаемый код, связанный с каждым значением SQLSTATE, SQL_ERROR, если не указано иное. Если ошибка возникает в одном столбце, SQLGetDiagField можно вызвать с помощью DiagIdentifier SQL_DIAG_COLUMN_NUMBER, чтобы определить столбец, в котором произошла ошибка; и SQLGetDiagField можно вызвать с помощью DiagIdentifier SQL_DIAG_ROW_NUMBER, чтобы определить строку, содержащую этот столбец.
| SQLSTATE | Ошибка | Описание |
|---|---|---|
| 01000 | Общее предупреждение | Информационное сообщение для конкретного драйвера. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01004 | Строковые данные, усеченные справа | Строковые или двоичные данные, возвращаемые для столбца, привели к усечению небланковых символов или двоичных данных, отличных от NULL. Если это строковое значение, оно было усечено по правому краю. Если это числовое значение, дробная часть числа была усечена. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S01 | Ошибка в строке | Произошла ошибка при выборе одной или нескольких строк. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S06 | Попытка получить, прежде чем результирующий набор вернул первый набор строк | Запрошенный набор строк перекрывал начало результирующих наборов, когда текущая позиция была за первой строкой, и значение FetchOrientation было SQL_PRIOR или FetchOrientation было SQL_RELATIVE с отрицательным значением FetchOffset, абсолютное значение которого было меньше или равно текущему SQL_ROWSET_SIZE. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 01S07 | Дробное усечение | Данные, возвращаемые для столбца, были усечены. Для числовых типов данных дробная часть числа была усечена. Для времени, метки времени и типы данных интервала, содержащие компонент времени, дробная часть времени была усечена. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 07006 | Нарушение атрибута ограниченного типа данных | Не удалось преобразовать значение данных в тип данных C, указанный TargetType в SQLBindCol. |
| 07009 | Недопустимый индекс дескриптора | Столбец 0 привязан к SQLBindCol, а атрибут инструкции SQL_ATTR_USE_BOOKMARKS был установлен на SQL_UB_OFF. |
| 08S01 | Сбой связи | Связь между драйвером и источником данных, к которому был подключен драйвер, произошел сбой до завершения обработки функции. |
| 22002 | Переменная индикатора, требуемая, но не указанная | Данные NULL извлеклись в столбец, StrLen_or_IndPtr заданный SQLBindCol был пустым указателем. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 22003 | Числовое значение вне диапазона | Возвращая числовое значение (как числовое или строковое) для одного или нескольких столбцов, было бы вызвано усечением всей части (в отличие от дробной) части числа. (Функция возвращает SQL_SUCCESS_WITH_INFO.) Дополнительные сведения см. в руководствах по типам данных интервала и числовых данных в приложении D: Типы данных. |
| 22007 | Недопустимый формат datetime | Столбец символов в результирующем наборе привязан к структуре даты, времени или метки времени, а значение в столбце было, соответственно, недопустимой датой, временем или меткой времени. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 22012 | Деление по нулю | Значение из арифметического выражения было возвращено, что привело к делении на нулю. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 22015 | Переполнение поля интервала | Назначение от точного числового или интервалного типа SQL к типу интервала C привело к потере значительных цифр в начале поля. При получении данных в тип C интервала не было представления значения типа SQL в типе C интервала. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 22018 | Недопустимое значение символа для спецификации приведения | Тип C был точным или приблизительным числом, датой и временем или типом данных интервала; Тип SQL столбца — символьный тип данных; значение в столбце не является допустимым литералом привязанного типа C. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 24000 | Недопустимое состояние курсора | ОператорHandle находился в состоянии выполнения, но результирующий набор не был связан с оператором StatementHandle. |
| HY000 | Общая ошибка | Произошла ошибка, для которой не было определенного SQLSTATE и для которого не было определено значение SQLSTATE для конкретной реализации. Сообщение об ошибке, возвращаемое SQLError в буфере *MessageText , описывает ошибку и ее причину. |
| HY001 | Ошибка выделения памяти | Драйверу не удалось выделить память, необходимую для поддержки выполнения или завершения функции. |
| HY008 | Операция отменена | Асинхронная обработка была включена для ОператораHandle. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана в операторе StatementHandle, а затем функция была вызвана снова на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLExtendedFetch . (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) SQLExtendedFetch был вызван для ИнструкцииHandle после вызова SQLFetch или SQLFetchScroll и до вызова SQLFreeStmt с параметром SQL_CLOSE. (DM) SQLBulkOperations был вызван для инструкции до вызова SQLFetch, SQLFetchScroll или SQLExtendedFetch , а затем sqlExtendedFetch был вызван до вызова SQLFreeStmt с параметром SQL_CLOSE. |
| HY013 | Ошибка управления памятью | Не удалось обработать вызов функции, так как к базовым объектам памяти не удалось получить доступ, возможно, из-за низкой памяти. |
| HY106 | Выборка типа вне диапазона | (DM) Значение, указанное для аргумента FetchOrientation , было недопустимым. (См. комментарии.) Аргумент FetchOrientation был SQL_FETCH_BOOKMARK, а для атрибута инструкции SQL_ATTR_USE_BOOKMARKS задано значение SQL_UB_OFF. Значение параметра оператора SQL_CURSOR_TYPE было SQL_CURSOR_FORWARD_ONLY, а значение аргумента FetchOrientation не было SQL_FETCH_NEXT. Аргумент FetchOrientation был SQL_FETCH_RESUME. |
| HY107 | Значение строки вне диапазона | Значение, указанное с параметром оператора SQL_CURSOR_TYPE, было SQL_CURSOR_KEYSET_DRIVEN, но значение, указанное атрибутом инструкции SQL_KEYSET_SIZE, было больше 0 и меньше значения, указанного атрибутом оператора SQL_ROWSET_SIZE. |
| HY111 | Недопустимое значение закладки | Аргумент FetchOrientation был SQL_FETCH_BOOKMARK, и закладка, указанная в аргументе FetchOffset , не была допустимой. |
| HY117 | Подключение приостановлено из-за неизвестного состояния транзакции. Разрешены только функции отключения и только для чтения. | (DM) Дополнительные сведения о приостановленном состоянии см. в статье SQLEndTran Function. |
| HYC00 | Необязательный компонент не реализован | Драйвер или источник данных не поддерживает указанный тип получения. Драйвер или источник данных не поддерживает преобразование, указанное сочетанием TargetType в SQLBindCol и типом данных SQL соответствующего столбца. Эта ошибка применяется только в том случае, если тип данных SQL столбца сопоставлен с типом данных SQL для конкретного драйвера. |
| HYT00 | Время ожидания истекло. | Срок ожидания запроса истек, прежде чем источник данных вернул результирующий набор. Период времени ожидания задается через SQLSetStmtOption, SQL_QUERY_TIMEOUT. |
| HYT01 | Время ожидания для подключения истекло | Срок ожидания подключения истек до того, как источник данных ответил на запрос. Период времени ожидания подключения задается через SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Драйвер не поддерживает эту функцию | (DM) Драйвер, связанный с StatementHandle , не поддерживает функцию. |
Комментарии
Поведение SQLExtendedFetch идентично поведению SQLFetchScroll со следующими исключениями:
SQLExtendedFetch и SQLFetchScroll используют различные методы для возврата количества строк, извлекаемых. SQLExtendedFetch возвращает количество строк, извлекаемых в *RowCountPtr; SQLFetchScroll возвращает количество строк, извлекаемых непосредственно в буфер, на который указывает SQL_ATTR_ROWS_FETCHED_PTR. Дополнительные сведения см. в аргументе RowCountPtr .
SQLExtendedFetch и SQLFetchScroll возвращают состояние каждой строки в разных массивах. Дополнительные сведения см. в аргументе RowStatusArray .
SQLExtendedFetch и SQLFetchScroll используют различные методы для получения закладки при SQL_FETCH_BOOKMARK FetchOrientation . SQLExtendedFetch не поддерживает закладки переменной длины или извлекает наборы строк в смещение, отличное от 0 из закладки. Дополнительные сведения см. в аргументе FetchOffset .
SQLExtendedFetch и SQLFetchScroll используют разные размеры набора строк. SQLExtendedFetch использует значение атрибута инструкции SQL_ROWSET_SIZE, а SQLFetchScroll использует значение атрибута инструкции SQL_ATTR_ROW_ARRAY_SIZE.
SQLExtendedFetch имеет немного отличается от семантики обработки ошибок, чем SQLFetchScroll. Дополнительные сведения см. в разделе "Обработка ошибок" в разделе "Комментарии" SQLFetchScroll.
SQLExtendedFetch не поддерживает смещения привязки (атрибут инструкции SQL_ATTR_ROW_BIND_OFFSET_PTR).
Вызовы SQLExtendedFetch не могут быть смешанными с вызовами SQLFetch или SQLFetchScroll, и если sqlBulkOperations вызывается перед вызовом любой функции получения, sqlExtendedFetch не может вызываться, пока курсор не будет закрыт и вновь открыт. То есть SQLExtendedFetch можно вызывать только в состоянии инструкции S7. Дополнительные сведения см. в разделе "Переходы инструкций " в приложении B: таблицы перехода состояния ODBC.
Когда приложение вызывает SQLFetchScroll при использовании драйвера ODBC 2*.x*, диспетчер драйверов сопоставляет этот вызов с SQLExtendedFetch. Дополнительные сведения см. в разделе "Драйверы SQLFetchScroll и ODBC 2*.x* в SQLFetchScroll.
В ODBC 2*.x* вызов SQLExtendedFetch был вызван для получения нескольких строк и SQLFetch был вызван для получения одной строки. С другой стороны, в ODBC 3*.x* можно вызвать SQLFetch , чтобы получить несколько строк.
Связанные функции
| Сведения | Смотрите |
|---|---|
| Привязка буфера к столбцу в результирующем наборе | Функция SQLBindCol |
| Выполнение операций массового вставки, обновления или удаления | Функция SQLBulkOperations |
| Отмена обработки инструкций | Функция SQLCancel |
| Возврат сведений о столбце в результирующем наборе | Функция SQLDescribeCol |
| Выполнение инструкции SQL | Функция SQLExecDirect |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |
| Возврат числа столбцов результирующего набора | Функция SQLNumResultCols |
| Размещение курсора, обновление данных в наборе строк или обновление или удаление данных в результирующем наборе | Функция SQLSetPos |
| Задание атрибута инструкции | Функция SQLSetStmtAttr |