Jeu d'enregistrements : ajout, modification et suppression d'enregistrements (ODBC)

Mise à jour : novembre 2007

Cette rubrique s'applique aux classes ODBC MFC.

Remarque :
Vous pouvez désormais ajouter des enregistrements en bloc de façon plus efficace. Pour plus d'informations, consultez Jeu d'enregistrements : ajout global d'enregistrements (ODBC).

Remarque :
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 Jeu d'enregistrements : extraction globale d'enregistrements (ODBC).

Les instantanés et les feuilles de réponse dynamiques permettent d'ajouter, de modifier ou de supprimer des enregistrements. Cette rubrique explique :

• comment déterminer si un jeu d'enregistrements est modifiable ;

• comment ajouter un nouvel enregistrement ;

• comment modifier un enregistrement ;

• comment supprimer un enregistrement.

Pour plus d'informations sur la façon dont les modifications sont effectuées et sur la façon dont elles apparaissent aux autres utilisateurs, consultez Jeu d'enregistrements : modification des enregistrements par les jeux d'enregistrements (ODBC). En principe, lorsque vous ajoutez, modifiez ou supprimez un enregistrement, le jeu d'enregistrements modifie aussitôt la source de données. Vous pouvez à la place traiter en lot, sous forme de transactions, les mises à jour associées. Si une transaction est en cours, la modification ne devient effective que lorsque la transaction a été validée. Cela permet de reprendre ou d'annuler les modifications effectuées. Pour plus d'informations sur les transactions, consultez Transaction (ODBC).

Le tableau suivant résume les options disponibles pour les jeux d'enregistrements, accompagnées des différentes caractéristiques de mise à jour.

Options lecture/modification d'un jeu d'enregistrements

Détermination du caractère modifiable du jeu d'enregistrements

Un objet recordset est modifiable si la source de données l'est et que le jeu d'enregistrements a été ouvert comme étant modifiable. Son caractère modifiable dépend également de l'instruction SQL que vous utilisez, des capacités du pilote ODBC et de l'éventuel chargement en mémoire de la bibliothèque de curseurs ODBC. Il est impossible de modifier une source de données ou un jeu d'enregistrements en lecture seule.

Pour déterminer si le jeu d'enregistrements est modifiable

• Appelez la fonction membre CanUpdate de l'objet recordset.

  CanUpdate retourne une valeur différente de zéro si le jeu d'enregistrements est modifiable.

Par défaut, les jeux d'enregistrements sont entièrement modifiables (vous pouvez effectuer les opérations AddNew, Edit et Delete). Mais vous pouvez également utiliser l'option appendOnly pour ouvrir des jeux d'enregistrements modifiables. Un jeu d'enregistrements ouvert de cette façon ne permet que l'ajout de nouveaux enregistrements à l'aide de AddNew. Il n'est pas possible de modifier ou de supprimer des enregistrements existants. Vous pouvez tester si un jeu d'enregistrements est ouvert uniquement pour permettre l'ajout en appelant la fonction membre CanAppend. CanAppend retourne une valeur différente de zéro si le jeu d'enregistrements est entièrement modifiable ou ouvert uniquement pour permettre l'ajout.

Le code suivant illustre comment vous pouvez utiliser CanUpdate pour un objet recordset appelé rsStudentSet :

if( !rsStudentSet.Open( ) )
    return FALSE;
if( !rsStudentSet.CanUpdate( ) )
{
    AfxMessageBox( "Unable to update the Student recordset." );
    return;
}

Attention :

Lorsque vous vous préparez à modifier un jeu d'enregistrements en appelant Update, prenez soin que le jeu d'enregistrements comporte toutes les colonnes composant la clé primaire de la table (ou toutes les colonnes d'un index unique de la table). Dans certains cas, l'infrastructure ne peut utiliser que les colonnes sélectionnées dans le jeu d'enregistrements pour identifier l'enregistrement de la table à modifier. Sans toutes les colonnes nécessaires, plusieurs enregistrements risquent d'être modifiés dans la table et l'intégrité référentielle de celle-ci peut s'en trouver altérée. Dans ce cas, l'infrastructure lève une exception quand vous appelez Update.

Ajout d'un enregistrement à un jeu d'enregistrements

Vous pouvez ajouter de nouveaux enregistrements à un jeu d'enregistrements si sa fonction membre CanAppend retourne une valeur différente de zéro.

Pour ajouter un nouvel enregistrement à un jeu d'enregistrements

1. Assurez-vous que des enregistrements peuvent être ajoutés au jeu d'enregistrements.

2. Appelez la fonction membre AddNew de l'objet recordset.

   AddNew prépare le jeu d'enregistrements de telle sorte qu'il fasse office de tampon d'édition. Tous les membres de données de type champ sont définis avec la valeur particulière Null et marqués comme non modifiés, de sorte que seules les valeurs modifiées (« dirty ») sont écrites dans la source de données lorsque vous appelez Update.

3. Définissez les valeurs des membres de données de type champ du nouvel enregistrement.

   Assignez des valeurs aux membres de données de type champ. Ceux auxquels ne sont pas assignées de valeurs ne sont pas écrits dans la source de données.

4. Appelez la fonction membre Update de l'objet recordset.

   Update termine l'ajout en écrivant le nouvel enregistrement dans la source de données. Pour plus d'informations sur ce qui se passe en cas d'échec de l'appel de la fonction Update, consultez Jeu d'enregistrements : modification des enregistrements par les jeux d'enregistrements (ODBC).

Pour plus d'informations sur le fonctionnement de l'ajout d'enregistrements et sur la disponibilité des enregistrements ajoutés dans le jeu d'enregistrements, consultez Jeu d'enregistrements : fonctionnement d'AddNew, Edit et Delete (ODBC).

L'exemple suivant illustre l'ajout d'un nouvel enregistrement :

if( !rsStudent.Open( ) )
    return FALSE;
if( !rsStudent.CanAppend( ) )
    return FALSE;                      // no field values were set
rsStudent.AddNew( );
rsStudent.m_strName = strName;
rsStudent.m_strCity = strCity;
rsStudent.m_strStreet = strStreet;
if( !rsStudent.Update( ) )
{
    AfxMessageBox( "Record not added; no field values were set." );
    return FALSE;
}

Conseil :
Pour annuler un appel de AddNew ou Edit, effectuez simplement un nouvel appel de AddNew ou Edit ou appelez Move avec le paramètre AFX_MOVE_REFRESH. Les membres de données sont réinitialisés à leurs valeurs précédentes et vous demeurez en mode Edit ou Add.

Modification d'un enregistrement dans un jeu d'enregistrements

Vous pouvez modifier des enregistrements existants si la fonction membre CanUpdate de votre jeu d'enregistrements retourne une valeur différente de zéro.

Pour modifier un enregistrement existant dans un jeu d'enregistrements

1. Assurez-vous que le jeu d'enregistrements est modifiable.

2. Accédez à l'enregistrement à mettre à jour.

3. Appelez la fonction membre Edit de l'objet recordset.

   Edit prépare le jeu d'enregistrements de telle sorte qu'il fasse office de tampon d'édition. Tous les membres de données de type champ sont marqués de sorte que le jeu d'enregistrements peut savoir, par la suite, s'ils ont été modifiés. Les nouvelles valeurs des membres de données de type champ modifiés sont écrites dans la source de données quand vous appelez Update.

4. Définissez les valeurs des membres de données de type champ du nouvel enregistrement.

   Assignez des valeurs aux membres de données de type champ. Les membres auxquels ne sont pas assignées de valeurs demeurent inchangés.

5. Appelez la fonction membre Update de l'objet recordset.

   Update termine la modification en écrivant l'enregistrement modifié dans la source de données. Pour plus d'informations sur ce qui se passe en cas d'échec de l'appel de la fonction Update, consultez Jeu d'enregistrements : modification des enregistrements par les jeux d'enregistrements (ODBC).

Après que vous avez modifié un enregistrement, celui-ci demeure l'enregistrement courant.

L'exemple suivant montre une opération Edit. L'exemple présume que l'utilisateur a atteint l'enregistrement qu'il souhaite modifier.

rsStudent.Edit( );
rsStudent.m_strStreet = strNewStreet;
rsStudent.m_strCity = strNewCity;
rsStudent.m_strState = strNewState;
rsStudent.m_strPostalCode = strNewPostalCode;
if( !rsStudent.Update( ) )
{
    AfxMessageBox( "Record not updated; no field values were set." );
    return FALSE;
}

Conseil :
Pour annuler un appel de AddNew ou Edit, effectuez simplement un nouvel appel de AddNew ou Edit ou appelez Move avec le paramètre AFX_MOVE_REFRESH. Les membres de données sont réinitialisés à leurs valeurs précédentes et vous demeurez en mode Edit ou Add.

Suppression d'un enregistrement du jeu d'enregistrements

Vous pouvez supprimer des enregistrements si la fonction membre CanUpdate de votre jeu d'enregistrements retourne une valeur différente de zéro.

Pour supprimer un enregistrement

1. Assurez-vous que le jeu d'enregistrements est modifiable.

2. Accédez à l'enregistrement à mettre à jour.

3. Appelez la fonction membre Delete de l'objet recordset.

   Delete marque immédiatement l'enregistrement comme supprimé, à la fois dans le jeu d'enregistrements et dans la source de données.

   Contrairement à AddNew et Edit, Delete n'appelle pas la fonction Update.

4. Accédez par défilement à un autre enregistrement.

   Remarque :
   Lorsque vous vous déplacez dans un jeu d'enregistrements, les enregistrements supprimés ne peuvent pas être ignorés. Pour plus d'informations, consultez la fonction membre IsDeleted.

L'exemple suivant montre une opération Delete. L'exemple présume que l'utilisateur a atteint l'enregistrement qu'il souhaite supprimer. Après l'appel de Delete, il est important de se déplacer jusqu'à un nouvel enregistrement.

rsStudent.Delete( );
rsStudent.MoveNext( );

Pour plus d'informations sur les conséquences des fonctions membres AddNew, Edit et Delete, consultez Jeu d'enregistrements : modification des enregistrements par les jeux d'enregistrements (ODBC).

Voir aussi

Concepts

Jeu d'enregistrements (ODBC)

Jeu d'enregistrements : verrouillage d'enregistrements (ODBC)