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.

grbit

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

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.

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

Vedere anche

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetRetrieveKey
JetSetIndexRange