Share via

Функция JetGetSecondaryIndexBookmark

  • Статья

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

Функция JetGetSecondaryIndexBookmark

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

Windows XP: JetGetSecondaryIndexBookmark появилась в Windows XP.

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const JET_GRBIT grbit
    );

Параметры

sesid

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

tableid

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

pvSecondaryKey

Выходной буфер, получающий вторичный ключ.

cbSecondaryKeyMax

Максимальный размер выходного буфера для вторичного ключа (в байтах).

pcbSecondaryKeyActual

Получает фактический размер вторичного ключа в байтах.

Если этот параметр имеет значение NULL, фактический размер вторичного ключа не будет возвращен.

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

pvPrimaryBookmark

Выходной буфер, получающий закладку первичного ключа.

cbPrimaryBookmarkMax

Максимальный размер (в байтах) выходного буфера для закладки первичного ключа.

pcbPrimaryKeyActual

Получает фактический размер закладки первичного ключа (в байтах).

Если этот параметр имеет значение NULL, фактический размер закладки первичного ключа не будет возвращен.

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

grbit

Зарезервировано для последующего использования.

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

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

Код возврата

Описание

JET_errSuccess

Операция выполнена успешно.

JET_errBufferTooSmall

Операция завершилась успешно, но один из буферов вывода был слишком мал для получения запрошенных данных.

Выходной буфер был заполнен максимальной частью закладки. При запросе также был возвращен фактический размер закладки.

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, столкнулся с неустранимой ошибкой, требующей отмены доступа ко всем данным для защиты целостности этих данных. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.

JET_errNoCurrentIndex

Курсор в настоящее время не находится на вторичном индексе.

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

JET_errNoCurrentRecord

Курсор не располагается на записи.

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

JET_errNotInitialized

Невозможно выполнить операцию, так как экземпляр, связанный с сеансом, еще не инициализирован.

JET_errRestoreInProgress

Невозможно выполнить операцию, так как операция восстановления выполняется в экземпляре, связанном с сеансом.

JET_errSessionSharingViolation

Один и тот же сеанс нельзя использовать для нескольких потоков одновременно. Эта ошибка будет возвращена только в Windows XP и более поздних выпусках.

JET_errTermInProgress

Невозможно завершить операцию, так как экземпляр, связанный с сеансом, завершает работу.

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

При сбое состояние выходных буферов и фактический размер дополнительной закладки индекса будут неопределенными, если не был возвращен JET_errBufferTooSmall. В случае возврата JET_errBufferTooSmall выходные буферы будут содержать столько дополнительной закладки индекса, сколько вместится в указанном пространстве, а фактический размер дополнительной закладки индекса будет точным. В любом случае изменение состояния базы данных не произойдет.

Комментарии

Закладки обычно следует рассматривать как непрозрачные блоки данных. Не следует пытаться использовать внутреннюю структуру этих данных. Однако для всех закладок ESENT можно знать следующие свойства:

  • Закладка однозначно идентифицирует запись в данной таблице.

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

  • Закладка записи совпадает с ключом этой записи в первичном индексе таблицы, содержащей запись. Если для этой таблицы не определен первичный индекс, ядро СУБД создаст собственную закладку для записи.

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

  • Сравнивать закладки записей из разных таблиц друг с другом бессмысленно.

  • Длина закладки всегда меньше или равна JET_cbBookmarkMost (256) байтам до Windows Vista. В Windows Vista и более поздних выпусках закладки могут быть больше. Максимальный размер закладки равен текущему значению JET_paramKeyMost + 1.

Ключи обычно следует рассматривать как непрозрачные блоки данных. Не следует пытаться использовать внутреннюю структуру этих данных. Однако для всех ключей ESENT можно знать следующие свойства:

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

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

  • Длина ключа всегда меньше или равна JET_cbKeyMost (255) байтам до Windows Vista. В Windows Vista и более поздних выпусках ключи могут быть больше. Максимальный размер ключа равен текущему значению JET_paramKeyMost.

Требования

Требование Значение

Клиент

Требуется Windows Vista или Windows XP.

Сервер

Требуется Windows Server 2008 или Windows Server 2003.

Верхняя часть

Объявлено в Esent.h.

Библиотека

Используйте ESENT.lib.

DLL

Требуется ESENT.dll.

См. также:

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp