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.

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

Vedere anche

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp