Funzione JetMove

Si applica a: Windows | Windows Server

Funzione JetMove

La funzione JetMove posiziona un cursore all'inizio o alla fine di un indice e attraversa le voci dell'indice in avanti o indietro. È anche possibile spostare il cursore avanti o indietro sull'indice corrente da un numero specificato di voci di indice. Un altro approccio consiste nel limitare artificialmente le voci di indice che possono essere enumerate usando JetMove configurando un intervallo di indici nel cursore usando JetSetIndexRange.

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

Parametri

sesid

Sessione da utilizzare per questa chiamata.

tableid

Cursore da utilizzare per questa chiamata.

Corvo

Offset arbitrario che indica lo spostamento desiderato del cursore sull'indice corrente.

Oltre agli offset standard, questo parametro può essere impostato anche con una delle opzioni seguenti.

Valore	Significato
JET_MoveFirst	Sposta il cursore sulla prima voce di indice nell'indice (se presente). In questo modo viene reimpostato qualsiasi intervallo di indici impostato con JetSetIndexRange. Nota Il valore letterale di -2147483648 viene usato per indicare questa opzione. Non utilizzare questo valore come offset ordinario o comportamento imprevisto.
JET_MoveLast	Sposta il cursore sull'ultima voce di indice nell'indice (se presente). In questo modo viene reimpostato qualsiasi intervallo di indici impostato con JetSetIndexRange. Nota Il valore letterale di 2147483647 viene usato per indicare questa opzione. Non utilizzare questo valore come offset ordinario o comportamento imprevisto.
JET_MoveNext	Sposta il cursore sulla voce di indice successiva nell'indice (se presente). Questo valore è esattamente uguale a un offset ordinario pari a +1. Rispetta gli intervalli di indici impostati con JetSetIndexRange.
JET_MovePrevious	Sposta il cursore sulla voce di indice precedente nell'indice (se presente). Rispetta gli intervalli di indici impostati con JetSetIndexRange. Questo valore è esattamente uguale a un offset ordinario di -1 o 0 (Zero). Il cursore rimane nella posizione logica corrente e verrà testata l'esistenza della voce di indice corrispondente a tale posizione logica.

grbit

Gruppo di bit che specificano zero o più delle opzioni seguenti.

Valore

Significato

JET_bitMoveKeyNE

Sposta il cursore avanti o indietro in base al numero di voci di indice necessarie per ignorare il numero richiesto di valori di chiave di indice rilevati nell'indice. Questo ha l'effetto di compressione delle voci di indice con valori di chiave duplicati in una singola voce di indice. In genere, un offset sposta il cursore in base al numero specificato di voci di indice indipendentemente dai relativi valori di chiave.

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. Per JetMove, ciò significa che è stata trovata una voce di indice nella posizione richiesta o nell'offset sull'indice corrente.
JET_errClientRequestToStopJetService	L'operazione non può essere completata perché tutte le attività nell'istanza associata alla sessione sono cessate a seguito di una chiamata a JetStopService.
JET_errInstanceUnavailable	Impossibile 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. Windows XP: Questo valore restituito viene introdotto in Windows XP.
JET_errNoCurrentRecord	Il cursore non è attualmente posizionato su una voce di indice. Per JetMove, ciò significa che non è stata trovata una voce di indice nella posizione richiesta o nell'offset sull'indice corrente.
JET_errNotInitialized	Impossibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errRecordDeleted	Il cursore è attualmente posizionato logicamente su una voce di indice che corrisponde a un record eliminato.
JET_errRestoreInProgress	Impossibile completare l'operazione perché è in corso un'operazione di ripristino nell'istanza associata alla sessione.
JET_errSessionSharingViolation	La stessa sessione non può essere usata contemporaneamente per più thread. Windows XP: Questo valore restituito viene introdotto in Windows XP.
JET_errTermInProgress	Impossibile completare l'operazione perché l'istanza associata alla sessione viene arrestata.

Se questa funzione ha esito positivo, il cursore verrà posizionato in corrispondenza di una voce di indice corrispondente alla posizione o all'offset richiesti. Se un record è stato preparato per l'aggiornamento, l'aggiornamento verrà annullato. Se un intervallo di indici è attivo e JET_MoveFirst o JET_MoveLast è stato specificato, tale intervallo di indici verrà annullato. Non verrà apportata alcuna modifica allo stato del database.

Se questa funzione ha esito negativo, la posizione del cursore rimarrà invariata a meno che non venga restituita JET_errNoCurrentRecord. In tal caso, il cursore verrà posizionato dove sarebbe stata la voce di indice corrispondente alla posizione o all'offset richiesto. Il cursore può essere spostato rispetto a tale posizione, ma non è ancora in una voce di indice valida. Se un record è stato preparato per l'aggiornamento, l'aggiornamento verrà annullato. Se un intervallo di indici è attivo e JET_MoveFirst o JET_MoveLast è stato specificato, tale intervallo di indici verrà annullato. Non verrà apportata alcuna modifica allo stato del database.

Commenti

Un cursore può essere spostato in due posizioni speciali usando JetMove, Before First e After Last. Se il cursore si trova sulla prima voce di indice nella tabella e JetMove viene chiamato con JET_MovePrevious, la chiamata avrà esito negativo con JET_errNoCurrentRecord e il cursore verrà posizionato logicamente prima della prima voce dell'indice. Questa posizione logica viene mantenuta anche se viene inserita un'altra voce di indice prima della prima voce dell'indice. Si verifica una situazione analoga per After Last rispetto alla fine dell'indice. Prima di First e After Last sono più utili durante la configurazione di un intervallo di voci di indice da eseguire tramite JetMove, usando un modello iteratore che prevede di passare sempre all'elemento successivo (o precedente) prima di usare tale elemento.

Il set di voci di indice che è possibile visitare da JetMove può essere limitato impostando un intervallo di indici sul cursore. Ciò è utile per le applicazioni che enumerare un set di voci di indice che corrispondono a criteri semplici che possono essere espressi tramite una coppia di chiavi di ricerca compilate per tale indice. Per altre informazioni, vedere JetSetIndexRange.

Nelle versioni precedenti a Windows Server 2003 SP1 esiste un problema in JetMove che si verifica in alcuni casi specifici, che influisce sull'imposizione corretta di un intervallo di indici impostato dalla funzione JetSetIndexRange . Se il cursore è attualmente precedente alla prima voce di indice e viene impostato un intervallo di indici con un limite superiore inferiore alla prima voce di indice, la chiamata successiva a JetMove passerà erroneamente a tale voce di indice anziché con errori con JET_errNoCurrentRecord, come previsto. Lo stesso errore si verificherà per la situazione analoga a partire dalla fine dell'indice. Questa situazione può verificarsi in un'applicazione che configura un intervallo di indici e la sposta usando un iteratore che prevede di iniziare prima della prima voce di indice membro del set di voci da enumerare, anziché iniziare sulla prima voce di indice del set. Questa situazione si verifica anche nel caso analogo a partire dalla fine dell'indice. La soluzione alternativa consiste nell'eseguire manualmente l'applicazione per verificare che la voce di indice acquisita si trova all'interno dell'intervallo di indici confrontando la chiave per la voce di indice corrente (recuperata tramite JetRetrieveKey) con la chiave che rappresenta la fine dell'intervallo di indici corrente (recuperata tramite JetRetrieveKey usando JET_bitRetrieveCopy).

È importante prestare attenzione quando si passano offset calcolati a JetMove. Se l'offset calcolato è minore o uguale a JET_MoveFirst, tale offset deve essere suddiviso in più parti, ognuna delle quali viene passata separatamente a JetMove ma all'interno di una singola transazione per ottenere l'effetto desiderato. Lo stesso vale per gli offset maggiori o uguali a JET_MoveNext. È improbabile che un'applicazione subisse questo problema nel mondo reale, ma è bene avere una difesa contro questo caso data la semantica molto diversa di JET_MoveFirst e JET_MoveLast da un offset ordinario.

Quando JetMove viene chiamato con un offset molto grande, ad esempio quando il parametro cRow è impostato su 1000, JetMove attraversa tutte le 1000 voci di indice per raggiungere la posizione finale. Attualmente, l'API ESE non offre un modo efficiente per passare direttamente a una determinata voce di indice in base all'offset senza attraversare ogni voce di indice.

Requisiti

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

Vedere anche

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange