Función JetSetLS

Se aplica a: Windows | Windows Server

Función JetSetLS

La función JetSetLS permite a la aplicación asociar un identificador de contexto conocido como Almacenamiento local con un cursor o la tabla asociada a ese cursor. La aplicación puede usar este identificador de contexto para almacenar datos auxiliares asociados a un cursor o una tabla. Posteriormente, se notifica a la aplicación mediante una devolución de llamada en tiempo de ejecución cuando se debe liberar el identificador de contexto. Esto permite asociar el estado asignado dinámicamente con un cursor o tabla.

Windows XP:JetSetLS se introduce en Windows XP.

    JET_ERR JET_API JetSetLS(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_LS ls,
      __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.

ls

Identificador de contexto que se va a asociar con el cursor o la tabla.

Cuando se especifica JET_bitLSReset, se omite el valor real de este parámetro y se usa JET_LSNil.

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_bitLSCursor	Esta opción indica que el identificador de contexto debe asociarse con el cursor especificado. Si no se especifica ni JET_bitLSCursor ni JET_bitLSTable, se supone JET_bitLSCursor. No es válido usar esta opción con JET_bitLSTable. Si se intenta, se producirá un error en la operación con JET_errInvalidgrbit.
JET_bitLSReset	Esta opción indica que se debe omitir el identificador de contexto especificado y que el identificador de contexto del objeto elegido debe restablecerse a JET_LSNil. Es importante tener en cuenta que esta acción no dará lugar a una devolución de llamada para limpiar el valor anterior del identificador de contexto para el objeto elegido. Se puede lograr una limpieza adecuada del identificador de contexto anterior mediante JetGetLS con JET_bitLSReset. Consulte JetGetLS para obtener más información.
JET_bitLSTable	Esta opción indica que el identificador de contexto debe estar asociado a la tabla asociada al cursor especificado. Es ilegal usar esta opción con JET_bitLSCursor. Si se intenta, se producirá un error en la operación con JET_errInvalidgrbit.

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_errInvalidgrbit	Una de las opciones solicitadas no era válida, se usaba incorrectamente o no se implementaba. Esto puede ocurrir para JetSetLS cuando se especifican JET_bitLSCursor y JET_bitLSTable.
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_errLSAlreadySet	El identificador de contexto especificado no se pudo asociar al objeto solicitado porque ya tenía un identificador de contexto asociado a él.
JET_errLSCallbackNotSpecified	No se pudo asociar el identificador de contexto especificado al objeto solicitado porque la devolución de llamada en tiempo de ejecución no se ha configurado para la instancia asociada a la sesión.
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_errTermInProgress	No es posible completar la operación porque la instancia asociada a la sesión se está cerrando.

Si se ejecuta correctamente, el identificador de contexto especificado se asoció correctamente con el objeto solicitado. No se producirá ningún cambio en el estado de la base de datos.

Si se produce un error, no se ha producido ningún cambio en el estado del objeto solicitado. No se producirá ningún cambio en el estado de la base de datos.

Comentarios

El almacenamiento local para un cursor o tabla debe verse como una caché volátil. La aplicación primero debe intentar recuperar el identificador de contexto mediante JetGetLS. Si no se establece el valor (es decir, es JET_LSNil), la aplicación debe crear un nuevo contexto y cargarlo en la memoria caché mediante JetSetLS. La aplicación puede purgar la memoria caché mediante una llamada a JetGetLS con JET_bitLSReset. Si el motor de base de datos purga la memoria caché, se generará una devolución de llamada en tiempo de ejecución para dar a la aplicación la oportunidad de limpiar ese contexto. El tipo de devolución de llamada se JET_cbtypFreeCursorLS para un identificador de contexto asociado a un cursor y JET_cbtypFreeTableLS para un identificador de contexto asociado a una tabla. En cualquier caso, el identificador de contexto se pasará como pvArg1. Consulte JET_CALLBACK para obtener más información.

La devolución de llamada en tiempo de ejecución debe estar configurada correctamente para la instancia asociada a la sesión especificada antes de que se pueda usar el almacenamiento local. Esta devolución de llamada se puede establecer mediante JetSetSystemParameter con JET_paramRuntimeCallback. Consulte JetSetSystemParameter y JET_paramRuntimeCallback en Parámetros del sistema para obtener más información.

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_CALLBACK
JET_ERR
JET_GRBIT
JET_LS
JET_SESID
JET_TABLEID
JetGetLS
JetSetSystemParameter
Parámetros del sistema