Recordset : fonctionnement d'AddNew, Edit et Delete (ODBC)
Cette rubrique s'applique aux classes ODBC MFC.
La présente rubrique explique le fonctionnement des fonctions membres AddNew, Edit et Delete de la classe CRecordset. Les rubriques traitées ici sont les suivantes :
le fonctionnement de l'ajout d'enregistrements ;
la visibilité des enregistrements ajoutés ;
le fonctionnement de la modification d'enregistrements ;
le fonctionnement de la suppression d'enregistrements.
Notes
Cette rubrique s'applique aux objets dérivés de CRecordset dans lesquels l'extraction de lignes en bloc n'a pas été implémentée. Si vous utilisez l'extraction de lignes en bloc, consultez Recordset : extraction globale d'enregistrements (ODBC).
Comme complément d'information, vous pouvez lire la rubrique RFX : fonctionnement de RFX, qui décrit le rôle correspondant de RFX dans les opérations de mise à jour.
Ajout d'un enregistrement
L'ajout d'un nouvel enregistrement à un recordset nécessite l'appel de la fonction membre AddNew du recordset, la définition des valeurs des membres de données de type champ du nouvel enregistrement et l'appel de la fonction membre Update pour écrire l'enregistrement dans la source de données.
Comme condition préalable de l'appel de AddNew, le recordset ne doit pas avoir été ouvert en lecture seule. Les fonctions membres CanUpdate et CanAppend permettent de définir ces conditions.
Lorsque vous appelez AddNew :
L'enregistrement du tampon d'édition est stocké, si bien que son contenu peut être restauré si l'opération est annulée.
Les membres de données de type champ sont pourvus d'un indicateur, de telle sorte qu'il est possible par la suite d'identifier les modifications dont ils ont été l'objet. Les membres de données de type champ sont aussi marqués comme non modifiés et définis avec la valeur Null.
Après que vous avez appelé AddNew, le tampon d'édition représente un nouvel enregistrement vide, prêt à être complété à l'aide de valeurs. À cette fin, vous assignez manuellement les valeurs. Au lieu d'indiquer la valeur réelle des données d'un champ, vous pouvez appeler SetFieldNull pour définir la valeur Null.
Pour valider les modifications, vous appelez Update. Lorsque vous appelez Update pour le nouvel enregistrement :
Si votre pilote ODBC prend en charge la fonction API ODBC ::SQLSetPos, MFC utilise la fonction pour ajouter l'enregistrement à la source de données. Avec ::SQLSetPos, MFC peut ajouter plus efficacement un enregistrement car il n'a pas à construire et à traiter une instruction SQL.
S'il n'est pas possible d'utiliser ::SQLSetPos, MFC procède de la manière suivante :
Si aucune modification n'est détectée, Update ne fait rien et retourne la valeur 0.
S'il y a eu des modifications, Update construit une instruction SQL INSERT. Les colonnes représentées par tous les membres de données de type champ modifiés (« dirty ») sont répertoriées dans l'instruction INSERT. Pour imposer l'insertion d'une colonne, appelez la fonction membre SetFieldDirty :
SetFieldDirty( &m_dataMember, TRUE );Update valide le nouvel enregistrement — l'instruction INSERT est exécutée et l'enregistrement est validé dans la table de la source de données (et le recordset, s'il ne s'agit pas d'un instantané) à moins qu'une transaction soit en cours.
L'enregistrement stocké est restauré dans le tampon d'édition. L'enregistrement qui était courant avant l'appel de AddNew redevient l'enregistrement courant, indépendamment du fait que l'instruction INSERT se soit déroulée ou non avec succès.
Conseil
Pour contrôler totalement le nouvel enregistrement, suivez la solution suivante : définissez les valeurs de tous les champs qui contiendront des valeurs, puis définissez explicitement tous les champs qui conserveront la valeur Null en appelant SetFieldNull avec un pointeur vers le champ et le paramètre avec la valeur TRUE (par défaut). Si vous voulez garantir qu'un champ ne sera pas écrit dans la source de données, appelez SetFieldDirty avec un pointeur vers le champ et le paramètre avec la valeur FALSE, et ne modifiez pas la valeur du champ. Pour déterminer si un champ peut avoir ou non la valeur Null, appelez IsFieldNullable.
Conseil
Pour détecter à quel moment les membres de données du recordset changent de valeur, MFC utilise la valeur PSEUDO_NULL appropriée à chaque type de données que vous pouvez stocker dans un recordset. Si vous devez explicitement définir un champ avec la valeur PSEUDO_NULL et qu'un champ a déjà été marqué avec la valeur Null, vous devez aussi appeler SetFieldNull, en passant l'adresse du champ dans le premier paramètre et FALSE dans le second paramètre.
Visibilité des enregistrements ajoutés
Quand le recordset peut-il voir un enregistrement ajouté ? Que des enregistrements ajoutés soient visibles ou non dépend de deux facteurs :
les capacités du pilote ;
les bénéfices dont l'infrastructure peut tirer parti.
Si votre pilote ODBC prend en charge la fonction API ODBC ::SQLSetPos, MFC utilise la fonction pour ajouter les enregistrements. Avec ::SQLSetPos, les enregistrements ajoutés sont visibles par tout recordset MFC modifiable. Sans prise en charge de la fonction, les enregistrements ajoutés ne sont pas visibles et vous devez appeler Requery pour les visualiser. L'utilisation de ::SQLSetPos est également plus efficace.
Modification d'un enregistrement existant
La modification d'un enregistrement existant dans un recordset nécessite de faire défiler le jeu jusqu'à l'enregistrement, d'appeler la fonction membre Edit du recordset, de définir les valeurs des membres de données de type champ du nouvel enregistrement et d'appeler la fonction membre Update pour écrire l'enregistrement modifié dans la source de données.
Comme condition préalable de l'appel de Edit, le recordset doit être modifiable et positionné sur un enregistrement. Les fonctions membres CanUpdate et IsDeleted permettent de définir ces conditions. L'enregistrement courant ne doit pas avoir été déjà supprimé et des enregistrements doivent être présents dans le recordset (IsBOF et IsEOF retournent la valeur 0).
Lorsque vous appelez Edit, l'enregistrement présent dans le tampon d'édition (l'enregistrement actif) est stocké. Les valeurs de l'enregistrement stocké sont ultérieurement utilisées pour détecter si des champs ont été modifiés.
Après que vous avez appelé Edit, le tampon d'édition continue de contenir l'enregistrement courant, mais il est désormais prêt à accepter les modifications sur les membres de données de type champ. Pour modifier l'enregistrement, définissez manuellement les valeurs des membres de données de type champ que vous voulez modifier. Au lieu d'indiquer la valeur réelle des données d'un champ, vous pouvez appeler SetFieldNull pour définir la valeur Null. Pour valider les modifications, appelez Update.
Conseil
Pour quitter le mode AddNew ou Edit, appelez Move avec le paramètre AFX_MOVE_REFRESH.
Comme condition préalable à l'appel de Update, le recordset ne doit pas être vide et l'enregistrement courant ne doit pas avoir été supprimé. IsBOF, IsEOF et IsDeleted doivent retourner la valeur 0.
Lorsque vous appelez Update pour l'enregistrement modifié :
Si votre pilote ODBC prend en charge la fonction API ODBC ::SQLSetPos, MFC utilise la fonction pour mettre à jour l'enregistrement dans la source de données. Avec ::SQLSetPos, le pilote compare le tampon d'édition et l'enregistrement correspondant sur le serveur, et met à jour l'enregistrement sur le serveur en cas de différence. Avec ::SQLSetPos, MFC peut mettre à jour plus efficacement un enregistrement car il n'a pas à construire et à traiter une instruction SQL.
ou
S'il n'est pas possible d'utiliser ::SQLSetPos, MFC procède de la manière suivante :
S'il n'y a eu aucune modification, Update ne fait rien et retourne la valeur 0.
S'il y a eu des modifications, Update construit une instruction SQL UPDATE. Les colonnes répertoriées dans l'instruction UPDATE sont établies à partir des membres de données de type champ qui ont été modifiés.
Update valide les modifications — exécution de l'instruction UPDATE — et l'enregistrement est modifié sur la source de données, mais non validé si une transaction est en cours (consultez Transaction : exécution d'une transaction dans un recordset (ODBC) pour plus d'informations sur la façon dont la transaction affecte la mise à jour). ODBC conserve une copie de l'enregistrement, qui change également.
Contrairement à AddNew, Edit ne restaure pas l'enregistrement stocké. L'enregistrement modifié demeure en place comme enregistrement courant.
Avertissement
Lorsque vous vous préparez à modifier un recordset en appelant Update, prenez soin que le recordset comporte toutes les colonnes composant la clé primaire de la table (ou toutes les colonnes d'un index unique sur la table, ou un nombre suffisant de colonnes pour identifier la ligne de façon unique). Dans certains cas, l'infrastructure ne peut utiliser que les colonnes sélectionnées dans le recordset pour identifier l'enregistrement de la table à modifier. Sans toutes les colonnes nécessaires, plusieurs enregistrements peuvent être modifiés dans la table. Dans ce cas, l'infrastructure lève une exception quand vous appelez Update.
Conseil
Si vous appelez AddNew ou Edit après avoir déjà appelé l'une ou l'autre des fonctions mais avant d'appeler Update, le tampon d'édition est actualisé avec l'enregistrement stocké, en remplacement du nouvel enregistrement ou de l'enregistrement modifié en cours. Ce comportement vous fournit un moyen d'interrompre une fonction AddNew ou Edit et d'en commencer une nouvelle : si vous établissez que l'enregistrement en cours est erroné, il vous suffit d'appeler de nouveau Edit ou AddNew.
Suppression d'un enregistrement
La suppression d'un enregistrement du recordset nécessite d'accéder à l'enregistrement et d'appeler la fonction membre Delete du recordset. Contrairement à AddNew et Edit, Delete n'appelle pas la fonction Update.
Comme condition préalable de l'appel de Delete, le recordset doit être modifiable et positionné sur un enregistrement. Les fonctions membres CanUpdate, IsBOF, IsEOF et IsDeleted permettent de définir ces conditions.
Lorsque vous appelez **Delete **:
Si votre pilote ODBC prend en charge la fonction API ODBC ::SQLSetPos, MFC utilise la fonction pour supprimer l'enregistrement dans la source de données. L'utilisation de ::SQLSetPos est également plus efficace que celle de SQL.
ou
S'il n'est pas possible d'utiliser ::SQLSetPos, MFC procède de la manière suivante :
L'enregistrement actif présent dans le tampon d'édition n'est pas sauvegardé comme dans AddNew et Edit.
Delete construit l'instruction SQL DELETE qui supprime l'enregistrement.
L'enregistrement courant du tampon d'édition n'est pas sauvegardé comme dans AddNew ou Edit.
Delete valide la suppression — exécution de l'instruction DELETE. L'enregistrement est marqué comme supprimé dans la source de données et, si l'enregistrement est un instantané, dans ODBC.
Les valeurs de l'enregistrement supprimé se trouvent toujours dans les membres de données de type champ de recordset, mais les membres de données de type champ sont marqués comme Null et la fonction membre du recordset IsDeleted retourne une valeur différente de zéro.
Notes
Après la suppression d'un enregistrement, vous devez accéder par défilement à un autre enregistrement pour remplir à nouveau le tampon d'édition avec les données du nouvel enregistrement. Un nouvel appel de Delete ou l'appel de Edit constitue une erreur.
Pour plus d'informations sur les instructions SQL utilisées dans les opérations de mise à jour, consultez SQL.
Voir aussi
Concepts
Recordset : informations complémentaires sur les mises à jour (ODBC)