次の方法で共有

JetGetSecondaryIndexBookmark 関数

  • [アーティクル]

適用対象: Windows |Windows Server

JetGetSecondaryIndexBookmark 関数

JetGetSecondaryIndexBookmark 関数は、カーソルの現在位置にあるセカンダリ インデックス エントリの特別なブックマークを取得します。 このブックマークを使用すると、 JetGotoSecondaryIndexBookmark を使用して、カーソルを同じインデックス エントリに効率的に再配置できます。 これは、重複するキーを含むセカンダリ インデックス、または同じレコードの複数のインデックス エントリを含むセカンダリ インデックスの位置を変更する場合に最も便利です。

Windows XP: JetGetSecondaryIndexBookmark は 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
    );

パラメーター

sesid

この呼び出しに使用するセッション。

tableid

この呼び出しに使用するカーソル。

pvSecondaryKey

セカンダリ キーを受け取る出力バッファー。

cbSecondaryKeyMax

セカンダリ キーの出力バッファーの最大サイズ (バイト単位)。

pcbSecondaryKeyActual

セカンダリ キーの実際のサイズをバイト単位で受け取ります。

このパラメーターが NULL の場合、セカンダリ キーの実際のサイズは返されません。

出力バッファーが小さすぎる場合でも、セカンダリ キーの実際のサイズが返されます。 つまり、この数は出力バッファーのサイズよりも大きくなります。

pvPrimaryBookmark

主キー ブックマークを受け取る出力バッファー。

cbPrimaryBookmarkMax

主キー ブックマークの出力バッファーの最大サイズ (バイト単位)。

pcbPrimaryKeyActual

主キー ブックマークの実際のサイズ (バイト単位) を受け取ります。

このパラメーターが NULL の場合、主キー ブックマークの実際のサイズは返されません。

出力バッファーが小さすぎる場合でも、主キー ブックマークの実際のサイズが返されます。 つまり、この数は出力バッファーのサイズよりも大きくなります。

grbit

将来利用するために予約されています。

戻り値

この関数は、次のいずれかの戻りコードを 使用して、JET_ERR データ型を返します。 考えられる ESE エラーの詳細については、「 拡張ストレージ エンジン エラー と エラー処理パラメーター」を参照してください。

リターン コード

説明

JET_errSuccess

操作は正常に完了しました。

JET_errBufferTooSmall

操作は正常に完了しましたが、出力バッファーの 1 つが小さすぎて、要求されたデータを受信できませんでした。

出力バッファーには、収まるのと同じ量のブックマークが入力されています。 要求された場合は、ブックマークの実際のサイズも返されます。

JET_errClientRequestToStopJetService

JetStopService の呼び出しの結果、セッションに関連付けられたインスタンスのすべてのアクティビティが停止したため、操作を完了できません。

JET_errInstanceUnavailable

セッションに関連付けられているインスタンスで、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。 このエラーは、Windows XP 以降のリリースでのみ返されます。

JET_errNoCurrentIndex

現在、カーソルはセカンダリ インデックス上にありません。

カーソルが現在セカンダリ インデックスを使用していない場合、セカンダリ インデックス ブックマークを取得することは意味がありません。 カーソルがセカンダリ インデックスにない場合は、JetGetBookmark を使用する必要があります。

JET_errNoCurrentRecord

カーソルはレコード上に配置されません。

これはさまざまな理由から起こります。 たとえば、カーソルが現在のインデックスの最後のレコードの後に現在配置されている場合に発生します。

JET_errNotInitialized

セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。

JET_errRestoreInProgress

セッションに関連付けられているインスタンスで復元操作が進行中のため、操作を完了できません。

JET_errSessionSharingViolation

同じセッションを複数のスレッドに同時に使用することはできません。 このエラーは、Windows XP 以降のリリースでのみ返されます。

JET_errTermInProgress

セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。

成功すると、カーソルの現在位置にあるインデックス エントリのセカンダリ インデックス ブックマークが出力バッファーに返されます。 データベースの状態に対する変更は行われません。

失敗した場合、出力バッファーの状態とセカンダリ インデックス ブックマークの実際のサイズは、JET_errBufferTooSmallが返されない限り未定義になります。 JET_errBufferTooSmallが返された場合、出力バッファーには、指定された領域に収まるのと同じ量のセカンダリ インデックス ブックマークが含まれており、セカンダリ インデックス ブックマークの実際のサイズは正確になります。 いずれの場合も、データベースの状態に対する変更は行われません。

解説

ブックマークは通常、データの不透明なチャンクとして扱う必要があります。 このデータの内部構造を悪用しようとしないでください。 ただし、すべての ESENT ブックマークに関して、次のプロパティを確認できます。

  • ブックマークは、特定のテーブル内のレコードを一意に識別します。

  • レコードのブックマークは、そのレコードの有効期間中は変更されません。

  • レコードのブックマークは、そのレコードを含むテーブルのプライマリ インデックス上のそのレコードのキーと同じです。 そのテーブルに対してプライマリ インデックスが定義されていない場合、データベース エンジンはレコードに対して独自のブックマークを作成します。

  • ブックマークは、 memcmp を使用して相互に比較して、ソース レコードのテーブルに対するプライマリ インデックスの相対順序を確立できます。 そのテーブルに対してプライマリ インデックスが定義されていない場合、そのテーブルからのブックマークの相対的な順序は意味がありません。

  • 異なるテーブルのレコードのブックマークを相互に比較することは意味がありません。

  • ブックマークは、Windows Vista より前の長さが常にJET_cbBookmarkMost (256) バイト以下です。 Windows Vista 以降のリリースでは、ブックマークを大きくすることができます。 ブックマークの最大サイズは、JET_paramKeyMost + 1 の現在の値と等しくなります。

キーは通常、データの不透明なチャンクとして扱う必要があります。 このデータの内部構造を悪用しようとしないでください。 ただし、すべての ESENT キーについて、次のプロパティを確認できます。

  • memcmp を使用してキーを相互に比較して、ソース インデックス エントリのテーブルに対する元のインデックスの相対順序を確立できます。

  • 異なるインデックスのインデックス エントリのキーを相互に比較することは意味がありません。

  • キーの長さは、常に Windows Vista より前のJET_cbKeyMost (255) バイト以下です。 Windows Vista 以降のリリースでは、キーを大きくすることができます。 キーの最大サイズは、JET_paramKeyMostの現在の値と等しくなります。

要件

要件 値

Client

Windows Vista または Windows XP が必要です。

[サーバー]

Windows Server 2008 または Windows Server 2003 が必要です。

Header

Esent.h で宣言されています。

Library

ESENT.lib を使用します。

[DLL]

ESENT.dllが必要です。

参照

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetGetBookmark
JetGotoSecondaryIndexBookmark
JetRetrieveKey
memcmp