Функция JetSetCurrentIndex4
Применимо к: Windows | Windows Server
Функция JetSetCurrentIndex4
Функция JetSetCurrentIndex4 используется для задания текущего индекса курсора. Текущий индекс курсора определяет, какие записи в таблице видимы для этого курсора, и порядок их отображения путем выбора набора записей индекса, используемых для предоставления этих записей.
JET_ERR JET_API JetSetCurrentIndex4(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in_opt JET_PCSTR szIndexName,
__in_opt JET_INDEXID* pindexid,
__in JET_GRBIT grbit,
__in unsigned long itagSequence
);
Параметры
sesid
Сеанс, используемый для этого вызова.
tableid
Курсор, используемый для этого вызова.
szIndexName
Имя индекса, выбранного для курсора. Если этот параметр имеет значение NULL или пустую строку, будет выбран кластеризованный индекс. Если для таблицы определен первичный индекс, этот индекс будет выбран, так как он совпадает с кластеризованным индексом. Если для таблицы не определен первичный индекс, будет выбран последовательный индекс. Последовательный индекс не имеет определения индекса. Дополнительные сведения см. в разделе JetCreateIndex .
Если pindexid не имеет значение NULL, имя индекса будет игнорироваться и индекс будет выбран по идентификатору индекса.
pindexid
Идентификатор индекса, который будет выбран для курсора.
Идентификатор индекса — это непрозрачный дескриптор, который можно использовать для быстрого выбора индекса. Этот идентификатор можно получить с помощью JetGetIndexInfo или JetGetTableIndexInfo с помощью параметра JET_IdxInfoIndexId.
Если pindexid имеет значение NULL, индекс будет выбран по имени индекса, а идентификатор индекса будет игнорироваться.
Если этот параметр отсутствует, его значение считается равным NULL.
grbit
Группа битов, содержащих параметры, которые будут использоваться для этого вызова, которые включают ноль или более из следующих значений.
Значение |
Значение |
|---|---|
JET_bitMoveFirst |
Этот параметр указывает, что курсор должен располагаться на первой записи указанного индекса. Если выбирается кластеризованный индекс (первичный или последовательный индекс), а текущий индекс является вторичным индексом, то предполагается JET_bitMoveFirst. Если выбран текущий индекс, этот параметр игнорируется, и изменение положения курсора не производится. |
JET_bitNoMove |
Этот параметр указывает, что курсор должен располагаться на записи нового индекса, соответствующей записи, связанной с записью индекса, в текущей позиции курсора на старом индексе. Если определение для нового индекса содержит хотя бы один многозначный ключевой столбец, то запись целевого индекса будет неоднозначной. В этом случае указанная функция itagSequence используется для выбора нескольких значений наиболее значительного ключевого столбца, используемого для размещения курсора. Необходимо передать только один параметр itagSequence даже в случае нескольких многозначных ключевых столбцов, так как подсистема развертывает все значения только для наиболее значительного многозначного ключевого столбца. Дополнительные сведения см. в разделе JetCreateIndex . Если указан JET_bitMoveFirst, этот параметр игнорируется. Если выбран текущий индекс, этот параметр игнорируется, и изменение положения курсора не производится. Если этот параметр отсутствует, его значение считается JET_bitMoveFirst. |
itagSequence
Порядковый номер многозначного значения столбца, который будет использоваться для размещения курсора на новом индексе.
Этот параметр используется только в сочетании с JET_bitNoMove. Дополнительные сведения см. в описании этого параметра.
Если этот параметр отсутствует или имеет значение 0, его значение считается равным 1.
Возвращаемое значение
Эта функция возвращает тип данных JET_ERR с одним из следующих кодов возврата. Дополнительные сведения о возможных ошибках ESE см. в разделах Ошибки подсистемы расширяемого хранилища и Параметры обработки ошибок.
Код возврата |
Описание |
|---|---|
JET_errSuccess |
Операция выполнена успешно. |
JET_errBadItagSequence |
Дополнительный индекс выбирается с параметром JET_bitNoMove, и в определении для нового индекса, соответствующего указанному порядковому номеру, отсутствует значение для первого многозначного ключевого столбца. |
JET_errClientRequestToStopJetService |
Невозможно выполнить операцию, так как все действия экземпляра, связанного с сеансом, прекратились в результате вызова JetStopService. |
JET_errInstanceUnavailable |
Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках. |
JET_errInvalidIndexId |
Содержимое идентификатора индекса было недопустимым или истекло, и его необходимо обновить. Это может произойти для JetSetCurrentIndex4, когда:
|
JET_errInvalidName |
Одно из указанных имен объектов было недопустимым. Все имена объектов должны соответствовать одному и тому же набору правил. Ниже приведены эти правила.
|
JET_errInvalidParameter |
Один из предоставленных параметров содержал непредвиденное значение или значение, которое не имело смысла в сочетании со значением другого параметра. Это может произойти для JetSetCurrentIndex4 , если pindexid не имеет значения NULL и pindexid-cbStruct> не имеет ожидаемого размера (Windows XP и более ранние выпуски). |
JET_errNoCurrentRecord |
Дополнительный индекс выбирается с параметром JET_bitNoMove, и в новом индексе отсутствует запись индекса, соответствующая записи, связанной с записью индекса в текущей позиции курсора на старом индексе. |
JET_errNotInitialized |
Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, еще не инициализирован. |
JET_errOutOfCursors |
Подсистема исчерпала свой пул ресурсов, используемых для открытия курсоров. Максимальное количество курсоров, которые можно открыть в любой момент времени, контролируется с помощью JET_paramMaxCursors. Дополнительные сведения см. в разделе JetSetSystemParameter . Это может произойти для JetSetCurrentIndex4 , если выбран вторичный индекс и подсистема не может открыть внутренний курсор для использования этого индекса. |
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. |
Юникод |
Реализовано как JetSetCurrentIndex4W (Юникод) и JetSetCurrentIndex4A (ANSI). |
См. также:
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSeek
JetSetSystemParameter