Функция JetMove

Статья
06/13/2023

Применимо к: Windows | Windows Server

Функция JetMove

Функция JetMove размещает курсор в начале или конце индекса и просматривает записи в этом индексе вперед или назад. Можно также переместить курсор вперед или назад по текущему индексу на указанное количество записей индекса. Другой подход заключается в искусственном ограничении записей индекса, которые можно перечислить с помощью JetMove , настроив диапазон индексов на курсоре с помощью JetSetIndexRange.

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

Параметры

sesid

Сеанс, используемый для этого вызова.

tableid

Курсор, используемый для этого вызова.

Ворона

Произвольное смещение, указывающее требуемое перемещение курсора по текущему индексу.

Помимо стандартных смещения, этот параметр также можно задать с помощью одного из следующих параметров.

Значение	Значение
JET_MoveFirst	Перемещает курсор к первой записи индекса в индексе (если она существует). При этом сбрасывается любой диапазон индексов, заданный с помощью JetSetIndexRange. Примечание Для обозначения этого параметра используется литеральное значение -2147483648. Не используйте это значение в качестве обычного смещения, иначе может возникнуть непреднамеренное поведение.
JET_MoveLast	Перемещает курсор на последнюю запись индекса в индексе (если она существует). При этом сбрасывается любой диапазон индексов, заданный с помощью JetSetIndexRange. Примечание Для обозначения этого параметра используется литеральное значение 2147483647. Не используйте это значение в качестве обычного смещения, иначе может возникнуть непреднамеренное поведение.
JET_MoveNext	Перемещает курсор к следующей записи индекса в индексе (если она существует). Это значение точно равно обычному смещению +1. Он учитывает диапазоны индексов, заданные с помощью JetSetIndexRange.
JET_MovePrevious	Перемещает курсор на предыдущую запись индекса (если она существует). Он учитывает диапазоны индексов, заданные с помощью JetSetIndexRange. Это значение точно равно обычному смещению –1 или 0 (ноль). Курсор остается в текущей логической позиции, и будет проверено существование записи индекса, соответствующей этой логической позиции.

grbit

Группа битов, задающая ноль или более следующих параметров.

Значение	Значение
JET_bitMoveKeyNE	Перемещает курсор вперед или назад на количество записей индекса, необходимых для пропуска запрошенного количества значений ключа индекса, встречающихся в индексе. Это происходит при сворачивании записей индекса с повторяющимися значениями ключа в одну запись индекса. Обычно смещение перемещает курсор на указанное количество записей индекса независимо от их значений ключа.

Значение

JET_bitMoveKeyNE

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

Возвращаемое значение

Эта функция возвращает тип данных JET_ERR с одним из следующих кодов возврата. Дополнительные сведения о возможных ошибках ESE см. в разделах Ошибки подсистемы расширяемого хранилища и Параметры обработки ошибок.

Код возврата	Описание
JET_errSuccess	Операция выполнена успешно. Для JetMove это означает, что запись индекса была найдена в запрошенном расположении или смещение текущего индекса.
JET_errClientRequestToStopJetService	Операция не может завершиться, так как все действия экземпляра, связанного с сеансом, прекратились в результате вызова JetStopService.
JET_errInstanceUnavailable	Операция не может завершиться, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Windows XP: Это возвращаемое значение появилось в Windows XP.
JET_errNoCurrentRecord	Курсор в данный момент не располагается на записи индекса. Для JetMove это означает, что запись индекса не найдена в запрошенном расположении или смещение текущего индекса.
JET_errNotInitialized	Операция не может завершиться, так как экземпляр, связанный с сеансом, еще не инициализирован.
JET_errRecordDeleted	В настоящее время курсор логически расположен на записи индекса, соответствующей записи, которая была удалена.
JET_errRestoreInProgress	Операция не может завершиться, так как в экземпляре, связанном с сеансом, выполняется операция восстановления.
JET_errSessionSharingViolation	Один и тот же сеанс нельзя использовать для нескольких потоков одновременно. Windows XP: Это возвращаемое значение появилось в Windows XP.
JET_errTermInProgress	Операция не может завершиться, так как экземпляр, связанный с сеансом, завершает работу.

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

