JetGetSecondaryIndexBookmark-Funktion

Gilt für: Windows | Windows Server

JetGetSecondaryIndexBookmark-Funktion

Die JetGetSecondaryIndexBookmark-Funktion ruft ein spezielles Lesezeichen für den sekundären Indexeintrag an der aktuellen Position eines Cursors ab. Dieses Lesezeichen kann dann verwendet werden, um den Cursor mithilfe von JetGotoSecondaryIndexBookmark effizient auf denselben Indexeintrag zurück zu positionieren. Dies ist am nützlichsten, wenn sie in einem sekundären Index neu positioniert werden, der doppelte Schlüssel enthält oder mehrere Indexeinträge für denselben Datensatz enthält.

Windows XP: JetGetSecondaryIndexBookmark wird in Windows XP eingeführt.

    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
    );

Parameter

sesid

Die Sitzung, die für diesen Aufruf verwendet werden soll.

tableid

Der Cursor, der für diesen Aufruf verwendet werden soll.

pvSecondaryKey

Der Ausgabepuffer, der den sekundären Schlüssel empfängt.

cbSecondaryKeyMax

Die maximale Größe des Ausgabepuffers für den sekundären Schlüssel in Bytes.

pcbSecondaryKeyActual

Empfängt die tatsächliche Größe des sekundären Schlüssels in Bytes.

Wenn dieser Parameter NULL ist, wird die tatsächliche Größe des sekundären Schlüssels nicht zurückgegeben.

Wenn der Ausgabepuffer zu klein ist, wird weiterhin die tatsächliche Größe des sekundären Schlüssels zurückgegeben. Das bedeutet, dass diese Zahl größer als die Größe des Ausgabepuffers ist.

pvPrimaryBookmark

Der Ausgabepuffer, der das Lesezeichen des Primärschlüssels empfängt.

cbPrimaryBookmarkMax

Die maximale Größe des Ausgabepuffers für das Primärschlüssel-Lesezeichen in Bytes.

pcbPrimaryKeyActual

Empfängt die tatsächliche Größe des Primärschlüssel-Lesezeichens in Bytes.

Wenn dieser Parameter NULL ist, wird die tatsächliche Größe des Primärschlüssel-Lesezeichens nicht zurückgegeben.

Wenn der Ausgabepuffer zu klein ist, wird die tatsächliche Größe des Primärschlüssel-Lesezeichens trotzdem zurückgegeben. Das bedeutet, dass diese Zahl größer als die Größe des Ausgabepuffers ist.

grbit

Für die zukünftige Verwendung reserviert.

Rückgabewert

Diese Funktion gibt den JET_ERR-Datentyp mit einem der folgenden Rückgabecodes zurück. Weitere Informationen zu möglichen ESE-Fehlern finden Sie unter Erweiterbare Speichermodulfehler und Fehlerbehandlungsparameter.

Bei Erfolg wird das Lesezeichen des sekundären Indexes für den Indexeintrag an der aktuellen Position eines Cursors in den Ausgabepuffern zurückgegeben. Es wird keine Änderung des Datenbankstatus vorgenommen.

Bei Einem Fehler sind der Zustand der Ausgabepuffer und die tatsächliche Größe des sekundären Index-Lesezeichens nicht definiert, es sei denn, JET_errBufferTooSmall wurde zurückgegeben. Für den Fall, dass JET_errBufferTooSmall zurückgegeben wird, enthalten die Ausgabepuffer so viel des sekundären Index-Lesezeichens, wie in den bereitgestellten Speicherplatz passt, und die tatsächliche Größe des Lesezeichens für den sekundären Index ist genau. In jedem Fall wird keine Änderung des Datenbankzustands vorgenommen.

Bemerkungen

Lesezeichen sollten im Allgemeinen als undurchsichtige Datenblöcke behandelt werden. Es sollte nicht versucht werden, die interne Struktur dieser Daten zu nutzen. Die folgenden Eigenschaften sind jedoch für alle ESENT-Lesezeichen bekannt:

• Ein Lesezeichen identifiziert einen Datensatz in einer bestimmten Tabelle eindeutig.

• Das Lesezeichen eines Datensatzes ändert sich für die Lebensdauer dieses Datensatzes nicht.

• Das Lesezeichen eines Datensatzes ist identisch mit dem Schlüssel dieses Datensatzes im primären Index für die Tabelle, die diesen Datensatz enthält. Wenn für diese Tabelle kein primärer Index definiert ist, erstellt die Datenbank-Engine ein eigenes Lesezeichen für den Datensatz.

• Lesezeichen können mithilfe von memcmp miteinander verglichen werden, um ihre relative Reihenfolge im primären Index gegenüber der Tabelle der Quelldatensätze festzulegen. Wenn für diese Tabelle kein primärer Index definiert ist, ist die relative Reihenfolge der Lesezeichen aus dieser Tabelle nicht sinnvoll.

• Es ist sinnlos, Lesezeichen von Datensätzen aus verschiedenen Tabellen miteinander zu vergleichen.

• Ein Lesezeichen ist immer kleiner oder gleich JET_cbBookmarkMost (256) Bytes länge vor Windows Vista. Unter Windows Vista und höheren Versionen können Lesezeichen größer sein. Die maximale Größe eines Lesezeichens entspricht dem aktuellen Wert von JET_paramKeyMost + 1.

Schlüssel sollten im Allgemeinen als undurchsichtige Datenblöcke behandelt werden. Es sollte nicht versucht werden, die interne Struktur dieser Daten zu nutzen. Die folgenden Eigenschaften sind jedoch für alle ESENT-Schlüssel bekannt:

• Schlüssel können unter Verwendung von memcmp miteinander verglichen werden, um ihre relative Reihenfolge im Ursprungsindex gegenüber der Tabelle der Quellindexeinträge festzulegen.

• Es ist sinnlos, Schlüssel von Indexeinträgen aus verschiedenen Indizes miteinander zu vergleichen.

• Ein Schlüssel ist immer kleiner oder gleich JET_cbKeyMost (255) Bytes länge vor Windows Vista. Unter Windows Vista und höheren Versionen können die Schlüssel größer sein. Die maximale Größe eines Schlüssels entspricht dem aktuellen Wert von JET_paramKeyMost.

Anforderungen

Weitere Informationen

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp