Condividi tramite

Funzione JetMakeKey

  • Articolo

Si applica a: Windows | Windows Server

Funzione JetMakeKey

La funzione JetMakeKey costruisce chiavi di ricerca che possono quindi essere usate per trovare un set di voci in un indice da alcuni criteri di ricerca semplici sui valori di colonna chiave. Una chiave di ricerca è anche una delle proprietà intrinseche di un cursore e viene usata dalle operazioni JetSeek e JetSetIndexRange per individuare le voci di indice corrispondenti a questi criteri di ricerca sull'indice corrente di tale cursore. Una chiave di ricerca completa viene compilata in una serie di chiamate JetMakeKey in cui ogni chiamata viene usata per caricare il valore della colonna per la colonna chiave successiva dell'indice corrente di un cursore. È anche possibile caricare una chiave di ricerca costruita in precedenza recuperata dal cursore usando JetRetrieveKey.

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit
    );

Parametri

sesid

Sessione da usare per questa chiamata.

tableid

Cursore da usare per questa chiamata.

pvData

Buffer di input contenente i dati di colonna per la colonna chiave corrente dell'indice corrente del cursore per cui viene creata la chiave di ricerca.

Il tipo di dati di colonna nel buffer di input deve corrispondere esattamente al tipo di dati e ad altre proprietà della definizione di colonna della colonna corrente. Nessuna coercizione dei tipi viene eseguita sui dati della colonna.

Se JET_bitNormalizedKey viene specificato nel parametro grbit , il buffer di input deve contenere una chiave di ricerca costruita in precedenza. Tali chiavi vengono ottenute usando una chiamata a JetRetrieveKey.

cbData

Dimensioni in byte dei dati di colonna forniti nel buffer di input.

Se JET_bitNormalizedKey viene specificato nel parametro grbit , questa è la dimensione della chiave di ricerca fornita nel buffer di input.

Se le dimensioni dei dati della colonna sono zero, il contenuto del buffer di input viene ignorato. Se JET_bitKeyDataZeroLength viene specificato nel parametro grbit e nella colonna chiave corrente dell'indice corrente del cursore è una colonna di lunghezza variabile, i dati della colonna di input vengono considerati un valore di lunghezza zero. In caso contrario, i dati della colonna di input vengono presupporti come valore NULL.

grbit

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

Valore

Significato

JET_bitFullColumnEndLimit

La chiave di ricerca deve essere costruita in modo che tutte le colonne chiave che provengono dopo che la colonna chiave corrente siano considerate caratteri jolly. Ciò significa che la chiave di ricerca costruita può essere usata per corrispondere alle voci di indice che hanno quanto segue:

  • I valori di colonna esatta forniti per questa colonna chiave e tutte le colonne chiave precedenti.

  • Tutti i valori di colonna necessari per le colonne chiave successive.

Questa opzione deve essere usata quando si compilano chiavi di ricerca con caratteri jolly da usare per trovare le voci di indice più vicine alla fine di un indice. La fine dell'indice è la voce di indice trovata quando si passa all'ultimo record in tale indice. La fine dell'indice non è uguale alla fine elevata dell'indice, che può cambiare a seconda dell'ordinamento delle colonne chiave nell'indice.

Questa opzione è disponibile solo nelle versioni di Windows XP e versioni successive.

JETbitFullColumnStartLimit

La chiave di ricerca deve essere costruita in modo che tutte le colonne chiave che vengono dopo la colonna chiave corrente devono essere considerate caratteri jolly. Ciò significa che la chiave di ricerca costruita può essere usata per corrispondere alle voci di indice che hanno quanto segue:

  • I valori di colonna esatta forniti per questa colonna chiave e tutte le colonne chiave precedenti.

  • Tutti i valori di colonna necessari per le colonne chiave successive.

Questa opzione deve essere usata quando si compilano chiavi di ricerca con caratteri jolly da usare per trovare le voci di indice più vicine all'inizio di un indice. L'inizio dell'indice è la voce di indice trovata quando si passa al primo record in tale indice. L'inizio dell'indice non corrisponde alla fine bassa dell'indice, che può cambiare a seconda dell'ordinamento delle colonne chiave nell'indice.

Questa opzione è disponibile solo nelle versioni di Windows XP e versioni successive.

JET_bitKeyDataZeroLength

Se le dimensioni del buffer di input sono zero e la colonna della chiave corrente è una colonna di lunghezza variabile, questa opzione indica che il buffer di input contiene un valore di lunghezza zero. In caso contrario, una dimensione del buffer di input pari a zero indica un valore NULL.

JET_bitNewKey

