Funzione JetSetLS

Si applica a: Windows | Windows Server

Funzione JetSetLS

La funzione JetSetLS consente all'applicazione di associare un handle di contesto noto come Archiviazione locale a un cursore o alla tabella associata a tale cursore. Questo handle di contesto può essere usato dall'applicazione per archiviare i dati ausiliari associati a un cursore o a una tabella. L'applicazione riceve successivamente una notifica tramite un callback di runtime quando è necessario rilasciare l'handle di contesto. In questo modo è possibile associare lo stato allocato dinamicamente a un cursore o a una tabella.

Windows XP:JetSetLS è stato introdotto in Windows XP.

    JET_ERR JET_API JetSetLS(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_LS ls,
      __in          JET_GRBIT grbit
    );

Parametri

sesid

Sessione da utilizzare per questa chiamata.

tableid

Cursore da utilizzare per questa chiamata.

ls

Handle di contesto da associare al cursore o alla tabella.

Quando si specifica JET_bitLSReset, il valore effettivo di questo parametro viene ignorato e viene usato JET_LSNil.

grbit

Gruppo di bit che contengono le opzioni da usare per questa chiamata, che includono zero o più dei seguenti elementi.

Valore	Significato
JET_bitLSCursor	Questa opzione indica che l'handle di contesto deve essere associato al cursore specificato. Se non viene specificato né JET_bitLSCursor né JET_bitLSTable, JET_bitLSCursor viene presunto. È illegale usare questa opzione con JET_bitLSTable. L'operazione avrà esito negativo con JET_errInvalidgrbit se si tenta di eseguire questa operazione.
JET_bitLSReset	Questa opzione indica che l'handle di contesto specificato deve essere ignorato e che l'handle di contesto per l'oggetto scelto deve essere reimpostato su JET_LSNil. È importante notare che questa azione non comporterà un callback per pulire il valore precedente dell'handle di contesto per l'oggetto scelto. È possibile ottenere una pulizia corretta dell'handle di contesto precedente usando JetGetLS con JET_bitLSReset. Per altre informazioni, vedere JetGetLS .
JET_bitLSTable	Questa opzione indica che l'handle di contesto deve essere associato alla tabella associata al cursore specificato. È illegale usare questa opzione con JET_bitLSCursor. L'operazione avrà esito negativo con JET_errInvalidgrbit se si tenta di eseguire questa operazione.

Valore restituito

Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sui possibili errori ESE, vedere Errori del motore di archiviazione estendibile e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errClientRequestToStopJetService	Non è possibile completare l'operazione perché tutte le attività sull'istanza associata alla sessione sono cessate a seguito di una chiamata a JetStopService.
JET_errInvalidgrbit	Una delle opzioni richieste non è valida, utilizzata in modo non corretto o non implementata. Questa situazione può verificarsi per JetSetLS quando vengono specificati JET_bitLSCursor e JET_bitLSTable.
JET_errInstanceUnavailable	Non è possibile completare l'operazione perché l'istanza associata alla sessione ha rilevato un errore irreversibile che richiede la revoca dell'accesso a tutti i dati per proteggere l'integrità dei dati. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errLSAlreadySet	L'handle di contesto specificato non può essere associato all'oggetto richiesto perché dispone già di un handle di contesto associato.
JET_errLSCallbackNotSpecified	Impossibile associare l'handle di contesto specificato all'oggetto richiesto perché il callback di runtime non è stato configurato per l'istanza associata alla sessione.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errRestoreInProgress	Non è possibile completare l'operazione perché è in corso un'operazione di ripristino nell'istanza associata alla sessione.
JET_errTermInProgress	Non è possibile completare l'operazione perché l'istanza associata alla sessione viene arrestata.

In caso di esito positivo, l'handle di contesto specificato è stato associato correttamente all'oggetto richiesto. Non verrà apportata alcuna modifica allo stato del database.

In caso di errore, non è stata apportata alcuna modifica allo stato dell'oggetto richiesto. Non verrà apportata alcuna modifica allo stato del database.

Commenti

L'archiviazione locale per un cursore o una tabella deve essere visualizzata come cache volatile. L'applicazione deve prima provare a recuperare l'handle di contesto usando JetGetLS. Se il valore non è impostato (ovvero è JET_LSNil), l'applicazione deve creare un nuovo contesto e caricarlo nella cache usando JetSetLS. L'applicazione può eliminare la cache usando una chiamata a JetGetLS con JET_bitLSReset. Se il motore di database elimina la cache, verrà generato un callback di runtime per consentire all'applicazione di pulire il contesto. Il tipo di callback verrà JET_cbtypFreeCursorLS per un handle di contesto associato a un cursore e JET_cbtypFreeTableLS per un handle di contesto associato a una tabella. In entrambi i casi, l'handle di contesto verrà passato come pvArg1. Per altre informazioni, vedere JET_CALLBACK .

Il callback di runtime deve essere configurato correttamente per l'istanza associata alla sessione specificata prima di poter usare l'archiviazione locale. Questo callback può essere impostato usando JetSetSystemParameter con JET_paramRuntimeCallback. Per altre informazioni, vedere JetSetSystemParameter e JET_paramRuntimeCallback in Parametri di sistema.

Requisiti

Requisito	Valore
Client	Richiede Windows Vista o Windows XP.
Server	Richiede Windows Server 2008 o Windows Server 2003.
Intestazione	Dichiarato in Esent.h.
Libreria	Usare ESENT.lib.
DLL	Richiede ESENT.dll.

Vedere anche

JET_CALLBACK
JET_ERR
JET_GRBIT
JET_LS
JET_SESID
JET_TABLEID
JetGetLS
JetSetSystemParameter
Parametri di sistema