Функция JetSetCurrentIndex3

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

Функция JetSetCurrentIndex3

Функция JetSetCurrentIndex3 используется для задания текущего индекса курсора. Текущий индекс курсора определяет, какие записи в таблице видимы для этого курсора, и порядок их отображения путем выбора набора записей индекса, используемых для предоставления этих записей.

    JET_ERR JET_API JetSetCurrentIndex3(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

Параметры

sesid

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

tableid

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

szIndexName

Имя индекса, который будет выбран для курсора.

Если этот параметр имеет значение NULL или пустую строку, будет выбран кластеризованный индекс. Если для таблицы определен первичный индекс, он будет выбран, так как он совпадает с кластеризованным индексом. Если для таблицы не определен первичный индекс, будет выбран последовательный индекс. Последовательный индекс не имеет определения индекса. Дополнительные сведения см. в разделе JetCreateIndex .

Если pindexid не равно NULL, имя индекса будет игнорироваться, а индекс будет выбран по идентификатору индекса.

grbit

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

Значение	Значение
JET_bitMoveFirst	Этот параметр указывает, что курсор должен располагаться на первой записи указанного индекса. Если выбирается кластеризованный индекс (первичный или последовательный индекс), а текущий индекс является вторичным индексом, то предполагается JET_bitMoveFirst. Если выбран текущий индекс, этот параметр игнорируется и не изменяется положение курсора.
JET_bitNoMove	Этот параметр указывает, что курсор должен располагаться на записи индекса нового индекса, которая соответствует записи, связанной с записью индекса, в текущей позиции курсора на старом индексе. Если определение для нового индекса содержит по крайней мере один многозначный ключевой столбец, то запись целевого индекса будет неоднозначной. В этом случае указанная функция itagSequence используется для выбора многозначного ключевого столбца, который используется для размещения курсора. Необходимо передать только один параметр itagSequence даже в случае нескольких многозначных ключевых столбцов, так как подсистема расширяет все значения только для наиболее значимого многозначного ключевого столбца. Дополнительные сведения см. в разделе JetCreateIndex . Если указан JET_bitMoveFirst, этот параметр игнорируется. Если выбран текущий индекс, этот параметр игнорируется и не изменяется положение курсора. Если этот параметр отсутствует, предполагается, что его значение JET_bitMoveFirst.

Значение

JET_bitMoveFirst

Этот параметр указывает, что курсор должен располагаться на первой записи указанного индекса. Если выбирается кластеризованный индекс (первичный или последовательный индекс), а текущий индекс является вторичным индексом, то предполагается JET_bitMoveFirst. Если выбран текущий индекс, этот параметр игнорируется и не изменяется положение курсора.

JET_bitNoMove

Этот параметр указывает, что курсор должен располагаться на записи индекса нового индекса, которая соответствует записи, связанной с записью индекса, в текущей позиции курсора на старом индексе.

Если определение для нового индекса содержит по крайней мере один многозначный ключевой столбец, то запись целевого индекса будет неоднозначной. В этом случае указанная функция itagSequence используется для выбора многозначного ключевого столбца, который используется для размещения курсора. Необходимо передать только один параметр itagSequence даже в случае нескольких многозначных ключевых столбцов, так как подсистема расширяет все значения только для наиболее значимого многозначного ключевого столбца. Дополнительные сведения см. в разделе JetCreateIndex .

Если указан JET_bitMoveFirst, этот параметр игнорируется.

Если выбран текущий индекс, этот параметр игнорируется и не изменяется положение курсора. Если этот параметр отсутствует, предполагается, что его значение JET_bitMoveFirst.

itagSequence

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

Этот параметр используется только в сочетании с JET_bitNoMove. Дополнительные сведения см. в описании этого параметра.

Если этот параметр отсутствует или имеет нулевое значение, предполагается, что его значение равно 1.

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

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

Код возврата	Описание
JET_errSuccess	Операция выполнена успешно.
JET_errBadItagSequence	Дополнительный индекс выбирается с параметром JET_bitNoMove, и в определении нового индекса отсутствует значение для первого многозначного ключевого столбца, соответствующего указанному порядковому номеру.
JET_errClientRequestToStopJetService	Невозможно выполнить операцию, так как все действия экземпляра, связанного с сеансом, прекратились в результате вызова JetStopService.
JET_errInstanceUnavailable	Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.
JET_errInvalidIndexId	Содержимое идентификатора индекса было недопустимым или истекло, и его необходимо обновить. Это может произойти для JetSetCurrentIndex3 , если: Pindexid-cbStruct> не соответствует ожидаемому размеру (Windows Server 2003 и более поздние версии). Подсистема была остановлена с момента получения идентификатора индекса. Все курсоры, ссылающиеся на таблицу, содержащую индекс, соответствующий идентификатору индекса, были закрыты, и подсистема исключила определение для этого индекса из кэша схемы. Идентификатор индекса используется с курсором, открытым в неправильной таблице. Индекс удален или еще не виден сеансу.
JET_errInvalidName	Одно из указанных имен объектов было недопустимым. Все имена объектов должны соответствовать одному набору правил. Ниже приведены эти правила. Имена объектов должны состоять из символов ASCII. Имена объектов должны содержать по крайней мере один символ. Длина имен объектов не может превышать JET_cbNameMost (64) символов. Имена объектов могут не начинаться с пробела. Имена объектов не могут содержать управляющие символы ASCII (0x00 по 0x1F). Имена объектов не могут содержать восклицательный знак (!), точку (.), левую скобку ([) или символ правой скобки (]). После проверки для имени объекта будет использоваться только часть строки вплоть до первого пробела (если таковой есть). Это фактически означает, что имена объектов также могут не содержать пробела.
JET_errInvalidParameter	Один из предоставленных параметров содержал непредвиденное значение или значение, которое не имело смысла в сочетании со значением другого параметра. Это может произойти для JetSetCurrentIndex3 , если pindexid не равен NULL, а pindexid-cbStruct> не имеет ожидаемого размера (Windows XP и более ранние выпуски).
JET_errNoCurrentRecord	Дополнительный индекс выбирается с параметром JET_bitNoMove, и в новом индексе отсутствует запись индекса, соответствующая записи, связанной с записью индекса в текущей позиции курсора на старом индексе.
JET_errNotInitialized	Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, еще не инициализирован.
JET_errOutOfCursors	Подсистема исчерпала свой пул ресурсов, используемых для открытия курсоров. Максимальное количество курсоров, которые можно открыть в любой момент времени, управляется с помощью JET_paramMaxCursors. Дополнительные сведения см. в разделе JetSetSystemParameter . Это может произойти для JetSetCurrentIndex3 , если выбран вторичный индекс и подсистема не может открыть внутренний курсор для использования этого индекса.
JET_errRestoreInProgress	Невозможно выполнить операцию, так как операция восстановления выполняется в экземпляре, связанном с сеансом.
JET_errSessionSharingViolation	Один и тот же сеанс нельзя использовать одновременно для нескольких потоков. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.
JET_errTermInProgress	Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, завершает работу.

При успешном выполнении текущий индекс курсора устанавливается в качестве запрошенного индекса. Записи индекса теперь можно искать с помощью JetSeek в соответствии с определением индекса запрошенного индекса. Записи индекса также можно перечислить с помощью JetMove в порядке, указанном в определении индекса. Текущее положение курсора устанавливается либо как первая запись индекса в индексе (JET_bitMoveFirst), либо определенная запись индекса, связанная с текущей позицией курсора по старому индексу (JET_bitNoMove). Изменение состояния базы данных не произойдет.

При сбое текущий индекс и текущее положение курсора находятся в неопределенном состоянии. Изменение состояния базы данных не произойдет.

Если указание идентификатора индекса устарело, API просто завершается ошибкой. В этом случае не требуется откат к текстовому имени индекса, как можно было бы ожидать. Этот резервный вариант должен выполняться вручную вызывающим элементом API.

Требования

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

См. также:

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSetSystemParameter
JetSeek

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2023-06-13

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

Функция JetSetCurrentIndex3