Partager via


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