Recordset : paramétrage d'un recordset (ODBC)

Cette rubrique s’applique aux classes ODBC MFC.

Vous souhaiterez peut-être parfois pouvoir sélectionner des enregistrements au moment de l’exécution, en utilisant les informations que vous avez calculées ou fournies par votre utilisateur final. Les paramètres de recordset vous permettent d’atteindre cet objectif.

Cette rubrique explique :

• L’objectif d’un recordset paramétré.

• Quand et pourquoi vous pouvez souhaiter paramétrer un recordset.

• Comment déclarer des membres de données de paramètre dans votre classe de recordset.

• Comment passer des informations sur les paramètres à un objet recordset au moment de l’exécution.

Jeux d’enregistrements paramétrés

Un recordset paramétré vous permet de passer des informations sur les paramètres au moment de l’exécution. Cette fonctionnalité a deux effets utiles :

• Cela peut entraîner une meilleure vitesse d’exécution.

• Cela vous permet de générer une requête au moment de l’exécution en fonction des informations qui ne sont pas à votre disposition au moment du design, comme les informations fournies par votre utilisateur ou calculées au moment de l’exécution.

Quand vous appelez Open pour exécuter la requête, le recordset utilise les informations sur les paramètres pour compléter son instruction SQL SELECT. Vous pouvez paramétrer n’importe quel recordset.

Quand utiliser des paramètres

Les utilisations courantes de paramètres sont notamment les suivantes :

• Passage d’arguments d’exécution à une requête prédéfinie.

  Pour passer des paramètres à une procédure stockée, vous devez spécifier une instruction CALL ODBC personnalisée complète (avec des espaces réservés de paramètres) quand vous appelez Open, en remplaçant l’instruction SQL par défaut du recordset. Pour plus d’informations, consultez CRecordset ::Open in the Class Library Reference and SQL : Personalizeing Your Recordset’s SQL Statement (ODBC) and Recordset : De declare a Class for a Predefined Query (ODBC).

• Exécution efficace de nombreuses nouvelles interrogations avec des informations sur les paramètres différentes.

  Par exemple, chaque fois que votre utilisateur final recherche des informations sur un élève particulier dans la base de données d’inscription des élèves, vous pouvez spécifier le nom ou l’ID de l’élève comme paramètre fourni par l’utilisateur. Ensuite, quand vous appelez la fonction membre Requery de votre recordset, la requête sélectionne uniquement l’enregistrement de cet élève.

  La chaîne de filtre de votre recordset, stockée dans m_strFilter, pourrait se présenter comme suit :

  "StudentID = ?"
  

  Supposons que vous obtenez l’ID d’élève dans la variable strInputID. Quand vous définissez un paramètre sur strInputID (par exemple, l’ID d’élève 100), la valeur de la variable est liée à l’espace réservé de paramètre représenté par le « ? » dans la chaîne de filtre.

  Affectez la valeur du paramètre comme suit :

  strInputID = "100";
  ...
  m_strParam = strInputID;
  

  Vous ne voulez pas configurer une chaîne de filtre de la manière suivante :

  m_strFilter = "StudentID = 100";   // 100 is incorrectly quoted
                                     // for some drivers
  

  Pour une discussion sur l’utilisation correcte des guillemets pour les chaînes de filtre, consultez Recordset : Filtrage d’enregistrements (ODBC).

  La valeur du paramètre est différente chaque fois que vous réinterrogez le recordset pour un nouvel ID d’élève.

  Conseil

  L’utilisation d’un paramètre est plus efficace que simplement un filtre. Pour un recordset paramétré, la base de données doit traiter une seule fois une instruction SQL SELECT. Pour un recordset filtré sans paramètres, l’instruction SELECT doit être traitée chaque fois que vous effectuez une nouvelle interrogation (Requery) avec une nouvelle valeur de filtre.

Pour plus d’informations sur les filtres, consultez Recordset : Filtering Records (ODBC).

Paramétrage de votre classe Recordset

Avant de créer votre classe de recordset, déterminez les paramètres dont vous avez besoin, leurs types de données et la façon dont le recordset les utilise.

Pour paramétrer une classe de recordset

