Función JetMakeKey

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetMakeKey

La función JetMakeKey crea claves de búsqueda que se pueden usar para buscar un conjunto de entradas en un índice mediante algunos criterios de búsqueda simples en sus valores de columna de clave. Una clave de búsqueda también es una de las propiedades intrínsecas de un cursor y se usa en las operaciones JetSeek y JetSetIndexRange para buscar entradas de índice que coincidan con estos criterios de búsqueda en el índice actual de ese cursor. Una clave de búsqueda completa se crea en una serie de llamadas JetMakeKey donde cada llamada se usa para cargar el valor de columna para la siguiente columna de clave del índice actual de un cursor. También es posible cargar una clave de búsqueda construida previamente que se ha recuperado del cursor mediante 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
    );

Parámetros

sesid

Sesión que se va a usar para esta llamada.

tableid

Cursor que se va a usar para esta llamada.

pvData

Búfer de entrada que contiene los datos de columna para la columna de clave actual del índice actual del cursor para el que se construye la clave de búsqueda.

El tipo de datos de la columna de los datos del búfer de entrada debe coincidir exactamente con el tipo de datos y otras propiedades de la definición de columna de la columna de clave actual. No se realiza ninguna coerción de tipos en los datos de columna.

Si JET_bitNormalizedKey se especifica en el parámetro grbit , el búfer de entrada debe contener una clave de búsqueda construida anteriormente. Estas claves se obtienen mediante una llamada a JetRetrieveKey.

cbData

Tamaño en bytes de los datos de columna proporcionados en el búfer de entrada.

Si JET_bitNormalizedKey se especifica en el parámetro grbit , este es el tamaño de la clave de búsqueda proporcionada en el búfer de entrada.

Si el tamaño de los datos de columna es cero, se omite el contenido del búfer de entrada. Si JET_bitKeyDataZeroLength se especifica en el parámetro grbit y la columna de clave actual del índice actual del cursor es una columna de longitud variable, se supone que los datos de la columna de entrada son un valor de longitud cero. De lo contrario, se supone que los datos de la columna de entrada son un valor NULL.

grbit

Un grupo de bits que especifica cero o más de las siguientes opciones.

Valor	Significado
JET_bitFullColumnEndLimit	La clave de búsqueda debe construirse de forma que las columnas de clave que vienen después de la columna de clave actual se consideran caracteres comodín. Esto significa que la clave de búsqueda construida se puede usar para buscar coincidencias con las entradas de índice que tienen lo siguiente: Valores exactos de columna proporcionados para esta columna de clave y todas las columnas de clave anteriores. Cualquier valor de columna necesario para las columnas de clave posteriores. Esta opción se debe usar al compilar claves de búsqueda con caracteres comodín para buscar entradas de índice más cercanas al final de un índice. El final del índice es la entrada de índice que se encuentra al pasar al último registro de ese índice. El final del índice no es el mismo que el extremo superior del índice, que puede cambiar según el criterio de ordenación de las columnas de clave del índice. Esta opción solo está disponible en Windows XP y versiones posteriores.
JETbitFullColumnStartLimit	La clave de búsqueda debe construirse de modo que las columnas de clave que vienen después de la columna de clave actual se deben considerar como caracteres comodín. Esto significa que la clave de búsqueda construida se puede usar para buscar coincidencias con las entradas de índice que tienen lo siguiente: Valores exactos de columna proporcionados para esta columna de clave y todas las columnas de clave anteriores. Cualquier valor de columna necesario para las columnas de clave posteriores. Esta opción se debe usar al compilar claves de búsqueda con caracteres comodín para buscar entradas de índice más cercanas al inicio de un índice. El inicio del índice es la entrada de índice que se encuentra al pasar al primer registro de ese índice. El inicio del índice no es el mismo que el extremo inferior del índice, que puede cambiar según el criterio de ordenación de las columnas de clave del índice. Esta opción solo está disponible en Windows XP y versiones posteriores.
JET_bitKeyDataZeroLength	Si el tamaño del búfer de entrada es cero y la columna de clave actual es una columna de longitud variable, esta opción indica que el búfer de entrada contiene un valor de longitud cero. De lo contrario, un tamaño de búfer de entrada de cero indicaría un valor NULL.
JET_bitNewKey	Se debe construir una nueva clave de búsqueda. Se descarta cualquier clave de búsqueda existente anteriormente.
JET_bitNormalizedKey	Cuando se especifica esta opción, se omiten todas las demás opciones, se descarta cualquier clave de búsqueda existente anteriormente y el contenido del búfer de entrada se carga como la nueva clave de búsqueda.
JET_bitPartialColumnEndLimit	La clave de búsqueda debe construirse de forma que la columna de clave actual se considere un carácter comodín de prefijo y que las columnas de clave que vienen después de la columna de clave actual deben considerarse caracteres comodín. Esto significa que la clave de búsqueda construida se puede usar para buscar coincidencias con las entradas de índice que tienen lo siguiente: Valores exactos de columna proporcionados para esta columna de clave y todas las columnas de clave anteriores. Cualquier valor de columna necesario para las columnas de clave posteriores. Esta opción se debe usar al compilar claves de búsqueda con caracteres comodín para buscar entradas de índice más cercanas al final de un índice. El final del índice es la entrada de índice que se encuentra al pasar al último registro de ese índice. El final del índice no es el mismo que el extremo superior del índice, que puede cambiar según el criterio de ordenación de las columnas de clave del índice. Esta opción no se puede usar cuando la columna de clave actual no es una columna de texto ni una columna binaria variable. Si se intenta, se producirá un error en la operación JET_errInvalidgrbit. Esta opción solo está disponible en Windows XP y versiones posteriores.
JET_bitPartialColumnStartLimit	Esta opción indica que la clave de búsqueda debe construirse de forma que la columna de clave actual se considere un carácter comodín de prefijo y que las columnas de clave que vienen después de la columna de clave actual deben considerarse como caracteres comodín. Esto significa que la clave de búsqueda construida se puede usar para buscar coincidencias con las entradas de índice que tienen lo siguiente: Valores exactos de columna proporcionados para esta columna de clave y todas las columnas de clave anteriores. Cualquier valor de columna necesario para las columnas de clave posteriores. Esta opción se debe usar al compilar claves de búsqueda con caracteres comodín para buscar entradas de índice más cercanas al inicio de un índice. El inicio del índice es la entrada de índice que se encuentra al pasar al primer registro de ese índice. El inicio del índice no es el mismo que el extremo inferior del índice, que puede cambiar según el criterio de ordenación de las columnas de clave del índice. Esta opción no se puede usar cuando la columna de clave actual no es una columna de texto ni una columna binaria variable. Si se intenta, se producirá un error en la operación JET_errInvalidgrbit. Esta opción solo está disponible en Windows XP y versiones posteriores.
JET_bitStrLimit	Esta opción indica que la clave de búsqueda debe construirse de forma que las columnas de clave que vienen después de la columna de clave actual se consideren caracteres comodín. Esto significa que la clave de búsqueda construida se puede usar para buscar coincidencias con las entradas de índice que tienen lo siguiente: Valores exactos de columna proporcionados para esta columna de clave y todas las columnas de clave anteriores. Cualquier valor de columna necesario para las columnas de clave posteriores. Esta opción se debe usar al compilar claves de búsqueda con caracteres comodín para buscar entradas de índice más cercanas al final de un índice. El final del índice es la entrada de índice que se encuentra al pasar al último registro de ese índice. El final del índice no es el mismo que el extremo superior del índice, que puede cambiar según el criterio de ordenación de las columnas de clave del índice. Cuando se especifica esta opción en combinación con JET_bitSubStrLimit y la columna de clave actual es una columna de texto, se omitirá esta opción. Este comportamiento está pensado para permitir que el tipo de la columna de clave actual se infiera al compilar la clave de búsqueda. Si desea crear una clave de búsqueda similar para el inicio de un índice, se debe realizar una llamada similar a JetMakeKey para la última columna de clave que no es un carácter comodín, pero sin opciones de caracteres comodín especificadas. A continuación, la clave de búsqueda se encuentra en un estado adecuado para usarla para dicha búsqueda. Esto es análogo al uso de JET_bitFullColumnStartLimit, salvo que la clave de búsqueda no finaliza limpiamente, ya que es después del uso de una opción de carácter comodín. Esta opción ha quedado en desuso para Windows XP y versiones posteriores con el fin de abordar esta semántica complicada. JET_bitFullColumnStartLimit y JET_bitFullColumnEndLimit deben usarse en su lugar siempre que sea posible.
JET_bitSubStrLimit	Esta opción indica que la clave de búsqueda debe construirse de forma que la columna de clave actual se considere un carácter comodín de prefijo y que las columnas de clave que vienen después de la columna de clave actual deben considerarse como caracteres comodín. Esto significa que la clave de búsqueda construida se puede usar para buscar coincidencias con las entradas de índice que tienen lo siguiente: Valores exactos de columna proporcionados para todas las columnas de clave anteriores. Los datos de columna especificados como prefijo de su valor de columna para la columna de clave actual. Cualquier valor de columna para las columnas de clave posteriores. Esta opción se debe usar al compilar claves de búsqueda con caracteres comodín para buscar entradas de índice más cercanas al final de un índice. El final del índice es la entrada de índice que se encuentra al pasar al último registro de ese índice. El final del índice no es el mismo que el extremo superior del índice, que puede cambiar según el criterio de ordenación de las columnas de clave del índice. Cuando esta opción se especifica en combinación con JET_bitStrLimit y la columna de clave actual es una columna de texto, esta opción tendrá prioridad. Esta opción se omite cuando la columna de clave actual no es una columna de texto. Este comportamiento está pensado para permitir que el tipo de la columna de clave actual se infiera al compilar la clave de búsqueda. Si desea crear una clave de búsqueda similar para el inicio de un índice, se debe realizar una llamada similar a JetMakeKey para la columna de clave que va a ser el comodín de prefijo, pero sin que se especifiquen opciones de caracteres comodín. La clave de búsqueda se encuentra en un estado adecuado para usarla para dicha búsqueda. Esto es análogo al uso de JET_bitPartialColumnStartLimit, excepto que la clave de búsqueda no está terminada limpiamente, ya que es después del uso de una opción de caracteres comodín. Esta opción ha quedado en desuso para Windows XP y versiones posteriores para abordar esta semántica complicada. JET_bitPartialColumnStartLimit y JET_bitPartialColumnEndLimit se deben usar en su lugar, siempre que sea posible.

Valor devuelto

Esta función devuelve el JET_ERR tipo de datos con uno de los siguientes códigos de retorno. Para obtener más información sobre los posibles errores de ESE, vea Extensible Storage Engine Errors and Error Handling Parameters.

Código devuelto	Descripción
JET_errSuccess	La operación se ha completado correctamente.
JET_errClientRequestToStopJetService	No es posible completar la operación porque toda la actividad de la instancia asociada a la sesión ha dejado de funcionar como resultado de una llamada a JetStopService.
JET_errIndexTuplesKeyTooSmall	Los datos de columna proporcionados eran demasiado pequeños para crear una clave válida para el índice actual porque ese índice es un índice de tupla y el tamaño mínimo de tupla era mayor que los datos de columna proporcionados. Consulte JetCreateIndex para obtener más información sobre los índices de tupla. Este error solo lo devolverá Windows XP y versiones posteriores.
JET_errInstanceUnavailable	No es posible completar la operación porque la instancia asociada a la sesión ha encontrado un error irrecuperable que requiere que se revoque el acceso a todos los datos para proteger la integridad de esos datos. Este error solo lo devolverá Windows XP y versiones posteriores.
JET_errInvalidBufferSize	Los datos de columna proporcionados no coincidieron con el tamaño requerido por la definición de columna. Esto puede ocurrir si el tipo de datos de la columna es intrínsecamente un tamaño determinado. Esto también puede ocurrir si el tipo de datos de la columna no es intrínsecamente un tamaño determinado, pero la definición de la columna lo declara de longitud fija. Una excepción a esto es que este error no se producirá cuando se proporcionen demasiados datos para una columna de texto de longitud fija, ya que los datos que faltan se rellenarán automáticamente con espacios. Una segunda excepción a esto es que este error no se producirá cuando se proporcionen demasiados datos para una columna binaria de longitud fija porque los datos que faltan se rellenarán automáticamente con ceros.
JET_errInvalidgrbit	Una de las opciones solicitadas no era válida, se usaba de forma ilegal o no se implementaba. Esto puede ocurrir para JetMakeKey cuando: JET_bitPartialColumnStartLimit o JET_bitPartialColumnEndLimit se especifican y la columna de clave correspondiente no es una columna de texto y no es una columna binaria de longitud variable. Este caso solo se produce en Windows XP y versiones posteriores. Se intenta usar más de una de las siguientes opciones: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit y JET_bitFullColumnEndLimit. Este caso solo se produce en Windows XP y versiones posteriores. Se intenta usar JET_bitStrLimit o JET_bitSubStrLimit cuando se usa una de las siguientes opciones: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit y JET_bitFullColumnEndLimit. Este caso solo se produce en Windows XP y versiones posteriores.
JET_errInvalidParameter	Uno de los parámetros proporcionados contenía un valor inesperado o contenía un valor que no tenía sentido cuando se combinaba con el valor de otro parámetro. Esto puede ocurrir para JetMakeKey cuando se especificó JET_bitNormalizedKey y el valor proporcionado en el búfer de entrada era demasiado grande para ser una clave de búsqueda válida.
JET_errKeyIsMade	Los datos de columna proporcionados a JetMakeKey se rechazaron porque los datos de columna ya se han proporcionado para todas las columnas de clave del índice actual. Esto puede ocurrir de tres maneras. La primera forma es si se proporcionan datos de columna para cada columna de clave del índice actual. La segunda forma es si se han proporcionado datos de columna para al menos una columna de clave y se ha elegido una opción de carácter comodín para la última llamada. La tercera manera es si se proporcionó una clave de búsqueda construida anteriormente mediante JET_bitNormalizedKey, que abarca todas las columnas de clave.
JET_errKeyNotMade	No hay ninguna clave de búsqueda actual para el cursor. Esto ocurrirá para JetMakeKey si no se especifica JET_bitNewKey y no se ha construido una clave de búsqueda para este cursor mediante una llamada anterior a JetMakeKey. La clave de búsqueda se eliminará mediante una llamada previa a cualquier API de navegación en el cursor que no sea JetMove.
JET_errNoCurrentIndex	No hay ningún índice actual para el cursor. Esto ocurrirá para JetMakeKey si el cursor está en el índice agrupado de una tabla, no se ha definido un índice principal y no se ha especificado JET_bitNormalizedKey. No es posible construir una clave de búsqueda si el cursor está en un índice que no tiene ninguna columna de clave a menos que se proporcione una clave de búsqueda construida previamente.
JET_errNotInitialized	No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errRestoreInProgress	No es posible completar la operación porque una operación de restauración está en curso en la instancia asociada a la sesión.
JET_errSessionSharingViolation	No se puede usar la misma sesión para más de un subproceso al mismo tiempo. Este error solo lo devolverá Windows XP y versiones posteriores.
JET_errTermInProgress	No es posible completar la operación porque la instancia asociada a la sesión se está cerrando.

Si JET_bitNormalizedKey y JET_bitNewKey no se especificó correctamente, los criterios de búsqueda generarán la clave de búsqueda para una columna de clave más en el índice actual. Si no se especificó JET_bitNormalizedKey y se especificó JET_bitNewKey, se descartará cualquier clave de búsqueda existente anteriormente y se habrá creado uno nuevo por los criterios de búsqueda de la primera columna de clave del índice actual. Si se especificó JET_bitNormalizedKey, se descartaba cualquier clave de búsqueda existente anteriormente y otra nueva cargada desde el búfer de entrada. En cualquier caso, no se producirá ningún cambio en el estado de la base de datos.

Si se ha especificado JET_bitNormalizedKey o JET_bitNewKey, el estado de la clave de búsqueda no está definido. Si no se especificaron ni JET_bitNormalizedKey ni JET_bitNewKey, no se producirá ningún cambio en el estado de la clave de búsqueda. En cualquier caso, no se producirá ningún cambio en el estado de la base de datos.

Observaciones

Las claves se deben tratar como fragmentos opacos de datos. No se debe intentar aprovechar la estructura interna de estos datos. Sin embargo, se conoce lo siguiente sobre todas las claves ESENT:

Las claves se pueden comparar entre sí mediante memcmp para establecer su ordenación relativa en el índice de origen en la tabla de las entradas del índice de origen.
No tiene sentido comparar las claves de las entradas de índice de los distintos índices entre sí.
Una clave siempre es menor o igual que JET_cbKeyMost (255) bytes de longitud antes de Windows Vista. En Windows Vista y versiones posteriores, las claves pueden ser mayores. El tamaño máximo de una clave es igual al valor actual de JET_paramKeyMost.

Las claves de búsqueda pueden ser de un byte más largo si se usó una opción de carácter comodín. En ese caso, la clave de búsqueda será de hasta JET_cbLimitKeyMost (256) bytes para las versiones anteriores a Windows Vista y JET_paramKeyMost + 1 bytes para Windows Vista y versiones posteriores.

Hay una ramificación muy importante para este tamaño máximo de clave. Siempre que haya una entrada de índice que tenga valores de columna lo suficientemente grandes como para hacer que se genere una clave para ese índice que, de lo contrario, sería mayor que este tamaño máximo, esa clave se trunca silenciosamente con ese tamaño máximo. Esto provoca dos efectos:

En el caso de las entradas de un índice único, provocará que las entradas que, de lo contrario, sean únicas, se declaren como duplicados.
En el caso de las entradas de todos los índices, el truncamiento de claves provocará entradas de índice que, de lo contrario, no coincidirían con los criterios de búsqueda de una clave de búsqueda determinada que se declararán como coincidencias.

Las aplicaciones deben prever este truncamiento y evitarlo o compensar sus efectos. En Windows Vista, se ha agregado una nueva marca de índice, JET_bitIndexDisallowTruncation, para facilitar a las aplicaciones evitar truncamientos de claves. Consulte la estructura de JET_INDEXCREATE para obtener más información sobre esta opción de indexación.

Requisitos

Requisito	Value
Cliente	Requiere Windows Vista, Windows XP o Windows 2000 Professional.
Servidor	Requiere Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Encabezado	Declarado en Esent.h.
Library	Use ESENT.lib.
Archivo DLL	Requiere ESENT.dll.

Consulte también

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange

Función JetMakeKey