Recordset : extraction globale d'enregistrements (ODBC)
Cette rubrique s’applique aux classes ODBC MFC.
La classe CRecordset prend en charge l’extraction de lignes en bloc, ce qui signifie que plusieurs enregistrements peuvent être récupérés simultanément lors d’une extraction unique, plutôt que de récupérer un enregistrement à la fois à partir de la source de données. Vous pouvez implémenter l’extraction de lignes en bloc uniquement dans une classe dérivée CRecordset . Le processus de transfert de données de la source de données vers l’objet recordset est appelé échange de champs d’enregistrement en bloc (RFX en bloc). Notez que si vous n’utilisez pas la récupération de lignes en bloc dans une CRecordsetclasse dérivée, les données sont transférées via l’échange de champs d’enregistrement (RFX). Pour plus d’informations, consultez Record Field Exchange (RFX).
Cette rubrique explique :
Comment CRecordset prend en charge l’extraction de lignes en bloc.
Quelques considérations spéciales lors de l’utilisation de la récupération de lignes en bloc.
Comment implémenter l’échange de champs d’enregistrement en bloc.
Comment CRecordset prend en charge l’extraction de lignes en bloc
Avant d’ouvrir votre objet recordset, vous pouvez définir une taille d’ensemble de lignes avec la SetRowsetSize fonction membre. La taille de l’ensemble de lignes spécifie le nombre d’enregistrements à récupérer lors d’une extraction unique. Lorsque l’extraction de lignes en bloc est implémentée, la taille d’ensemble de lignes par défaut est 25. Si l’extraction de lignes en bloc n’est pas implémentée, la taille de l’ensemble de lignes reste fixe à 1.
Une fois que vous avez initialisé la taille de l’ensemble de lignes, appelez la fonction De membre Open . Ici, vous devez spécifier l’option CRecordset::useMultiRowFetch du paramètre dwOptions pour implémenter l’extraction de lignes en bloc. Vous pouvez également définir l’option CRecordset::userAllocMultiRowBuffers . Le mécanisme d’échange de champs d’enregistrement en bloc utilise des tableaux pour stocker les plusieurs lignes de données récupérées lors d’une extraction. Ces mémoires tampons de stockage peuvent être allouées automatiquement par l’infrastructure ou vous pouvez les allouer manuellement. La spécification de l’option CRecordset::userAllocMultiRowBuffers signifie que vous allez effectuer l’allocation.
Le tableau suivant répertorie les fonctions membres fournies pour CRecordset prendre en charge l’extraction de lignes en bloc.
| Fonction membre | Description |
|---|---|
| CheckRowsetError | Fonction virtuelle qui gère les erreurs qui se produisent lors de l’extraction. |
| DoBulkFieldExchange | Implémente l’échange de champs d’enregistrement en bloc. Appelé automatiquement pour transférer plusieurs lignes de données de la source de données vers l’objet recordset. |
| GetRowsetSize | Récupère le paramètre actuel pour la taille de l’ensemble de lignes. |
| GetRowsFetched | Indique le nombre de lignes réellement récupérées après une extraction donnée. Dans la plupart des cas, il s’agit de la taille de l’ensemble de lignes, sauf si un ensemble de lignes incomplet a été récupéré. |
| GetRowStatus | Retourne un état d’extraction pour une ligne particulière dans un ensemble de lignes. |
| RefreshRowset | Actualise les données et l’état d’une ligne particulière dans un ensemble de lignes. |
| SetRowsetCursorPosition | Déplace le curseur vers une ligne particulière dans un ensemble de lignes. |
| SetRowsetSize | Fonction virtuelle qui modifie le paramètre de la taille de l’ensemble de lignes par la valeur spécifiée. |
Points particuliers à prendre en compte
Bien que l’extraction de lignes en bloc soit un gain de performances, certaines fonctionnalités fonctionnent différemment. Avant de décider d’implémenter l’extraction de lignes en bloc, tenez compte des éléments suivants :
L’infrastructure appelle automatiquement la
DoBulkFieldExchangefonction membre pour transférer des données de la source de données vers l’objet recordset. Toutefois, les données ne sont pas transférées du jeu d’enregistrements vers la source de données. L’appel desAddNewfonctions , ouEditDeleteUpdatemembres entraîne une assertion ayant échoué. Bien qu’actuellementCRecordsetne fournisse pas de mécanisme de mise à jour des lignes de données en bloc, vous pouvez écrire vos propres fonctions à l’aide de la fonctionSQLSetPosAPI ODBC. Pour plus d’informations surSQLSetPos, consultez la référence du programmeur ODBC.Les fonctions
IsDeletedmembres , , ,IsFieldNullableIsFieldDirtyIsFieldNull, etSetFieldDirtySetFieldNullne peuvent pas être utilisées sur les jeux d’enregistrements qui implémentent la récupération de lignes en bloc. Toutefois, vous pouvez appelerGetRowStatusà la place deIsDeleted, etGetODBCFieldInfoà la place deIsFieldNullable.Les
Moveopérations repositionnent votre jeu d’enregistrements par ensemble de lignes. Par exemple, supposons que vous ouvrez un jeu d’enregistrements qui a 100 enregistrements avec une taille initiale d’ensemble de lignes de 10.Openrécupère les lignes 1 à 10, avec l’enregistrement actif positionné sur la ligne 1. Un appel pourMoveNextextraire l’ensemble de lignes suivant, et non la ligne suivante. Cet ensemble de lignes se compose de lignes 11 à 20, avec l’enregistrement actif positionné sur la ligne 11. Notez que etMove( 1 )neMoveNextsont pas équivalents lorsque l’extraction de lignes en bloc est implémentée.Move( 1 )récupère l’ensemble de lignes qui commence 1 ligne à partir de l’enregistrement actif. Dans cet exemple, l’appelMove( 1 )après l’appelOpenrécupère l’ensemble de lignes composé de lignes 2 à 11, avec l’enregistrement actif positionné sur la ligne 2. Pour plus d’informations, consultez la fonction Déplacer un membre.Contrairement à l’échange de champs d’enregistrement, les Assistants ne prennent pas en charge l’échange de champs d’enregistrement en bloc. Cela signifie que vous devez déclarer manuellement vos membres de données de champ et remplacer
DoBulkFieldExchangemanuellement en écrivant des appels aux fonctions RFX en bloc. Pour plus d’informations, consultez Fonctions d’échange de champs d’enregistrement dans la référence de la bibliothèque de classes.
Comment implémenter l’échange de champs d’enregistrement en bloc
L’échange de champs d’enregistrement en bloc transfère un ensemble de lignes de données de la source de données à l’objet recordset. Les fonctions RFX en bloc utilisent des tableaux pour stocker ces données, ainsi que des tableaux pour stocker la longueur de chaque élément de données dans l’ensemble de lignes. Dans votre définition de classe, vous devez définir vos membres de données de champ en tant que pointeurs pour accéder aux tableaux de données. En outre, vous devez définir un ensemble de pointeurs pour accéder aux tableaux de longueurs. Tous les membres de données de paramètre ne doivent pas être déclarés en tant que pointeurs ; La déclaration de membres de données de paramètre lors de l’utilisation de l’échange de champs d’enregistrement en bloc est identique à la déclaration lors de l’utilisation de l’échange de champs d’enregistrement. Le code suivant montre un exemple simple :
class MultiRowSet : public CRecordset
{
public:
// Field/Param Data
// field data members
long* m_rgID;
LPSTR m_rgName;
// pointers for the lengths
// of the field data
long* m_rgIDLengths;
long* m_rgNameLengths;
// input parameter data member
CString m_strNameParam;
.
.
.
}
Vous pouvez allouer ces mémoires tampons de stockage manuellement ou avoir l’infrastructure à effectuer l’allocation. Pour allouer les mémoires tampons vous-même, vous devez spécifier l’option CRecordset::userAllocMultiRowBuffers du paramètre dwOptions dans la Open fonction membre. Veillez à définir les tailles des tableaux au moins égales à la taille de l’ensemble de lignes. Si vous souhaitez que l’infrastructure effectue l’allocation, vous devez initialiser vos pointeurs sur NULL. Cela est généralement effectué dans le constructeur de l’objet recordset :
MultiRowSet::MultiRowSet( CDatabase* pDB )
: CRecordset( pDB )
{
m_rgID = NULL;
m_rgName = NULL;
m_rgIDLengths = NULL;
m_rgNameLengths = NULL;
m_strNameParam = "";
m_nFields = 2;
m_nParams = 1;
.
.
.
}
Enfin, vous devez remplacer la DoBulkFieldExchange fonction membre. Pour les membres de données de champ, appelez les fonctions RFX en bloc ; pour tous les membres de données de paramètre, appelez les fonctions RFX. Si vous avez ouvert le jeu d’enregistrements en transmettant une instruction SQL ou une procédure stockée, Openl’ordre dans lequel vous effectuez les appels RFX en bloc doit correspondre à l’ordre des colonnes dans le jeu d’enregistrements ; de même, l’ordre des appels RFX pour les paramètres doit correspondre à l’ordre des paramètres de l’instruction SQL ou de la procédure stockée.
void MultiRowSet::DoBulkFieldExchange( CFieldExchange* pFX )
{
// call the Bulk RFX functions
// for field data members
pFX->SetFieldType( CFieldExchange::outputColumn );
RFX_Long_Bulk( pFX, _T( "[colRecID]" ),
&m_rgID, &m_rgIDLengths );
RFX_Text_Bulk( pFX, _T( "[colName]" ),
&m_rgName, &m_rgNameLengths, 30 );
// call the RFX functions for
// for parameter data members
pFX->SetFieldType( CFieldExchange::inputParam );
RFX_Text( pFX, "NameParam", m_strNameParam );
}
Remarque
Vous devez appeler la Close fonction membre avant que votre classe dérivée CRecordset ne soit hors de portée. Cela garantit que toutes les mémoires allouées par l’infrastructure sont libérées. Il est recommandé de programmer toujours explicitement l’appel Close, que vous ayez implémenté l’extraction de lignes en bloc.
Pour plus d’informations sur l’échange de champs d’enregistrement (RFX), consultez Record Field Exchange : How RFX Works. Pour plus d’informations sur l’utilisation de paramètres, consultez CFieldExchange ::SetFieldType et Recordset : Paramétrage d’un recordset (ODBC).
Voir aussi
Recordset (ODBC)
CRecordset ::m_nFields
CRecordset ::m_nParams