Recordset : fonctionnement d'AddNew, Edit et Delete (ODBC)

Cette rubrique s’applique aux classes ODBC MFC.

Cette rubrique explique le fonctionnement des fonctions membres AddNew, Edit et Delete de la classe CRecordset. Sont abordés les sujets suivants :

• Fonctionnement de l’ajout d’enregistrements

• Visibilité des enregistrements ajoutés

• Comment fonctionne la modification des enregistrements

• Fonctionnement de la suppression d’enregistrements

En guise de supplément, vous pouvez lire l’échange de champs d’enregistrement : 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 jeu d’enregistrements implique l’appel de la fonction membre AddNew du jeu d’enregistrements, la définition des valeurs des membres de données de champ du nouvel enregistrement et l’appel de la fonction membre Update pour écrire l’enregistrement dans la source de données.

En tant que condition préalable à l’appel AddNew, le jeu d’enregistrements ne doit pas avoir été ouvert en lecture seule. Les fonctions membres CanUpdate et CanAppend vous permettent de déterminer ces conditions.

Quand vous appelez AddNew:

• L’enregistrement dans la mémoire tampon d’édition est stocké, de sorte que son contenu peut être restauré si l’opération est annulée.

• Les membres de données de champ sont marqués de manière à pouvoir détecter les modifications apportées ultérieurement. Les membres de données de champ sont également marqués comme propres (inchangés) et définis sur une valeur Null.

Une fois que vous avez appelé AddNew, la mémoire tampon d’édition représente un nouvel enregistrement vide, prêt à être rempli avec des valeurs. Pour ce faire, vous définissez manuellement les valeurs en les affectant. Au lieu de spécifier une valeur de données réelle pour un champ, vous pouvez appeler SetFieldNull pour spécifier la valeur Null.

Pour valider vos modifications, vous appelez Update. Lorsque vous appelez Update pour le nouvel enregistrement :

• Si votre pilote ODBC prend en charge la ::SQLSetPos fonction API ODBC, MFC utilise la fonction pour ajouter l’enregistrement sur la source de données. Avec ::SQLSetPos, MFC peut ajouter un enregistrement plus efficacement, car il n’est pas obligé de construire et de traiter une instruction SQL.

• Si ::SQLSetPos ne peut pas être utilisé, MFC effectue les opérations suivantes :

  1. Si aucune modification n’est détectée, Update ne fait rien et retourne 0.

  2. S’il existe des modifications, Update construit une instruction SQL INSERT . Les colonnes représentées par tous les membres de données de champ sales sont répertoriées dans l’instruction INSERT . Pour forcer l’inclusion d’une colonne, appelez la fonction membre SetFieldDirty :

     SetFieldDirty( &m_dataMember, TRUE );
     

  3. Update valide le nouvel enregistrement : l’instruction INSERT est exécutée et l’enregistrement est validé dans la table sur la source de données (et le jeu d’enregistrements, si ce n’est pas un instantané), sauf si une transaction est en cours.

  4. L’enregistrement stocké est restauré dans la mémoire tampon d’édition. L’enregistrement qui était actuel avant l'appel AddNew redevient actuel, indépendamment du fait que l'instruction INSERT ait été exécutée avec succès.

  Conseil

  Pour contrôler complètement un nouvel enregistrement, suivez l’approche suivante : définissez les valeurs de tous les champs qui auront des valeurs, puis définissez explicitement tous les champs qui resteront Null en appelant SetFieldNull avec un pointeur vers le champ et le paramètre TRUE (valeur par défaut). Si vous souhaitez vous assurer qu’un champ n’est pas écrit dans la source de données, appelez SetFieldDirty avec un pointeur vers le champ et le paramètre FALSE et ne modifiez pas la valeur du champ. Pour déterminer si un champ est autorisé à être Null, appelez IsFieldNullable.

  Conseil

  Pour détecter quand les membres de données recordset changent de valeur, MFC utilise une valeur PSEUDO_NULL appropriée à chaque type de données que vous pouvez stocker dans un recordset. Si vous devez définir explicitement un champ sur la valeur PSEUDO_NULL et que le champ se trouve déjà marqué Null, vous devez également appeler SetFieldNull, en passant l'adresse du champ dans le premier paramètre et FALSE dans le deuxième paramètre.

Visibilité des enregistrements ajoutés

Quand un enregistrement ajouté est-il visible dans votre jeu d’enregistrements ? Les enregistrements ajoutés s’affichent parfois et parfois ne sont pas visibles, en fonction de deux éléments :

• Ce que votre pilote est capable de.

• Ce que le framework peut tirer parti de.

Si votre pilote ODBC prend en charge la ::SQLSetPos fonction API ODBC, MFC utilise la fonction pour ajouter des enregistrements. Avec ::SQLSetPos, les enregistrements ajoutés sont visibles par n’importe quel jeu d’enregistrements MFC pouvant être mis à jour. Sans prise en charge de la fonction, les enregistrements ajoutés ne sont pas visibles et vous devez appeler Requery pour les afficher. L’utilisation ::SQLSetPos est également plus efficace.

Modification d’un enregistrement existant

La modification d'un enregistrement existant dans un jeu d’enregistrements implique de faire défiler jusqu'à l'enregistrement, d’appeler la fonction membre Edit du jeu d’enregistrements, en définissant les valeurs des membres de données de champ du nouvel enregistrement et d'appeler la fonction membre Update pour écrire l’enregistrement modifié dans la source de données.

En tant que condition préalable à l’appel Edit, le jeu d’enregistrements doit être modifiable et positionné sur un enregistrement. Les fonctions membres CanUpdate et IsDeleted vous permettent de déterminer ces conditions. L’enregistrement actif ne doit pas non plus avoir déjà été supprimé, et il doit y avoir des enregistrements dans le jeu d’enregistrements (à la fois IsBOF et IsEOF retourner 0).

Lorsque vous appelez Edit, l’enregistrement dans la mémoire tampon d’édition (l’enregistrement actif) est stocké. Les valeurs de l’enregistrement stocké sont utilisées ultérieurement pour détecter si des champs ont changé.

Après l’appel Edit, la mémoire tampon d’édition représente toujours l’enregistrement actif, mais est maintenant prête à accepter les modifications apportées aux membres de données de champ. Pour modifier l’enregistrement, vous définissez manuellement les valeurs des membres de données de champ que vous souhaitez modifier. Au lieu de spécifier une valeur de données réelle pour un champ, vous pouvez appeler SetFieldNull pour spécifier la valeur Null. Pour valider vos modifications, appelez Update.

En tant que condition préalable à l’appel Update, le jeu d’enregistrements ne doit pas être vide et l’enregistrement actif n’a pas été supprimé. IsBOF, IsEOFet IsDeleted doit tous retourner 0.

Lorsque vous appelez l’enregistrement modifié Update :

• Si votre pilote ODBC prend en charge la ::SQLSetPos fonction API ODBC, MFC utilise la fonction pour mettre à jour l’enregistrement sur la source de données. Avec ::SQLSetPos, le pilote compare votre mémoire tampon d’édition avec l’enregistrement correspondant sur le serveur, en mettant à jour l’enregistrement sur le serveur si les deux sont différents. Avec ::SQLSetPos, MFC peut mettre à jour un enregistrement plus efficacement, car il n’est pas obligé de construire et de traiter une instruction SQL.

  - ou -

• Si ::SQLSetPos ne peut pas être utilisé, MFC effectue les opérations suivantes :

  1. Si aucune modification n’a été apportée, Update ne fait rien et retourne 0.

  2. S’il existe des modifications, Update construit une instruction SQL UPDATE . Les colonnes répertoriées dans l’instruction UPDATE sont basées sur les membres de données de champ qui ont changé.

  3. Update valide les modifications ( exécute l’instruction UPDATE ) et l’enregistrement est modifié sur la source de données, mais n’est pas validé si une transaction est en cours (voir 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.

  4. Contrairement au processus pour AddNew, le Edit processus ne restaure pas l’enregistrement stocké. L'enregistrement modifié reste en place en tant qu'enregistrement actuel.

  Attention

  Lorsque vous préparez à mettre à jour un recordset en appelant Update, veillez à ce que votre jeu d’enregistrements inclut toutes les colonnes qui composent la clé primaire de la table (ou toutes les colonnes d’un index unique sur la table, ou suffisamment de colonnes pour identifier la ligne de manière unique). Dans certains cas, l’infrastructure peut utiliser uniquement les colonnes sélectionnées dans votre jeu d’enregistrements pour identifier l’enregistrement dans votre table à mettre à jour. Sans toutes les colonnes nécessaires, plusieurs enregistrements peuvent être mis à jour dans la table. Dans ce cas, le cadre lève des exceptions lorsque vous appelez Update.

  Conseil

  Si vous appelez AddNew ou Edit après avoir précédemment appelé l'une des deux fonctions, mais avant d'appeler Update, la mémoire tampon de modification est actualisée avec l'enregistrement stocké, remplaçant l'enregistrement nouveau ou en cours de modification. Ce comportement vous permet d’abandonner un AddNew ou un Edit et de commencer un nouveau : si vous déterminez que l’enregistrement en cours est erroné, appelez simplement Edit ou AddNew à nouveau.

Suppression d’un enregistrement

La suppression d’un enregistrement d’un jeu d’enregistrements implique le défilement vers l’enregistrement et l’appel de la fonction membre Delete du jeu d’enregistrements. Contrairement à AddNew et Edit, Delete ne nécessite pas d’appel correspondant à Update.

En tant que condition préalable à l’appel Delete, le jeu d’enregistrements doit être mis à jour et doit être sur un enregistrement. Les fonctions membres CanUpdate, IsBOF, IsEOF et IsDeleted vous permettent de déterminer ces conditions.

Quand vous appelez Delete:

• Si votre pilote ODBC prend en charge la ::SQLSetPos fonction API ODBC, MFC utilise la fonction pour supprimer l’enregistrement sur la source de données. L’utilisation ::SQLSetPos est généralement plus efficace que l’utilisation de SQL.

  - ou -

• Si ::SQLSetPos ne peut pas être utilisé, MFC effectue les opérations suivantes :

  1. L’enregistrement actif dans la mémoire tampon d’édition n’est pas sauvegardé comme dans AddNew et Edit.

  2. Delete construit une instruction SQL DELETE qui supprime l’enregistrement.

     L’enregistrement actif dans la mémoire tampon d’édition n’est pas stocké comme dans AddNew et Edit.

  3. Delete valide la suppression : exécute l’instruction DELETE . L’enregistrement est marqué supprimé sur la source de données et, si l’enregistrement est un instantané, dans ODBC.

  4. Les valeurs de l’enregistrement supprimé se trouvent toujours dans les champs du jeu d’enregistrements, mais les champs sont marqués Null et la fonction membre du IsDeleted jeu d’enregistrements retourne une valeur non nulle.

  Remarque

  Après avoir supprimé un enregistrement, vous devez faire défiler vers un autre enregistrement pour remplir la mémoire tampon d’édition avec les données du nouvel enregistrement. Il est erroné de rappeler Delete ou d'appeler Edit.

Pour plus d’informations sur les instructions SQL utilisées dans les opérations de mise à jour, consultez SQL.

Voir aussi

Recordset (ODBC)
Recordset : informations complémentaires sur les mises à jour (ODBC)
Record Field Exchange (RFX)