Funzione JetRetrieveKey

Si applica a: Windows | Windows Server

Funzione JetRetrieveKey

La funzione JetRetrieveKey recupera la chiave per la voce di indice nella posizione corrente di un cursore. Tali chiavi vengono costruite dalle chiamate a JetMakeKey. La chiave recuperata può quindi essere usata per restituire in modo efficiente tale cursore alla stessa voce di indice tramite una chiamata a JetSeek.

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

Parametri

sesid

Sessione da usare per questa chiamata.

tableid

Cursore da usare per questa chiamata.

pvData

Buffer di output che riceverà la chiave.

cbMax

Dimensione massima in byte del buffer di output.

pcbActual

Riceve le dimensioni effettive in byte della chiave.

Se questo parametro è NULL, le dimensioni effettive della chiave non verranno restituite.

Se il buffer di output è troppo piccolo, le dimensioni effettive della chiave verranno comunque restituite. Ciò significa che questo numero sarà maggiore delle dimensioni del buffer di output.

grbit

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

Valore	Significato
JET_bitRetrieveCopy	Se specificato, il motore restituirà la chiave di ricerca per il cursore. La chiave di ricerca viene compilata usando una o più chiamate precedenti a JetMakeKey ai fini della ricerca di tale chiave usando JetSeek o impostando un intervallo di indici usando JetSetIndexRange.

Valore restituito

Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sugli errori ESE possibili, vedere Errori del motore di archiviazione estendibili e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errClientRequestToStopJetService	Non è possibile completare l'operazione perché tutte le attività nell'istanza associata alla sessione non sono state interrotte in seguito a una chiamata a JetStopService.
JET_errInstanceUnavailable	Non è possibile completare l'operazione perché l'istanza associata alla sessione ha rilevato un errore irreversibile che richiede che l'accesso a tutti i dati venga revocato per proteggere l'integrità dei dati. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errKeyNotMade	Non esiste alcuna chiave di ricerca corrente per il cursore. Ciò avviene per JetRetrieveKey se viene specificato JET_bitRetrieveCopy e non è stata creata 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 spostamento nel cursore diverso da JetMove.
JET_errNoCurrentRecord	Il cursore non è posizionato su un record. I motivi possono essere diversi. Si verificherà, ad esempio, se il cursore è attualmente posizionato dopo l'ultimo record dell'indice corrente.
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é un'operazione di ripristino è in corso 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.
JET_wrnBufferTruncated	L'operazione è stata completata correttamente, ma il buffer di output era troppo piccolo per ricevere l'intera chiave. Il buffer di output è stato riempito con la quantità di chiave adatta. Le dimensioni effettive della chiave sono state restituite anche, se richiesto. Nota Questo errore non verrà restituito se viene specificato JET_bitRetrieveCopy. Per altre informazioni, vedere la sezione Osservazioni.

In caso di esito positivo, la chiave per la voce di indice nella posizione corrente di un cursore verrà restituita nel buffer di output. Se JET_wrnBufferTruncated viene restituito, il buffer di output conterrà la quantità di chiave adattata nello spazio fornito e le dimensioni effettive della chiave saranno accurate. Non verrà eseguita alcuna modifica allo stato del database.

In caso di errore, lo stato del buffer di output e le dimensioni effettive della chiave non verranno definiti. Non verrà eseguita alcuna modifica allo stato del database.

Commenti

Le chiavi devono essere generalmente considerate blocchi opachi di dati. Non è necessario eseguire alcun tentativo di sfruttare la struttura interna di questi dati. Tuttavia, le proprietà seguenti possono essere note su tutte le chiavi ESENT:

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

• È senza significato 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 maggiori. La dimensione massima di una chiave è uguale al valore corrente di JET_paramKeyMost.

Oltre alle proprietà precedenti delle chiavi ESENT in generale, è importante notare che una chiave di ricerca è diversa dalla chiave per una voce di indice. In particolare, una chiave di ricerca può essere più lunga di una chiave normale. Questa lunghezza aggiuntiva si verifica quando viene usata un'opzione con caratteri jolly durante la costruzione della chiave di ricerca. Per altre informazioni, vedere JetMakeKey .

C'è un bug importante in questa API presente in tutte le versioni. Se la chiave di ricerca viene richiesta usando l'uso di JET_bitRetrieveCopy e il buffer di output è troppo piccolo per ricevere l'intera chiave, JET_wrnBufferTruncated non verrà restituito. JET_errSuccess verrà restituito invece. È importante verificare che le dimensioni effettive della chiave restituite usando pcbActual siano inferiori o uguali alle dimensioni del buffer di output. Se la dimensione effettiva è maggiore della dimensione del buffer di output, il chiamante di JetRetrieveKey deve reagire come se JET_wrnBufferTruncated fosse restituito.

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
JetMakeKey
JetSeek
JetSetIndexRange