Функция JetGetBookmark

Статья
09/24/2022

Область применения: Windows | Сервер Windows

Функция 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 выходной буфер будет содержать столько закладки, сколько будет соответствовать указанному пространству, а фактический размер закладки будет точным. Изменение состояния базы данных не произойдет.

Remarks

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

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

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

Требования

Требование	Значение
Клиент	Требуется Windows Vista, Windows XP или Windows 2000 Professional.
Server	Требуется 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