JetSetColumn 関数

2023-06-13

適用対象: 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 (ゼロ) に設定されている場合は、指定された値を複数値のシーケンスの末尾に追加する必要があります。指定されたシーケンス番号が、既存の最後の複数値の値より大きい場合は、指定された値が値のシーケンスの末尾に追加されます。シーケンス番号が既存の値に対応する場合、その値は指定された値に置き換えられます。

価値

意味

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 フラグを設定するときにも返されます。
インスタンスが利用できません	セッションに関連付けられているインスタンスで、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了することはできません。 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 が呼び出された後にのみ更新されます。これにより、インデックスに複数の列が変更される場合に、インデックスを最も効率的に更新できます。

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

要求事項

要件	価値
クライアント	Windows Vista、Windows XP、または Windows 2000 Professional が必要です。
サーバー	Windows Server 2008、Windows Server 2003、または Windows 2000 Server が必要です。
ヘッダー	Esent.h で宣言されています。
図書館	ESENT.lib を使用します。
DLL	ESENT.dllが必要です。

こちらもご覧ください

JET_COLUMNID
JET_ERR
JET_SESID
JET_TABLEID
JET_SETINFO
JetRetrieveColumn をする
JetSetColumns

次の方法で共有

JetSetColumn 関数