次の方法で共有

JetMakeKey 関数

  • [アーティクル]

適用対象: Windows |Windows Server

JetMakeKey 関数

JetMakeKey 関数は、検索キーを構築し、キー列の値に対する単純な検索条件によってインデックス内のエントリのセットを検索するために使用できます。 検索キーは、カーソルの組み込みプロパティの 1 つでもあり、 JetSeek および JetSetIndexRange 操作によって使用され、カーソルの現在のインデックスでこれらの検索条件に一致するインデックス エントリを検索します。 完全な検索キーは、一連の JetMakeKey 呼び出しに組み込まれており、各呼び出しを使用して、カーソルの現在のインデックスの次のキー列の列値を読み込みます。 JetRetrieveKey を使用して、カーソルから取得した以前に構築された検索キーを読み込むこともできます。

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit
    );

パラメーター

sesid

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

tableid

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

pvData

検索キーが作成されているカーソルの現在のインデックスの現在のキー列の列データを格納している入力バッファー。

入力バッファー内の列データのデータ型は、現在のキー列の列定義のデータ型とその他のプロパティと完全に一致している必要があります。 列データに対して型強制は実行されません。

grbit パラメーターにJET_bitNormalizedKeyが指定されている場合、入力バッファーには、以前に構築された検索キーが含まれている必要があります。 このようなキーは、 JetRetrieveKey の呼び出しを使用して取得されます。

cbData

入力バッファーで提供される列データのサイズ (バイト単位)。

grbit パラメーターにJET_bitNormalizedKeyが指定されている場合、これは入力バッファーに指定された検索キーのサイズです。

列データのサイズが 0 の場合、入力バッファーの内容は無視されます。 JET_bitKeyDataZeroLengthが grbit パラメーターで指定され、カーソルの現在のインデックスの現在のキー列が可変長列である場合、入力列のデータは長さ 0 の値であると想定されます。 それ以外の場合、入力列データは NULL 値と見なされます。

grbit

次のオプションの 0 個以上を指定するビットのグループ。

値

説明

JET_bitFullColumnEndLimit

検索キーは、現在のキー列の後にあるキー列がワイルドカードと見なされるように構築する必要があります。 つまり、構築された検索キーを使用して、次のインデックス エントリを照合できます。

  • このキー列と以前のすべてのキー列に対して指定された正確な列値。

  • 後続のキー列に必要な列値。

このオプションは、インデックスの末尾に最も近いインデックス エントリを検索するために使用するワイルドカード検索キーを作成するときに使用する必要があります。 インデックスの末尾は、そのインデックス内の最後のレコードに移動するときに見つかったインデックス エントリです。 インデックスの末尾は、インデックスの上端と同じではありません。これは、インデックス内のキー列の並べ替え順序に応じて変更される可能性があります。

このオプションは、Windows XP 以降のリリースでのみ使用できます。

JETbitFullColumnStartLimit

検索キーは、現在のキー列の後にあるキー列がワイルドカードと見なされるように構築する必要があります。 つまり、構築された検索キーを使用して、次のインデックス エントリを照合できます。

  • このキー列と以前のすべてのキー列に対して指定された正確な列値。

  • 後続のキー列に必要な列値。

このオプションは、インデックスの先頭に最も近いインデックス エントリを検索するために使用するワイルドカード検索キーを作成するときに使用する必要があります。 インデックスの先頭は、そのインデックス内の最初のレコードに移動するときに見つかったインデックス エントリです。 インデックスの先頭がインデックスの下端と同じではなく、インデックス内のキー列の並べ替え順序に応じて変更される可能性があります。

このオプションは、Windows XP 以降のリリースでのみ使用できます。

JET_bitKeyDataZeroLength

入力バッファーのサイズが 0 で、現在のキー列が可変長列の場合、このオプションは、入力バッファーに長さ 0 の値が含まれていることを示します。 それ以外の場合、0 の入力バッファー サイズは NULL 値を示します。

JET_bitNewKey

新しい検索キーを作成する必要があります。 以前に既存の検索キーはすべて破棄されます。

JET_bitNormalizedKey

このオプションを指定すると、他のすべてのオプションは無視され、以前に既存の検索キーが破棄され、入力バッファーの内容が新しい検索キーとして読み込まれます。

JET_bitPartialColumnEndLimit

検索キーは、現在のキー列がプレフィックス ワイルドカードと見なされ、現在のキー列の後に来るキー列がワイルドカードと見なされるように構築する必要があります。 つまり、構築された検索キーを使用して、次のインデックス エントリを照合できます。

  • このキー列と以前のすべてのキー列に対して指定された正確な列値。

  • 後続のキー列に必要な列値。

このオプションは、インデックスの末尾に最も近いインデックス エントリを検索するために使用するワイルドカード検索キーを作成するときに使用する必要があります。 インデックスの末尾は、そのインデックス内の最後のレコードに移動するときに見つかったインデックス エントリです。 インデックスの末尾は、インデックスの上端と同じではありません。これは、インデックス内のキー列の並べ替え順序に応じて変更される可能性があります。

現在のキー列がテキスト列または変数バイナリ列でない場合は、このオプションを使用できません。 この操作が試行された場合、JET_errInvalidgrbitで操作は失敗します。

このオプションは、Windows XP 以降のリリースでのみ使用できます。

JET_bitPartialColumnStartLimit

このオプションは、現在のキー列がプレフィックス ワイルドカードと見なされ、現在のキー列の後にあるキー列がワイルドカードと見なされるように、検索キーを構築する必要があることを示します。 つまり、構築された検索キーを使用して、次のインデックス エントリを照合できます。

  • このキー列と以前のすべてのキー列に対して指定された正確な列値。

  • 後続のキー列に必要な列値。

このオプションは、インデックスの先頭に最も近いインデックス エントリを検索するために使用するワイルドカード検索キーを作成するときに使用する必要があります。 インデックスの先頭は、そのインデックス内の最初のレコードに移動するときに見つかったインデックス エントリです。 インデックスの先頭がインデックスの下端と同じではなく、インデックス内のキー列の並べ替え順序に応じて変更される可能性があります。

現在のキー列がテキスト列または変数バイナリ列でない場合は、このオプションを使用できません。 この操作が試行された場合、JET_errInvalidgrbitで操作は失敗します。

このオプションは、Windows XP 以降のリリースでのみ使用できます。

JET_bitStrLimit

このオプションは、現在のキー列の後に来るキー列がワイルドカードと見なされるように、検索キーを構築する必要があることを示します。 つまり、構築された検索キーを使用して、次のインデックス エントリを照合できます。

  • このキー列と以前のすべてのキー列に対して指定された正確な列値。

  • 後続のキー列に必要な列値。

このオプションは、インデックスの末尾に最も近いインデックス エントリを検索するために使用するワイルドカード検索キーを作成するときに使用する必要があります。 インデックスの末尾は、そのインデックス内の最後のレコードに移動するときに見つかったインデックス エントリです。 インデックスの末尾は、インデックスの上端と同じではありません。これは、インデックス内のキー列の並べ替え順序に応じて変更される可能性があります。

このオプションをJET_bitSubStrLimitと組み合わせて指定し、現在のキー列がテキスト列である場合、このオプションは無視されます。 この動作は、検索キーの作成時に現在のキー列の型を推論することを目的としています。

インデックスの先頭に対して同様の検索キーを作成する場合は、ワイルドカードではなくワイルドカード オプションが指定されていない最後のキー列に対して、 JetMakeKey の同様の呼び出しを行う必要があります。 検索キーは、このような検索に使用する適切な状態になります。 これはJET_bitFullColumnStartLimitの使用に似ていますが、ワイルドカード オプションを使用した後は、検索キーが正常に終了しない点が除きます。

この厄介なセマンティックに対処するために、このオプションは Windows XP 以降のリリースでは非推奨となりました。 JET_bitFullColumnStartLimitとJET_bitFullColumnEndLimitは、可能な限り代わりに使用する必要があります。

JET_bitSubStrLimit

