Функция JetMove

Применимо к: 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 (ноль).

Курсор остается в текущей логической позиции и наличие записи индекса, соответствующей этой логической позиции, будет проверено.

гбит

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

Значение

Значение

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 относительно конца индекса. До первого и после последнего наиболее полезны при настройке диапазона записей индекса для итерации с помощью 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 Профессиональный.

Server

Требуется 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