Funzione JetIntersectIndexes
Si applica a: Windows | Windows Server
Funzione JetIntersectIndexes
La funzione JetIntersectIndexes calcola l'intersezione tra più set di voci di indice da indici secondari diversi sulla stessa tabella. Questa operazione è utile per trovare il set di record in una tabella che corrispondono a due o più criteri che possono essere espressi usando intervalli di indici.
JET_ERR JET_API JetIntersectIndexes(
__in JET_SESID sesid,
__in JET_INDEXRANGE* rgindexrange,
__in unsigned long cindexrange,
__in_out JET_RECORDLIST* precordlist,
__in JET_GRBIT grbit
);
Parametri
sesid
Sessione da utilizzare per questa chiamata.
rgindexrange
Puntatore a una matrice di strutture JET_IndexRange . Ogni struttura include una JET_TABLEID configurata per contenere uno degli intervalli di indici da intersecare. Per altre informazioni, vedere JET_IndexRange.
cindexrange
Numero di strutture JET_IndexRange nella matrice contenuta nel parametro rgindexrange .
precordlist
Puntatore a una struttura JET_RECORDLIST . Questa struttura verrà popolata con informazioni sufficienti per attraversare la tabella temporanea con i risultati di JetIntersectIndexes.
Buffer di output che riceve una struttura JET_RECORDLIST . La struttura contiene una descrizione del set di risultati dell'intersezione.
grbit
Riservato per utilizzi futuri.
Valore restituito
Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sugli errori ESE, vedere Extensible Storage Engine Errors and Error Handling Parameters.For more information about ESE errors errors, see Extensible Storage Engine Errors and Error Handling Parameters.
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_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. Windows XP: Questo valore restituito viene introdotto in Windows XP. |
JET_errInvalidgrbit |
Una delle opzioni richieste non è valida, utilizzata in modo non corretto o non implementata. Questo errore viene restituito da JetIntersectIndexes quando: Il grbit contenuto nella struttura JET_IndexRange a cui punta qualsiasi elemento nella matrice rgindexrange non è uguale a JET_bitRecordInIndex. |
JET_errInvalidParameter |
Uno dei parametri forniti contiene un valore imprevisto o un valore incoerente se combinato con il valore di un altro parametro. Questo errore viene restituito da JetIntersectIndexes per i motivi seguenti:
|
JET_errInvalidSesid |
L'handle di sessione non è valido o fa riferimento a una sessione chiusa. Questo errore non viene restituito in tutte le circostanze. Gli handle vengono convalidati solo in base al massimo sforzo. |
JET_errNotInitialized |
Non è possibile completare l'operazione perché l'istanza associata alla sessione non è stata inizializzata. |
JET_errOutOfCursors |
L'operazione non è riuscita perché il motore non è riuscito ad allocare le risorse necessarie per aprire un nuovo cursore. Le risorse del cursore vengono configurate chiamando JetSetSystemParameter con JET_paramMaxCursors specificato nel parametro paramid . |
JET_errOutOfMemory |
L'operazione non è riuscita perché non è possibile allocare memoria sufficiente per completarla. JetIntersectIndexes può restituire JET_errOutOfMemory se lo spazio degli indirizzi del processo host diventa troppo frammentato. Gestione tabelle temporanee allocherà sempre un blocco di 1 MB di spazio indirizzi per ogni tabella temporanea creata indipendentemente dalla quantità di dati da archiviare. JetIntersectIndexes creerà una tabella temporanea per ogni JET_IndexRange specificata nel parametro rgindexrange e una tabella temporanea per l'output in JET_RECORDLIST. |
JET_errRestoreInProgress |
Non è possibile completare l'operazione perché è in corso un'operazione di ripristino nell'istanza associata alla sessione. |
JET_errSessionSharingViolation |
È illegale usare la stessa sessione da più thread contemporaneamente. Windows XP: Questo valore restituito viene introdotto in Windows XP. |
JET_errTermInProgress |
Non è possibile completare l'operazione perché l'istanza associata alla sessione viene arrestata. |
JET_errTooManyOpenIndexes |
L'operazione non è riuscita perché il motore non è riuscito ad allocare le risorse necessarie per memorizzare nella cache gli indici della tabella. Il numero di indici il cui schema può essere memorizzato nella cache viene configurato usando JetSetSystemParameter con JET_paramMaxOpenTables specificato nel parametro paramid . |
JET_errTooManyOpenTables |
L'operazione non è riuscita perché il motore non è riuscito ad allocare le risorse necessarie per memorizzare nella cache lo schema della tabella. Il numero di tabelle il cui schema può essere memorizzato nella cache viene configurato usando JetSetSystemParameter con JET_paramMaxOpenTables specificato nel parametro paramid . |
JET_errTooManySorts |
L'operazione non è riuscita perché il motore non è riuscito ad allocare le risorse necessarie per creare una tabella temporanea. Le risorse di tabella temporanee vengono configurate usando JetSetSystemParameter con JET_paramMaxTemporaryTables specificato nel parametro paramid . |
In caso di esito positivo, viene restituita una nuova tabella temporanea che contiene i segnalibri dei record che soddisfano i criteri rappresentati da ognuna delle descrizioni dell'intervallo di indice di input.
In caso di errore, la tabella temporanea contenente i risultati non verrà creata. Lo stato del database temporaneo può essere modificato. Lo stato di tutti i database ordinari in uso dal motore di database rimarrà invariato. La posizione corrente della JET_TABLEIDfornita a questa funzione può essere modificata.
Commenti
JetIntersectIndexes può essere usato per filtrare in modo efficiente i record in una tabella in base a più criteri se tali criteri possono essere espressi in termini di indici secondari su tale tabella. Si consideri, ad esempio, che si disponga di una tabella molto grande contenente persone. La tabella può contenere colonne per l'ID utente, il nome, il cognome e così via. Si supponga che ognuna di queste colonne venga indicizzata separatamente e che l'indice primario della tabella sia superiore all'ID utente. Se si desidera trovare tutti i cui nomi iniziano con un A e il cui cognome inizia con G, seguire questa procedura:
Aprire un nuovo cursore nella tabella e impostare tale cursore per usare l'indice sulla colonna "first name". Configurare quindi un intervallo di indici per tutte le persone il cui "nome" ha iniziato con "A" e compilare uno struct JET_IndexRange che contiene questo cursore.
Ripetere il passaggio 1 con un nuovo cursore sull'indice "cognome" per tutte le persone il cui "cognome" è iniziato con 'G'.
Passare questi criteri a JetIntersectIndexes per calcolare il risultato in una tabella temporanea.
Attraversare la tabella temporanea e recuperare ognuno dei record che superano i criteri in base al segnalibro.
La tabella temporanea contenente il set di risultati è una tabella semplice con una colonna contenente il segnalibro di ogni record che ha superato tutti i criteri usati per calcolare l'intersezione. Il set di risultati viene ordinato nello stesso ordine dell'indice primario e non contiene voci duplicate. L'applicazione può enumerare i risultati dell'intersezione enumerando le righe nella tabella temporanea, recuperando il segnalibro per ogni risultato usando JetRetrieveColumn e quindi visitando il record nel database chiamando JetGotoBookmark con tale segnalibro su un cursore posizionato sull'indice primario.
La tabella temporanea restituita da JetIntersectIndexes può essere analizzata solo in una direzione in avanti. Deve anche essere chiuso tramite JetCloseTable al termine dell'analisi. Per altre informazioni sulle tabelle temporanee e sul funzionamento, vedere JetOpenTemporaryTable.
JetIntersectIndexes è in genere un modo efficiente e pratico per filtrare i record in base a più criteri indicizzati. Tuttavia, ci sono alcuni suggerimenti importanti che devono essere seguiti per ottimizzare l'utilità di questa funzionalità. Se si sa che uno dei criteri è così restrittivo che l'intervallo di indici risultante ha molto pochi record, probabilmente è preferibile semplicemente camminare tale intervallo di indici e filtrare i record a livello di applicazione. Inoltre, se si conosce che si hanno criteri molto meno restrittivi rispetto ad altri criteri nell'intersezione, è possibile considerare l'eliminazione di tali criteri molto meno restrittivi dall'intersezione. Infine, se si sa che uno dei criteri non è affatto restrittivo in modo che l'intervallo di indici risultanti sia quasi grande come l'indice primario, è improbabile che l'intersecazione con tale intervallo di indici beneficierà (ridurre le dimensioni del set di risultati). In tutti i casi, è consigliabile selezionare i criteri in modo da accettare le voci di indice più possibili sull'input e generare il set più specifico di segnalibri sull'output per ottenere prestazioni massime.
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
JET_IndexRange
JET_RECORDLIST
JetGotoBookmark
JetRetrieveColumn
JetSetIndexRange