Deve essere creata una nuova chiave di ricerca. Qualsiasi chiave di ricerca esistente precedentemente esistente viene eliminata.

JET_bitNormalizedKey

Quando questa opzione viene specificata, tutte le altre opzioni vengono ignorate, qualsiasi chiave di ricerca precedentemente esistente viene eliminata e il contenuto del buffer di input viene caricato come nuova chiave di ricerca.

JET_bitPartialColumnEndLimit

La chiave di ricerca deve essere costruita in modo che la colonna chiave corrente sia considerata un carattere jolly di prefisso e che tutte le colonne chiave che provengono dopo la colonna chiave corrente devono essere considerate caratteri jolly. Ciò significa che la chiave di ricerca costruita può essere usata per corrispondere alle voci di indice che hanno quanto segue:

  • I valori di colonna esatta forniti per questa colonna chiave e tutte le colonne chiave precedenti.

  • Tutti i valori di colonna necessari per le colonne chiave successive.

Questa opzione deve essere usata quando si compilano chiavi di ricerca con caratteri jolly da usare per trovare le voci di indice più vicine alla fine di un indice. La fine dell'indice è la voce di indice trovata quando si passa all'ultimo record in tale indice. La fine dell'indice non è uguale alla fine elevata dell'indice, che può cambiare a seconda dell'ordinamento delle colonne chiave nell'indice.

Questa opzione non può essere usata quando la colonna chiave corrente non è una colonna di testo o una colonna binaria variabile. L'operazione avrà esito negativo con JET_errInvalidgrbit se viene tentato.

Questa opzione è disponibile solo nelle versioni di Windows XP e versioni successive.

JET_bitPartialColumnStartLimit

Questa opzione indica che la chiave di ricerca deve essere costruita in modo che la colonna chiave corrente sia considerata un carattere jolly di prefisso e che tutte le colonne chiave che provengono dopo la colonna chiave corrente devono essere considerate caratteri jolly. Ciò significa che la chiave di ricerca costruita può essere usata per corrispondere alle voci di indice che hanno quanto segue:

  • I valori di colonna esatta forniti per questa colonna chiave e tutte le colonne chiave precedenti.

  • Tutti i valori di colonna necessari per le colonne chiave successive.

Questa opzione deve essere usata quando si compilano chiavi di ricerca con caratteri jolly da usare per trovare le voci di indice più vicine all'inizio di un indice. L'inizio dell'indice è la voce di indice trovata quando si passa al primo record in tale indice. L'inizio dell'indice non corrisponde alla fine bassa dell'indice, che può cambiare a seconda dell'ordinamento delle colonne chiave nell'indice.

Questa opzione non può essere usata quando la colonna chiave corrente non è una colonna di testo o una colonna binaria variabile. L'operazione avrà esito negativo con JET_errInvalidgrbit se viene tentato.

Questa opzione è disponibile solo nelle versioni di Windows XP e versioni successive.

JET_bitStrLimit

Questa opzione indica che la chiave di ricerca deve essere costruita in modo che tutte le colonne chiave che provengono dopo che la colonna chiave corrente deve essere considerata caratteri jolly. Ciò significa che la chiave di ricerca costruita può essere usata per corrispondere alle voci di indice che hanno quanto segue:

  • I valori di colonna esatta forniti per questa colonna chiave e tutte le colonne chiave precedenti.

  • Tutti i valori di colonna necessari per le colonne chiave successive.

Questa opzione deve essere usata quando si compilano chiavi di ricerca con caratteri jolly da usare per trovare le voci di indice più vicine alla fine di un indice. La fine dell'indice è la voce di indice trovata quando si passa all'ultimo record in tale indice. La fine dell'indice non è uguale alla fine elevata dell'indice, che può cambiare a seconda dell'ordinamento delle colonne chiave nell'indice.

Quando questa opzione viene specificata in combinazione con JET_bitSubStrLimit e la colonna chiave corrente è una colonna di testo, questa opzione verrà ignorata. Questo comportamento è destinato a consentire il tipo della colonna chiave corrente da dedurre durante la compilazione della chiave di ricerca.

Se si vuole creare una chiave di ricerca simile per l'inizio di un indice, deve essere eseguita una chiamata simile a JetMakeKey per l'ultima colonna chiave che non è un carattere jolly, ma senza opzioni con caratteri jolly specificati. La chiave di ricerca è quindi in uno stato appropriato da usare per tale ricerca. Ciò è analogo all'uso di JET_bitFullColumnStartLimit, ad eccezione del fatto che la chiave di ricerca non viene completata correttamente perché è dopo l'uso di un'opzione con caratteri jolly.

Questa opzione è stata deprecata per Windows XP e versioni successive per risolvere questo problema semantico. JET_bitFullColumnStartLimit e JET_bitFullColumnEndLimit devono essere usati invece ovunque possibile.

JET_bitSubStrLimit

Questa opzione indica che la chiave di ricerca deve essere costruita in modo che la colonna chiave corrente sia considerata un carattere jolly di prefisso e che tutte le colonne chiave che provengono dopo la colonna chiave corrente devono essere considerate caratteri jolly. Ciò significa che la chiave di ricerca costruita può essere usata per corrispondere alle voci di indice che hanno quanto segue:

  • I valori di colonna esatta forniti per tutte le colonne chiave precedenti.

  • I dati di colonna specificati come prefisso del valore della colonna per la colonna corrente.

  • Qualsiasi valore di colonna per le colonne chiave successive.

Questa opzione deve essere usata quando si compilano chiavi di ricerca con caratteri jolly da usare per trovare le voci di indice più vicine alla fine di un indice. La fine dell'indice è la voce di indice trovata quando si passa all'ultimo record in tale indice. La fine dell'indice non corrisponde all'estremità superiore dell'indice, che può cambiare a seconda dell'ordinamento delle colonne chiave nell'indice.

Quando questa opzione viene specificata in combinazione con JET_bitStrLimit e la colonna chiave corrente è una colonna di testo, questa opzione avrà la precedenza. Questa opzione viene ignorata quando la colonna chiave corrente non è una colonna di testo. Questo comportamento consente di dedurre il tipo della colonna chiave corrente durante la compilazione della chiave di ricerca.

Se si vuole creare una chiave di ricerca simile per l'inizio di un indice, deve essere eseguita una chiamata simile a JetMakeKey per la colonna chiave che deve essere il carattere jolly del prefisso, ma senza che siano specificate opzioni con caratteri jolly. La chiave di ricerca viene quindi in uno stato appropriato da usare per una ricerca di questo tipo. Ciò è analogo all'uso di JET_bitPartialColumnStartLimit, ad eccezione del fatto che la chiave di ricerca non viene completata correttamente perché è dopo l'uso di un'opzione con caratteri jolly.

Questa opzione è stata deprecata per Windows XP e versioni successive per risolvere questo problema semantico. JET_bitPartialColumnStartLimit e JET_bitPartialColumnEndLimit devono essere invece usati, quando possibile.

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_errIndexTuplesKeyTooSmall

I dati della colonna forniti sono troppo piccoli per compilare una chiave valida per l'indice corrente perché l'indice è un indice di tupla e la dimensione minima della tupla è maggiore dei dati della colonna specificati. Per altre informazioni sugli indici di tupla, vedere JetCreateIndex . Questo errore verrà restituito solo da Windows XP e versioni successive.

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_errInvalidBufferSize

I dati della colonna specificati non corrispondono alle dimensioni richieste dalla definizione di colonna. Ciò può verificarsi se il tipo di dati della colonna è intrinsecamente una determinata dimensione. Ciò può verificarsi anche se il tipo di dati della colonna non è intrinsecamente una determinata dimensione, ma la definizione della colonna lo dichiara a lunghezza fissa. Un'eccezione è che questo errore non si verificherà quando vengono forniti dati troppo piccoli per una colonna di testo a lunghezza fissa perché tutti i dati mancanti verranno riempiti automaticamente con spazi. Una seconda eccezione è che questo errore non si verificherà quando vengono forniti dati troppo piccoli per una colonna binaria a lunghezza fissa perché tutti i dati mancanti verranno riempiti automaticamente con zere.

JET_errInvalidgrbit

Una delle opzioni richieste non è valida, utilizzata in modo non valido o non implementata. Questa situazione può verificarsi per JetMakeKey quando:

  • vengono specificati JET_bitPartialColumnStartLimit o JET_bitPartialColumnEndLimit e la colonna chiave corrispondente non è una colonna di testo e non è una colonna binaria a lunghezza variabile. Questo caso si verifica solo in Windows XP e versioni successive.

  • Viene effettuato un tentativo di usare più di una delle opzioni seguenti: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit e JET_bitFullColumnEndLimit. Questo caso si verifica solo in Windows XP e versioni successive.

  • Si tenta di usare JET_bitStrLimit o JET_bitSubStrLimit quando viene usata una delle opzioni seguenti: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit e JET_bitFullColumnEndLimit. Questo caso si verifica solo in Windows XP e versioni successive.

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 JetMakeKey quando è stato specificato JET_bitNormalizedKey e il valore fornito nel buffer di input è troppo grande per essere una chiave di ricerca valida.

JET_errKeyIsMade

