次の方法で共有

JetEnumerateColumns 関数

  • [アーティクル]

適用対象: Windows |Windows Server

JetEnumerateColumns 関数

JetEnumerateColumns 関数は、カーソルの現在のレコードまたはそのカーソルのコピー バッファーから、一連の列とその値を効率的に取得します。 取得される列と値は、列 ID、 itagSequence 番号、およびその他の特性のリストによって制限できます。 この列取得 API は、ユーザー指定の 再割 り当て互換コールバックを使用して取得された、動的に割り当てられたメモリ内の情報を返すという点で一意です。 この新しい柔軟性により、呼び出し元に不明な特定の特性 (サイズや多重度など) を持つ列データを効率的に取得できます。 これにより、 JetRetrieveColumn の探索モードを使用して、目的のデータを正常に取得する JetRetrieveColumn への最終的な呼び出しを設定するために、これらの特性を判断する必要がなくなります。

Windows XP: JetEnumerateColumns は Windows XP で導入されています。

    JET_ERR JET_API JetEnumerateColumns(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long cEnumColumnId,
      __in_opt      JET_ENUMCOLUMNID* rgEnumColumnId,
      __out         unsigned long* pcEnumColumn,
      __out         JET_ENUMCOLUMN** prgEnumColumn,
      __in          JET_PFNREALLOC pfnRealloc,
      __in          void* pvReallocContext,
      __in          unsigned long cbDataMost,
      __in          JET_GRBIT grbit
    );

パラメーター

sesid

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

tableid

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

cEnumColumnId

列挙する itagSequence 番号の省略可能な配列を持つ列 ID の配列。

cEnumColumnId が 0 (ゼロ) の場合、rgEnumColumnId は無視され、すべての列値が列挙され、呼び出し元に返されます。 列 ID 配列の要素が 0 (ゼロ) の列 ID を参照している場合、その列の列挙はスキップされ、出力内の対応するスロットがJET_wrnColumnSkipped列の状態で生成されます。

列 ID 配列の特定の要素に対して ctagSequence が 0 (ゼロ) の場合、 rgtagSequence は無視され、その列 ID のすべての列値が列挙され、呼び出し元に返されます。 itagSequence 数値配列の要素が 0 (ゼロ) の itagSequence 番号を参照している場合、その itagSequence 番号の列挙はスキップされ、出力内の対応するスロットがJET_wrnColumnSkippedの列値の状態で生成されます。

rgEnumColumnId

cEnumColumnId を参照してください。

pcEnumColumn

指定された itagSequence 互換コールバックを介して割り当てられたメモリ内の列とその値の列挙配列を返します。

入力時に列 ID の配列が要求された場合、出力配列の順序とサイズには、入力配列の順序とサイズが反映されます。 同様に、入力時に特定の列 ID に対して itagSequence 番号の配列が要求された場合、その列の列値の出力配列の順序とサイズには、入力配列の順序とサイズが反映されます。

出力パラメーターは、JET_errBadColumnIdとJET_errColumnNotFoundを除くすべてのエラーで 0 (ゼロ) と NULL に設定されます。 これらのエラーが返されると、出力データは有効で、影響を受ける列 ID 以外のすべての列 ID に対して完了します。 影響を受ける各列 ID の状態コードは、これらのエラーの 1 つに設定されているため、呼び出し元は、どの列 ID が正しくなかったかを判断し、修正アクションを実行する可能性があります。

prgEnumColumn

「pcEnumColumn」を参照してください。

pfnRealloc

列とその値の出力配列にメモリを割り当てるために使用される 、再割 り当て互換コールバックと省略可能なコンテキスト ポインターを識別します。

pvReallocContext

pfnRealloc を参照してください。

cbDataMost

長いテキストまたは長いバイナリ列から返されるデータの量に上限を設定します。

このパラメーターを使用すると、列の値が非常に大きくなるのを防ぐことができます。 通常、このような列挙は、JET_errOutOfMemoryを使用して API 呼び出しを失敗する可能性があります。 このような方法で大きな列の値が切り捨てられると、列の値の状態がJET_wrnColumnTruncatedされます。

grbit

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

値

説明

JET_bitEnumerateCompressOutput

列の値を列挙する場合、すべての値を取得し、NULL 以外の列値が 1 つしかないすべての列を圧縮形式で返すことができます。 このような列の状態は JET_wrnColumnSingleValue に設定され、列値と列値を含むメモリのサイズは 、JET_ENUMCOLUMN 構造体で直接返されます。 すべての有効な列がこの方法で圧縮されるとは限りません。 詳細については、「 JET_ENUMCOLUMN 」を参照してください。

JET_bitEnumerateCopy

このオプションは、レコードの変更された列値を元の列値ではなく列挙する必要があることを示します。 列の値が変更されていない場合は、元の列の値が列挙されます。 この方法では、レコードを挿入または更新するときに、まだ挿入または更新されていない列値を列挙できます。

このオプションは、JetRetrieveColumn または JetRetrieveColumns で使用する場合のJET_bitRetrieveCopyと同じです。

JET_bitEnumerateIgnoreDefault

特定の列がレコードに存在しない場合、列の値は返されません。 通常、この場合、列の既定値 (存在する場合) が返されます。 列が既定値とは異なる値に設定されている場合は、その異なる値が返されます (つまり、既定値を持つ列が明示的に NULL に設定されている場合は、その列の値として NULL が返されます)。 このオプションが要求された場合でも、既定値と等しい列値を確認することはできます。 既定値と一致する列値を削除する作業は行われません。

このオプションは、JET_bitEnumeratePresenceOnlyまたはJET_bitEnumerateTaggedOnlyで使用した場合の JetEnumerateColumns の 出力に影響を与える点に注意してください。

JET_bitEnumerateIgnoreUserDefinedDefault

特定の列がレコードに存在せず、ユーザー定義の既定値がある場合、列値は返されません。 このオプションを使用すると、その列の値を列挙するときに、列のユーザー定義の既定値を計算するコールバックが呼び出されなくなります。

Windows Server 2003 以前: Windows Server 2003 以前のリリースでは、操作はJET_errCallbackFailedで失敗します。

Windows Server 2003 SP1: この値は、Windows Server 2003 SP1 以降のオペレーティング システムでのみ使用できます。 この可能な値を指定し、ユーザー定義の既定値を持つ列がテーブルに含まれている場合、操作はJET_errCallbackFailedで失敗します。

JET_bitEnumeratePresenceOnly

要求された列または列の値に NULL 以外の値が存在する場合、関連付けられているデータは返されません。 代わりに、その列または列の値に関連付けられている状態がJET_wrnColumnPresentに設定されます。 列または列の値が NULL の 場合、JET_wrnColumnNullは通常どおり返されます。

JET_bitEnumerateTaggedOnly

レコード内のすべての列値を列挙する場合 (たとえば、 cEnumColumnId が 0 の場合)、タグ付けされた列の値のみが返されます。 列 ID の特定の配列を列挙する場合、このオプションは使用できません。

JET_bitEnumerateInRecordOnly

Windows 7: JET_bitEnumerateInRecordOnlyは Windows 7 で導入されています。

戻り値

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

リターン コード

説明

JET_errSuccess

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

JET_errBadColumnId

指定された列 ID は、列 ID の法的制限を超えています。 このエラーは、特定の列 ID が要求され、それらの列 ID の 1 つが無効であり、列の状態コードに対してこのエラーで最初の無効な列 ID が失敗した場合に、 JetEnumerateColumns によって返されます。

JET_errClientRequestToStopJetService

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

JET_errColumnNotFound

指定された列 ID で記述された列がテーブルに存在しません。 このエラーは、特定の列 ID が要求され、それらの列 ID のいずれかが無効であり、列の状態コードに対してこのエラーが発生して最初の無効な列 ID が失敗した場合、 JetEnumerateColumns によって返されます。

JET_errInstanceUnavailable

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

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

JET_errInvalidgrbit

要求されたオプションの 1 つが無効であるか、実装されていません。 このエラーは、次の場合に JetEnumerateColumns によって返されます。

  • JET_bitEnumerateLocalが指定されています。

  • 無効な grbit が指定されています。

JET_errInvalidParameter

指定されたパラメーターの 1 つに予期しない値が含まれていたか、別のパラメーターの値と組み合わせたときに意味のない値が含まれていました。 このエラーは、次の場合に JetEnumerateColumns によって返されます。

  • pcEnumColumn は NULL です。

  • prgEnumColumn は NULL です。

  • pfnRealloc は NULL です。

JET_errNoCurrentRecord

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

JET_errNotInitialized

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

JET_errRecordDeleted

削除されたレコードにカーソルが置かれます。 これはさまざまな理由から起こります。 最も一般的な理由は、セッションがトランザクション内に存在せず、カーソルがレコードに配置され、そのレコードが削除された後、カーソルがそのレコードを参照しようとしたということです。

JET_errRestoreInProgress

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

JET_errSessionSharingViolation

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

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

JET_errTermInProgress

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

成功すると、要求されたデータが出力バッファーに返されます。 このコールバックによって割り当てられ、出力バッファーで返されるすべてのメモリを解放するのは呼び出し元の責任です。 そのメモリは、提供された realloc 互換コールバックを使用して解放する必要があります。 データベースの状態に対する変更は行われません。

失敗した場合、要求されたデータは返されません。 呼び出し中に割り当てられたメモリは、指定された 再割り当 て互換コールバックを使用して自動的に解放されます。 データベースの状態に対する変更は行われません。

解説

レコード内のすべての列値を列挙していて、JET_bitEnumerateIgnoreDefaultsを指定しなかった場合、状態コードがJET_wrnColumnNullの列または列の値が表示されないことを想定することはできません。 この状態コードは、列に既定値があり、明示的に NULL に設定されている場合、または列が非スパース列 (固定列や変数列など) である場合に表示されます。

cbDataMost パラメーターは、すべての列値に適用されるわけではありません。 このパラメーターでは、長いテキストと長いバイナリ列の値が切り捨てられるのは、レコードとは別に格納されているほど大きい値だけです。

JetEnumerateColumns が出力パラメーター内のデータを返す場合、呼び出し元は、配列内のメモリと、その配列に埋め込まれたポインターによって参照されるメモリを解放します。

必要条件

要件 値

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
JET_ENUMCOLUMNID
JET_ENUMCOLUMN
JET_ENUMCOLUMNVALUE
JET_PFNREALLOC
realloc
JetRetrieveColumn
JetRetrieveColumns