JetPrepareUpdate fonction)
S’applique à : Windows | Windows Serveurs
JetPrepareUpdate fonction)
La fonction JetPrepareUpdate est la première opération d’exécution d’une mise à jour, dans le cadre de l’insertion d’un nouvel enregistrement ou du remplacement d’un enregistrement existant par de nouvelles valeurs. Les mises à jour sont effectuées en appelant JetPrepareUpdate, puis en appelant JetSetColumn ou JetSetColumns zéro, une 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 que seul l’état de mise à jour final d’un enregistrement soit entré dans les index. Cela est à la fois plus efficace, mais également requis dans les cas où les données doivent correspondre à un état valide par rapport à l’opération de définition de colonne.
Il existe différentes options pour l’insertion ou le remplacement 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 Force JetPrepareUpdate à annuler la mise à jour pour ce curseur. |
JET_prepInsert |
Cet indicateur force le curseur à préparer une insertion d’un nouvel enregistrement. Toutes les données sont initialisées à l’État par défaut de l’enregistrement. Si la table comporte une colonne à incrémentation automatique, une nouvelle valeur est affectée à cet enregistrement, que la mise à jour réussisse ou non, échoue ou est annulée. |
JET_prepInsertCopy |
Cet indicateur force le curseur à préparer une 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 en cours. Les valeurs longues qui sont stockées hors enregistrement sont virtuellement copiées. |
JET_prepInsertCopyDeleteOriginal |
Cet indicateur force le curseur à préparer une 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 été modifiée. |
JET_prepReplace |
Cet indicateur force le curseur à préparer un remplacement de l’enregistrement en cours. Si la table contient une colonne 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 la version dans l’enregistrement n’est pas affectée. Un verrou de mise à jour est appliqué à 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 PREP mais pas JET_prepCancel et le curseur était déjà à l’état préparé. |
JET_errClientRequestToStopJetService |
Il n’est pas possible de terminer l’opération, car toute activité sur l’instance associée à la session a été interrompue suite à un appel à JetStopService. |
JET_errInstanceUnavailable |
Il n’est pas possible de terminer l’opération, car l’instance associée à la session a rencontré une erreur irrécupérable qui requiert que l’accès à toutes les données soit révoqué pour protéger l’intégrité de ces données. cette erreur est renvoyée uniquement par Windows XP et les versions ultérieures. |
JET_errInvalidParameter |
L’indicateur PREP donné n’est pas un indicateur valide. |
JET_errNotInitialized |
Impossible de terminer l’opération, car l’instance associée à la session n’a pas encore été initialisée. |
JET_errNotInTransaction |
JetPrepareUpdate a été appelé pour remplacer un enregistrement qui avait des colonnes SLV. Colonnes SLV. Notez que les colonnes SLV sont une fonctionnalité qui n’est pas destinée à 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 de terminer l’opération, car une opération de restauration est en cours sur l’instance associée à 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 les 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 est renvoyée uniquement par Windows XP et les versions ultérieures. |
JET_errTermInProgress |
Il n’est pas possible de terminer l’opération, car l’instance associée à 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 passe à l’état préparé dans le cadre 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 passe à l’état non préparé, mais les modifications ne sont pas toutes annulées.
Notes
L’insertion d’une copie d’un enregistrement est une optimisation importante lorsque les 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înera une rafale des données, de sorte que chaque enregistrement possède 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 la mise à jour d’un enregistrement à l’aide d’une mise à jour d’un autre enregistrement. Il s’agit d’une fonctionnalité centrale de ESE qui porte le nom de verrouillage au niveau des enregistrements.
Les opérations JetUpdate qui échouent laissent le curseur dans l’état préparé de 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 explicitement appeler JetPrepareUpdate avec JET_prepCancel.
Configuration requise
| Condition requise | Valeur |
|---|---|
Client |
requiert Windows Vista, Windows XP ou Windows 2000 Professional. |
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 |
Requiert ESENT.dll. |
Voir aussi
JET_ERR
JET_SESID
JET_TABLEID
JetRetrieveColumn
JetSetColumn
JetUpdate