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 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.

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

Vedere anche

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange