JetEscrowUpdate 関数

[アーティクル]
06/13/2023

適用対象: Windows |Windows Server

JetEscrowUpdate 関数

JetEscrowUpdate 関数は、1 つの列に対してアトミック加算操作を実行します。この関数を使用すると、複数のセッションで競合することなく、同じレコードを同時に更新できます。

    JET_ERR JET_API JetEscrowUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in          void* pv,
      __in          unsigned long cbMax,
      __out_opt     void* pvOld,
      __in          unsigned long cbOldMax,
      __out_opt     unsigned long* pcbOldActual,
      __in          JET_GRBIT grbit
    );

パラメーター

sesid

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

tableid

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

columnid

更新する列の columnid 。

列の addend を含むバッファーへのポインター。

cbMax

addend を含むバッファーのサイズ。

pvOld

データベースに格納されている列の現在の値を受け取る出力バッファー (バージョン管理は無視されます)。

cbOldMax

列の現在の値を受け取る出力バッファーの最大サイズ。現在、JET_coltypLongのみがサポートされているため、バッファーの長さは 4 バイトまたは 0 バイトである必要があります。 pvOld が NULL の場合、cbOldMax は 0 である必要があります。

pcbOldActual

出力バッファーで受信した生の値データの実際の量を受け取ります。

grbit

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

値	説明
JET_bitEscrowNoRollback	エスクロー更新を実行するセッションにトランザクションロールバックがある場合でも、この更新は元に戻されません。ログレコードがディスクにフラッシュされない可能性があるため、クラッシュが発生すると、このフラグで行われた最近のエスクロー更新が失われる可能性があることに注意してください。

値

説明

JET_bitEscrowNoRollback

エスクロー更新を実行するセッションにトランザクションロールバックがある場合でも、この更新は元に戻されません。ログレコードがディスクにフラッシュされない可能性があるため、クラッシュが発生すると、このフラグで行われた最近のエスクロー更新が失われる可能性があることに注意してください。

戻り値

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

リターンコード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errAlreadyPrepared	カーソルには、 JetPrepareUpdate で準備された更新プログラムがあります。
JET_errClientRequestToStopJetService	JetStopService の呼び出しの結果、セッションに関連付けられたインスタンス上のすべてのアクティビティが停止したため、操作を完了することはできません。
JET_errInstanceUnavailable	セッションに関連付けられているインスタンスで致命的なエラーが発生したため、操作を完了できません。このエラーでは、そのデータの整合性を保護するためにすべてのデータへのアクセスを取り消す必要があります。このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errInvalidBufferSize	無効なバッファーサイズが渡されました。現在、JET_coltypLongのみがサポートされているため、バッファーは 4 バイトである必要があります。
JET_errInvalidOperation	無効な列が指定されました。列は、JET_bitColumnEscrowUpdate指定して作成する必要があります。 JET_coltypLongの固定列のみをエスクロー更新可能として指定できます。
JET_errNoCurrentRecord	列を更新するには、レコードにカーソルを置く必要があります。
JET_errNotInTransaction	エスクロー更新は、トランザクション内のセッションによってのみ実行できます。
JET_errNotInitialized	セッションに関連付けられているインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errPermissionDenied	カーソルを読み取り専用にして、レコードを更新することはできません。
JET_errRestoreInProgress	セッションに関連付けられているインスタンスで復元操作が進行中であるため、操作を完了できません。
JET_errSessionSharingViolation	同じセッションを複数のスレッドから同時に使用することはできません。このエラーは、Windows XP 以降のリリースでのみ返されます。
JET_errTermInProgress	セッションに関連付けられているインスタンスがシャットダウンされているため、操作を完了できません。
JET_errTransReadOnly	セッションには、レコードを更新するための書き込みアクセス許可が必要です。
JET_errWriteConflict	競合する更新が要求されたときに返されるエラー。

解説

通常、2 つのセッションでレコードを同時に更新しようとすると、セッションが完全にシリアル化されない限り、2 番目のセッションはJET_errWriteConflictエラーを受け取ります。同じレコードを更新する 2 つのセッションをシリアル化するには、2 番目のセッションは、最初のトランザクションがトランザクションをコミットした後にトランザクションを開始する必要があります。詳細については、「 JetBeginTransaction 」を参照してください。

同じレコード内の複数の列をエスクロー更新できます。更新は互いに影響しません。

JetEscrowUpdate 操作のみが相互に互換性があります。 2 つの異なるセッションで更新の準備または同じレコードの削除を試みると、書き込みの競合が生成されます。

		セッション B JetEscrowUpdate	JetPrepareUpdate	JetDelete
	JetEscrowUpdate	JET_errSuccess	JET_errWriteConflict	JET_errWriteConflict
	JetUpdate	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict
セッション A	JetDelete	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict

エスクロー操作はバージョン管理され、 JetRollback を使用して元に戻されます (JET_bitEscrowNoRollback指定されていない限り)。 JetEscrowUpdate は、データベースに格納されている列の生の値を返します。これは、アプリケーションがセンチネル値にヒットしたときに特別なアクションを実行する場合があるためです。 JetRetrieveColumn は列の正しいバージョン管理されたビューを返し、同時セッションによって行われた更新は無視されます。

同じレコードの同じ列で 2 つのセッションが動作している場合、このしくみを確認できます。列の先頭の値が 0 であるとします。

Session	操作	格納された値	戻り値
A	JetBeginTransation
A	JetBeginTransation		0
A	JetEscrowUpdate (4)	4	0
A	JetRetrieveColumn		4
B	JetBeginTransaction
B	JetRetrieveColumn		0
B	JetEscrowUpdate (3)	7	4
B	JetRetrieveColumn		3
A	JetEscrowUpdate (2)	9	7
A	JetEscrowUpdate (-7)	2	9
B	JetRetrieveColumn		3
A	JetRetrieveColumn		-1
B	JetRollback	-1
A	JetRetrieveColumn		-1

レコードのエスクロー更新を実行するのと同じトランザクション内のレコードを置き換えることはお勧めしません。特に、レコードの更新が 1 つのJET_TABLEID で準備され、別の JET_TABLEID を使用してレコードをエスクロー更新する場合、 JetUpdate が呼び出されると、更新されたエスクローは失われます。これは、更新中にエスクロー列が設定されていない場合でも発生します。

エスクロー更新可能列の値が 0 の場合は、特別な動作をトリガーできます。この動作は 、JetEscrowUpdate 操作によって列の値が 0 になる場合にのみ発生します。アクションはすぐには実行されませんが、列の値が 0 のコミットの原因となったトランザクションの後に発生することがあります。列の値は 0 である必要があります (つまり、他のセッションで列が変更されていない場合)。列が JET_bitColumnDeleteOnZero で作成された場合、その列を含むレコードは削除されます。列が JET_bitColumnFinalize で作成された場合は、コールバックが発行されます。クラッシュすると、これらのアクションが発生しない可能性がありますが、オンラインメンテナンス ( JetDefragment 関数を使用) はアクションを正しくやり直します。

必要条件

要件	値
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_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction
JetDefragment
JetPrepareUpdate
JetRetrieveColumn
JetRollback
JetStopService
JetUpdate

次の方法で共有

JetEscrowUpdate 関数