Функция SQLFetchScroll
Соответствие
Представлена версия: соответствие стандартам ODBC 3.0: ISO 92
Сводка
SQLFetchScroll извлекает указанный набор строк данных из результирующего набора и возвращает данные для всех привязанных столбцов. Наборы строк можно указать в абсолютной или относительной позиции или по закладке.
При работе с драйвером ODBC 2.x диспетчер драйверов сопоставляет эту функцию с SQLExtendedFetch. Дополнительные сведения см. в разделе "Функции замены сопоставления" для обеспечения обратной совместимости приложений.
Синтаксис
SQLRETURN SQLFetchScroll(
SQLHSTMT StatementHandle,
SQLSMALLINT FetchOrientation,
SQLLEN FetchOffset);
Аргументы
ОператорHandle
[Входные данные] Дескриптор инструкции.
FetchOrientation
[Входные данные]
Тип получения:
SQL_FETCH_NEXT
SQL_FETCH_PRIOR
SQL_FETCH_FIRST
SQL_FETCH_LAST
SQL_FETCH_ABSOLUTE
SQL_FETCH_RELATIVE
SQL_FETCH_BOOKMARK
Дополнительные сведения см. в разделе "Размещение курсора" в разделе "Комментарии".
FetchOffset
[Входные данные]
Число строк для получения. Интерпретация этого аргумента зависит от значения аргумента FetchOrientation . Дополнительные сведения см. в разделе "Размещение курсора" в разделе "Комментарии".
Возвраты
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR или SQL_INVALID_HANDLE.
Диагностика
Когда SQLFetchScroll возвращает SQL_ERROR или SQL_SUCCESS_WITH_INFO, связанное значение SQLSTATE можно получить путем вызова SQLGetDiagRec с помощью HandleType SQL_HANDLE_STMT и handle of StatementHandle. В следующей таблице перечислены значения SQLSTATE, которые обычно возвращаются SQLFetchScroll и объясняются каждый из них в контексте этой функции. Нотация "(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*, его можно игнорировать.) |
| 01S06 | Попытка получить, прежде чем результирующий набор вернул первый набор строк | Запрошенный набор строк перекрывал начало результирующий набор при SQL_FETCH_PRIOR FetchOrientation, текущее положение было за первой строкой, а число текущей строки меньше или равно размеру набора строк. Запрошенный набор строк перекрывал начало результирующий набор при SQL_FETCH_PRIOR FetchOrientation, текущая позиция была за пределами результирующих наборов, а размер набора строк превышает размер результированного набора. Запрошенный набор строк перекрывал начало результирующий набор, когда SQL_FETCH_RELATIVE FetchOrientation, FetchOffset был отрицательным, и абсолютное значение FetchOffset было меньше или равно размеру набора строк. Запрошенный набор строк перекрывал начало результирующий набор при SQL_FETCH_ABSOLUTE FetchOrientation, FetchOffset был отрицательным, и абсолютное значение FetchOffset было больше размера результированного набора, но меньше или равно размеру набора строк. (Функция возвращает SQL_SUCCESS_WITH_INFO.) |
| 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. Функция была вызвана и до завершения выполнения, SQLCancel или SQLCancelHandle была вызвана на ОператорHandle. Затем функция снова была вызвана на ОператорHandle. Функция была вызвана и до завершения выполнения SQLCancel или SQLCancelHandle была вызвана оператором StatementHandle из другого потока в многопотоковом приложении. |
| HY010 | Ошибка последовательности функций | (DM) Асинхронно выполняющаяся функция была вызвана для дескриптора соединения, связанного с ОператоромHandle. Эта асинхронная функция по-прежнему выполнялась при вызове функции SQLFetchScroll . (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.) |
| HY106 | Выборка типа вне диапазона | DM) Значение, указанное для аргумента FetchOrientation, было недопустимым. (DM) Аргумент FetchOrientation был SQL_FETCH_BOOKMARK, а для атрибута оператора SQL_ATTR_USE_BOOKMARKS задано значение SQL_UB_OFF. Значение атрибута оператора SQL_ATTR_CURSOR_TYPE было SQL_CURSOR_FORWARD_ONLY, а значение аргумента FetchOrientation не было SQL_FETCH_NEXT. Значение атрибута оператора SQL_ATTR_CURSOR_SCROLLABLE было SQL_NONSCROLLABLE, а значение аргумента FetchOrientation не SQL_FETCH_NEXT. |
| HY107 | Значение строки вне диапазона | Значение, указанное атрибутом инструкции SQL_ATTR_CURSOR_TYPE, было SQL_CURSOR_KEYSET_DRIVEN, но значение, указанное с атрибутом инструкции SQL_ATTR_KEYSET_SIZE, было больше 0 и меньше значения, указанного атрибутом оператора SQL_ATTR_ROW_ARRAY_SIZE. |
| HY111 | Недопустимое значение закладки | Аргумент FetchOrientation был SQL_FETCH_BOOKMARK, и закладка, на которую указывает значение в атрибуте инструкции SQL_ATTR_FETCH_BOOKMARK_PTR, недопустимо или было пустым указателем. |
| 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 должен вызываться на дескрипторе для выполнения последующей обработки и завершения операции. |
Комментарии
SQLFetchScroll возвращает указанный набор строк из результирующий набор. Наборы строк можно указать по абсолютной или относительной позиции или по закладке. SQLFetchScroll можно вызывать только в то время, когда результирующий набор существует , то есть после вызова, создающего результирующий набор, и до закрытия курсора над этим результирующий набор. Если какие-либо столбцы привязаны, он возвращает данные в этих столбцах. Если приложение указало указатель на массив состояния строки или буфер, в котором будет возвращено количество строк, извлекаемых, SQLFetchScroll также возвращает эти сведения. Вызовы SQLFetchScroll могут быть смешанными с вызовами SQLFetch, но не могут быть смешанными с вызовами SQLExtendedFetch.
Дополнительные сведения см. в разделе "Использование блочных курсоров " и "Использование прокручиваемых курсоров".
Размещение курсора
При создании результирующий набор курсор размещается перед началом результирующий набор. SQLFetchScroll размещает курсор блока на основе значений аргументов FetchOrientation и FetchOffset , как показано в следующей таблице. Точные правила определения начала нового набора строк показаны в следующем разделе.
| FetchOrientation | Значение |
|---|---|
| SQL_FETCH_NEXT | Возвращает следующий набор строк. Это эквивалентно вызову SQLFetch. SQLFetchScroll игнорирует значение FetchOffset. |
| SQL_FETCH_PRIOR | Возвращает предыдущий набор строк. SQLFetchScroll игнорирует значение FetchOffset. |
| SQL_FETCH_RELATIVE | Возвращает набор строк FetchOffset из начала текущего набора строк. |
| SQL_FETCH_ABSOLUTE | Возвращает набор строк, начиная с строки FetchOffset. |
| SQL_FETCH_FIRST | Возвращает первый набор строк в результирующем наборе. SQLFetchScroll игнорирует значение FetchOffset. |
| SQL_FETCH_LAST | Возвращает последний полный набор строк в результирующем наборе. SQLFetchScroll игнорирует значение FetchOffset. |
| SQL_FETCH_BOOKMARK | Возвращает строки набора строк FetchOffset из закладки, указанной атрибутом инструкции SQL_ATTR_FETCH_BOOKMARK_PTR. |
Драйверы не требуются для поддержки всех ориентаций получения; приложение вызывает SQLGetInfo с типом сведений SQL_DYNAMIC_CURSOR_ATTRIBUTES1, SQL_KEYSET_CURSOR_ATTRIBUTES1 или SQL_STATIC_CURSOR_ATTRIBUTES1 (в зависимости от типа курсора), чтобы определить, какие ориентации получения поддерживаются драйвером. Приложение должно просмотреть SQL_CA1_NEXT, SQL_CA1_RELATIVE, SQL_CA1_ABSOLUTE и WQL_CA1_BOOKMARK битовые маски в этих типах информации. Кроме того, если курсор доступен только для пересылки и FetchOrientation не SQL_FETCH_NEXT, SQLFetchScroll возвращает SQLSTATE HY106 (тип извлечения вне диапазона).
Атрибут оператора SQL_ATTR_ROW_ARRAY_SIZE указывает количество строк в наборе строк. Если набор строк, извлекаемый SQLFetchScroll , перекрывает конец результируемого набора, SQLFetchScroll возвращает частичный набор строк. То есть, если S + R - 1 больше L, где S является начальной строкой набора строк, R — это размер набора строк, а L — последняя строка в результирующем наборе, то допустимы только первые строки - S + 1 набора строк. Остальные строки пусты и имеют состояние SQL_ROW_NOROW.
После возврата SQLFetchScroll текущая строка является первой строкой набора строк.
Правила расположения курсоров
В следующих разделах описываются точные правила для каждого значения FetchOrientation. Эти правила используют следующую нотацию.
| Представление | Значение |
|---|---|
| Перед началом работы | Курсор блока размещается перед началом результирующий набор. Если первая строка нового набора строк находится перед началом результирующий набор, SQLFetchScroll возвращает SQL_NO_DATA. |
| После окончания | Курсор блока размещается после окончания результирующий набор. Если первая строка нового набора строк после окончания результирующий набор, SQLFetchScroll возвращает SQL_NO_DATA. |
| CurrRowsetStart | Число первой строки в текущем наборе строк. |
| LastResultRow | Число последней строки в результирующем наборе. |
| RowsetSize | Размер набора строк. |
| FetchOffset | Значение аргумента FetchOffset . |
| ЗакладкаRow | Строка, соответствующая закладке, указанной атрибутом инструкции SQL_ATTR_FETCH_BOOKMARK_PTR. |
SQL_FETCH_NEXT
Применяются следующие правила.
| Condition | Первая строка нового набора строк |
|---|---|
| Перед началом работы | 1 |
| CurrRowsetStart + RowsetSize[1] <= LastResultRow | CurrRowsetStart + RowsetSize[1] |
| CurrRowsetStart + RowsetSize[1]> LastResultRow | После окончания |
| После окончания | После окончания |
[1] Если размер набора строк был изменен с момента предыдущего вызова для получения строк, это размер набора строк, который использовался с предыдущим вызовом.
SQL_FETCH_PRIOR
Применяются следующие правила.
| Condition | Первая строка нового набора строк |
|---|---|
| Перед началом работы | Перед началом работы |
| CurrRowsetStart = 1 | Перед началом работы |
| 1 < CurrRowsetStart <= RowsetSize [2] | 1 [1] |
| CurrRowsetStart > RowsetSize [2] | CurrRowsetStart — RowsetSize [2] |
| После окончания И LastResultRow < RowsetSize [2] | 1 [1] |
| После окончания AND LastResultRow >= RowsetSize [2] | LastResultRow - RowsetSize + 1 [2] |
[1] SQLFetchScroll возвращает SQLSTATE 01S06 (попытка получить, прежде чем результирующий набор вернул первый набор строк) и SQL_SUCCESS_WITH_INFO.
[2] Если размер набора строк был изменен с момента предыдущего вызова получения строк, это новый размер набора строк.
SQL_FETCH_RELATIVE
Применяются следующие правила.
| Condition | Первая строка нового набора строк |
|---|---|
| (Перед запуском AND FetchOffset > 0) OR (после окончания И FetchOffset < 0) | --[1] |
| BeforeStart AND FetchOffset <= 0 | Перед началом работы |
| CurrRowsetStart = 1 AND FetchOffset < 0 | Перед началом работы |
| CurrRowsetStart 1 AND CurrRowsetStart > + FetchOffset < 1 AND | FetchOffset | > RowsetSize [3] | Перед началом работы |
| CurrRowsetStart 1 AND CurrRowsetStart > + FetchOffset < 1 AND | FetchOffset | <= RowsetSize [3] | 1 [2] |
| 1 <= CurrRowsetStart + FetchOffset <= LastResultRow | CurrRowsetStart + FetchOffset |
| CurrRowsetStart + FetchOffset > LastResultRowRow | После окончания |
| После окончания AND FetchOffset >= 0 | После окончания |
[1] SQLFetchScroll возвращает тот же набор строк, что и при вызове с параметром FetchOrientation, равным SQL_FETCH_ABSOLUTE. Дополнительные сведения см. в разделе "SQL_FETCH_ABSOLUTE".
[2] SQLFetchScroll возвращает SQLSTATE 01S06 (попытка получить, прежде чем результирующий набор вернул первый набор строк) и SQL_SUCCESS_WITH_INFO.
[3] Если размер набора строк был изменен с момента предыдущего вызова для получения строк, это новый размер набора строк.
SQL_FETCH_ABSOLUTE
Применяются следующие правила.
| Condition | Первая строка нового набора строк |
|---|---|
| FetchOffset < 0 AND | FetchOffset | <= LastResultRow | LastResultRow + FetchOffset + 1 |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | > RowsetSize [2] | Перед началом работы |
| FetchOffset < 0 AND | FetchOffset | > LastResultRow AND | FetchOffset | <= RowsetSize [2] | 1 [1] |
| FetchOffset = 0 | Перед началом работы |
| 1 <= FetchOffset <= LastResultRow | FetchOffset |
| FetchOffset > LastResultRow | После окончания |
[1] SQLFetchScroll возвращает SQLSTATE 01S06 (попытка получить, прежде чем результирующий набор вернул первый набор строк) и SQL_SUCCESS_WITH_INFO.
[2] Если размер набора строк был изменен с момента предыдущего вызова получения строк, это новый размер набора строк.
Абсолютная выборка, выполняемая для динамического курсора, не может обеспечить необходимый результат, так как позиции строк в динамическом курсоре не определены. Такая операция эквивалентна выборке, за которой следует относительный результат; Это не атомарная операция, как и абсолютное получение статического курсора.
SQL_FETCH_FIRST
Применяются следующие правила.
| Condition | Первая строка нового набора строк |
|---|---|
| Any | 1 |
SQL_FETCH_LAST
Применяются следующие правила.
| Condition | Первая строка нового набора строк |
|---|---|
| RowsetSize [1]<= LastResultRow | LastResultRow - RowsetSize + 1 [1] |
| RowsetSize [1]> LastResultRow | 1 |
[1] Если размер набора строк был изменен с момента предыдущего вызова получения строк, это новый размер набора строк.
SQL_FETCH_BOOKMARK
Применяются следующие правила.
| Condition | Первая строка нового набора строк |
|---|---|
| ЗакладкаRow + FetchOffset < 1 | Перед началом работы |
| 1 <= BookmarkRow + FetchOffset <= LastResultRow | ЗакладкаRow + FetchOffset |
| BookmarkRow + FetchOffset > LastResultRow | После окончания |
Сведения о закладках см. в разделе "Закладки" (ODBC).
Эффект удаленных, добавленных и ошибок при перемещении курсоров
Статические и управляемые набором ключей курсоры иногда обнаруживают строки, добавленные в результирующий набор, и удаляют строки, удаленные из результирующий набор. Вызывая SQLGetInfo с параметрами SQL_STATIC_CURSOR_ATTRIBUTES2 и SQL_KEYSET_CURSOR_ATTRIBUTES2 и просматривая SQL_CA2_SENSITIVITY_ADDITIONS, SQL_CA2_SENSITIVITY_DELETIONS и SQL_CA2_SENSITIVITY_UPDATES битовые маски, приложение определяет, выполняются ли курсоры определенным драйвером. Для драйверов, которые могут обнаруживать удаленные строки и удалять их, в следующих абзацах описываются последствия этого поведения. Для драйверов, которые могут обнаруживать удаленные строки, но не могут их удалить, удаления не влияют на движения курсоров, а следующие абзацы не применяются.
Если курсор обнаруживает строки, добавленные в результирующий набор, или удаляет строки, удаленные из результирующий набор, он отображается так, как если он обнаруживает эти изменения только при получении данных. Это включает в себя случай, когда sqlFetchScroll вызывается с параметром FetchOrientation, равным SQL_FETCH_RELATIVE и FetchOffset, равным 0, для ссылки на тот же набор строк, но не включает случай, когда SQLSetPos вызывается с набором fOption, равным SQL_REFRESH. В последнем случае данные в буферах набора строк обновляются, но не возвращаются, а удаленные строки не удаляются из результированного набора. Таким образом, при удалении или вставке строки в текущий набор строк курсор не изменяет буферы набора строк. Вместо этого он обнаруживает изменение при получении любого набора строк, который ранее включал удаленную строку или теперь включает вставленную строку.
Например:
// Fetch the next rowset.
SQLFetchScroll(hstmt, SQL_FETCH_NEXT, 0);
// Delete third row of the rowset. Does not modify the rowset buffers.
SQLSetPos(hstmt, 3, SQL_DELETE, SQL_LOCK_NO_CHANGE);
// The third row has a status of SQL_ROW_DELETED after this call.
SQLSetPos(hstmt, 3, SQL_REFRESH, SQL_LOCK_NO_CHANGE);
// Refetch the same rowset. The third row is removed, replaced by what
// was previously the fourth row.
SQLFetchScroll(hstmt, SQL_FETCH_RELATIVE, 0);
Когда SQLFetchScroll возвращает новый набор строк, имеющий позицию относительно текущего набора строк, то есть FetchOrientation SQL_FETCH_NEXT, SQL_FETCH_PRIOR или SQL_FETCH_RELATIVE — он не включает изменения в текущий набор строк при вычислении начальной позиции нового набора строк. Однако он включает изменения за пределами текущего набора строк, если он способен обнаруживать их. Кроме того, если SQLFetchScroll возвращает новый набор строк, который имеет позицию независимо от текущего набора строк, то есть FetchOrientation SQL_FETCH_FIRST, SQL_FETCH_LAST, SQL_FETCH_ABSOLUTE или SQL_FETCH_BOOKMARK — включает все изменения, которые он может обнаруживать, даже если они находятся в текущем наборе строк.
При определении того, находятся ли недавно добавленные строки внутри или за пределами текущего набора строк, частичный набор строк считается конечным в последней допустимой строке; То есть последняя строка, для которой состояние строки не SQL_ROW_NOROW. Например, предположим, что курсор может обнаруживать только что добавленные строки, текущий набор строк является частичным набором строк, приложение добавляет новые строки, а курсор добавляет эти строки в конец результирующий набор. Если приложение вызывает SQLFetchScroll с набором FetchOrientation для SQL_FETCH_NEXT, SQLFetchScroll возвращает набор строк, начиная с первой добавленной строки.
Например, предположим, что текущий набор строк состоит из строк 21–30, размер набора строк равен 10, курсор удаляет строки, удаленные из результирующий набор, и курсор обнаруживает строки, добавленные в результирующий набор. В следующей таблице показаны строки SQLFetchScroll в различных ситуациях.
| Изменение | Тип получения | FetchOffset | Новый набор строк[1] |
|---|---|---|---|
| Удаление строки 21 | ДАЛЕЕ | 0 | От 31 до 40 |
| Удаление строки 31 | ДАЛЕЕ | 0 | От 32 до 41 |
| Вставка строки между строками 21 и 22 | ДАЛЕЕ | 0 | От 31 до 40 |
| Вставка строки между строками 30 и 31 | ДАЛЕЕ | 0 | Вставленная строка, от 31 до 39 |
| Удаление строки 21 | PRIOR | 0 | От 11 до 20 |
| Удаление строки 20 | PRIOR | 0 | От 10 до 19 |
| Вставка строки между строками 21 и 22 | PRIOR | 0 | От 11 до 20 |
| Вставка строки между строками 20 и 21 | PRIOR | 0 | От 12 до 20, вставленная строка |
| Удаление строки 21 | Относительное значение | 0 | От 22 до 31[2] |
| Удаление строки 21 | Относительное значение | 1 | От 22 до 31 |
| Вставка строки между строками 21 и 22 | Относительное значение | 0 | 21, вставленная строка, 22–29 |
| Вставка строки между строками 21 и 22 | Относительное значение | 1 | От 22 до 31 |
| Удаление строки 21 | ABSOLUTE | 21 | От 22 до 31[2] |
| Удаление строки 22 | ABSOLUTE | 21 | 21, 23–31 |
| Вставка строки между строками 21 и 22 | ABSOLUTE | 22 | Вставленная строка, от 22 до 29 |
[1] В этом столбце используются номера строк до вставки или удаления строк.
[2] В этом случае курсор пытается вернуть строки, начиная с строки 21. Так как строка 21 удалена, первая строка, которая возвращается, — это строка 22.
Строки ошибок (т. е. строки с состоянием SQL_ROW_ERROR) не влияют на перемещение курсора. Например, если текущий набор строк начинается с строки 11, а состояние строки 11 — SQL_ROW_ERROR, вызывая SQLFetchScroll с набором FetchOrientation значение SQL_FETCH_RELATIVE и FetchOffset, равное 5, возвращает набор строк, начиная с строки 16, так же, как если бы состояние строки 11 было SQL_SUCCESS.
Возврат данных в привязанных столбцах
SQLFetchScroll возвращает данные в привязанных столбцах так же, как и SQLFetch. Дополнительные сведения см. в разделе "Возврат данных в привязанных столбцах" в функции SQLFetch.
Если столбцы не привязаны, SQLFetchScroll не возвращает данные, но перемещает курсор блока в указанную позицию. Можно ли получить данные из несвязанных столбцов курсора блока с SQLGetData , зависящего от драйвера. Эта возможность поддерживается, если вызов SQLGetInfo возвращает SQL_GD_BLOCK бит для типа сведений SQL_GETDATA_EXTENSIONS.
Адреса буферов
SQLFetchScroll использует ту же формулу, чтобы определить адрес буферов данных и длины или индикатора в качестве SQLFetch. Дополнительные сведения см. в разделе "Буферные адреса" в функции SQLBindCol.
Массив статусов строк
SQLFetchScroll задает значения в массиве состояния строки таким же образом, как и SQLFetch. Дополнительные сведения см. в разделе "Массив состояния строк" в функции SQLFetch.
Извлекаемый буфер строк
SQLFetchScroll возвращает количество строк, извлекаемых в буфере строк таким же образом, как и SQLFetch. Дополнительные сведения см. в разделе "Извлекаемый буфер строк" в функции SQLFetch.
Обработка ошибок
Когда приложение вызывает SQLFetchScroll в драйвере ODBC 3.x, диспетчер драйверов вызывает SQLFetchScroll в драйвере. Когда приложение вызывает SQLFetchScroll в драйвере ODBC 2.x, диспетчер драйверов вызывает SQLExtendedFetch в драйвере. Так как SQLFetchScroll и SQLExtendedFetch обрабатывают ошибки немного иначе, приложение видит немного другое поведение ошибки при вызове SQLFetchScroll в драйверах ODBC 2.x и ODBC 3.x.
SQLFetchScroll возвращает ошибки и предупреждения таким же образом, как и SQLFetch; дополнительные сведения см. в разделе "Обработка ошибок" в SQLFetch. SQLExtendedFetch возвращает ошибки таким же образом, как и SQLFetch, с следующими исключениями:
При возникновении предупреждения, которое применяется к определенной строке в наборе строк, SQLExtendedFetch задает соответствующую запись в массиве состояния строки SQL_ROW_SUCCESS, а не SQL_ROW_SUCCESS_WITH_INFO.
Если ошибки возникают в каждой строке набора строк, SQLExtendedFetch возвращает SQL_SUCCESS_WITH_INFO, а не SQL_ERROR.
В каждой группе записей состояния, которая применяется к отдельной строке, первая запись состояния, возвращаемая SQLExtendedFetch, должна содержать SQLSTATE 01S01 (ошибка в строке); SQLFetchScroll не возвращает этот SQLSTATE. Если SQLExtendedFetch не может возвращать дополнительные SQLSTATEs, он по-прежнему должен вернуть этот SQLSTATE.
SQLFetchScroll и оптимистическое параллелизм
Если курсор использует оптимистическую параллелизму , то есть атрибут оператора SQL_ATTR_CONCURRENCY имеет значение SQL_CONCUR_VALUES или SQL_CONCUR_ROWVER . SQLFetchScroll обновляет значения оптимистического параллелизма, используемые источником данных, чтобы определить, изменилась ли строка. Это происходит всякий раз, когда SQLFetchScroll извлекает новый набор строк, в том числе при ссылке на текущий набор строк. (Он вызывается с параметром FetchOrientation, равным SQL_FETCH_RELATIVE и FetchOffset, равным 0.)
Драйверы SQLFetchScroll и ODBC 2.x
Когда приложение вызывает SQLFetchScroll в драйвере ODBC 2.x, диспетчер драйверов сопоставляет этот вызов с SQLExtendedFetch. Он передает следующие значения для аргументов SQLExtendedFetch.
| Аргумент SQLExtendedFetch | Значение |
|---|---|
| ОператорHandle | ОператорHandle в SQLFetchScroll. |
| FetchOrientation | FetchOrientation в SQLFetchScroll. |
| FetchOffset | Если FetchOrientation не SQL_FETCH_BOOKMARK, используется значение аргумента FetchOffset в SQLFetchScroll . Если параметр FetchOrientation SQL_FETCH_BOOKMARK, используется значение, хранящееся по адресу, указанному атрибутом инструкции SQL_ATTR_FETCH_BOOKMARK_PTR. |
| RowCountPtr | Адрес, указанный атрибутом инструкции SQL_ATTR_ROWS_FETCHED_PTR. |
| RowStatusArray | Адрес, указанный атрибутом инструкции SQL_ATTR_ROW_STATUS_PTR. |
Дополнительные сведения см. в разделе "Блокировать курсоры", "Прокручиваемые курсоры" и "Обратная совместимость " в приложении G. Рекомендации по драйверам для обеспечения обратной совместимости.
Дескрипторы и SQLFetchScroll
SQLFetchScroll взаимодействует с дескрипторами так же, как и SQLFetch. Дополнительные сведения см. в разделе "Дескрипторы и SQLFetchScroll" в функции SQLFetch.
Пример кода
См. статью "Привязка со столбцами", "Привязка со строками", "Позиционированные инструкции" и "Удаление" и "Обновление строк" в наборе строк с помощью SQLSetPos.
Связанные функции
| Сведения | Смотрите |
|---|---|
| Привязка буфера к столбцу в результирующем наборе | Функция SQLBindCol |
| Выполнение операций массового вставки, обновления или удаления | Функция SQLBulkOperations |
| Отмена обработки инструкций | Функция SQLCancel |
| Возврат сведений о столбце в результирующем наборе | Функция SQLDescribeCol |
| Выполнение инструкции SQL | Функция SQLExecDirect |
| Выполнение подготовленной инструкции SQL | Функция SQLExecute |
| Получение одной строки или блока данных в направлении только для пересылки | Функция SQLFetch |
| Закрытие курсора в инструкции | Функция SQLFreeStmt |
| Возврат числа столбцов результирующего набора | Функция SQLNumResultCols |
| Размещение курсора, обновление данных в наборе строк или обновление или удаление данных в результирующем наборе | Функция SQLSetPos |
| Задание атрибута инструкции | Функция SQLSetStmtAttr |