Recordset : création et fermeture de recordsets (ODBC)

Cette rubrique s'applique aux classes ODBC MFC.

Pour utiliser un recordset, construisez un objet recordset et appelez sa fonction membre Open pour exécuter la requête du recordset et sélectionner les enregistrements. Lorsque vous avez fini d'utiliser le recordset, fermez l'objet et supprimez-le.

Cette rubrique explique :

• quand et comment créer un objet recordset ;

• quand et comment qualifier le comportement du recordset en le paramétrant, le filtrant, le triant ou le verrouillant ;

• quand et comment fermer un objet recordset.

Création de recordsets à l'exécution

Avant de créer les objets recordset dans votre programme, vous écrivez généralement les classes de recordset propres à l'application. Pour plus d'informations sur cette étape préliminaire, consultez Ajout d'un consommateur ODBC MFC.

Ouvrez un objet feuille de réponse dynamique ou instantané lorsque vous devez sélectionner des enregistrements à partir d'une source de données. Le type d'objet à créer dépend de votre utilisation des données dans l'application et de la prise en charge assurée par le pilote ODBC. Pour plus d'informations, Feuille de réponse dynamique et Instantané.

Pour ouvrir un recordset

1. Construisez l'objet de la classe dérivée de CRecordset.

   Vous pouvez construire l'objet sur le tas ou sur le frame de pile d'une fonction.

2. Modifiez, le cas échéant, le comportement par défaut du recordset. Pour connaître les options disponibles, consultez Définition des options du recordset.

3. Appelez la fonction membre Open de l'objet.

Dans le constructeur, passez un pointeur à un objet de CDatabaseou la valeur NULL pour utiliser un objet temporaire de base de données que l'infrastructure construit et ouvre en fonction de la chaîne de connexion retournée par la fonction membre GetDefaultConnect. L'objet CDatabase peut déjà être connecté à une source de données.

L'appel de Open utilise SQL pour sélectionner les enregistrements de la source de données. Le premier enregistrement sélectionné (s'il en existe) constitue l'enregistrement courant. Les valeurs des champs de cet enregistrement sont stockées dans les membres de données de type champ de l'objet recordset. Si des enregistrements ont été sélectionnés, les deux fonctions membres IsBOF et IsEOF retournent 0.

Dans l'appel de Open, vous pouvez :

• Indiquer si le recordset est une feuille de réponse dynamique ou un instantané. Par défaut, les recordsets sont ouverts en tant qu'instantanés. Vous pouvez aussi définir un recordset en avant seulement (forward-only), si vous voulez faire défiler les enregistrements l'un après l'autre sans revenir en arrière.

  Par défaut, un recordset utilise le type par défaut stocké dans le membre m_nDefaultType du membre de données de CRecordset. Les Assistants écrivent le code nécessaire à l'initialisation du membre m_nDefaultType avec le type de recordset sélectionné dans l'Assistant. Au lieu d'accepter cette valeur par défaut, vous pouvez utiliser un autre type de recordset.

• Définir une chaîne pour remplacer l'instruction SQL par défaut SELECT que le recordset construit.

• Indiquer si le recordset est en lecture seule ou en ajout seul. Les recordsets permettent une mise à jour complète par défaut, mais vous pouvez n'autoriser que l'ajout de nouveaux enregistrements ou interdire toutes les mises à jour.

L'exemple suivant montre comment ouvrir un objet instantané en lecture seule de la classe CStudentSet, laquelle est propre à l'application :

// Construct the snapshot object
CStudentSet rsStudent( NULL );
// Set options if desired, then open the recordset
if(!rsStudent.Open(CRecordset::snapshot, NULL, CRecordset::readOnly))
    return FALSE;
// Use the snapshot to operate on its records...

Après l'appel de Open, utilisez les fonctions membres et les membres de données de l'objet pour manipuler les enregistrements. Dans certains cas, il se peut que vous souhaitiez lancer une nouvelle requête ou actualiser le recordset pour inclure les modifications intervenues sur la source de données. Pour plus d'informations, consultez Recordset : lancement d'une nouvelle requête sur un recordset (ODBC).

Définition des options du recordset

Après avoir construit votre objet recordset et avant d'appeler Open pour sélectionner les enregistrements, il se peut que vous souhaitiez définir certaines options pour contrôler le comportement du recordset. Pour l'ensemble des recordsets, vous pouvez :

• définir un filtre pour limiter le nombre d'enregistrements sélectionnés ;

• définir un ordre de tri pour les enregistrements ;

• définir des paramètres afin de pouvoir sélectionner des enregistrements à l'aide des informations fournies ou calculées lors de l'exécution.

Vous pouvez aussi définir l'option suivante si les conditions sont remplies :

• Si le recordset est modifiable et prend en charge les options de verrouillage, vous pouvez définir la méthode de verrouillage utilisée pour les mises à jour.

Fermeture d'un recordset

Lorsque vous avez fini d'utiliser votre recordset, vous devez le supprimer et désallouer sa mémoire.

Pour fermer un recordset

1. Appelez sa fonction membre Close.

2. Supprimez l'objet recordset.

   Si vous l'avez déclaré sur le frame de pile d'une fonction, l'objet est supprimé automatiquement quand il devient hors de portée. Sinon, utilisez l'opérateur delete.

La fonction Close libère le handle HSTMT du recordset. Elle ne supprime pas l'objet C++.

Voir aussi

Concepts

Recordset (ODBC)

Recordset : défilement (ODBC)

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