JetRetrieveColumn 関数
適用対象: Windows |Windows Server
JetRetrieveColumn 関数
JetRetrieveColumn 関数は、現在のレコードから 1 つの列値を取得します。 レコードは、カーソルの現在位置にあるインデックス エントリに関連付けられているレコードです。 または、この関数は、カーソル コピー バッファーに作成されているレコードから列を取得できます。 この関数は、現在のレコードを参照するインデックス エントリから列データを取得することもできます。 JetRetrieveColumn は、実際の列値を取得するだけでなく、列データ自体を取得する前に列のサイズを取得して、アプリケーション バッファーのサイズを適切に設定することもできます。
JET_ERR JET_API JetRetrieveColumn(
__in JET_SESID sesid,
__in JET_TABLEID tableid,
__in JET_COLUMNID columnid,
__out_opt void* pvData,
__in unsigned long cbData,
__out_opt unsigned long* pcbActual,
__in JET_GRBIT grbit,
__in_out_opt JET_RETINFO* pretinfo
);
パラメーター
sesid
この呼び出しに使用するセッション。
tableid
この呼び出しに使用するカーソル。
columnid
取得する列の JET_COLUMNID 。
columnid 値 0 (ゼロ) を指定できます。これは、それ自体が個々の列を参照していません。 columnid 0 (ゼロ) を指定すると、すべてのタグ付き列、スパース列、および複数値列が 1 つの列として扱われます。 これにより、レコードに存在するすべてのスパース列の取得が容易になります。
pvData
列の値を受け取る出力バッファー。
cbData
出力バッファーの最大サイズ (バイト単位)。
pcbActual
列値の実際のサイズ (バイト単位) を受け取ります。
このパラメーターが NULL の場合、列値の実際のサイズは返されません。
grbit
この呼び出しに使用するオプションを含むビットのグループ。次の 0 個以上が含まれます。
値 |
説明 |
|---|---|
JET_bitRetrieveCopy |
このフラグにより、元の値ではなく変更された値が取得されます。 値が変更されていない場合は、元の値が取得されます。 この方法では、レコードを挿入または更新する操作中に、まだ挿入または更新されていない値を取得できます。 |
JET_bitRetrieveFromIndex |
このオプションは、可能であれば、レコードにアクセスせずにインデックスから列の値を取得するために使用されます。 この方法では、インデックス エントリ自体から必要なデータを使用できる場合に、レコードの不要な読み込みを回避できます。 元の列の値をインデックスから取得できない場合は、元に戻せない変換またはデータの切り捨てが原因で、レコードにアクセスし、通常どおりデータを取得します。 これはパフォーマンス オプションであり、列の値をインデックスから取得できる可能性がある場合にのみ指定する必要があります。 現在のインデックスがクラスター化インデックスの場合は、このオプションを指定しないでください。これは、クラスター化インデックスまたはプライマリ インデックスのインデックス エントリがレコード自体であるためです。 JET_bitRetrieveFromPrimaryBookmarkも設定されている場合、このビットは設定できません。 |
JET_bitRetrieveFromPrimaryBookmark |
このオプションは、インデックス ブックマークから列の値を取得するために使用され、プライマリ インデックスと現在のインデックスの両方に列が表示される場合、インデックス値とは異なる場合があります。 現在のインデックスがクラスター化インデックスまたはプライマリ インデックスの場合は、このオプションを指定しないでください。 JET_bitRetrieveFromIndexも設定されている場合、このビットは設定できません。 |
JET_bitRetrieveTag |
このオプションは、pretinfo-itagSequence> の複数値列値のシーケンス番号を取得するために使用されます。 通常、itagSequence フィールドは、レコードから複数値の列値を取得するための入力です。 ただし、インデックスから値を取得する場合は、インデックス エントリを特定のシーケンス番号に関連付けて、このシーケンス番号を取得することもできます。 シーケンス番号の取得はコストのかかる操作であり、必要な場合にのみ行う必要があります。 |
JET_bitRetrieveNull |
このオプションは、複数値列 の NULL 値を取得するために使用されます。 このオプションを指定しない場合、複数値列 の NULL 値は自動的にスキップされます。 |
JET_bitRetrieveIgnoreDefault |
このオプションは、複数値の列にのみ影響し、要求されたシーケンス番号が 1 で、レコード内の列の設定値がない場合に NULL 値が返されます。 |
JET_bitRetrieveLongId |
このフラグは内部使用のみを目的としており、アプリケーションで使用するためのものではありません。 |
JET_bitRetrieveLongValueRefCount |
このフラグは内部使用のみを目的としており、アプリケーションで使用するためのものではありません。 |
JET_bitRetrieveTuple |
このフラグを使用すると、インデックスのタプル セグメントを取得できます。 このビットは、JET_bitRetrieveFromIndexで指定する必要があります。 |
pretinfo
pretinfo に NULL が指定されている場合、関数は itagSequence が 1 で、ibLongValue が 0 (ゼロ) であるかのように動作します。 これにより、列の取得により、複数値の列の最初の値が取得され、オフセット 0 (ゼロ) の長いデータが取得されます。
このパラメーターは、次の 1 つ以上を指定するために使用されます。
値 |
説明 |
|---|---|
ibLongValue |
列値の一部を取得するときに、長い列の値にバイナリ オフセットを指定します。 |
itagSequence |
目的の複数値列値のシーケンス番号を指定します。 このフィールドは、JET_bitRetrieveTagが指定されている場合にのみ設定されることに注意してください。 それ以外の場合は、変更されません。 |
columnidNextTagged |
0 (ゼロ) の columnid を渡して、タグ付けされた列、スパース列、および複数値の列をすべて取得するときに、返される列値の列 ID を返します。 |
戻り値
この関数は、次のいずれかの戻りコードを 使用して、JET_ERR データ型を返します。 考えられる ESE エラーの詳細については、「 拡張ストレージ エンジン エラー と エラー処理パラメーター」を参照してください。
リターン コード |
説明 |
|---|---|
JET_errSuccess |
操作は正常に完了しました。 |
JET_errBadColumnId |
指定された列 ID は、列 ID の法的制限を超えています。 |
JET_errBadItagSequence |
pretinfo-itagSequence> で無効な複数値列シーケンス番号値が渡されました。 複数値の列値シーケンス番号の有効な値は 1 以上です。 この関数では、値 0 (ゼロ) は無効です。 |
JET_errClientRequestToStopJetService |
JetStopService の呼び出しの結果、セッションに関連付けられたインスタンスのすべてのアクティビティが停止したため、操作を完了できません。 |
JET_errColumnNotFound |
指定された columnid によって記述された列がテーブルに存在しません。 |
JET_errIndexTuplesCannotRetrieveFromIndex |
部分文字列としてインデックスが作成された列は、インデックスから取得できません。通常、各インデックス エントリには列のごく一部のみが存在するためです。 |
JET_errInstanceUnavailable |
セッションに関連付けられているインスタンスで、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。 このエラーは、Windows XP 以降のリリースでのみ返されます。 |
JET_errInvalidBufferSize |
場合によっては、列値の任意の量を返すために、取得列に指定されたバッファーのサイズを十分に設定する必要があります。 たとえば、エスクロー更新可能な列は、呼び出し元セッションのトランザクション コンテキストに対して一貫するように調整され、この調整には呼び出し元によって提供されるバッファーが必要です。 バッファー領域が不足している場合は、JET_errInvalidBufferSizeが返され、列データは返されません。 |
JET_errInvalidParameter |
指定された 1 つ以上のパラメーターが正しくありません。 これは、retinfo.cbStruct がJET_RETINFOのサイズより小さい場合に発生 する可能性があります。 |
JET_errInvalidgrbit |
指定されたオプションは不明であるか、既知のビット設定の無効な組み合わせです。 |
JET_errNoCurrentRecord |
カーソルはレコード上に配置されません。 これはさまざまな理由から起こります。 たとえば、カーソルが現在のインデックスの最後のレコードの後に現在配置されている場合に発生します。 |
JET_errNotInitialized |
セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。 |
JET_errRestoreInProgress |
セッションに関連付けられているインスタンスで復元操作が進行中であるため、操作を完了できません。 |
JET_errSessionSharingViolation |
同じセッションを複数のスレッドに同時に使用することはできません。 Windows XP: このエラーは、Windows XP 以降のリリースでのみ返されます。 |
JET_errTermInProgress |
セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。 |
JET_wrnBufferTruncated |
指定されたバッファーが列のサイズよりも小さいため、列全体の値を取得できませんでした。 |
JET_wrnColumnNull |
取得される列の値は NULL です。 |
成功すると、指定された列の列値が、指定されたバッファーにコピーされます。 すべての列値より小さい値がコピーされ、警告JET_wrnBufferTruncatedが返されます。 pcbActual が指定された場合は、列値の実際のサイズが返されます。 NULL 値の長さは 0 (ゼロ) であるため、返されるサイズは 0 (ゼロ) に設定されます。 取得された列が複数値の列で、 pretinfo が指定され、JET_bitReturnTagがオプションとして設定されている場合、列値のシーケンス番号は pretinfo-itagSequence> で返されます。
失敗した場合、カーソル位置は変更されず、指定されたバッファーにデータはコピーされません。
注釈
この呼び出しは、複数値以外の列の固定または既知のサイズのデータを取得するために 1 回だけ使用されます。 ただし、列データのサイズが不明な場合、この呼び出しは通常 2 回使用されます。 必要な記憶域を割り当てることができるように、データのサイズを決定するために最初に呼び出されます。 次に、列データを取得するために同じ呼び出しが再度行われます。 列が複数値であるため、実際の値の数が不明な場合、呼び出しは通常 3 回使用されます。 最初に値の数を取得し、さらに 2 回ストレージを割り当てて実際のデータを取得します。
複数値の列のすべての値を取得するには、pretinfo-itagSequence> 値が 1 から始まり、後続の呼び出しごとに増加して、この関数を繰り返し呼び出します。 最後の列の値は、関数からJET_wrnColumnNullが返されたときに取得されることがわかっている。 複数値列の値シーケンスに明示的な NULL 値が設定されている場合、これらの値はスキップされるため、このメソッドを実行できないことに注意してください。 アプリケーションが NULL に明示的に設定されているものも含め、複数値のすべての列値を取得する場合は、JetRetrieveColumn の代わりに JetRetrieveColumns を使用する必要があります。 itagSequence 値が 0 (ゼロ) の場合、この関数は複数値関数の値の数を返しません。 itagSequence 値 0 (ゼロ) が渡されると、JetRetrieveColumns のみが列値の値の数を返します。
たとえば、この関数がトランザクション レベル 0 (ゼロ) で呼び出された場合、呼び出し元のセッション自体がトランザクション内に存在しない場合、トランザクションは関数内で開かれて閉じられます。 この目的は、長い値がデータベース ページにまたがる場合に一貫した結果を返します。 セッションがトランザクション内にない場合、トランザクションは関数呼び出しとこの関数の一連の呼び出しの間で解放され、この関数の最初の呼び出し後に更新されたデータが返される可能性があることに注意してください。
既定の列値は、JET_bitRetrieveIgnoreDefault オプションが設定されていない限り、列が別の値に明示的に設定されていない場合に取得されます。
挿入前にコピー バッファーから自動作成列の値を取得することは、正規化されたデータを複数のテーブルに挿入するときにリンケージのレコードを一意に識別する一般的な手段です。 自動作成値は、挿入操作の開始時に割り当てられ、更新が完了するまでいつでもコピー バッファーから取得できます。
columnid を 0 (ゼロ) に設定して、すべてのタグ付き列、複数値列、およびスパース列を取得すると、列は最も低い columnid から最上位の columnid に列 id 順に取得されます。 列の値が取得されるたびに、同じ順序の列値が返されます。 順序は決定論的です。
要件
| 要件 | 値 |
|---|---|
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_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_RETINFO
JetSetColumn
JetRetrieveColumns