Функция JetMakeKey

  • Статья

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

Функция JetMakeKey

Функция JetMakeKey создает ключи поиска, которые затем можно использовать для поиска набора записей в индексе по некоторым простым условиям поиска по значениям их ключевых столбцов. Ключ поиска также является одним из встроенных свойств курсора и используется операциями JetSeek и JetSetIndexRange для поиска записей индекса, соответствующих этим условиям поиска, в текущем индексе этого курсора. Полный ключ поиска создается в серии вызовов JetMakeKey , где каждый вызов используется для загрузки значения столбца для следующего ключевого столбца текущего индекса курсора. Можно также загрузить ранее созданный ключ поиска, полученный из курсора, с помощью JetRetrieveKey.

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit
    );

Параметры

sesid

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

tableid

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

pvData

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

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

Если JET_bitNormalizedKey указан в параметре grbit , входной буфер должен содержать ранее созданный ключ поиска. Такие ключи получаются с помощью вызова JetRetrieveKey.

cbData

Размер данных столбца, предоставленных во входном буфере, в байтах.

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

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

grbit

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

Значение

Значение

JET_bitFullColumnEndLimit

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

  • Точные значения столбцов, указанные для этого ключевого столбца и всех предыдущих ключевых столбцов.

  • Все значения столбцов, необходимые для последующих ключевых столбцов.

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

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

JETbitFullColumnStartLimit

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

  • Точные значения столбцов, указанные для этого ключевого столбца и всех предыдущих ключевых столбцов.

  • Все значения столбцов, необходимые для последующих ключевых столбцов.

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

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

JET_bitKeyDataZeroLength

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

JET_bitNewKey

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

JET_bitNormalizedKey

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

JET_bitPartialColumnEndLimit

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

  • Точные значения столбцов, указанные для этого ключевого столбца и всех предыдущих ключевых столбцов.

  • Все значения столбцов, необходимые для последующих ключевых столбцов.

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

Этот параметр нельзя использовать, если текущий ключевой столбец не является текстовым или переменным двоичным столбцом. Операция завершится ошибкой с JET_errInvalidgrbit, если предпринята попытка.

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

JET_bitPartialColumnStartLimit

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

  • Точные значения столбцов, указанные для этого ключевого столбца и всех предыдущих ключевых столбцов.

  • Все значения столбцов, необходимые для последующих ключевых столбцов.

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

Этот параметр нельзя использовать, если текущий ключевой столбец не является текстовым или переменным двоичным столбцом. Операция завершится ошибкой с JET_errInvalidgrbit, если предпринята попытка.

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

JET_bitStrLimit

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

  • Точные значения столбцов, указанные для этого ключевого столбца и всех предыдущих ключевых столбцов.

  • Все значения столбцов, необходимые для последующих ключевых столбцов.

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

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

Если вы хотите создать аналогичный ключ поиска для начала индекса, следует выполнить аналогичный вызов JetMakeKey для последнего ключевого столбца, который не является подстановочным знаком, но без указанных параметров подстановочного знака. Затем ключ поиска находится в соответствующем состоянии для такого поиска. Это аналогично использованию JET_bitFullColumnStartLimit, за исключением того, что ключ поиска не завершен четко, как после использования параметра с подстановочными знаками.

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

JET_bitSubStrLimit

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

  • Точные значения столбцов, предоставленные для всех предыдущих ключевых столбцов.

  • Указанные данные столбца в качестве префикса значения столбца для текущего ключевого столбца.

  • Любые значения столбцов для последующих ключевых столбцов.

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

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

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

Этот параметр не рекомендуется использовать для Windows XP и более поздних выпусков, чтобы устранить эту неудобную семантику. по возможности следует использовать JET_bitPartialColumnStartLimit и JET_bitPartialColumnEndLimit.

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

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

Код возврата

Описание

JET_errSuccess

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

JET_errClientRequestToStopJetService

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

JET_errIndexTuplesKeyTooSmall

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

JET_errInstanceUnavailable

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

JET_errInvalidBufferSize

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

JET_errInvalidgrbit

Один из запрошенных вариантов был недопустимым, использовался незаконным образом или не был реализован. Это может произойти для JetMakeKey , если:

  • JET_bitPartialColumnStartLimit или JET_bitPartialColumnEndLimit, а соответствующий ключевой столбец не является текстовым столбцом и двоичным столбцом переменной длины. Этот случай происходит только в Windows XP и более поздних выпусках.

  • Предпринимается попытка одновременно использовать несколько следующих параметров: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit и JET_bitFullColumnEndLimit. Этот случай происходит только в Windows XP и более поздних выпусках.

  • Попытка использовать JET_bitStrLimit или JET_bitSubStrLimit при использовании одного из следующих параметров: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit и JET_bitFullColumnEndLimit. Этот случай происходит только в Windows XP и более поздних выпусках.

JET_errInvalidParameter

Один из предоставленных параметров содержал непредвиденное значение или значение, которое не имело смысла в сочетании со значением другого параметра.

Это может произойти для JetMakeKey , если JET_bitNormalizedKey указан и значение, указанное во входном буфере, было слишком большим, чтобы быть допустимым ключом поиска.

JET_errKeyIsMade

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

JET_errKeyNotMade

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

JET_errNoCurrentIndex

Текущий индекс для курсора отсутствует. Это произойдет для JetMakeKey , если курсор находится на кластеризованном индексе таблицы, первичный индекс не определен, а JET_bitNormalizedKey не указан. Невозможно создать ключ поиска, если курсор находится на индексе, который не содержит ключевых столбцов, если не указан ранее созданный ключ поиска.

JET_errNotInitialized

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

JET_errTermInProgress

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

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

Если JET_bitNormalizedKey или JET_bitNewKey указана ошибка, состояние ключа поиска не определено. Если ни JET_bitNormalizedKey, ни JET_bitNewKey не указаны, изменение состояния ключа поиска не произойдет. В любом случае изменение состояния базы данных не произойдет.

Комментарии

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

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

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

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

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

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

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

  • Для записей во всех индексах усечение ключа приведет к тому, что записи индекса, которые в противном случае не соответствовали бы условиям поиска данного ключа поиска, будут объявлены как совпадения.

Приложения должны предвидеть такое усечение и либо избегать его, либо компенсировать его последствия. В Windows Vista добавлен новый флаг индекса, JET_bitIndexDisallowTruncation, чтобы упростить для приложений предотвращение усечений ключей. Дополнительные сведения об этом параметре индексирования см. в разделе структура JET_INDEXCREATE .

Требования

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

Клиент

Требуется 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
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange