Función JetRetrieveKey

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetRetrieveKey

La función JetRetrieveKey recupera la clave de la entrada de índice en la posición actual de un cursor. Estas claves se construyen mediante llamadas a JetMakeKey. A continuación, la clave recuperada se puede usar para devolver eficazmente ese cursor a la misma entrada de índice mediante una llamada a 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
    );

Parámetros

sesid

La sesión que se va a usar para esta llamada.

tableid

Cursor que se va a usar para esta llamada.

pvData

Búfer de salida que recibirá la clave.

cbMax

Tamaño máximo en bytes del búfer de salida.

pcbActual

Recibe el tamaño real en bytes de la clave.

Si este parámetro es NULL, no se devolverá el tamaño real de la clave.

Si el búfer de salida es demasiado pequeño, se devolverá el tamaño real de la clave. Esto significa que este número será mayor que el tamaño del búfer de salida.

grbit

Un grupo de bits que contienen las opciones que se usarán para esta llamada, que incluyen cero o más de lo siguiente.

Valor	Significado
JET_bitRetrieveCopy	Cuando se especifica, el motor devolverá la clave de búsqueda del cursor. La clave de búsqueda se crea con una o varias llamadas anteriores a JetMakeKey con el fin de buscar esa clave mediante JetSeek o establecer un intervalo de índices mediante JetSetIndexRange.

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_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_errKeyNotMade	No hay ninguna clave de búsqueda actual para el cursor. Esto ocurrirá para JetRetrieveKey si se especifica JET_bitRetrieveCopy 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_errNoCurrentRecord	El cursor no se coloca en un registro. Esto puede ocurrir por diversos motivos. Por ejemplo, esto ocurrirá si el cursor se coloca actualmente después del último registro del índice actual.
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.
JET_wrnBufferTruncated	La operación se completó correctamente, pero el búfer de salida era demasiado pequeño para recibir toda la clave. El búfer de salida se ha rellenado con la mayor parte de la clave que cabría. También se ha devuelto el tamaño real de la clave, si se solicita. Nota Este error no se devolverá si se especifica JET_bitRetrieveCopy. Consulte la sección Comentarios para obtener más información.

Si se ejecuta correctamente, la clave de la entrada de índice en la posición actual de un cursor se devolverá en el búfer de salida. Si se devuelve JET_wrnBufferTruncated, el búfer de salida contendrá la mayor parte de la clave que caberá en el espacio proporcionado y el tamaño real de la clave será preciso. No se producirá ningún cambio en el estado de la base de datos.

Si se produce un error, el estado del búfer de salida y el tamaño real de la clave no se definirán. No se producirá ningún cambio en el estado de la base de datos.

Comentarios

Por lo general, las claves se deben tratar como fragmentos opacos de datos. No se debe intentar aprovechar la estructura interna de estos datos. Sin embargo, se pueden conocer las siguientes propiedades sobre todas las claves DE ESENT:

Las claves se pueden comparar entre sí mediante la función 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.

Además de las propiedades anteriores de las claves ESENT en general, es importante tener en cuenta que una clave de búsqueda es diferente de la clave para una entrada de índice. En concreto, una clave de búsqueda puede ser mayor que una clave normal. Esta longitud adicional se produce cuando se usa una opción comodín al construir la clave de búsqueda. Consulte JetMakeKey para obtener más información.

Hay un error importante en esta API que está presente en todas las versiones. Si se solicita la clave de búsqueda con el uso de JET_bitRetrieveCopy y el búfer de salida es demasiado pequeño para recibir toda la clave, no se devolverá JET_wrnBufferTruncated. JET_errSuccess se devolverá en su lugar. Es importante comprobar que el tamaño real de la clave tal y como se devuelve mediante pcbActual es menor o igual que el tamaño del búfer de salida. Si el tamaño real es mayor que el tamaño del búfer de salida, el autor de la llamada de JetRetrieveKey debe reaccionar como si se devolvieran JET_wrnBufferTruncated en su lugar.

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
JetMakeKey
JetSeek
JetSetIndexRange

Función JetRetrieveKey