JetSetColumn 関数

適用対象: Windows |Windows Server

JetSetColumn 関数

JetSetColumn 関数は、変更されたレコード内の 1 つの列値を、挿入または現在のレコードの更新に変更します。 既存の値を上書きしたり、複数値列の値のシーケンスに新しい値を追加したり、複数値列の値のシーケンスから値を削除したり、長い値のすべてまたは一部を更新したり、 型がJET_coltypLongText または JET_coltypLongBinaryの列を更新したりできます。

    JET_ERR JET_API JetSetColumn(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit,
      __in_opt      JET_SETINFO* psetinfo
    );

パラメーター

sesid

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

tableid

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

columnid

取得する列の JET_COLUMNID 。 または、0 (ゼロ) の columnid 値を指定することもできます。 columnid 0 (ゼロ) を指定すると、スパース列と複数値列のタグ付けされたすべての列が 1 つの列として扱われます。 これにより、レコードに存在するすべてのスパース列の取得が容易になります。

pvData

列値に使用するデータを含む入力バッファー。

cbData

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

grbit

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

値	説明
JET_bitSetAppendLV	このオプションは、JET_coltypLongText型または JET_coltypLongBinary 型の列にデータを追加するために使用 されます。 同じ動作を実現するには、既存の long 値のサイズを決定し、psetinfo で ibLongValue を指定します。 ただし、既存の列値のサイズを把握する必要がないため、この grbit を使用する方が簡単です。
JET_bitSetOverwriteLV	このオプションを使用すると、既存の long 値が新しく指定されたデータに置き換えられます。 このオプションを使用すると、新しいデータを設定する前に、既存の long 値の長さが 0 (ゼロ) に設定されているかのように表示されます。
JET_bitSetRevertToDefaultValue	このオプションは、タグ付けされた列、スパース列、または複数値の列にのみ適用されます。 これにより、列は、後続の列の取得操作で既定の列値を返します。 既存の列値はすべて削除されます。
JET_bitSetSeparateLV	このオプションは、長い値、 JET_coltypLongText 型または JET_coltypLongBinaryの列を、残りのレコード データとは別に格納するために使用されます。 これは通常、長い値のサイズが残りのレコード データと共に格納されないようにする場合に発生します。 ただし、このオプションを使用すると、long 値を個別に格納するように強制できます。 小さいサイズの長い値 4 バイトは、強制的に分離できないことに注意してください。 このような場合、オプションは無視されます。
JET_bitSetSizeLV	このオプションは、指定された columnid によって記述される長い値の長さとして設定する整数バイト数として入力バッファーを解釈するために使用され、指定されている場合は psetinfo-itagSequence> のシーケンス番号です。 指定されたサイズが既存の列値より大きい場合、列は 0 で拡張されます。 サイズが既存の列値よりも小さい場合、値は切り捨てられます。
JET_bitSetUniqueMultiValues	このオプションは、複数値の列のすべての値が異なっていることを強制するために使用されます。 このオプションは、変換を行わずにソース列データを他の既存の列値と比較し、重複が見つかった場合にエラーが返されます。 このオプションを指定すると、JET_bitSetAppendLV、JET_bitSetOverwriteLV、JET_bitSetSizeLVも指定できません。
JET_bitSetUniqueNormalizedMultiValues	このオプションは、複数値の列のすべての値が異なっていることを強制するために使用されます。 このオプションは、列データのキー正規化変換を他の同様に変換された既存の列値と比較し、重複が見つかった場合にエラーが返されます。 このオプションを指定すると、JET_bitSetAppendLV、JET_bitSetOverwriteLV、JET_bitSetSizeLVも指定できません。
JET_bitSetZeroLength	このオプションは、値を長さ 0 に設定するために使用されます。 通常、列の値は、cbMax を 0 (ゼロ) に渡すことによって NULL に 設定されます。 ただし、 JET_coltypTextなどの一部の型では、列の値は NULL ではなく 0 (ゼロ) の長さにすることができ、このオプションは NULL と 0 (ゼロ) の長さを区別するために使用されます。 メモ 一般に、列が固定長列の場合、このビットは無視され、列は NULL に設定されます。 ただし、列が固定長のタグ付き列の場合、列の長さは 0 に設定されます。 固定長タグ付き列の長さが 0 に設定されている場合、 JetRetrieveColumn または JetRetrieveColumns を使用して列の取得を試みますが、 cbActual パラメーターで返される実際の長さは 0 です。
JET_bitSetIntrinsicLV	このオプションは、長い値全体をレコードに格納するために使用されます。
JET_bitSetCompressed	このオプションは、データを格納するときにデータ圧縮を試みるために使用されます。 Windows 7: JET_bitSetCompressedは Windows 7 で導入されています。
JET_bitSetUncompressed	このオプションは、データの格納時に圧縮を試みない場合に使用されます。 Windows 7: JET_bitSetUnCompressedは Windows 7 で導入されています。

psetinfo

JET_SETINFO構造体を使用してこの関数に設定できる省略可能な入力パラメーターへのポインター。

psetinfo に NULL が指定されている場合、関数は itagSequence が 1 で、ibLongValue が 0 (ゼロ) であるかのように動作します。 これにより、列セットは複数値の列の最初の値を設定し、オフセット 0 (ゼロ) から始まる長いデータを設定します。

このパラメーターには、次のオプションを設定できます。

値	説明
ibLongValue	セット データを開始する長い列値へのバイナリ オフセット。
itagSequence	設定する目的の複数値列値のシーケンス番号。 itagSequence が 0 (ゼロ) に設定されている場合は、指定された値を複数値のシーケンスの末尾に追加する必要があります。 指定されたシーケンス番号が、既存の最後の複数値の値より大きい場合は、指定された値が値のシーケンスの末尾に追加されます。 シーケンス番号が既存の値に対応する場合、その値は指定された値に置き換えられます。

戻り値

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

リターン コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errBadColumnId	指定された列 ID が列 ID の法的制限を超えています。
JET_errClientRequestToStopJetService	JetStopService の呼び出しの結果、セッションに関連付けられたインスタンス上のすべてのアクティビティが停止したため、操作を完了することはできません。
JET_errColumnNotFound	指定された columnid によって記述された列がテーブルに存在しません。
JET_errColumnNotUpdatable	コピーの挿入削除の元の更新操作中に長い値を更新しようとしました。
JET_errColumnTooBig	入力バッファーに指定された列値データが、固定長列に対して自然なサイズ制限を超えるか、固定長テキストまたはバイナリ列用に構成されています。 このエラーは、長い列に 1024 バイトを超えるデータを渡し、JET_bitSetIntrinsicLV フラグを設定するときにも返されます。
JET_errInstanceUnavailable	セッションに関連付けられているインスタンスで、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。 Windows XP: このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errInvalidBufferSize	指定された列値のデータ サイズが、固定長データ型の自然なサイズと一致しません。
JET_errInvalidColumnType	挿入操作または更新操作中に自動インクリメント列を更新するか、置換操作中にバージョン列を更新しようとしました。
JET_errInvalidgrbit	指定されたオプションは不明であるか、既知のビット設定の組み合わせが正しくありません。
JET_errInvalidParameter	指定された psetinfo-cbStruct> は、 JET_SETINFO 構造体の有効なサイズではありません。
JET_errMultiValuedDuplicate	列の設定操作で重複する値を作成しようとしましたが、JET_bitSetUniqueMultiValuesまたはJET_bitSetUniqueNormalizedMultiValuesを指定しました。
JET_errNotInitialized	セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errNotInTransaction	呼び出し元のセッションがトランザクションに含まれていないときに、長い列値を更新しようとしました。
JET_errNullInvalid	NULL 以外の列を NULL に設定しようとしました。
JET_errColumnIllegalNull	JET_errNullInvalidと同じです。
JET_errRecordTooBig	列の値を入力バッファーの値に設定できませんでした。これは、レコードがページ サイズ関連のサイズ制限を超える原因となったためです。 JET_coltypLongText型またはJET_coltypLongBinary型の列は、残りのレコード データとは別に格納できます。 ただし、他の列はレコードと共に格納する必要があり、レコード サイズの制限を超える可能性があります。 長い列でも、リンケージとしてレコード内に 5 バイトの領域が必要です。これにより、JET_errRecordTooBigが返される可能性もあります。
JET_errRestoreInProgress	セッションに関連付けられているインスタンスで復元操作が進行中のため、操作を完了できません。
JET_errSessionSharingViolation	同じセッションを複数のスレッドに同時に使用することはできません。 Windows XP: このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errTermInProgress	セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。
JET_errUpdateNotPrepared	カーソルは現在、新しいレコードの挿入または既存のレコードの更新の処理中ではありません。
JET_errVersionStoreOutOfMemory	このエラーは、バージョン ストアの構成済みサイズが、未処理のすべての更新プログラムを保持するのに不十分な場合に発生します。
JET_wrnColumnMaxTruncated	入力バッファー内の列値が可変長列に対して構成された最大長を超え、切り捨てられました。

成功すると、指定された列の列値の目的の部分が、入力バッファーからコピーされたデータで設定されます。 可変長列に指定された最大長を超えた場合、データ・セットが切り捨てられた可能性があります。

失敗した場合、カーソル位置は変更されず、コピー バッファー内の列値データは更新されません。

解説

長い値の設定、 JET_coltypLongText 型または JET_coltypLongBinary 型の列 JET_coltypLongBinaryの値は、呼び出し元のセッションがトランザクション内にある場合にのみ行う必要があります。 呼び出し元のセッションがトランザクション内にない場合は、更新操作が後で取り消された場合でも、個別に格納されている長い値に対する変更が完全にコミットされる可能性があります。 呼び出し元のセッションがトランザクション内にある場合は、更新を取り消してセッション トランザクションをロールバックすることで、更新の影響を完全にロールバックできます。

インデックスの更新は、 JetSetColumn 操作の結果として実行されません。 代わりに、インデックスは、すべての列の変更が完了し、 JetUpdate が呼び出された後にのみ更新されます。 これにより、インデックスに複数の列が変更されている場合に、インデックスを最も効率的に更新できます。

レコードのサイズは、データベース のページ サイズに基づいて制限されます。 5 バイトを超えるレコード内の長い値は、 JetSetColumn 操作の結果としてレコード内のデータがその制限を超えた場合、レコードとは別に格納されます。 エラー JET_errRecordTooBigは、分離可能なすべてのレコード列データがレコードとは別に格納され、レコードのサイズ制限を超えた後にのみ返されます。

必要条件

要件	値
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_SETINFO
JetRetrieveColumn
JetSetColumns