1. Exécutez l’Assistant Consommateur ODBC MFC à partir de l’option Ajouter une classe pour créer la classe.

2. Spécifiez des membres de données de champ pour les colonnes du recordset.

3. Une fois que l’Assistant a écrit la classe dans un fichier de votre projet, accédez au fichier .h et ajoutez manuellement un ou plusieurs membres de données de paramètre à la déclaration de classe. Cet ajout pourrait ressembler à l’exemple suivant, représentant une partie d’un instantané de la classe conçue pour répondre à la requête « Quels élèves sont en terminale ? ».

   class CStudentSet : public CRecordset
   {
   // Field/Param Data
       CString m_strFirstName;
       CString m_strLastName;
       CString m_strStudentID;
       CString m_strGradYear;
   
       CString m_strGradYrParam;
   };
   

   Ajoutez vos membres de données de paramètre après les membres de données de champ générés par l’Assistant. La convention est d’ajouter le mot « Param » à chaque nom de paramètre défini par l’utilisateur.

4. Modifiez la définition de fonction membre DoFieldExchange dans le fichier .cpp. Ajoutez un appel de fonction RFX pour chaque membre de données de paramètre que vous avez ajouté à la classe. Pour plus d’informations sur l’écriture de vos fonctions RFX, consultez Record Field Exchange : How RFX Works. Faites précéder les appels de fonction RFX pour les paramètres d’un appel unique à :

   pFX->SetFieldType( CFieldExchange::param );
   // RFX calls for parameter data members
   

5. Dans le constructeur de votre classe de recordset, incrémentez le nombre de paramètres, m_nParams.

   Pour plus d’informations, consultez Record Field Exchange : Utilisation du code de l’Assistant.

6. Quand vous écrivez le code qui crée un objet de recordset de cette classe, placez un symbole « ? » (point d’interrogation) à chaque endroit de l’instruction SQL où un paramètre doit être remplacé.

   Au moment de l’exécution, les espaces réservés « ? » sont remplis, dans l’ordre, par les valeurs de paramètre que vous passez. Le premier membre de données de paramètre défini après l’appel à SetFieldType remplace le premier « ? » dans la chaîne SQL, le deuxième membre de données de paramètre remplace le deuxième « ? », etc.

Passage de valeurs de paramètre au moment de l’exécution

Vous devez spécifier des valeurs de paramètre avant d’appeler Open (pour un nouvel objet recordset) ou Requery (pour un objet recordset existant).

Pour passer des valeurs de paramètre à un objet recordset au moment de l’exécution

1. Construisez l’objet recordset.

2. Préparez une ou plusieurs chaînes, comme la chaîne m_strFilter, contenant l’instruction SQL ou des parties de celle-ci. Mettez des espaces réservés « ? » aux endroits où les informations sur les paramètres doivent être placées.

3. Affectez une valeur de paramètre d’exécution à chaque membre de données de paramètre de l’objet.

4. Appelez la fonction membre Open (ou Requery pour un recordset existant).

Par exemple, supposons que vous voulez spécifier une chaîne de filtre pour votre recordset en utilisant des informations obtenues au moment de l’exécution. Partons du principe que vous avez précédemment construit un recordset de la classe CStudentSet, appelé rsStudents, et que vous voulez maintenant le réinterroger pour un type particulier d’informations sur les élèves.

// Set up a filter string with
// parameter placeholders
rsStudents.m_strFilter = "GradYear <= ?";

// Obtain or calculate parameter values
// to pass--simply assigned here
CString strGradYear = GetCurrentAcademicYear( );

// Assign the values to parameter data members
rsStudents.m_strGradYrParam = strGradYear;

// Run the query
if( !rsStudents.Requery( ) )
    return FALSE;

Le recordset contient les enregistrements des élèves dont les enregistrements remplissent les conditions spécifiées par le filtre, lequel a été construit à partir de paramètres d’exécution. Dans le cas présent, le recordset contient les enregistrements de tous les élèves en classe de terminale.

Voir aussi

Recordset (ODBC)
Recordset : ajout, modification et suppression d’enregistrements (ODBC)
Recordset : sélection d’enregistrements par les recordsets (ODBC)