Fonction JetEscrowUpdate

S’applique à : Windows | Windows Server

Fonction JetEscrowUpdate

La fonction JetEscrowUpdate effectue une opération d’ajout atomique sur une colonne. Cette fonction permet à plusieurs sessions de mettre à jour le même enregistrement simultanément sans conflit.

    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
    );

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

Columnid

Columnid de la colonne à mettre à jour.

pv

Pointeur vers une mémoire tampon contenant l’addend de la colonne.

cbMax

Taille de la mémoire tampon contenant l’addend.

pvOld

Mémoire tampon de sortie qui recevra la valeur actuelle de la colonne telle qu’elle est stockée dans la base de données (le contrôle de version est ignoré).

cbOldMax

Taille maximale de la mémoire tampon de sortie qui recevra la valeur actuelle de la colonne. Actuellement, seule JET_coltypLong est prise en charge, de sorte que la mémoire tampon doit avoir une longueur de 4 octets ou de 0 octet. Si pvOld a la valeur NULL, cbOldMax doit être 0.

pcbOldActual

Reçoit la quantité réelle de données de valeur brute reçues dans la mémoire tampon de sortie.

grbit

Groupe de bits spécifiant zéro ou plusieurs des options suivantes.

Valeur	Signification
JET_bitEscrowNoRollback	Même si la session qui effectue la mise à jour de l’entiercement a sa restauration de transaction, cette mise à jour ne sera pas annulée. Notez que, comme les enregistrements du journal peuvent ne pas être vidés sur le disque, les mises à jour d’entiercement récentes effectuées avec cet indicateur peuvent être perdues en cas d’incident.

Valeur renvoyée

Cette fonction retourne le type de données JET_ERR avec l’un des codes de retour suivants. Pour plus d’informations sur les erreurs ESE possibles, consultez Erreurs du moteur de stockage extensible et Paramètres de gestion des erreurs.

Code de retour	Description
JET_errSuccess	L’opération s’est terminée avec succès.
JET_errAlreadyPrepared	Une mise à jour du curseur est préparée avec JetPrepareUpdate.
JET_errClientRequestToStopJetService	Il n’est pas possible d’effectuer l’opération, car toutes les activités sur le instance associées à la session ont cessé à la suite d’un appel à JetStopService.
JET_errInstanceUnavailable	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session a rencontré une erreur irrécupérable qui exige que l’accès à toutes les données soit révoqué pour protéger l’intégrité de ces données. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errInvalidBufferSize	Une taille de mémoire tampon non valide a été transmise. Actuellement, seule JET_coltypLong est prise en charge, de sorte que la mémoire tampon doit être de 4 octets.
JET_errInvalidOperation	Une colonne non valide a été spécifiée. La colonne doit être créée avec JET_bitColumnEscrowUpdate spécifié. Seules les colonnes fixes de JET_coltypLong peuvent être spécifiées comme pouvant être mises à jour par dépôt d’entiercement.
JET_errNoCurrentRecord	Le curseur doit se trouver sur un enregistrement pour mettre à jour une colonne.
JET_errNotInTransaction	Les mises à jour d’entiercement ne peuvent être effectuées que par les sessions d’une transaction.
JET_errNotInitialized	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session n’a pas encore été initialisé.
JET_errPermissionDenied	Le curseur ne peut pas être en lecture seule et mettre à jour un enregistrement.
JET_errRestoreInProgress	Il n’est pas possible d’effectuer l’opération, car une opération de restauration est en cours sur le instance associé à la session.
JET_errSessionSharingViolation	La même session ne peut pas être utilisée à partir de plusieurs threads en même temps. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.
JET_errTermInProgress	Il n’est pas possible d’effectuer l’opération, car le instance associé à la session est en cours d’arrêt.
JET_errTransReadOnly	La session doit disposer des autorisations d’écriture pour mettre à jour un enregistrement.
JET_errWriteConflict	Erreur retournée lorsqu’une mise à jour en conflit est demandée.

Notes

