Funzione JetGetSecondaryIndexBookmark

Si applica a: Windows | Windows Server

Funzione JetGetSecondaryIndexBookmark

La funzione JetGetSecondaryIndexBookmark recupera un segnalibro speciale per la voce di indice secondaria nella posizione corrente di un cursore. Questo segnalibro può quindi essere usato per riposizionare in modo efficiente il cursore alla stessa voce di indice usando JetGotoSecondaryIndexBookmark. Ciò è particolarmente utile quando si riposiziona su un indice secondario contenente chiavi duplicate o che contiene più voci di indice per lo stesso record.

Windows XP: JetGetSecondaryIndexBookmark è stato introdotto in Windows XP.

    JET_ERR JET_API JetGetSecondaryIndexBookmark(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvSecondaryKey,
      __in          unsigned long cbSecondaryKeyMax,
      __out_opt     unsigned long* pcbSecondaryKeyActual,
      __out_opt      void* pvPrimaryBookmark,
      __in          unsigned long cbPrimaryBookmarkMax,
      __out_opt     unsigned long* pcbPrimaryKeyActual,
      __in          const JET_GRBIT grbit
    );

Parametri

sesid

Sessione da utilizzare per questa chiamata.

tableid

Cursore da utilizzare per questa chiamata.

pvSecondaryKey

Buffer di output che riceve la chiave secondaria.

cbSecondaryKeyMax

Dimensioni massime, in byte, del buffer di output per la chiave secondaria.

pcbSecondaryKeyActual

Riceve le dimensioni effettive in byte della chiave secondaria.

Se questo parametro è NULL, le dimensioni effettive della chiave secondaria non verranno restituite.

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

pvPrimaryBookmark

Buffer di output che riceve il segnalibro della chiave primaria.

cbPrimaryBookmarkMax

Dimensioni massime, in byte, del buffer di output per il segnalibro della chiave primaria.

pcbPrimaryKeyActual

Riceve le dimensioni effettive, in byte, del segnalibro della chiave primaria.

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

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

grbit

Riservato per utilizzi futuri.

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 Errori del motore di archiviazione estendibile e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errBufferTooSmall	L'operazione è stata completata correttamente, ma uno dei buffer di output era troppo piccolo per ricevere i dati richiesti. Il buffer di output è stato riempito con la quantità di segnalibro adatta. Vengono restituite anche le dimensioni effettive del segnalibro, se richiesto.
JET_errClientRequestToStopJetService	Non è possibile completare l'operazione perché tutte le attività sull'istanza associata alla sessione sono cessate a seguito di una chiamata a JetStopService.
JET_errInstanceUnavailable	Non è possibile 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. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errNoCurrentIndex	Il cursore non è attualmente in un indice secondario. Non è significativo recuperare un segnalibro di indice secondario quando il cursore non usa attualmente un indice secondario. JetGetBookmark deve essere usato quando il cursore non si trova in un indice secondario.
JET_errNoCurrentRecord	Il cursore non è posizionato su un record. I motivi possono essere diversi. Ad esempio, ciò si verifica se il cursore è attualmente 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 associata alla sessione.
JET_errSessionSharingViolation	La stessa sessione non può essere usata contemporaneamente per più thread. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errTermInProgress	Non è possibile completare l'operazione perché l'istanza associata alla sessione viene arrestata.

In caso di esito positivo, il segnalibro di indice secondario per la voce di indice nella posizione corrente di un cursore verrà restituito nei buffer di output. Non verrà apportata alcuna modifica allo stato del database.

In caso di errore, lo stato dei buffer di output e le dimensioni effettive del segnalibro di indice secondario non verranno definiti a meno che non venga restituito JET_errBufferTooSmall. Nel caso in cui JET_errBufferTooSmall venga restituito, i buffer di output conterranno la maggior parte del segnalibro di indice secondario, come lo spazio specificato e le dimensioni effettive del segnalibro dell'indice secondario saranno accurate. In ogni caso, 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 proprietà seguenti possono essere note su 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 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, l'ordinamento relativo dei segnalibri da tale tabella non è significativo.

• 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. In Windows Vista e versioni successive i segnalibri possono essere più grandi. La dimensione massima di un segnalibro è uguale al valore corrente di JET_paramKeyMost + 1.

Le chiavi devono in genere essere considerate blocchi opachi di dati. Non è necessario tentare 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 memcmp per stabilire l'ordinamento relativo nell'indice di origine sulla tabella delle voci dell'indice di origine.

• Non è significativo 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 più grandi. La dimensione massima di una chiave è uguale al valore corrente di JET_paramKeyMost.

Requisiti

Requisito	Valore
Client	Richiede Windows Vista o Windows XP.
Server	Richiede Windows Server 2008 o Windows Server 2003.
Intestazione	Dichiarato in Esent.h.
Libreria	Usare ESENT.lib.
DLL	Richiede ESENT.dll.

Vedere anche

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp