Condividi tramite

Funzione JetSetCurrentIndex4

  • Articolo

Si applica a: Windows | Windows Server

Funzione JetSetCurrentIndex4

La funzione JetSetCurrentIndex4 viene utilizzata per impostare l'indice corrente di un cursore. L'indice corrente di un cursore definisce i record in una tabella visibili a tale cursore e l'ordine in cui vengono visualizzati selezionando il set di voci di indice da utilizzare per esporre tali record.

    JET_ERR JET_API JetSetCurrentIndex4(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      JET_PCSTR szIndexName,
      __in_opt      JET_INDEXID* pindexid,
      __in          JET_GRBIT grbit,
      __in          unsigned long itagSequence
    );

Parametri

sesid

Sessione da utilizzare per questa chiamata.

tableid

Cursore da utilizzare per questa chiamata.

szIndexName

Nome dell'indice da selezionare per il cursore. Se questo parametro è NULL o una stringa vuota, verrà selezionato l'indice cluster. Se per la tabella viene definito un indice primario, tale indice verrà selezionato perché corrisponde all'indice cluster. Se non viene definito alcun indice primario per la tabella, verrà selezionato l'indice sequenziale. L'indice sequenziale non ha alcuna definizione di indice. Per altre informazioni, vedere JetCreateIndex .

Se pindexid non è NULL, il nome dell'indice verrà ignorato e l'indice verrà selezionato dal relativo ID indice.

pindexid

ID dell'indice da selezionare per il cursore.

L'ID indice è un handle volatile e opaco che può essere usato per selezionare rapidamente un indice. Questo ID può essere recuperato usando JetGetIndexInfo o JetGetTableIndexInfo usando l'opzione JET_IdxInfoIndexId.

Se pindexid è NULL, l'indice verrà selezionato in base al nome dell'indice e l'ID dell'indice verrà ignorato.

Quando questo parametro non è presente, si presuppone che il relativo valore sia NULL.

grbit

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

Valore

Significato

JET_bitMoveFirst

Questa opzione indica che il cursore deve essere posizionato sulla prima voce dell'indice specificato. Se l'indice cluster è selezionato (indice primario o indice sequenziale) e l'indice corrente è un indice secondario, si presuppone JET_bitMoveFirst. Se l'indice corrente è selezionato, questa opzione viene ignorata e non viene apportata alcuna modifica alla posizione del cursore.

JET_bitNoMove

Questa opzione indica che il cursore deve essere posizionato sulla voce di indice del nuovo indice corrispondente al record associato alla voce di indice nella posizione corrente del cursore sull'indice precedente.

Se la definizione per il nuovo indice contiene almeno una colonna chiave multivalore, la voce dell'indice di destinazione è ambigua. In questo caso, l'oggetto itagSequence specificato viene usato per selezionare il multivalore della colonna chiave multivalore più significativa utilizzata per posizionare il cursore. È necessario passare un singolo itagSequence anche nel caso di più colonne chiave multivalore, perché il motore espande solo tutti i valori per la colonna chiave multivalore più significativa. Per altri dettagli, vedere JetCreateIndex .

Se viene specificato JET_bitMoveFirst, questa opzione viene ignorata.

Se l'indice corrente è selezionato, questa opzione viene ignorata e non viene apportata alcuna modifica alla posizione del cursore. Quando questo parametro non è presente, si presuppone che il relativo valore sia JET_bitMoveFirst.

itagSequence

Numero di sequenza del valore di colonna multivalore che verrà utilizzato per posizionare il cursore sul nuovo indice.

Questo parametro viene usato solo in combinazione con JET_bitNoMove. Per altri dettagli, vedere la descrizione di questa opzione.

Quando questo parametro non è presente o è impostato su zero, si presuppone che il valore sia 1.

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_errBadItagSequence

Viene selezionato un indice secondario con l'opzione JET_bitNoMove e non esiste alcun valore per la prima colonna chiave multivalore nella definizione per il nuovo indice corrispondente al numero di sequenza specificato.

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_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_errInvalidIndexId

