JetPrepareUpdate 関数

適用対象: Windows |Windows Server

JetPrepareUpdate 関数

JetPrepareUpdate 関数は、新しいレコードを挿入したり、既存のレコードを新しい値に置き換えたりするために、更新を実行する最初の操作です。 更新は、JetPrepareUpdate を呼び出し、JetSetColumn または JetSetColumns を 0 回以上呼び出し、最後に JetUpdate を呼び出して操作を完了することによって行われます。 JetPrepareUpdate と JetUpdate は更新操作の境界を設定し、インデックスに入力されたレコードの最終更新状態のみを保持する場合に重要です。 これはどちらもより効率的ですが、設定された列操作よりも有効な状態とデータが一致する必要がある場合にも必要です。

レコードの挿入または置換にはいくつかの異なるオプションがあり、以下で詳しく説明します。

    JET_ERR JET_API JetPrepareUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          unsigned long prep
    );

パラメーター

sesid

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

tableid

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

準備

更新プログラムの準備に使用できるオプションには、次のものが含まれます。

値	説明
JET_prepCancel	このフラグにより、 JetPrepareUpdate はこのカーソルの更新を取り消します。
JET_prepInsert	このフラグにより、カーソルは新しいレコードの挿入を準備します。 すべてのデータは、レコードの既定の状態に初期化されます。 テーブルに自動インクリメント列がある場合、更新が最終的に成功したか、失敗したか、取り消されたかに関係なく、このレコードに新しい値が割り当てられます。
JET_prepInsertCopy	このフラグにより、カーソルは既存のレコードのコピーの挿入を準備します。 このオプションを使用する場合は、現在のレコードが存在する必要があります。 新しいレコードの初期状態は、現在のレコードからコピーされます。 レコード外に格納されている長い値は、事実上コピーされます。
JET_prepInsertCopyDeleteOriginal	このフラグにより、カーソルは同じレコードの挿入、および削除または元のレコードの挿入を準備します。 主キーが変更された場合に使用されます。
JET_prepReplace	このフラグにより、カーソルは現在のレコードの置き換えを準備します。 テーブルにバージョン列がある場合、バージョン列はそのシーケンスの次の値に設定されます。 この更新が完了しない場合、レコードのバージョン値は影響を受けません。 このセッションが完了する前に他のセッションがこのレコードを更新しないように、レコードに対して更新ロックが行われます。
JET_prepReplaceNoLock	このフラグはJET_prepReplaceに似ていますが、他のセッションがこのレコードを更新できないようにするためのロックは行われません。 代わりに、このセッションは JetUpdate を 呼び出して更新を完了したときにJET_errWriteConflictを受け取る場合があります。

戻り値

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

リターン コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errAlreadyPrepared	JetPrepareUpdate は準備に有効なフラグを指定して呼び出されましたが、JET_prepCancelではなく、カーソルは既に準備済みの状態でした。
JET_errClientRequestToStopJetService	JetStopService の呼び出しの結果、セッションに関連付けられたインスタンスのすべてのアクティビティが停止したため、操作を完了できません。
JET_errInstanceUnavailable	セッションに関連付けられているインスタンスで、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。 このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errInvalidParameter	指定された準備フラグが有効なフラグではありません。
JET_errNotInitialized	セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errNotInTransaction	SLV 列を含むレコードを置き換えるために、JetPrepareUpdate が呼び出されました。 SLV 列。 SLV 列は一般的な使用を目的とした機能ではないことに注意してください。 この機能は、Microsoft Exchange インフラストラクチャをサポートするために使用され、アプリケーションで使用することを意図したものではありません。
JET_errRestoreInProgress	セッションに関連付けられているインスタンスで復元操作が進行中のため、操作を完了できません。
JET_errRollbackError	JetPrepareUpdate はJET_prepCancelで呼び出されましたが、JET_coltypLongText型の列や型JET_coltypLongBinaryの列に加えられたすべての変更をロールバックできませんでした。
JET_errSessionSharingViolation	このフラグは、複数のスレッドから同時に同じセッションで使用することはできません。 このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errTermInProgress	セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。
JET_errUpdateNotPrepared	JetPrepareUpdate がJET_prepCancelで呼び出されましたが、カーソルが準備された状態にありません。

成功すると、カーソルは目的の更新のために準備された状態に変更されます。または、JET_prepCancelの場合、カーソルは準備されていない状態に戻され、変更はすべて破棄されます。

失敗した場合、カーソルの状態は変更されません。 エラーがJET_errRollbackErrorされた場合、カーソルの状態は準備されていない状態に変更されますが、すべての変更が元に戻されたわけではありません。

注釈

レコードのコピーを挿入することは、レコードがJET_coltypLongText型やJET_coltypLongBinaryのデータを共有する場合に重要な最適化です。 このデータは、大きい場合はレコード外に格納され、複数のレコードで同じ物理的なデータ表現を共有できます。 この場合、いずれかのレコードからデータを更新できますが、その場合、各レコードに独自のコピーが含まれるようにデータがバーストされます。 別のレコードからの変更によって、あるレコードのデータを変更することはできません。 また、別のレコードの更新によって 1 つのレコードの更新をブロックすることはできません。 これは ESE の中心的な機能であり、レコード レベル ロックと呼ばれます。

JetUpdate 操作が失敗すると、カーソルは更新準備済み状態になります。 これは、更新状態の再作成を必要とせずに、間違った列値などの一部のエラーを修正できるようにするためです。 つまり、カーソルが更新を破棄するすべての場合は、JET_prepCancelを使用して JetPrepareUpdate を明示的に呼び出す必要があります。

要件

要件	値
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_ERR
JET_SESID
JET_TABLEID
JetRetrieveColumn
JetSetColumn
JetUpdate