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

Функция JetRetrieveKey

  • Статья

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

Функция JetRetrieveKey

Функция JetRetrieveKey извлекает ключ для записи индекса в текущей позиции курсора. Такие ключи создаются с помощью вызовов JetMakeKey. Затем полученный ключ можно использовать для эффективного возврата курсора в ту же запись индекса путем вызова JetSeek.

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

Параметры

sesid

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

tableid

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

pvData

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

cbMax

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

pcbActual

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

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

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

grbit

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

Значение

Значение

JET_bitRetrieveCopy

Если этот параметр указан, подсистема вернет ключ поиска для курсора. Ключ поиска создается с помощью одного или нескольких предыдущих вызовов JetMakeKey для поиска этого ключа с помощью JetSeek или задания диапазона индекса с помощью JetSetIndexRange.

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

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

Код возврата

Описание

JET_errSuccess

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

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

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

JET_errKeyNotMade

Текущий ключ поиска для курсора отсутствует. Это произойдет для JetRetrieveKey , если указан JET_bitRetrieveCopy и ключ поиска не был создан для этого курсора с помощью предварительного вызова JetMakeKey. Ключ поиска будет удален при предварительном вызове любого навигационного API на курсоре, отличном от JetMove.

JET_errNoCurrentRecord

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

JET_errNotInitialized

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

JET_errTermInProgress

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

JET_wrnBufferTruncated

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

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

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

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

Комментарии

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

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

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

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

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

В этом API есть важная ошибка, которая присутствует во всех выпусках. Если ключ поиска запрашивается с использованием JET_bitRetrieveCopy и выходной буфер слишком мал для получения всего ключа, JET_wrnBufferTruncated не возвращается. вместо этого будет возвращено JET_errSuccess. Важно убедиться, что фактический размер ключа, возвращенного с помощью pcbActual , меньше или равен размеру выходного буфера. Если фактический размер превышает размер выходного буфера, вызывающий объект JetRetrieveKey должен реагировать так, как если бы вместо этого возвращались JET_wrnBufferTruncated.

Требования

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

Клиент

Требуется Windows Vista, Windows XP или Windows 2000 Профессиональная.

Сервер

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

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

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

Библиотека

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

DLL

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

См. также:

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange