Jeu d'enregistrements : paramétrage d'un jeu d'enregistrements (ODBC)

Article
08/21/2008

Mise à jour : novembre 2007

Cette rubrique s'applique aux classes ODBC MFC.

Il peut arriver que vous souhaitiez sélectionner des enregistrements à l'exécution, à l'aide d'informations préalablement calculées ou fournies par l'utilisateur final. Les paramètres de jeu d'enregistrements permettent d'atteindre cet objectif.

Cette rubrique explique :

l'objectif d'un jeu d'enregistrements paramétré ;
quand et pourquoi paramétrer un jeu d'enregistrements ;
comment déclarer des membres de données de type paramètre dans votre classe de jeu d'enregistrements ;
comment passer les informations sur les paramètres à un objet recordset lors de l'exécution.

Jeux d'enregistrements paramétrés

Un jeu d'enregistrements paramétré permet de passer des informations sur les paramètres à l'exécution. Il s'ensuit deux conséquences appréciables :

une exécution en principe plus rapide ;
la possibilité de créer une requête à l'exécution, à partir d'informations non disponibles au moment du design, comme celles qui sont calculées ou fournies par un utilisateur lors de l'exécution.

Quand vous appelez la fonction Open pour exécuter la requête, le jeu d'enregistrements utilise les informations sur les paramètres pour compléter son instruction SQL SELECT. Tout jeu d'enregistrements peut être paramétré.

Quand utiliser les paramètres

Parmi les utilisations de paramètres les plus classiques figurent les utilisations suivantes :

Passage, lors de l'exécution, d'arguments à une requête prédéfinie.

Pour passer des paramètres à une procédure stockée, vous devez définir une instruction CALL ODBC personnalisée complète (avec des emplacements réservés de paramètres) lorsque vous appelez la fonction Open, substituant ainsi l'instruction SQL par défaut du jeu d'enregistrements. Pour plus d'informations, consultez CRecordset::Open dans Class Library Reference ainsi que SQL : personnalisation de l'instruction SQL du jeu d'enregistrements (ODBC) et Jeu d'enregistrements : déclaration de la classe d'une requête prédéfinie (ODBC).

Exécution efficace de nombreuses requêtes comportant différentes informations sur les paramètres.

Par exemple, chaque fois que l'utilisateur final recherche des informations sur un étudiant dans la base de données des étudiants inscrits; vous pouvez définir le nom de l'étudiant ou son ID comme étant des paramètres fournis par l'utilisateur. Ensuite, quand vous appelez la fonction membre Requery du jeu d'enregistrements, la requête ne sélectionne que l'enregistrement concernant cet étudiant.

La chaîne de filtre du jeu d'enregistrements, stockée dans m_strFilter, a la forme suivante :

"StudentID = ?"

