次の方法で共有

JetRetrieveKey 関数

  • [アーティクル]

適用対象: Windows |Windows Server

JetRetrieveKey 関数

JetRetrieveKey 関数は、カーソルの現在位置にあるインデックス エントリのキーを取得します。 このようなキーは、 JetMakeKey の呼び出しによって構築されます。 取得したキーを使用すると、 JetSeek の呼び出しによって、そのカーソルを同じインデックス エントリに効率的に返すことができます。

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

パラメーター

sesid

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

tableid

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

pvData

キーを受け取る出力バッファー。

cbMax

出力バッファーの最大サイズ (バイト単位)。

pcbActual

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

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

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

grbit

この呼び出しに使用するオプションを含むビットのグループ。これには、次の 0 個以上が含まれます。

値

説明

JET_bitRetrieveCopy

指定すると、エンジンはカーソルの検索キーを返します。 検索キーは、JetSeek を使用してそのキーをシークしたり、JetSetIndexRange を使用してインデックス範囲を設定したりする目的で、JetMakeKey の 1 つ以上の以前の呼び出しを使用して構築されます。

戻り値

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

リターン コード

説明

JET_errSuccess

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

JET_errClientRequestToStopJetService

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

JET_errInstanceUnavailable

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

JET_errKeyNotMade

カーソルの現在の検索キーはありません。 これは、 JetRetrieveKey でJET_bitRetrieveCopyが指定されていて、 JetMakeKey の以前の呼び出しを使用してこのカーソルに対して検索キーが作成されていない場合に発生します。 検索キーは、 JetMove 以外のカーソル上のナビゲーション API の以前の呼び出しによって削除されます。

JET_errNoCurrentRecord

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

JET_errNotInitialized

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

JET_errTermInProgress

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

JET_wrnBufferTruncated

操作は正常に完了しましたが、出力バッファーが小さすぎてキー全体を受信できませんでした。 出力バッファーには、収まるのと同じ量のキーが入力されています。 要求された場合は、キーの実際のサイズも返されます。

メモ JET_bitRetrieveCopyが指定されている場合、このエラーは返されません。 詳細については、「解説」セクションを参照してください。

成功すると、カーソルの現在位置にあるインデックス エントリのキーが出力バッファーに返されます。 JET_wrnBufferTruncatedが返された場合、出力バッファーには、指定された領域に収まるのと同じ量のキーが含まれており、キーの実際のサイズが正確になります。 データベースの状態は変更されません。

失敗した場合、出力バッファーの状態とキーの実際のサイズは未定義になります。 データベースの状態は変更されません。

注釈

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

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

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

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

一般に、ESENT キーの上記のプロパティに加えて、検索キーはインデックス エントリのキーとは異なる点に注意してください。 具体的には、検索キーが通常のキーよりも長い場合があります。 この余分な長さは、検索キーの作成時にワイルドカード オプションが使用される場合に発生します。 詳細については、「 JetMakeKey 」を参照してください。

この API には、すべてのリリースに存在する重要なバグがあります。 JET_bitRetrieveCopyを使用して検索キーが要求され、出力バッファーが小さすぎてキー全体を受信できない場合、JET_wrnBufferTruncatedは返されません。 代わりにJET_errSuccessが返されます。 pcbActual を使用して返されるキーの実際のサイズが出力バッファーのサイズ以下であることを確認することが重要です。 実際のサイズが出力バッファーのサイズより大きい場合、 JetRetrieveKey の呼び出し元は、代わりにJET_wrnBufferTruncatedが返されたかのように反応する必要があります。

要件

要件 値

Client

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

[サーバー]

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

Header

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

Library

ESENT.lib を使用します。

[DLL]

ESENT.dllが必要です。

参照

JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange