Funzione JetGetBookmark

Si applica a: Windows | server Windows

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 utilizzare per questa chiamata.

tableid

Cursore da utilizzare per questa chiamata.

pvBookmark

Buffer di output che riceve il segnalibro.

cbMax

Dimensione massima, 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 della dimensione del buffer di output.

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 Extensible Archiviazione Engine Errors and Error Handling Parameters.For more information about the possible ESE errors errors, see Extensible Archiviazione Engine Errors and Error Handling Parameters.

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. Vengono restituite anche le dimensioni effettive del segnalibro, se richiesto.
JET_errClientRequestToStopJetService	L'operazione non può essere completata perché tutte le attività nell'istanza associata alla sessione sono cessate a seguito di una chiamata a JetStopService.
JET_errInstanceUnavailable	Impossibile 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: questi valori restituiti vengono introdotti in Windows XP.
JET_errNoCurrentRecord	Il cursore non è posizionato su un record. I motivi possono essere diversi. Ad esempio, ciò si verifica se il cursore viene posizionato dopo l'ultimo record nell'indice corrente.
JET_errNotInitialized	Impossibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
JET_errRestoreInProgress	Impossibile 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. 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à apportata 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 che si adatta allo spazio fornito e le dimensioni effettive del segnalibro saranno accurate. Non verrà apportata alcuna modifica allo stato del database.

Commenti

I segnalibri devono in genere essere considerati blocchi opachi di dati. Non è necessario tentare di sfruttare la struttura interna di questi dati. Tuttavia, le condizioni seguenti sono vere per 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 corrisponde alla chiave del 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.

• Non è significativo confrontare segnalibri di record di tabelle diverse tra loro.

• Un segnalibro è sempre minore o uguale a JET_cbBookmarkMost (256) byte di lunghezza, prima di Windows Vista.

Windows Vista: in Windows Vista e versioni successive, 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