このオプションは、現在のキー列がプレフィックス ワイルドカードと見なされ、現在のキー列の後にあるキー列がワイルドカードと見なされるように、検索キーを構築する必要があることを示します。 つまり、構築された検索キーを使用して、次のインデックス エントリを照合できます。

  • 前のすべてのキー列に対して指定された正確な列値。

  • 現在のキー列の列値のプレフィックスとして指定された列データ。

  • 後続のキー列の任意の列値。

このオプションは、インデックスの末尾に最も近いインデックス エントリを検索するために使用するワイルドカード検索キーを作成するときに使用する必要があります。 インデックスの末尾は、そのインデックス内の最後のレコードに移動するときに検出されるインデックス エントリです。 インデックスの末尾は、インデックスの上端と同じではなく、インデックス内のキー列の並べ替え順序に応じて変更される可能性があります。

このオプションを JET_bitStrLimit と組み合わせて指定し、現在のキー列がテキスト列である場合、このオプションが優先されます。 現在のキー列がテキスト列でない場合、このオプションは無視されます。 この動作は、検索キーの作成時に現在のキー列の型を推論できるようにするためです。

インデックスの先頭に対して同様の検索キーを作成する場合は、プレフィックス ワイルドカードであるキー列に対して JetMakeKey の同様の呼び出しを行う必要がありますが、ワイルドカード オプションは指定されません。 検索キーは、そのような検索に使用する適切な状態になります。 これはJET_bitPartialColumnStartLimitの使用に似ていますが、ワイルドカード オプションを使用した後は検索キーが正常に終了しない点が除きます。

この扱いにくいセマンティックに対処するために、このオプションは Windows XP 以降のリリースでは非推奨となりました。 可能な場合は、代わりにJET_bitPartialColumnStartLimitとJET_bitPartialColumnEndLimitを使用する必要があります。

戻り値

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

リターン コード

説明

JET_errSuccess

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

JET_errClientRequestToStopJetService

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

JET_errIndexTuplesKeyTooSmall

指定された列データが小さすぎて、現在のインデックスの有効なキーを作成できませんでした。これは、そのインデックスがタプル インデックスであり、最小タプル サイズが指定された列データよりも大きかったためです。 タプル インデックスの詳細については、「 JetCreateIndex 」を参照してください。 このエラーは、Windows XP 以降のリリースでのみ返されます。

JET_errInstanceUnavailable

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

JET_errInvalidBufferSize

指定された列データが、列定義に必要なサイズと一致しませんでした。 これは、列のデータ型が本質的に特定のサイズである場合に発生する可能性があります。 これは、列のデータ型が本質的に特定のサイズではないが、列の定義で固定長であると宣言されている場合にも発生する可能性があります。 これに対する 1 つの例外は、不足しているデータがスペースで自動的に埋め込まれるため、固定長テキスト列に対して提供されるデータが少なすぎると、このエラーは発生しないということです。 これに対する 2 つ目の例外は、不足しているデータが自動的にゼロで埋め込まれるため、固定長バイナリ列に対して提供されるデータが少なすぎると、このエラーは発生しないということです。

JET_errInvalidgrbit

要求されたオプションの 1 つが無効であるか、不正な方法で使用されたか、実装されていませんでした。 これは、次の場合に JetMakeKey で発生する可能性があります。

  • JET_bitPartialColumnStartLimitまたはJET_bitPartialColumnEndLimitが指定され、対応するキー列がテキスト列ではなく、可変長バイナリ列ではありません。 このケースは、Windows XP 以降のリリースでのみ発生します。

  • JET_bitPartialColumnStartLimit、JET_bitPartialColumnEndLimit、JET_bitFullColumnStartLimit、JET_bitFullColumnEndLimitの複数のオプションを同時に使用しようとしました。 このケースは、Windows XP 以降のリリースでのみ発生します。

  • JET_bitPartialColumnStartLimit、JET_bitPartialColumnEndLimit、JET_bitFullColumnStartLimit、JET_bitFullColumnEndLimitのいずれかのオプションを使用すると、JET_bitStrLimitまたはJET_bitSubStrLimitが試行されます。 このケースは、Windows XP 以降のリリースでのみ発生します。

