Función JetGetBookmark

Artículo
06/13/2023

Se aplica a: Windows | Windows Server

Función JetGetBookmark

La función JetGetBookmark recupera el marcador del registro asociado a la entrada de índice en la posición actual de un cursor. A continuación, este marcador se puede usar para cambiar la posición del cursor al mismo registro mediante JetGoToBookmark.

    JET_ERR JET_API JetGetBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual
    );

Parámetros

sesid

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

tableid

Cursor que se va a usar para esta llamada.

pvBookmark

Búfer de salida que recibe el marcador.

cbMax

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

pcbActual

Tamaño real, en bytes, del marcador.

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

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

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_errBufferTooSmall	La operación se completó correctamente, pero el búfer de salida era demasiado pequeño para recibir todo el marcador. 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	La operación no se puede completar 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	La operación no se puede completar porque la instancia asociada a la sesión encontró un error irrecuperable que requiere que se revoque el acceso a todos los datos para proteger la integridad de esos datos. Windows XP: Estos valores devueltos se introducen en Windows XP.
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 después del último registro del índice actual.
JET_errNotInitialized	La operación no se puede completar porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errRestoreInProgress	La operación no se puede completar 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: Este valor devuelto se introduce en Windows XP.
JET_errTermInProgress	La operación no se puede completar porque la instancia asociada a la sesión se está cerrando.

Si esta función se ejecuta correctamente, el marcador del registro asociado a la entrada de índice en la posición actual de un cursor se devolverá en el búfer de salida. No se producirá ningún cambio en el estado de la base de datos.

Si se produce un error en esta función, el estado del búfer de salida y el tamaño real del marcador no se definirán a menos que se devuelva JET_errBufferTooSmall. En caso de que se devuelva JET_errBufferTooSmall, el búfer de salida contendrá la mayor parte del marcador según se ajuste al espacio proporcionado y el tamaño real del marcador será preciso. No se producirá ningún cambio en el estado de la base de datos.

Observaciones

Por lo general, los marcadores deben tratarse como fragmentos opacos de datos. No se debe intentar aprovechar la estructura interna de estos datos. Sin embargo, las siguientes condiciones son verdaderas de 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 la función 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, no es significativo usar el orden relativo de los marcadores de esa tabla.
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.

Windows Vista: En Windows Vista y versiones posteriores, los marcadores pueden ser mayores que JET_cbBookmarkMost (256) bytes. El tamaño máximo de un marcador es igual al valor actual de JET_paramKeyMost + 1.

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_SESID
JET_TABLEID
JetGoToBookmark
JetStopService
memcmp

Función JetGetBookmark