Normalement, si deux sessions tentent de mettre à jour un enregistrement simultanément, la deuxième session reçoit une erreur de JET_errWriteConflict, sauf si les sessions sont complètement sérialisées. Pour sérialiser deux sessions qui mettent à jour le même enregistrement, la deuxième session doit démarrer sa transaction après que la première transaction valide sa transaction. Pour plus d’informations, consultez JetBeginTransaction .

Plusieurs colonnes du même enregistrement peuvent être mises à jour par séquestre. Les mises à jour ne s’affectent pas les unes les autres.

Seules les opérations JetEscrowUpdate sont compatibles les unes avec les autres. Si deux sessions différentes tentent de préparer des mises à jour ou de supprimer le même enregistrement, un conflit d’écriture est généré.

		Session B JetEscrowUpdate	JetPrepareUpdate	JetDelete
	JetEscrowUpdate	JET_errSuccess	JET_errWriteConflict	JET_errWriteConflict
	JetUpdate	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict
Session A	JetDelete	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict

Les opérations d’entiercement sont versionnée et annulées à l’aide de JetRollback (sauf si JET_bitEscrowNoRollback a été spécifié). JetEscrowUpdate retourne la valeur brute de la colonne stockée dans la base de données, car une application peut vouloir effectuer une action spéciale lorsqu’une valeur sentinelle est atteinte. JetRetrieveColumn retourne la vue avec version correcte de la colonne, en ignorant les mises à jour effectuées par les sessions simultanées.

Étant donné que deux sessions fonctionnent sur la même colonne du même enregistrement, nous pouvons voir comment cela fonctionne. Supposons que la colonne commence par une valeur de 0.

session	Opération	Valeur stockée	Valeur renvoyée
Un	JetBeginTransation
Un	JetBeginTransation		0
Un	JetEscrowUpdate (4)	4	0
Un	JetRetrieveColumn		4
B	JetBeginTransaction
B	JetRetrieveColumn		0
B	JetEscrowUpdate (3)	7	4
B	JetRetrieveColumn		3
Un	JetEscrowUpdate (2)	9	7
Un	JetEscrowUpdate (-7)	2	9
B	JetRetrieveColumn		3
Un	JetRetrieveColumn		-1
B	JetRollback	-1
Un	JetRetrieveColumn		-1

Il n’est pas recommandé de remplacer un enregistrement dans la même transaction qui effectue des mises à jour d’entiercement dans un enregistrement. En particulier, si une mise à jour d’un enregistrement est préparée avec un JET_TABLEID et qu’une autre JET_TABLEID est utilisée pour mettre à jour l’enregistrement, l’entiercement mis à jour est perdu lorsque JetUpdate est appelé. Cela se produit même si la colonne d’entiercement n’a pas été définie pendant la mise à jour.

Lorsqu’une colonne pouvant être mise à jour avec une valeur égale à zéro, un comportement spécial peut être déclenché. Ce comportement se produit uniquement si une opération JetEscrowUpdate entraîne la valeur zéro de la colonne. L’action ne se produit pas immédiatement, mais se produit quelque temps après la transaction, ce qui a provoqué la valeur zéro validations de la colonne. La colonne doit toujours avoir une valeur de zéro (autrement dit, si aucune autre session n’a modifié la colonne). Si la colonne a été créée avec JET_bitColumnDeleteOnZero, l’enregistrement contenant la colonne est supprimé. Si la colonne a été créée avec JET_bitColumnFinalize un rappel est émis. Un plantage peut empêcher ces actions de se produire, mais la maintenance en ligne (à l’aide de la fonction JetDefragment ) rétablit correctement les actions.

Spécifications

Condition requise	Valeur
Client	Nécessite Windows Vista, Windows XP ou Windows 2000 Professionnel.
Serveur	Nécessite Windows Server 2008, Windows Server 2003 ou Windows 2000 Server.
En-tête	Déclaré dans Esent.h.
Bibliothèque	Utilisez ESENT.lib.
DLL	Nécessite ESENT.dll.

Voir aussi

JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction
JetDefragment
JetPrepareUpdate
JetRetrieveColumn
JetRollback
JetStopService
JetUpdate