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 |
JET_errSuccess |
JET_errWriteConflict |
JET_errWriteConflict |
|
JET_errWriteConflict |
JET_errWriteConflict |
JET_errWriteConflict |
||
Session A |
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 |
|||
Un |
0 |
||
Un |
JetEscrowUpdate (4) |
4 |
0 |
Un |
4 |
||
B |
|||
B |
0 |
||
B |
JetEscrowUpdate (3) |
7 |
4 |
B |
3 |
||
Un |
JetEscrowUpdate (2) |
9 |
7 |
Un |
JetEscrowUpdate (-7) |
2 |
9 |
B |
3 |
||
Un |
-1 |
||
B |
-1 |
||
Un |
-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