Функция 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	Error	Description
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

См. также

Справочник по API ODBC
Файлы заголовков ODBC