I dati della colonna forniti a JetMakeKey sono stati rifiutati perché i dati della colonna sono già stati forniti per tutte le colonne chiave nell'indice corrente. Questo può verificarsi in tre modi. Il primo modo consiste nel caso in cui vengano forniti dati di colonna per ogni colonna chiave nell'indice corrente. Il secondo modo è se i dati della colonna sono stati forniti per almeno una colonna chiave e per l'ultima chiamata è stata scelta un'opzione con caratteri jolly. Il terzo modo è se è stata fornita una chiave di ricerca costruita in precedenza usando JET_bitNormalizedKey, che copre tutte le colonne chiave.

JET_errKeyNotMade

Non esiste una chiave di ricerca corrente per il cursore. Ciò si verifica per JetMakeKey se non viene specificato JET_bitNewKey e non è stata costruita una chiave di ricerca per questo cursore usando una chiamata precedente a JetMakeKey. La chiave di ricerca verrà eliminata da una chiamata precedente a qualsiasi API di navigazione sul cursore diversa da JetMove.

JET_errNoCurrentIndex

Non esiste alcun indice corrente per il cursore. Ciò si verifica per JetMakeKey se il cursore si trova nell'indice cluster di una tabella, non è stato definito un indice primario e JET_bitNormalizedKey non è stato specificato. Non è possibile costruire una chiave di ricerca se il cursore si trova in un indice che non dispone di colonne chiave a meno che non venga specificata una chiave di ricerca costruita in precedenza.

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_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, se JET_bitNormalizedKey e JET_bitNewKey non sono stati specificati, la chiave di ricerca sarà stata compilata dai criteri di ricerca per un'altra colonna chiave nell'indice corrente. Se JET_bitNormalizedKey non è stato specificato e JET_bitNewKey è stato specificato, qualsiasi chiave di ricerca esistente in precedenza è stata eliminata e ne verrà creata una nuova dai criteri di ricerca per la prima colonna chiave nell'indice corrente. Se è stato specificato JET_bitNormalizedKey, tutte le chiavi di ricerca esistenti in precedenza sono state eliminate e ne è stata caricata una nuova dal buffer di input. In ogni caso, non verrà apportata alcuna modifica allo stato del database.

In caso di errore, se è stato specificato JET_bitNormalizedKey o JET_bitNewKey, lo stato della chiave di ricerca non è definito. Se non sono stati specificati né JET_bitNormalizedKey né JET_bitNewKey, non verrà apportata alcuna modifica allo stato della chiave di ricerca. In ogni caso, non verrà apportata alcuna modifica allo stato del database.

Commenti

Le chiavi devono essere considerate come blocchi opachi di dati. Non è necessario tentare di sfruttare la struttura interna di questi dati. Tuttavia, le informazioni seguenti sono note su tutte le chiavi ESENT:

  • Le chiavi possono essere confrontate tra loro usando memcmp per stabilire l'ordinamento relativo nell'indice di origine sulla tabella delle voci dell'indice di origine.

  • Non è significativo confrontare le chiavi delle voci di indice da indici diversi tra loro.

  • Una chiave è sempre minore o uguale a JET_cbKeyMost (255) byte di lunghezza prima di Windows Vista. In Windows Vista e versioni successive le chiavi possono essere più grandi. La dimensione massima di una chiave è uguale al valore corrente di JET_paramKeyMost.

Le chiavi di ricerca possono essere più lunghe di un byte se è stata usata un'opzione con caratteri jolly. In tal caso, la chiave di ricerca sarà fino a JET_cbLimitKeyMost (256) byte per le versioni precedenti a Windows Vista e JET_paramKeyMost + 1 byte per Windows Vista e versioni successive.

C'è una ramificazione molto importante per questa dimensione massima della chiave. Ogni volta che è presente una voce di indice con valori di colonna sufficientemente grandi da generare una chiave per tale indice che altrimenti sarebbe maggiore di questa dimensione massima, tale chiave viene troncata automaticamente a tale dimensione massima. Ciò causa due effetti:

  • Per le voci in un indice univoco, causerà la dichiarazione di voci altrimenti univoche come duplicati.

  • Per le voci in tutti gli indici, il troncamento della chiave causerà la mancata corrispondenza dei criteri di ricerca di una chiave di ricerca specificata come corrispondenze.

Le applicazioni devono prevedere questo troncamento ed evitarlo o compensarne gli effetti. In Windows Vista è stato aggiunto un nuovo flag di indice, JET_bitIndexDisallowTruncation, per semplificare l'esecuzione delle applicazioni per evitare troncamenti chiave. Per altre informazioni su questa opzione di indicizzazione, vedere la struttura JET_INDEXCREATE .

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
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange