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