JetGetBookmark (funzione)

Si applica a: Windows | Windows Server

JetGetBookmark (funzione)

La funzione JetGetBookmark Recupera il segnalibro per il record associato alla voce di indice in corrispondenza della posizione corrente di un cursore. Questo segnalibro può quindi essere utilizzato per riposizionare il cursore sullo stesso record utilizzando 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, verranno comunque restituite le dimensioni effettive del segnalibro. 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 seguenti codici restituiti. Per ulteriori informazioni sugli errori ESE possibili, vedere la pagina relativa agli errori e ai parametri di gestione deglierrori del motore di archiviazione estensibile .

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 maggior parte del segnalibro. Anche le dimensioni effettive del segnalibro sono state restituite, se richiesto.

JET_errClientRequestToStopJetService

Non è possibile completare l'operazione perché tutte le attività nell'istanza associata alla sessione 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.

Windows XP: Questi valori restituiti sono introdotti in Windows XP.

JET_errNoCurrentRecord

Il cursore non è posizionato in corrispondenza di un record. I motivi possono essere diversi. Questa situazione si verifica, ad esempio, se il cursore è posizionato dopo l'ultimo record nell'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é è in corso un'operazione di ripristino nell'istanza di associata alla sessione.

JET_errSessionSharingViolation

Non è possibile usare la stessa sessione per più di un thread nello stesso momento.

Windows XP: Questo valore restituito è stato introdotto in Windows XP.

JET_errTermInProgress

Non è possibile completare l'operazione perché è in corso l'arresto dell'istanza associata alla sessione.

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

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

Commenti

In genere i segnalibri devono essere trattati come blocchi opachi di dati. Non è necessario effettuare alcun tentativo 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 tabella specificata.

  • Il segnalibro di un record non viene modificato per la durata di tale record.

  • Il segnalibro di un record corrisponde alla chiave di tale record nell'indice primario della tabella che contiene il record. Se nella tabella non è definito alcun indice primario, il motore di database creerà il proprio segnalibro per il record.

  • I segnalibri possono essere confrontati tra loro tramite la funzione memcmp per stabilire il relativo ordinamento nell'indice primario sulla tabella dei record di origine. Se non viene definito alcun indice primario su tale tabella, non è significativo utilizzare l'ordinamento relativo dei segnalibri della tabella.

  • Non è significativo confrontare i segnalibri dei 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 più grandi di JET_cbBookmarkMost (256) byte. La dimensione massima di un segnalibro è uguale al valore corrente di JET_paramKeyMost + 1.

Requisiti

Client

Richiede Windows Vista, Windows XP o Windows 2000 Professional.

Server

Richiede Windows Server 2008, Windows Server 2003 o Windows 2000 Server.

Intestazione

Dichiarata in esent. h.

Libreria

Usare ESENT. lib.

DLL

Richiede ESENT.dll.

Vedere anche

JET_ERR
JET_SESID
JET_TABLEID
JetGoToBookmark
JetStopService
memcmp