Función JetGetSecondaryIndexBookmark

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetGetSecondaryIndexBookmark

La función JetGetSecondaryIndexBookmark recupera un marcador especial para la entrada de índice secundario en la posición actual de un cursor. Después, este marcador se puede usar para cambiar la posición eficaz del cursor a la misma entrada de índice mediante JetGotoSecondaryIndexBookmark. Esto es más útil al cambiar la posición de un índice secundario que contiene claves duplicadas o que contiene varias entradas de índice para el mismo registro.

Windows XP: JetGetSecondaryIndexBookmark se introduce en Windows XP.

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const 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.

pvSecondaryKey

Búfer de salida que recibe la clave secundaria.

cbSecondaryKeyMax

Tamaño máximo, en bytes, del búfer de salida de la clave secundaria.

pcbSecondaryKeyActual

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

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

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

pvPrimaryBookmark

Búfer de salida que recibe el marcador de clave principal.

cbPrimaryBookmarkMax

Tamaño máximo, en bytes, del búfer de salida del marcador de clave principal.

pcbPrimaryKeyActual

Recibe el tamaño real, en bytes, del marcador de clave principal.

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

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

grbit

Reservado para uso futuro.

Valor devuelto

Esta función devuelve el tipo de datos JET_ERR 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_errBufferTooSmall	La operación se completó correctamente, pero uno de los búferes de salida era demasiado pequeño para recibir los datos solicitados. El búfer de salida se ha rellenado con la mayor parte del marcador que cabría. También se ha devuelto el tamaño real del marcador, si se solicita.
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. Windows XP solo devolverá este error y versiones posteriores.
JET_errNoCurrentIndex	El cursor no está actualmente en un índice secundario. No es significativo recuperar un marcador de índice secundario cuando el cursor no usa actualmente un índice secundario. JetGetBookmark debe usarse cuando el cursor no está en un índice secundario.
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 hay una operación de restauración 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. Windows XP solo devolverá este error y versiones posteriores.
JET_errTermInProgress	No es posible completar la operación porque se está cerrando la instancia asociada a la sesión.

Si se ejecuta correctamente, el marcador de índice secundario de la entrada de índice en la posición actual de un cursor se devolverá en los búferes de salida. No se producirá ningún cambio en el estado de la base de datos.

En caso de error, el estado de los búferes de salida y el tamaño real del marcador de índice secundario no se definirán a menos que se devuelva JET_errBufferTooSmall. En caso de que se devuelva JET_errBufferTooSmall, los búferes de salida contendrán tanto el marcador de índice secundario como se ajustará en el espacio proporcionado y el tamaño real del marcador de índice secundario será preciso. En cualquier caso, no se producirá ningún cambio en el estado de la base de datos.

Observaciones

Por lo general, los marcadores 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 todos los marcadores ESENT:

Un marcador identifica de forma única un registro en una tabla determinada.
El marcador de un registro no cambiará durante la vigencia de ese registro.
El marcador de un registro es el mismo que la clave de ese registro en el índice principal sobre la tabla que contiene ese registro. Si no se define ningún índice principal sobre esa tabla, el motor de base de datos creará su propio marcador para el registro.
Los marcadores se pueden comparar entre sí mediante memcmp para establecer su ordenación relativa en el índice principal sobre la tabla de los registros de origen. Si no se define ningún índice principal sobre esa tabla, el orden relativo de los marcadores de esa tabla no es significativo.
No tiene sentido comparar marcadores de registros de tablas diferentes entre sí.
Un marcador siempre es menor o igual que JET_cbBookmarkMost (256) bytes de longitud antes de Windows Vista. En Windows Vista y versiones posteriores, los marcadores pueden ser mayores. El tamaño máximo de un marcador es igual al valor actual de JET_paramKeyMost + 1.

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 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 claves de entradas de índice de índices diferentes 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 más grandes. El tamaño máximo de una clave es igual al valor actual de JET_paramKeyMost.

Requisitos

Requisito	Value
Cliente	Requiere Windows Vista o Windows XP.
Servidor	Requiere Windows Server 2008 o Windows Server 2003.
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
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp

Compartir a través de

Función JetGetSecondaryIndexBookmark