Fonction JetPrepareUpdate

S’applique à : Windows | Windows Server

Fonction JetPrepareUpdate

La fonction JetPrepareUpdate est la première opération d’exécution d’une mise à jour, dans le but d’insérer un nouvel enregistrement ou de remplacer un enregistrement existant par de nouvelles valeurs. Mises à jour sont effectuées en appelant JetPrepareUpdate, puis en appelant JetSetColumn ou JetSetColumns zéro ou plusieurs fois et enfin en appelant JetUpdate pour terminer l’opération. JetPrepareUpdate et JetUpdate définissent les limites d’une opération de mise à jour et sont importants pour avoir uniquement l’état de mise à jour final d’un enregistrement entré dans les index. Cela est à la fois plus efficace, mais également nécessaire dans les cas où les données doivent correspondre à un état valide via plus que sur l’opération de colonne définie.

Il existe plusieurs options différentes pour insérer ou remplacer des enregistrements et elles sont décrites plus en détail ci-dessous.

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

Paramètres

sesid

Session à utiliser pour cet appel.

tableid

Curseur à utiliser pour cet appel.

Préparation

Options qui peuvent être utilisées pour préparer une mise à jour, notamment les suivantes.

Valeur	Signification
JET_prepCancel	Cet indicateur entraîne l’annulation par JetPrepareUpdate de la mise à jour de ce curseur.
JET_prepInsert	Cet indicateur entraîne la préparation du curseur pour l’insertion d’un nouvel enregistrement. Toutes les données sont initialisées à l’état par défaut pour l’enregistrement. Si la table a une colonne d’incrémentation automatique, une nouvelle valeur est affectée à cet enregistrement, que la mise à jour aboutisse, échoue ou soit annulée.
JET_prepInsertCopy	Cet indicateur permet au curseur de préparer l’insertion d’une copie de l’enregistrement existant. Il doit y avoir un enregistrement actif si cette option est utilisée. L’état initial du nouvel enregistrement est copié à partir de l’enregistrement actif. Les valeurs longues stockées hors enregistrement sont pratiquement copiées.
JET_prepInsertCopyDeleteOriginal	Cet indicateur permet au curseur de préparer l’insertion du même enregistrement, ainsi qu’une suppression ou l’enregistrement d’origine. Il est utilisé dans les cas où la clé primaire a changé.
JET_prepReplace	Cet indicateur entraîne la préparation du curseur pour un remplacement de l’enregistrement actif. Si la table a une colonne de version, la colonne version est définie sur la valeur suivante dans sa séquence. Si cette mise à jour ne se termine pas, la valeur de version dans l’enregistrement n’est pas affectée. Un verrou de mise à jour est pris sur l’enregistrement pour empêcher d’autres sessions de mettre à jour cet enregistrement avant la fin de cette session.
JET_prepReplaceNoLock	Cet indicateur est similaire à JET_prepReplace, mais aucun verrou n’est pris pour empêcher d’autres sessions de mettre à jour cet enregistrement. Au lieu de cela, cette session peut recevoir des JET_errWriteConflict lorsqu’elle appelle JetUpdate pour terminer la mise à jour.

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	JetPrepareUpdate a été appelé avec un indicateur valide pour la préparation, mais pas JET_prepCancel et le curseur était déjà à l’état préparé.
JET_errClientRequestToStopJetService	Il n’est pas possible d’effectuer l’opération, car toutes les activités sur le instance associée à 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 nécessite 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_errInvalidParameter	L’indicateur de préparation donné n’est pas un indicateur valide.
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_errNotInTransaction	JetPrepareUpdate a été appelé pour remplacer un enregistrement contenant des colonnes SLV. Colonnes SLV. Notez que les colonnes SLV ne sont pas destinées à une utilisation générale. Cette fonctionnalité est utilisée pour prendre en charge l’infrastructure Microsoft Exchange et n’est pas destinée à être utilisée dans votre application.
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_errRollbackError	JetPrepareUpdate a été appelé avec JET_prepCancel mais n’a pas pu restaurer toutes les modifications apportées aux colonnes de type JET_coltypLongText et/ou aux colonnes de type JET_coltypLongBinary.
JET_errSessionSharingViolation	Cet indicateur ne peut pas être utilisé avec la même session à 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_errUpdateNotPrepared	JetPrepareUpdate a été appelé avec JET_prepCancel, mais le curseur n’était pas dans l’état préparé.

En cas de réussite, le curseur est remplacé par l’état préparé pour les besoins de la mise à jour souhaitée, ou dans le cas de JET_prepCancel, le curseur est rétabli à l’état non préparé et toutes les modifications sont ignorées.

En cas d’échec, l’état du curseur reste inchangé. Si l’échec a été JET_errRollbackError l’état du curseur est remplacé par l’état non préparé, mais toutes les modifications n’ont pas été annulées.

Notes

L’insertion d’une copie d’un enregistrement est une optimisation importante lorsque des enregistrements partagent des données de type JET_coltypLongText et/ou JET_coltypLongBinary. Ces données sont stockées hors enregistrement lorsqu’elles sont volumineuses et il est possible que plusieurs enregistrements partagent la même représentation physique des données. Dans ce cas, les données peuvent être mises à jour à partir de l’un ou l’autre enregistrement, mais cela entraîne l’éclatement des données de sorte que chaque enregistrement ait sa propre copie. Il n’est pas possible de modifier les données d’un enregistrement par une modification d’un autre enregistrement. En outre, il n’est pas possible de bloquer une mise à jour d’un enregistrement par une mise à jour d’un autre enregistrement. Il s’agit d’une fonctionnalité centrale de l’ESE, connue sous le nom de verrouillage au niveau de l’enregistrement.

Les opérations JetUpdate qui échouent laissent le curseur dans l’état de préparation de la mise à jour. Cela permet de corriger certaines erreurs, telles qu’une valeur de colonne incorrecte, sans nécessiter la recréation de l’état de mise à jour. Cela signifie que dans tous les cas où un curseur abandonne une mise à jour, il doit appeler explicitement JetPrepareUpdate avec JET_prepCancel.

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