Поделиться через

SQLFetchScroll (библиотека курсоров)

  • Статья

Внимание

Эта функция будет удалена в будущей версии Windows. Избегайте использования этой функции в новых рабочих областях разработки и планируете изменять приложения, которые в настоящее время используют эту функцию. Корпорация Майкрософт рекомендует использовать функции курсора драйвера.

В этом разделе рассматривается использование функции SQLFetchScroll в библиотеке курсоров. Общие сведения о SQLFetchScroll см. в разделе "Функция SQLFetchScroll".

Библиотека курсоров реализует SQLFetchScroll путем многократного вызова SQLFetch в драйвере. Он передает данные, полученные из драйвера, в буферы набора строк, предоставляемые приложением. Он также кэширует данные в файлах памяти и диска. Когда приложение запрашивает новый набор строк, библиотека курсоров извлекает его по мере необходимости из драйвера (если он не был получен ранее) или кэш (если он был получен ранее). Наконец, библиотека курсоров сохраняет состояние кэшированных данных и возвращает эти сведения приложению в массиве состояния строки.

При использовании библиотеки курсоров вызовы SQLFetchScroll нельзя смешать с вызовами SQLFetch или SQLExtendedFetch.

При использовании библиотеки курсоров вызовы SQLFetchScroll поддерживаются как для ODBC 2.x и для ODBC 3.драйверы x .

Буферы набора строк

Библиотека курсоров оптимизирует передачу данных из драйвера в буфер набора строк, предоставленный приложением, если:

  • Приложение использует привязку по строкам.

  • Между полями в структуре приложения нет неиспользуемых байтов, которые приложение объявляет для хранения строки данных.

  • Поля, в которых SQLFetch или SQLFetchScroll возвращают длину или индикатор столбца следует буферу для этого столбца и предшествует буферу для следующего столбца. Эти поля являются необязательными.

Когда приложение запрашивает новый набор строк, библиотека курсоров извлекает данные из своего кэша и от драйвера по мере необходимости. Если новые и старые наборы строк перекрываются, библиотека курсоров может оптимизировать свою производительность, повторно используя данные из перекрывающихся разделов буферов набора строк. Поэтому несохраненные изменения буферов набора строк теряются, если новые и старые наборы строк не перекрываются, а изменения находятся в перекрывающихся разделах буферов набора строк. Чтобы сохранить изменения, приложение отправляет позиционированную инструкцию обновления.

Обратите внимание, что библиотека курсоров всегда обновляет буферы набора строк с данными из кэша, когда приложение вызывает SQLFetchScroll с аргументом FetchOrientation, равным SQL_FETCH_RELATIVE, и аргумент FetchOffset имеет значение 0.

Библиотека курсоров поддерживает вызов SQLSetStmtAttr с атрибутомSQL_ATTR_ROW_ARRAY_SIZE для изменения размера набора строк во время открытия курсора. Новый размер набора строк вступит в силу при следующем вызове SQLFetchScroll .

Членство в результирующем наборе

Библиотека курсоров извлекает данные из драйвера только так, как приложение запрашивает его. В зависимости от источника данных и параметра атрибута оператора SQL_CONCURRENCY это имеет следующие последствия:

  • Данные, полученные библиотекой курсоров, могут отличаться от данных, доступных во время выполнения инструкции. Например, после открытия курсора строки, вставляемые в точку за пределами текущей позиции курсора, могут быть получены некоторыми драйверами.

  • Данные в результирующем наборе могут быть заблокированы источником данных для библиотеки курсоров и поэтому недоступны для других пользователей.

После кэширования строки данных библиотека курсоров не может обнаруживать изменения в этой строке в базовом источнике данных (за исключением размещенных обновлений и удалений, работающих в кэше того же курсора). Это происходит потому, что для вызовов SQLFetchScroll библиотека курсоров никогда не запрашивает данные из источника данных. Вместо этого он возвращает данные из кэша.

Прокрутка

Библиотека курсоров поддерживает следующие типы получения в SQLFetchScroll.

Тип курсора Типы получения
Однонаправленный SQL_FETCH_NEXT
Статические SQL_FETCH_NEXT

SQL_FETCH_PRIOR

SQL_FETCH_FIRST

SQL_FETCH_LAST

SQL_FETCH_RELATIVE

SQL_FETCH_ABSOLUTE

SQL_FETCH_BOOKMARK

ошибки

При вызове SQLFetchScroll и одном из вызовов SQLFetch возвращается SQL_ERROR, библиотека курсоров продолжается следующим образом. После выполнения этих действий библиотека курсоров продолжает обработку.

  1. Вызывает SQLGetDiagRec для получения сведений об ошибке от драйвера и записывает его в качестве диагностической записи в диспетчере драйверов.

  2. Задает поле SQL_DIAG_ROW_NUMBER в записи диагностики соответствующим значением.

  3. Задает поле SQL_DIAG_COLUMN_NUMBER в диагностической записи соответствующим значением, если применимо; в противном случае он задает значение 0.

  4. Задает значение строки в ошибке в массиве состояния строки SQL_ROW_ERROR.

После того как библиотека курсоров несколько раз вызвала SQLFetch В реализации SQLFetchScroll, любая ошибка или предупреждение, возвращаемое одним из вызовов SQLFetch, будет находиться в диагностической записи и может быть извлечена вызовом SQLGetDiagRec. Если данные были усечены при получении, усеченные данные теперь будут находиться в кэше библиотеки курсоров. Последующие вызовы SQLFetchScroll для прокрутки к строке с усеченными данными возвращают усеченные данные, и предупреждение не будет возникать, так как данные извлекаются из кэша библиотеки курсоров. Чтобы отслеживать длину возвращаемых данных, чтобы определить, были ли возвращены данные в буфере, приложение должно привязать буфер длины или индикатора.

Операции закладки

Библиотека курсоров поддерживает вызов SQLFetchScroll с помощью FetchOrientation SQL_FETCH_BOOKMARK. Он также поддерживает указание смещения в аргументе FetchOffset , который можно использовать в операции закладки. Это единственная операция закладки, поддерживающая библиотеку курсоров. Библиотека курсоров не поддерживает вызов SQLBulkOperations.

Если приложение задало атрибут инструкции SQL_ATTR_USE_BOOKMARKS и привязывается к столбцу закладки, библиотека курсоров создает закладку фиксированной длины и возвращает ее приложению. Библиотека курсоров создает и поддерживает используемые закладки; Он не использует закладки, поддерживаемые в источнике данных. При вызове SQLFetchScroll для получения блока данных, который уже извлечен из источника данных, он извлекает данные из кэша библиотеки курсоров. В результате закладка, используемая в вызове SQLFetchScroll с помощью FetchOrientation SQL_FETCH_BOOKMARK, должна быть создана и поддерживаться библиотекой курсоров.

Взаимодействие с другими функциями

Приложение должно вызывать SQLFetch или SQLFetchScroll перед подготовкой или выполнением любых позиционированных инструкций обновления или удаления.