Imaginons que l'ID de l'étudiant soit placé dans la variable strInputID. Lorsque vous définissez un paramètre pour strInputID (par exemple, l'ID étudiant 100) la valeur de la variable est associée à l'emplacement de paramètre réservé, représenté par le « ? » dans la chaîne de filtre.

Assignez la valeur du paramètre de la façon suivante :

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

Vous ne pourriez pas définir une chaîne de filtre de la façon suivante :

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

Pour plus d'informations sur l'utilisation appropriée des guillemets dans les chaînes de filtre, consultez Jeu d'enregistrements : filtrage d'enregistrements (ODBC).

La valeur du paramètre diffère à chaque fois que vous lancez une nouvelle requête sur le jeu d'enregistrements avec un nouvel ID étudiant.

Conseil :
L'utilisation d'un paramètre est plus efficace que la seule utilisation d'un filtre. Dans le cas d'un jeu d'enregistrements paramétré, la base de données ne doit traiter qu'une seule fois une instruction SQL SELECT. Dans le cas d'un jeu d'enregistrements filtré, l'instruction SELECT doit être exécutée chaque fois que vous lancez une nouvelle requête (Requery) avec une nouvelle valeur de filtre.

L'utilisation d'un paramètre est plus efficace que la seule utilisation d'un filtre. Dans le cas d'un jeu d'enregistrements paramétré, la base de données ne doit traiter qu'une seule fois une instruction SQL SELECT. Dans le cas d'un jeu d'enregistrements filtré, l'instruction SELECT doit être exécutée chaque fois que vous lancez une nouvelle requête (Requery) avec une nouvelle valeur de filtre.

Pour plus d'informations sur les filtres, consultez Jeu d'enregistrements : filtrage d'enregistrements (ODBC).

Paramétrage de la classe de jeu d'enregistrements

Remarque :
Cette section 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, l'implémentation de paramètres obéit à un processus similaire. Pour plus d'informations, consultez Jeu d'enregistrements : extraction globale d'enregistrements (ODBC).

Avant de créer la classe de jeu d'enregistrements, déterminez les paramètres dont vous avez besoin, leurs types de données et comment le jeu d'enregistrements les utilise.

Pour paramétrer une classe de jeu d'enregistrements

Exécutez l'Assistant Consommateur ODBC MFC à partir de l'Assistant Ajouter une classe pour créer la classe.
Indiquez les membres de données de type champ des colonnes du jeu d'enregistrements.
Une fois que l'Assistant a écrit la classe dans un fichier du projet, accédez au fichier .h et ajoutez manuellement un ou plusieurs membres de données de type paramètre à la déclaration de classe. Cet ajout est similaire à celui de l'exemple suivant, relatif à une classe instantanée conçue pour répondre à la question « Which students are in the senior class? » (« Quels étudiants font partie de la classe senior ? »).
```
class CStudentSet : public CRecordset
{
// Field/Param Data
    CString m_strFirstName;
    CString m_strLastName;
    CString m_strStudentID;
    CString m_strGradYear;

    CString m_strGradYrParam;
};
```
Ajoutez les membres de données de type paramètre après les membres de données de type champ générés par l'Assistant. Par convention, le mot « Param » est ajouté à chaque nom de paramètre défini par l'utilisateur.
Modifiez la définition de la fonction membre DoFieldExchange dans le fichier .cpp. Ajoutez un appel de fonctions RFX pour chaque membre de données de type paramètre ajouté à la classe. Pour plus d'informations sur l'écriture de fonctions RFX, consultez Record Field Exchange : fonctionnement de RFX. Faites précéder les appels RFX des paramètres par un appel unique à :
```
pFX->SetFieldType( CFieldExchange::param );
// RFX calls for parameter data members
```
Dans le constructeur de la classe de jeu d'enregistrements, incrémentez le compteur de paramètres, m_nParams.

Pour des informations, consultez Record Field Exchange : utilisation du code écrit par l'Assistant.
Lorsque vous écrivez le code créant l'objet recordset de la classe, placez un « ? » (point d'interrogation) à chaque endroit de l'instruction SQL où un paramètre doit être remplacé par une valeur.

Lors de l'exécution; les emplacements réservés sont remplacés dans l'ordre par les valeurs que vous passez. Le premier membre de données de type paramètre défini après l'appel de SetFieldType remplace le premier « ? » de la chaîne SQL, le deuxième membre de données de type paramètre remplace le deuxième « ? », et ainsi de suite.

Remarque :
L'ordre des paramètres est important : l'ordre des appels RFX des paramètres dans la fonction DoFieldExchange doit être identique à celui des emplacements de paramètres réservés dans la chaîne SQL.

Conseil :
Il est probable que la chaîne utilisée soit celle que vous avez définie, le cas échéant, pour le membre de données m_strFilter de la classe, mais certains pilotes ODBC autorisent des paramètres dans d'autres clauses SQL.

Passage des valeurs des paramètres à l'exécution

Vous devez définir les valeurs des paramètres avant d'appeler les fonctions Open (dans le cas d'un nouvel objet recordset) ou Requery (dans le cas d'un objet recordset existant).

Pour passer les valeurs des paramètres à un objet recordset à l'exécution

Construisez l'objet recordset.
Préparez une ou plusieurs chaînes, comme m_strFilter, contenant la totalité ou une partie de l'instruction SQL. Placez les emplacements réservés « ? » à l'endroit où les informations des paramètres doivent prendre place.
Assignez la valeur du paramètre fournie lors de l'exécution à chaque membre de données de type paramètre de l'objet.
Appelez la fonction membre Open (ou Requery pour un jeu d'enregistrements existant).

Imaginons, par exemple, que vous vouliez définir une chaîne de filtre pour le jeu d'enregistrements en utilisant les informations fournies lors de l'exécution. Considérons que vous avez construit préalablement un jeu d'enregistrements de la classe CStudentSet — appelé rsStudents — et que vous voulez maintenant lancer une nouvelle requête pour obtenir un type particulier d'informations sur les étudiants.

// 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 jeu d'enregistrements contient les enregistrements obéissant aux conditions définies par le filtre, construit à partir des paramètres fournis à l'exécution. Dans le cas présent, le jeu d'enregistrements contient les enregistrements de tous les « senior students » (étudiants seniors).

Remarque :
Si nécessaire, vous pouvez définir un membre de données de type paramètre avec la valeur Null, à l'aide de SetParamNull. Vous pouvez de même vérifier si un membre de données de type paramètre a la valeur Null, à l'aide de IsFieldNull.

Voir aussi

Concepts

Jeu d'enregistrements (ODBC)

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

Jeu d'enregistrements : sélection d'enregistrements par les jeux d'enregistrements (ODBC)

Partager via