次の方法で共有

JetRetrieveColumns 関数

  • [アーティクル]

適用対象: Windows |Windows サーバー

JetRetrieveColumns 関数

JetRetrieveColumns 関数は、1 回の操作で現在のレコードから複数の列値を取得します。 JET_RETRIEVECOLUMN構造体の配列を使用して、取得する列値のセットを記述し、取得する各列値の出力バッファーを記述します。

    JET_ERR JET_API JetRetrieveColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_out_opt  JET_RETRIEVECOLUMN* pretrievecolumn,
      __in          unsigned long cretrievecolumn
    );

パラメーター

sesid

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

tableid

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

pretrievecolumn

1 つ以上の JET_RETRIEVECOLUMN 構造体の配列へのポインター。 各構造体には、取得する列値と、返されたデータを格納する場所の説明が含まれています。

cretrievecolumn

pretrievecolumn によって指定された配列内のJET_RETRIEVECOLUMN構造体の数。

戻り値

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

リターン コード

説明

JET_errSuccess

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

JET_errBadItagSequence

pretinfo-itagSequence> で無効な複数値の列シーケンス番号値が渡されました。 複数値列値シーケンス番号の有効な値は 1 以上です。 0 (ゼロ) の値は、この関数に対して有効ですが、 JetRetrieveColumn では無効です。

JET_errBadColumnId

指定された列 ID は、列 ID の法的制限を超えています。

JET_errClientRequestToStopJetService

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

JET_errColumnNotFound

指定された columnid によって記述された列がテーブルに存在しません。

JET_errIndexTuplesCannotRetrieveFromIndex

通常、各インデックス エントリには列のごく一部のみが存在するため、部分文字列としてインデックスが作成された列はインデックスから取得できません。

JET_errInvalidBufferSize

場合によっては、列値の任意の量を返すために、取得列に指定されたバッファーのサイズを十分に設定する必要があります。 たとえば、エスクロー更新可能な列は、呼び出し元セッションのトランザクション コンテキストに一貫性を持つよう調整され、この調整には呼び出し元によって提供されるバッファーが必要です。 バッファー領域が不足している場合は、JET_errInvalidBufferSizeが返され、列データは一切返されません。

JET_errInvalidgrbit

指定されたオプションは不明か、既知のビット設定の不適切な組み合わせです。

JET_errInvalidParameter

指定された 1 つ以上のパラメーターが正しくありません。 これは、retinfo.cbStruct が JET_RETINFOのサイズより小さい場合に発生する可能性があります。

JET_errInstanceUnavailable

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

Windows XP: このエラーは、Windows XP 以降のリリースでのみ返されます。

JET_errNoCurrentRecord

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

JET_errNotInitialized

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

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

同じセッションを複数のスレッドに同時に使用することはできません。

Windows XP: このエラーは、Windows XP 以降のリリースでのみ返されます。

JET_errTermInProgress

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

JET_wrnBufferTruncated

指定されたバッファーが列のサイズよりも小さいため、列全体の値を取得できませんでした。

成功すると、列データと列サイズは、 JET_RETRIEVECOLUMN 構造体の配列で説明されている指定されたバッファーで返されます。 itagSequence が 0 (ゼロ) に設定され、列データではなく複数値フィールドのインスタンス数が必要であることを示す場合、itagSequence フィールド自体に複数値の列のインスタンス数が返されます。 各 JET_RETRIEVECOLUMN 構造体には、取得した列の警告を含むエラー フィールドがあります。 列が NULL 値の場合、エラー コードはJET_wrnColumnNullに設定されます。

エラーが発生した場合、カーソルの位置は変更されず、指定されたバッファーにデータはコピーされません。

解説

JetRetrieveColumns では、 JetRetrieveColumn ではサポートされていない 1 つの機能がサポートされています。 これは、複数値列のインスタンスの数を取得する機能です。 この機能の目的は、アプリケーションが列のすべての値を取得できるようにすることです。 これを行うには、最初に列に含まれる値の数を決定します。 次に、列データの長さを決定するために、値ごとに 1 つのJET_RETRIEVECOLUMN構造体が割り当てられた JetRetrieveColumns をもう一度呼び出すことで、それらの長さを決定できます。 これを行うには、cbMax が 0 (ゼロ) の NULLpvData ポインターを渡し、cbActual で列の長さを取得します。 3 番目と最後の呼び出しは、列値データに割り当てられたメモリを使用して行うことができます。

長さのバッファーが不足しているために取得された列が切り捨てられている場合、API はJET_wrnBufferTruncatedを返します。 ただし、その他のエラー JET_wrnColumnNullは、 JET_RETRIEVECOLUMNのエラー フィールドにのみ返されます。 その理由は、アプリケーションが多くの場合、すべてのデータが確実に取得され、 JetRetrieveColumns からこのエラーを返すことが、この理解を容易にするためです。

必要条件

要件 値

Client

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

[サーバー]

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

ヘッダー

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

Library

ESENT.lib を使用します。

[DLL]

ESENT.dllが必要です。

参照

JET_ERR
JET_SESID
JET_TABLEID
JET_RETRIEVECOLUMN
JetEnumerateColumns
JetRetrieveColumn
JetSetColumns