Если эта функция завершается сбоем, положение курсора останется неизменным, если не был возвращен JET_errNoCurrentRecord. В этом случае курсор будет располагаться там, где была бы запись индекса, соответствующая требуемому расположению или смещению. Курсор можно переместить относительно этой позиции, но он по-прежнему не находится в допустимой записи индекса. Если запись подготовлена к обновлению, это обновление будет отменено. Если диапазон индексов действует и указан JET_MoveFirst или JET_MoveLast, этот диапазон индексов будет отменен. Изменение состояния базы данных не произойдет.

Курсор можно переместить в две специальные позиции с помощью JetMove: Before First и After Last. Если курсор находится на первой записи индекса в таблице и JetMove вызывается с JET_MovePrevious, вызов завершится ошибкой с JET_errNoCurrentRecord и курсор будет логически расположен перед первой записью в индексе. Эта логическая позиция сохраняется, даже если перед первой записью в индексе вставляется другая запись индекса. Аналогичная ситуация возникает для параметра After Last относительно конца индекса. Параметр Before First и After Last наиболее полезен при настройке диапазона записей индекса для итерации с помощью JetMove с использованием модели итератора, которая всегда должна переходить к следующему (или предыдущему) элементу до использования этого элемента.

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

В выпусках до Windows Server 2003 с пакетом обновления 1 (SP1) в JetMove возникает проблема, которая в некоторых случаях влияет на правильное применение диапазона индексов, настроенного функцией JetSetIndexRange . Если курсор находится перед первой записью индекса, а диапазон индексов задан с верхним пределом, который меньше первой записи индекса, следующий вызов JetMove будет ошибочно переходить к этой записи индекса вместо сбоя с JET_errNoCurrentRecord, как ожидалось. Та же ошибка будет происходить в аналогичной ситуации, начиная с конца индекса. Такая ситуация может возникнуть в приложении, которое настраивает диапазон индексов и перемещается по нему с помощью итератора, который ожидает начаться до первой записи индекса, которая является членом набора записей для перечисления, а не с первой записи индекса этого набора. Эта ситуация также возникает в аналогичном случае, начиная с конца индекса. Обходной путь заключается в том, чтобы приложение вручную проверяло, что полученная запись индекса находится внутри диапазона индекса, сравнив ключ для текущей записи индекса (полученной с помощью JetRetrieveKey) с ключом, представляющим конец текущего диапазона индексов (извлекается с помощью JetRetrieveKey с помощью JET_bitRetrieveCopy).

Важно соблюдать осторожность при передаче вычисляемых смещения в JetMove. Если вычисленное смещение меньше или равно JET_MoveFirst, это смещение должно быть разбито на несколько частей, каждый из которых передается в JetMove отдельно, но в рамках одной транзакции, чтобы получить требуемый эффект. То же самое относится к смещениям, превышающим или равным JET_MoveNext. Маловероятно, что приложение будет проходить это в реальном мире, но хорошо иметь защиту от этого случая, учитывая очень разную семантику JET_MoveFirst и JET_MoveLast от обычного смещения.

При вызове JetMove с очень большим смещением, например если параметр cRow имеет значение 1000, JetMove проходит все 1000 записей индекса, чтобы достичь конечной позиции. В настоящее время API ESE не предоставляет эффективный способ перехода непосредственно к заданной записи индекса путем смещения без обхода каждой записи индекса.

Требования

Требование	Значение
Клиент	Требуется Windows Vista, Windows XP или Windows 2000 Профессиональная.
Сервер	Требуется Windows Server 2008, Windows Server 2003 или Windows 2000 Server.
Верхняя часть	Объявлено в Esent.h.
Библиотека	Используйте ESENT.lib.
DLL	Требуется ESENT.dll.

См. также:

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange

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

Функция JetMove