Il contenuto dell'ID indice non è valido o è scaduto e deve essere aggiornato. Ciò può verificarsi per JetSetCurrentIndex4 quando:

  • pindexid-cbStruct> non è delle dimensioni previste (Windows Server 2003 e versioni successive).

  • Il motore è stato arrestato dopo il recupero dell'ID di indice.

  • Tutti i cursori che fanno riferimento alla tabella contenente l'indice corrispondente all'ID di indice sono stati chiusi e il motore ha rimosso la definizione dell'indice dalla cache dello schema.

  • L'ID di indice viene usato con un cursore aperto nella tabella errata.

  • L'indice è stato eliminato o non è ancora visibile alla sessione.

JET_errInvalidName

Uno dei nomi di oggetto specificati non è valido. Tutti i nomi degli oggetti devono essere conformi allo stesso set di regole. Le regole sono le seguenti:

  • I nomi degli oggetti devono essere costituiti da caratteri ASCII.

  • I nomi degli oggetti devono avere almeno un carattere di lunghezza.

  • I nomi degli oggetti non possono superare JET_cbNameMost (64) caratteri di lunghezza.

  • I nomi degli oggetti potrebbero non iniziare con uno spazio.

  • I nomi degli oggetti non possono contenere caratteri di controllo ASCII (0x00 tramite 0x1F).

  • I nomi degli oggetti non possono contenere un punto esclamativo (!), punto (.), parentesi quadra sinistra ([) o parentesi quadra chiusa (]).

  • Dopo la convalida, solo la parte della stringa fino al primo spazio (se presente) verrà usata per il nome dell'oggetto. Ciò significa che i nomi degli oggetti potrebbero non contenere uno spazio.

JET_errInvalidParameter

Uno dei parametri forniti conteneva un valore imprevisto o conteneva un valore che non ha senso se combinato con il valore di un altro parametro. Ciò può verificarsi per JetSetCurrentIndex4 quando pindexid non è NULL e pindexid-cbStruct> non è delle dimensioni previste (Windows XP e versioni precedenti).

JET_errNoCurrentRecord

Viene selezionato un indice secondario con l'opzione JET_bitNoMove e non è presente alcuna voce di indice nel nuovo indice corrispondente al record associato alla voce di indice nella posizione corrente del cursore sull'indice precedente.

JET_errNotInitialized

Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.

JET_errOutOfCursors

Il motore ha esaurito il pool di risorse usate per aprire i cursori. Il numero massimo di cursori che è possibile aprire contemporaneamente viene controllato tramite JET_paramMaxCursors. Per altre informazioni, vedere JetSetSystemParameter . Ciò può verificarsi per JetSetCurrentIndex4 quando è stato selezionato un indice secondario e il motore non può aprire un cursore interno per usare tale indice.

JET_errRestoreInProgress

Non è possibile 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.

Questo errore verrà restituito solo da Windows XP e versioni successive.

JET_errTermInProgress

Non è possibile completare l'operazione perché l'istanza associata alla sessione viene arrestata.

In caso di esito positivo, l'indice corrente del cursore è impostato sull'indice richiesto. Le voci di indice possono ora essere richieste usando JetSeek in base alla definizione di indice dell'indice richiesto. Le voci di indice possono essere enumerate anche usando JetMove nell'ordine specificato da tale definizione di indice. La posizione corrente del cursore è impostata sulla prima voce di indice dell'indice (JET_bitMoveFirst) o su una voce di indice specifica correlata alla posizione corrente del cursore sull'indice precedente (JET_bitNoMove). Non verrà eseguita alcuna modifica allo stato del database.

In caso di errore, l'indice corrente e la posizione corrente del cursore si trovano in uno stato non definito. Non verrà eseguita alcuna modifica allo stato del database.

Commenti

Se l'hint ID di indice non è aggiornato, l'API ha semplicemente esito negativo. Non esiste alcun fallback al nome di testo dell'indice in questo caso, come si potrebbe aspettare. Questo fallback deve essere eseguito manualmente dal chiamante dell'API.

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.

Unicode

Implementato come JetSetCurrentIndex4W (Unicode) e JetSetCurrentIndex4A (ANSI).

Vedere anche

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JET_INDEXID
JetCreateIndex
JetGetCurrentIndex
JetGetIndexInfo
JetGetTableIndexInfo
JetMove
JetSeek
JetSetSystemParameter