JET_errInvalidParameter

指定されたパラメーターの 1 つに、予期しない値が含まれていたか、別のパラメーターの値と組み合わせると意味のない値が含まれていました。

これは、JET_bitNormalizedKeyが指定されていて、入力バッファーに指定された値が大きすぎて有効な検索キーになられなかった場合に 、JetMakeKey で発生する可能性があります。

JET_errKeyIsMade

JetMakeKey に指定された列データは、現在のインデックス内のすべてのキー列に対して列データが既に提供されているため、拒否されました。 これは、3 つの方法で発生する可能性があります。 最初の方法は、現在のインデックス内のキー列ごとに列データが提供される場合です。 2 つ目の方法は、少なくとも 1 つのキー列に列データが指定されていて、最後の呼び出しでワイルドカード オプションが選択されている場合です。 3 番目の方法は、以前に構築された検索キーが、すべてのキー列をカバーする JET_bitNormalizedKey を使用して提供された場合です。

JET_errKeyNotMade

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

JET_errNoCurrentIndex

カーソルの現在のインデックスはありません。 これは、カーソルがテーブルのクラスター化インデックス上にあり、プライマリ インデックスが定義されておらず、JET_bitNormalizedKeyが指定されていない場合に、 JetMakeKey で発生します。 以前に構築した検索キーが指定されていない限り、カーソルがキー列を持たないインデックス上にある場合、検索キーを構築することはできません。

JET_errNotInitialized

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

JET_errTermInProgress

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

成功すると、JET_bitNormalizedKeyとJET_bitNewKeyが指定されていない場合、現在のインデックス内の 1 つ以上のキー列の検索条件によって検索キーが構築されます。 JET_bitNormalizedKeyが指定されておらず、JET_bitNewKeyが指定されている場合、既存の検索キーはすべて破棄され、現在のインデックスの最初のキー列の検索条件によって新しい検索キーが作成されます。 JET_bitNormalizedKeyが指定されている場合は、以前に既存の検索キーが破棄され、入力バッファーから新しい検索キーが読み込まれました。 いずれの場合も、データベースの状態は変更されません。

失敗した場合、JET_bitNormalizedKeyまたはJET_bitNewKeyが指定された場合、検索キーの状態は未定義です。 JET_bitNormalizedKeyもJET_bitNewKeyも指定されていない場合、検索キーの状態は変更されません。 いずれの場合も、データベースの状態は変更されません。

解説

キーは、データの不透明なチャンクとして扱う必要があります。 このデータの内部構造を悪用しようとしないでください。 ただし、すべての ESENT キーについては、次の既知の情報があります。

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

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

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

ワイルドカード オプションを使用した場合、検索キーは 1 バイト長くできます。 その場合、検索キーは、Windows Vista より前のリリースでは最大JET_cbLimitKeyMost (256) バイト、Windows Vista 以降のリリースでは JET_paramKeyMost + 1 バイトになります。

この最大キー サイズには非常に重要な影響があります。 この最大サイズを超えるインデックスに対してキーが生成されるのに十分な大きさの列値を持つインデックス エントリがある場合、そのキーはその最大サイズで自動的に切り捨てられます。 これにより、次の 2 つの効果が発生します。

  • 一意のインデックス内のエントリの場合、それ以外の場合は一意のエントリが重複として宣言されます。

  • すべてのインデックスのエントリの場合、キーの切り捨てにより、指定された検索キーの検索条件と一致しないインデックス エントリが一致として宣言されます。

アプリケーションでは、この切り捨てを予測し、それを回避するか、その効果を補正する必要があります。 Windows Vista では、新しいインデックス フラグ JET_bitIndexDisallowTruncation が追加され、アプリケーションがキーの切り捨てを防ぐのを容易にしました。 このインデックス作成オプションの詳細については、「 JET_INDEXCREATE 構造」を参照してください。

要件

要件 値

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
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange