Funzione JetGetBookmark

Articolo
06/13/2023

Si applica a: Windows | Windows Server

Funzione JetGetBookmark

La funzione JetGetBookmark recupera il segnalibro per il record associato alla voce di indice nella posizione corrente di un cursore. Questo segnalibro può quindi essere usato per riposizionare il cursore nello stesso record usando JetGoToBookmark.

    JET_ERR JET_API JetGetBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvBookmark,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual
    );

Parametri

sesid

Sessione da usare per questa chiamata.

tableid

Cursore da usare per questa chiamata.

pvBookmark

Buffer di output che riceve il segnalibro.

cbMax

Dimensioni massime, in byte, del buffer di output.

pcbActual

Dimensioni effettive, in byte, del segnalibro.

Se questo parametro è NULL , le dimensioni effettive del segnalibro non verranno restituite.

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

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_errBufferTooSmall	L'operazione è stata completata correttamente, ma il buffer di output era troppo piccolo per ricevere l'intero segnalibro. Il buffer di output è stato riempito con la quantità di segnalibro adatta. Le dimensioni effettive del segnalibro sono state restituite anche, se richiesto.
JET_errClientRequestToStopJetService	L'operazione non può essere completata perché tutte le attività nell'istanza associata alla sessione hanno interrotto come risultato di una chiamata a JetStopService.
JET_errInstanceUnavailable	Impossibile 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. Windows XP: Questo valore restituito viene introdotto in Windows XP.
JET_errNoCurrentRecord	Il cursore non è posizionato su un record. I motivi possono essere diversi. Si verificherà, ad esempio, se il cursore viene posizionato dopo l'ultimo record dell'indice corrente.
JET_errNotInitialized	L'operazione non può essere completata perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errRestoreInProgress	L'operazione non può essere completata 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. Windows XP: Questo valore restituito viene introdotto in Windows XP.
JET_errTermInProgress	Impossibile completare l'operazione perché l'istanza associata alla sessione viene arrestata.

Se questa funzione ha esito positivo, il segnalibro per il record associato alla voce di indice nella posizione corrente di un cursore verrà restituito nel buffer di output. Non verrà eseguita alcuna modifica allo stato del database.

Se questa funzione ha esito negativo, lo stato del buffer di output e le dimensioni effettive del segnalibro non verranno definiti a meno che non venga restituito JET_errBufferTooSmall. Nel caso in cui JET_errBufferTooSmall venga restituito, il buffer di output conterrà la maggior parte del segnalibro corrispondente allo spazio fornito e le dimensioni effettive del segnalibro saranno accurate. Non verrà eseguita alcuna modifica allo stato del database.

Commenti

I segnalibri devono essere generalmente considerati blocchi opachi di dati. Non è necessario eseguire alcun tentativo di sfruttare la struttura interna di questi dati. Tuttavia, le condizioni seguenti sono vere di tutti i segnalibri ESENT:

Un segnalibro identifica in modo univoco un record in una determinata tabella.
Il segnalibro di un record non cambierà per la durata del record.
Il segnalibro di un record è uguale alla chiave di tale record nell'indice primario sulla tabella contenente tale record. Se non viene definito alcun indice primario su tale tabella, il motore di database creerà il proprio segnalibro per il record.
I segnalibri possono essere confrontati tra loro usando la funzione memcmp per stabilire l'ordinamento relativo nell'indice primario sulla tabella dei record di origine. Se non viene definito alcun indice primario su tale tabella, non è significativo usare l'ordinamento relativo dei segnalibri da tale tabella.
È senza senso confrontare i segnalibri di record da tabelle diverse tra loro.
Un segnalibro è sempre minore o uguale a JET_cbBookmarkMost (256) byte in lunghezza, prima di Windows Vista.

Windows Vista: Nelle versioni successive e Windows Vista i segnalibri possono essere maggiori di JET_cbBookmarkMost (256) byte. La dimensione massima di un segnalibro è uguale al valore corrente di JET_paramKeyMost + 1.

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_SESID
JET_TABLEID
JetGoToBookmark
JetStopService
memcmp

Funzione JetGetBookmark