Функция JetGetBookmark

Статья
06/13/2023

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

Функция JetGetBookmark

Функция JetGetBookmark извлекает закладку для записи, связанной с записью индекса в текущей позиции курсора. Затем эту закладку можно использовать для перемещения курсора обратно в ту же запись с помощью JetGoToBookmark.

    JET_ERR JET_API JetGetBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual
    );

Параметры

sesid

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

tableid

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

pvBookmark

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

cbMax

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

pcbActual

Фактический размер закладки (в байтах).

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

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

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

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

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

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

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

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

Закладка однозначно идентифицирует запись в данной таблице.
Закладка записи не будет изменяться в течение времени существования этой записи.
Закладка записи совпадает с ключом этой записи в первичном индексе таблицы, содержащей запись. Если для этой таблицы не определен первичный индекс, ядро СУБД создаст собственную закладку для записи.
Закладки можно сравнить друг с другом с помощью функции memcmp , чтобы установить их относительный порядок в основном индексе по таблице исходных записей. Если для этой таблицы не определен первичный индекс, использовать относительный порядок закладок из этой таблицы не имеет смысла.
Сравнивать закладки записей из разных таблиц друг с другом бессмысленно.
Длина закладки всегда меньше или равна JET_cbBookmarkMost (256) байтам до Windows Vista.

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

Требования

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

См. также:

JET_ERR
JET_SESID
JET_TABLEID
JetGoToBookmark
JetStopService
memcmp

Функция JetGetBookmark