Classe CRecordset

Représente un ensemble d'enregistrements sélectionnés à partir d'une source de données.

Syntaxe

class CRecordset : public CObject

Membres

Constructeurs publics

Nom	Description
CRecordset::CRecordset	Construit un objet CRecordset. Votre classe dérivée doit fournir un constructeur qui appelle celui-ci.

Méthodes publiques

Nom	Description
CRecordset::AddNew	Prépare l’ajout d’un nouvel enregistrement. Appelez Update pour terminer l’ajout.
CRecordset::CanAppend	Retourne une valeur différente de zéro si de nouveaux enregistrements peuvent être ajoutés au jeu d’enregistrements via la AddNew fonction membre.
CRecordset::CanBookmark	Retourne une valeur différente de zéro si le jeu d’enregistrements prend en charge les signets.
CRecordset::Cancel	Annule une opération asynchrone ou un processus à partir d’un deuxième thread.
CRecordset::CancelUpdate	Annule les mises à jour en attente en raison d’une ou Edit d’une AddNew opération.
CRecordset::CanRestart	Retourne une valeur différente de zéro si Requery vous pouvez appeler pour réexécuter la requête du jeu d’enregistrements.
CRecordset::CanScroll	Retourne une valeur différente de zéro si vous pouvez faire défiler les enregistrements.
CRecordset::CanTransact	Retourne une valeur différente de zéro si la source de données prend en charge les transactions.
CRecordset::CanUpdate	Retourne une valeur différente de zéro si le jeu d’enregistrements peut être mis à jour (vous pouvez ajouter, mettre à jour ou supprimer des enregistrements).
CRecordset::CheckRowsetError	Appelé pour gérer les erreurs générées lors de l’extraction d’enregistrements.
CRecordset::Close	Ferme le jeu d’enregistrements et ODBC HSTMT associé à celui-ci.
CRecordset::Delete	Supprime l’enregistrement actif du jeu d’enregistrements. Vous devez faire défiler explicitement vers un autre enregistrement après la suppression.
CRecordset::DoBulkFieldExchange	Appelé pour échanger des lignes de données en bloc de la source de données vers le jeu d’enregistrements. Implémente l’échange de champs d’enregistrement en bloc (RFX en bloc).
CRecordset::DoFieldExchange	Appelé pour échanger des données (dans les deux sens) entre les membres de données de champ du jeu d’enregistrements et l’enregistrement correspondant sur la source de données. Implémente l’échange de champs d’enregistrement (RFX).
CRecordset::Edit	Prépare les modifications apportées à l’enregistrement actif. Appel Update pour terminer la modification.
CRecordset::FlushResultSet	Retourne une valeur différente de zéro si un autre jeu de résultats doit être récupéré lors de l’utilisation d’une requête prédéfinie.
CRecordset::GetBookmark	Affecte la valeur de signet d’un enregistrement à l’objet de paramètre.
CRecordset::GetDefaultConnect	Appelé pour obtenir la chaîne de connexion par défaut.
CRecordset::GetDefaultSQL	Appelé pour obtenir la chaîne SQL par défaut à exécuter.
CRecordset::GetFieldValue	Retourne la valeur d’un champ dans un jeu d’enregistrements.
CRecordset::GetODBCFieldCount	Retourne le nombre de champs dans le jeu d’enregistrements.
CRecordset::GetODBCFieldInfo	Retourne des types d’informations spécifiques sur les champs d’un jeu d’enregistrements.
CRecordset::GetRecordCount	Retourne le nombre d’enregistrements dans le jeu d’enregistrements.
CRecordset::GetRowsetSize	Retourne le nombre d’enregistrements que vous souhaitez récupérer lors d’une extraction unique.
CRecordset::GetRowsFetched	Retourne le nombre réel de lignes récupérées lors d’une extraction.
CRecordset::GetRowStatus	Retourne l’état de la ligne après une extraction.
CRecordset::GetSQL	Obtient la chaîne SQL utilisée pour sélectionner des enregistrements pour le jeu d’enregistrements.
CRecordset::GetStatus	Obtient l’état du jeu d’enregistrements : index de l’enregistrement actif et indique si un nombre final des enregistrements a été obtenu.
CRecordset::GetTableName	Obtient le nom de la table sur laquelle le jeu d’enregistrements est basé.
CRecordset::IsBOF	Retourne une valeur différente de zéro si le jeu d’enregistrements a été positionné avant le premier enregistrement. Il n’y a pas d’enregistrement actif.
CRecordset::IsDeleted	Retourne une valeur différente de zéro si le jeu d’enregistrements est positionné sur un enregistrement supprimé.
CRecordset::IsEOF	Retourne une valeur différente de zéro si le jeu d’enregistrements a été positionné après le dernier enregistrement. Il n’y a pas d’enregistrement actif.
CRecordset::IsFieldDirty	Retourne une valeur différente de zéro si le champ spécifié dans l’enregistrement actif a été modifié.
CRecordset::IsFieldNull	Retourne une valeur différente de zéro si le champ spécifié dans l’enregistrement actif est null (n’a aucune valeur).
CRecordset::IsFieldNullable	Retourne une valeur différente de zéro si le champ spécifié dans l’enregistrement actif peut être défini sur Null (sans valeur).
CRecordset::IsOpen	Retourne une valeur différente de zéro si Open elle a été appelée précédemment.
CRecordset::Move	Positionne le jeu d’enregistrements sur un nombre spécifié d’enregistrements de l’enregistrement actif dans les deux sens.
CRecordset::MoveFirst	Positionne l’enregistrement actif sur le premier enregistrement dans le jeu d’enregistrements. Testez d’abord IsBOF .
CRecordset::MoveLast	Positionne l’enregistrement actif sur le dernier enregistrement ou sur le dernier ensemble de lignes. Testez d’abord IsEOF .
CRecordset::MoveNext	Positionne l’enregistrement actif sur l’enregistrement suivant ou sur l’ensemble de lignes suivant. Testez d’abord IsEOF .
CRecordset::MovePrev	Positionne l’enregistrement actif sur l’enregistrement précédent ou sur l’ensemble de lignes précédent. Testez d’abord IsBOF .
CRecordset::OnSetOptions	Appelé pour définir des options (utilisées sur la sélection) pour l’instruction ODBC spécifiée.
CRecordset::OnSetUpdateOptions	Appelé pour définir les options (utilisées lors de la mise à jour) pour l’instruction ODBC spécifiée.
CRecordset::Open	Ouvre le jeu d’enregistrements en récupérant la table ou en effectuant la requête que représente le jeu d’enregistrements.
CRecordset::RefreshRowset	Actualise les données et l’état des lignes spécifiées.
CRecordset::Requery	Exécute à nouveau la requête du jeu d’enregistrements pour actualiser les enregistrements sélectionnés.
CRecordset::SetAbsolutePosition	Positionne le jeu d’enregistrements sur l’enregistrement correspondant au numéro d’enregistrement spécifié.
CRecordset::SetBookmark	Positionne le jeu d’enregistrements sur l’enregistrement spécifié par le signet.
CRecordset::SetFieldDirty	Marque le champ spécifié dans l’enregistrement actif comme modifié.
CRecordset::SetFieldNull	Définit la valeur du champ spécifié dans l’enregistrement actif sur Null (sans valeur).
CRecordset::SetLockingMode	Définit le mode de verrouillage sur le verrouillage « optimiste » (la valeur par défaut) ou le verrouillage « pessimiste ». Détermine comment les enregistrements sont verrouillés pour les mises à jour.
CRecordset::SetParamNull	Définit le paramètre spécifié sur Null (sans valeur).
CRecordset::SetRowsetCursorPosition	Positionne le curseur sur la ligne spécifiée dans l’ensemble de lignes.
CRecordset::SetRowsetSize	Spécifie le nombre d’enregistrements que vous souhaitez récupérer lors d’une extraction.
CRecordset::Update	Termine une AddNew opération en Edit enregistrant les données nouvelles ou modifiées sur la source de données.

Membres de données publiques

Nom	Description
CRecordset::m_hstmt	Contient le handle d’instruction ODBC pour le jeu d’enregistrements. Tapez HSTMT.
CRecordset::m_nFields	Contient le nombre de membres de données de champ dans le jeu d’enregistrements. Tapez UINT.
CRecordset::m_nParams	Contient le nombre de membres de données de paramètre dans le jeu d’enregistrements. Tapez UINT.
CRecordset::m_pDatabase	Contient un pointeur vers l’objet CDatabase via lequel le jeu d’enregistrements est connecté à une source de données.
CRecordset::m_strFilter	Contient une CString clause langage SQL (SQL). WHERE Utilisé comme filtre pour sélectionner uniquement les enregistrements qui répondent à certains critères.
CRecordset::m_strSort	Contient une CString clause SQL qui spécifie une clause SQL ORDER BY . Permet de contrôler la façon dont les enregistrements sont triés.

Notes

Les objets appelés « recordsets » CRecordset sont généralement utilisés sous deux formes : des feuilles de réponse dynamiques et des instantané. Une feuille de réponse dynamique reste synchronisée avec les mises à jour des données effectuées par d’autres utilisateurs. Une instantané est une vue statique des données. Chaque formulaire représente un ensemble d’enregistrements fixes au moment de l’ouverture du jeu d’enregistrements. Lorsque vous faites défiler vers un enregistrement dans une feuille de réponse dynamique, il reflète les modifications apportées à l’enregistrement, soit par d’autres utilisateurs, soit par d’autres jeux d’enregistrements dans votre application.

Remarque

Si vous utilisez les classes DAO (Data Access Objects) plutôt que les classes Open Database Connecter ivity (ODBC), utilisez plutôt la classeCDaoRecordset. Pour plus d’informations, consultez Vue d’ensemble : Programmation de base de données.

Pour utiliser l’un ou l’autre type d’recordset, vous dérivez généralement une classe recordset spécifique à l’application à partir de CRecordset. Les recordsets sélectionnent des enregistrements à partir d’une source de données, puis vous pouvez :

• Faites défiler les enregistrements.

• Mettez à jour les enregistrements et spécifiez un mode de verrouillage.

• Filtrez le jeu d’enregistrements pour limiter les enregistrements qu’il sélectionne parmi ceux disponibles sur la source de données.

• Triez le jeu d’enregistrements.

• Paramétrez le jeu d’enregistrements pour personnaliser sa sélection avec des informations non connues jusqu’au moment de l’exécution.

Pour utiliser votre classe, ouvrez une base de données et construisez un objet recordset, en transmettant au constructeur un pointeur vers votre CDatabase objet. Appelez ensuite la fonction membre du Open jeu d’enregistrements, où vous pouvez spécifier si l’objet est une feuille de réponse dynamique ou une instantané. L’appel Open sélectionne des données à partir de la source de données. Une fois l’objet recordset ouvert, utilisez ses fonctions membres et ses membres de données pour parcourir les enregistrements et les exploiter. Les opérations disponibles varient selon que l’objet est une feuille de réponse dynamique ou un instantané, qu’il soit mis à jour ou en lecture seule (cela dépend de la capacité de la source de données Open Database Connecter ivity (ODBC) et que vous ayez implémenté la récupération de lignes en bloc. Pour actualiser les enregistrements qui ont peut-être été modifiés ou ajoutés depuis l’appel Open , appelez la fonction membre de l’objet Requery . Appelez la fonction membre de Close l’objet et détruisez l’objet lorsque vous avez terminé avec celui-ci.

Dans une classe dérivée CRecordset , l’échange de champs d’enregistrement (RFX) ou l’échange de champs d’enregistrement en bloc (RFX en bloc) est utilisé pour prendre en charge la lecture et la mise à jour des champs d’enregistrement.

Pour plus d’informations sur les recordsets et l’échange de champs d’enregistrement, consultez les articles Vue d’ensemble : Programmation de base de données, Recordset (ODBC), Recordset : Extraction d’enregistrements en bloc (ODBC) et Échange de champs d’enregistrement (RFX). Pour vous concentrer sur les feuilles de réponse dynamique et les instantané, consultez les articles Dynaset et Snapshot.

Hiérarchie d’héritage

CObject

CRecordset

Spécifications

En-têteafxdb.h:

CRecordset::AddNew

Prépare l’ajout d’un nouvel enregistrement à la table.

virtual void AddNew();

Notes

Vous devez appeler la Requery fonction membre pour voir l’enregistrement nouvellement ajouté. Les champs de l’enregistrement sont initialement Null. (Dans la terminologie de la base de données, Null signifie « sans valeur » et n’est pas identique à NULL en C++.) Pour terminer l’opération, vous devez appeler la Update fonction membre. Update enregistre vos modifications dans la source de données.

Remarque

Si vous avez implémenté la récupération de lignes en bloc, vous ne pouvez pas appeler AddNew. Cela entraîne une assertion ayant échoué. Bien que la classe CRecordset ne fournisse pas de mécanisme pour mettre à jour des lignes de données en bloc, vous pouvez écrire vos propres fonctions à l’aide de la fonction SQLSetPosAPI ODBC. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

AddNew prépare un nouvel enregistrement vide à l’aide des membres de données de champ du jeu d’enregistrements. Après avoir appelé AddNew, définissez les valeurs souhaitées dans les membres de données de champ du jeu d’enregistrements. (Vous n’avez pas besoin d’appeler le Modifiez la fonction membre à cet effet ; utilisez Edit uniquement pour les enregistrements existants.) Lorsque vous appelez Update, les valeurs modifiées dans les membres de données de champ sont enregistrées sur la source de données.

Attention

Si vous faites défiler vers un nouvel enregistrement avant d’appeler Update, le nouvel enregistrement est perdu et aucun avertissement n’est donné.

Si la source de données prend en charge les transactions, vous pouvez faire partie de votre AddNew appel d’une transaction. Pour plus d’informations sur les transactions, consultez la classe CDatabase. Appel avant d’appeler CDatabase::BeginTransAddNew.

Remarque

Pour les feuilles de réponse dynamiques, de nouveaux enregistrements sont ajoutés au jeu d’enregistrements comme dernier enregistrement. Les enregistrements ajoutés ne sont pas ajoutés aux instantané ; vous devez appeler Requery pour actualiser le jeu d’enregistrements.

Il est illégal d’appeler AddNew un jeu d’enregistrements dont Open la fonction membre n’a pas été appelée. A CDBException est levée si vous appelez AddNew un jeu d’enregistrements qui ne peut pas être ajouté. Vous pouvez déterminer si le jeu d’enregistrements est pouvant être mis à jour en appelant CanAppend.

Pour plus d’informations, consultez les articles suivants : Recordset : How Recordsets Update Records (ODBC), Recordset : Adding, Update and Deleting Records (ODBC) and Transaction (ODBC).

Exemple

voir Transaction : exécution d’une transaction dans un recordset (ODBC)

CRecordset::CanAppend

Détermine si le jeu d’enregistrements précédemment ouvert vous permet d’ajouter de nouveaux enregistrements.

BOOL CanAppend() const;

Valeur retournée

Différent de zéro si le jeu d’enregistrements autorise l’ajout de nouveaux enregistrements ; sinon 0. CanAppend retourne 0 si vous avez ouvert le jeu d’enregistrements en lecture seule.

CRecordset::CanBookmark

Détermine si le jeu d’enregistrements vous permet de marquer des enregistrements à l’aide de signets.

BOOL CanBookmark() const;

Valeur retournée

Différent de zéro si le jeu d’enregistrements prend en charge les signets ; sinon 0.

Notes

Cette fonction est indépendante de l’option CRecordset::useBookmarks dans le dwOptions paramètre de la Open fonction membre. CanBookmark indique si le pilote ODBC et le type de curseur donnés prennent en charge les signets. CRecordset::useBookmarks indique si les signets seront disponibles, à condition qu’ils soient pris en charge.

Remarque

Les signets ne sont pas pris en charge sur les jeux d’enregistrements en avant uniquement.

Pour plus d’informations sur les signets et la navigation dans le jeu d’enregistrements, consultez les articles Recordset : Signets et positions absolues (ODBC) et Recordset : Défilement (ODBC).

CRecordset::Cancel

Demande que la source de données annule une opération asynchrone en cours ou un processus à partir d’un deuxième thread.

void Cancel();

Notes

Les classes ODBC MFC n’utilisent plus le traitement asynchrone ; pour effectuer une opération asynchrone, vous devez appeler directement la fonction SQLSetConnectOptionAPI ODBC. Pour plus d’informations, consultez « Exécution asynchrone de fonctions » dans le Guide du programmeur du SDK ODBC.

CRecordset::CancelUpdate

Annule les mises à jour en attente, provoquées par une Edit ou AddNew une opération, avant Update d’être appelées.

void CancelUpdate();

Notes

Remarque

Cette fonction membre n’est pas applicable sur les jeux d’enregistrements qui utilisent l’extraction de lignes en bloc, car ces jeux d’enregistrements ne peuvent pas appeler Edit, AddNewou Update. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Si le champ de sale automatique case activée est activé, CancelUpdate restaure les variables membres sur les valeurs qu’elles avaient avant Edit ou AddNew a été appelées ; sinon, toutes les modifications de valeur restent. Par défaut, le champ automatique case activée ing est activé lorsque le jeu d’enregistrements est ouvert. Pour le désactiver, vous devez spécifier le CRecordset::noDirtyFieldCheck paramètre de la dwOptionsfonction Membre Open .

Pour plus d’informations sur la mise à jour des données, consultez Recordset : Ajout, mise à jour et suppression d’enregistrements (ODBC).

CRecordset::CanRestart

Détermine si le jeu d’enregistrements autorise le redémarrage de sa requête (pour actualiser ses enregistrements) en appelant la Requery fonction membre.

BOOL CanRestart() const;

Valeur retournée

Différent de zéro si la requête est autorisée ; sinon 0.

CRecordset::CanScroll

Détermine si le jeu d’enregistrements autorise le défilement.

BOOL CanScroll() const;

Valeur retournée

Différent de zéro si le jeu d’enregistrements autorise le défilement ; sinon 0.

Notes

Pour plus d’informations sur le défilement, consultez Recordset : Défilement (ODBC).

CRecordset::CanTransact

Détermine si le jeu d’enregistrements autorise les transactions.

BOOL CanTransact() const;

Valeur retournée

Différent de zéro si le jeu d’enregistrements autorise les transactions ; sinon 0.

Notes

Pour plus d’informations, consultez Transaction (ODBC).

CRecordset::CanUpdate

Détermine si le jeu d’enregistrements peut être mis à jour.

BOOL CanUpdate() const;

Valeur retournée

Différent de zéro si le jeu d’enregistrements peut être mis à jour ; sinon 0.

Notes

Un recordset peut être en lecture seule si la source de données sous-jacente est en lecture seule ou si vous avez spécifié CRecordset::readOnly dans le dwOptions paramètre lorsque vous avez ouvert le jeu d’enregistrements.

CRecordset::CheckRowsetError

Appelé pour gérer les erreurs générées lors de l’extraction d’enregistrements.

virtual void CheckRowsetError(RETCODE nRetCode);

Paramètres

nRetCode
Code de retour d’une fonction API ODBC. Pour plus d'informations, consultez Notes.

Notes

Cette fonction membre virtuelle gère les erreurs qui se produisent lorsque les enregistrements sont récupérés et sont utiles lors de la récupération de lignes en bloc. Vous pouvez envisager de CheckRowsetError remplacer pour implémenter votre propre gestion des erreurs.

CheckRowsetError est appelé automatiquement dans une opération de navigation de curseur, telle que Open, Requeryou toute Move opération. Elle a passé la valeur de retour de la fonction SQLExtendedFetchAPI ODBC. Le tableau suivant répertorie les valeurs possibles pour le nRetCode paramètre.

nRetCode	Description
SQL_SUCCESS	La fonction s’est terminée correctement ; aucune information supplémentaire n’est disponible.
SQL_SUCCESS_WITH_INFO	La fonction s’est terminée avec succès, éventuellement avec une erreur non irrécupérable. Des informations supplémentaires peuvent être obtenues en appelant SQLError.
SQL_NO_DATA_FOUND	Toutes les lignes du jeu de résultats ont été extraites.
SQL_ERROR	Échec de la fonction. Des informations supplémentaires peuvent être obtenues en appelant SQLError.
SQL_INVALID_HANDLE	La fonction a échoué en raison d’un handle d’environnement non valide, d’un handle de connexion ou d’un handle d’instruction. Cela indique une erreur de programmation. Aucune information supplémentaire n’est disponible à partir de SQLError.
SQL_STILL_EXECUTING	Une fonction démarrée de façon asynchrone est toujours en cours d’exécution. Par défaut, MFC ne transmet jamais cette valeur à CheckRowsetError; MFC continuera à appeler SQLExtendedFetch jusqu’à ce qu’il ne retourne SQL_STILL_EXECUTINGplus .

Pour plus d’informations sur SQLError, consultez le Kit de développement logiciel (SDK) Windows. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

CRecordset::Close

Ferme le jeu d’enregistrements.

virtual void Close();

Notes

Odbc HSTMT et toutes les mémoires allouées pour le jeu d’enregistrements sont libérées. En règle générale, après l’appel Close, vous supprimez l’objet recordset C++ s’il a été alloué avec new.

Vous pouvez appeler Open à nouveau après l’appel Close. Cela vous permet de réutiliser l’objet recordset. L’alternative consiste à appeler Requery.

Exemple

// Construct a snapshot object
CCustomer rsCustSet(NULL);

if (!rsCustSet.Open())
return;

// Use the snapshot ...

// Close the snapshot
rsCustSet.Close();

// Destructor is called when the function exits

CRecordset::CRecordset

Construit un objet CRecordset.

CRecordset(CDatabase* pDatabase = NULL);

Paramètres

pDatabase
Contient un pointeur vers un CDatabase objet ou la valeur NULL. Si ce n’est pas NULL le cas et que la fonction membre de Open l’objet CDatabase n’a pas été appelée pour la connecter à la source de données, le jeu d’enregistrements tente de l’ouvrir pour vous pendant son propre Open appel. Si vous passez, un CDatabase objet est construit et connecté pour vous à l’aide des informations de source de données que vous avez spécifiées NULLlorsque vous avez dérivé votre classe recordset avec ClassWizard.

Notes

Vous pouvez utiliser CRecordset directement ou dériver une classe spécifique à l’application à partir de CRecordset. Vous pouvez utiliser ClassWizard pour dériver vos classes recordset.

Remarque

Une classe dérivée doit fournir son propre constructeur. Dans le constructeur de votre classe dérivée, appelez le constructeur CRecordset::CRecordset, en lui transmettant les paramètres appropriés.

NULL Passez à votre constructeur recordset pour avoir un CDatabase objet construit et connecté automatiquement pour vous. Il s’agit d’un raccourci utile qui ne vous oblige pas à construire et à connecter un CDatabase objet avant de construire votre jeu d’enregistrements.

Exemple

Pour plus d’informations, consultez Recordset : Déclaration d’une classe pour une table (ODBC).

CRecordset::Delete

Supprime l’enregistrement actif.

virtual void Delete();

Notes

Une fois la suppression réussie, les membres de données de champ du jeu d’enregistrements sont définis sur une valeur Null et vous devez appeler explicitement l’une des Move fonctions pour déplacer l’enregistrement supprimé. Une fois que vous déplacez l’enregistrement supprimé, il n’est pas possible de le retourner. Si la source de données prend en charge les transactions, vous pouvez effectuer la Delete partie d’appel d’une transaction. Pour plus d’informations, consultez Transaction (ODBC).

Remarque

Si vous avez implémenté la récupération de lignes en bloc, vous ne pouvez pas appeler Delete. Cela entraîne une assertion ayant échoué. Bien que la classe CRecordset ne fournisse pas de mécanisme pour mettre à jour des lignes de données en bloc, vous pouvez écrire vos propres fonctions à l’aide de la fonction SQLSetPosAPI ODBC. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Attention

Le jeu d’enregistrements doit être mis à jour et il doit y avoir un enregistrement valide actif dans le jeu d’enregistrements lorsque vous appelez Delete; sinon, une erreur se produit. Par exemple, si vous supprimez un enregistrement mais que vous ne faites pas défiler vers un nouvel enregistrement avant d’appeler Delete à nouveau, Delete lève une exception CDBException.

Contrairement AddNew à et Edit, un appel à Delete n’est pas suivi d’un appel à Update. Si un Delete appel échoue, les membres de données de champ restent inchangés.

Exemple

Cet exemple montre un jeu d’enregistrements créé sur le cadre d’une fonction. L’exemple suppose l’existence d’une m_dbCustvariable membre de type CDatabase déjà connectée à la source de données.

// Create a derived CRecordset object
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if (rsCustSet.IsEOF() || !rsCustSet.CanUpdate() ||
   !rsCustSet.CanTransact())
{
   return;
}

m_dbCust.BeginTrans();

// Perhaps scroll to a new record...
// Delete the current record
rsCustSet.Delete();

// Finished commands for this transaction
if (IDYES == AfxMessageBox(_T("Commit transaction?"), MB_YESNO))
m_dbCust.CommitTrans();
else // User changed mind
m_dbCust.Rollback();

CRecordset::DoBulkFieldExchange

Appelé pour échanger des lignes de données en bloc de la source de données vers le jeu d’enregistrements. Implémente l’échange de champs d’enregistrement en bloc (RFX en bloc).

virtual void DoBulkFieldExchange(CFieldExchange* pFX);

Paramètres

pFX
Pointeur vers un objet CFieldExchange. L’infrastructure a déjà configuré cet objet pour spécifier un contexte pour l’opération d’échange de champs.

Notes

Lorsque l’extraction de lignes en bloc est implémentée, l’infrastructure appelle cette fonction membre pour transférer automatiquement des données de la source de données vers votre objet recordset. DoBulkFieldExchange lie également vos membres de données de paramètre, le cas échéant, aux espaces réservés de paramètres dans la chaîne d’instruction SQL pour la sélection du jeu d’enregistrements.

Si la récupération de lignes en bloc n’est pas implémentée, l’infrastructure appelle DoFieldExchange. Pour implémenter l’extraction de lignes en bloc, vous devez spécifier l’option CRecordset::useMultiRowFetch du paramètre dwOptions dans la Open fonction membre.

Remarque

DoBulkFieldExchange est disponible uniquement si vous utilisez une classe dérivée de CRecordset. Si vous avez créé un objet recordset directement à partir duquel CRecordsetvous devez appeler la GetFieldValue fonction membre pour récupérer des données.

L’échange de champs d’enregistrement en bloc (RFX en bloc) est similaire à l’échange de champs d’enregistrement (RFX). Les données sont automatiquement transférées de la source de données à l’objet recordset. Toutefois, vous ne pouvez pas appeler AddNew, Editou DeleteUpdate transférer les modifications vers la source de données. La classe CRecordset ne fournit actuellement pas de mécanisme permettant de mettre à jour des lignes de données en bloc . Toutefois, vous pouvez écrire vos propres fonctions à l’aide de la fonction SQLSetPosAPI ODBC.

ClassWizard ne prend pas en charge l’échange de champs d’enregistrement en bloc ; par conséquent, vous devez remplacer DoBulkFieldExchange manuellement en écrivant des appels aux fonctions RFX en bloc. Pour plus d’informations sur ces fonctions, consultez Record Field Exchange Functions.

Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC). Pour plus d’informations, consultez Record Field Exchange (RFX).

CRecordset::DoFieldExchange

Appelé pour échanger des données (dans les deux sens) entre les membres de données de champ du jeu d’enregistrements et l’enregistrement correspondant sur la source de données. Implémente l’échange de champs d’enregistrement (RFX).

virtual void DoFieldExchange(CFieldExchange* pFX);

Paramètres

pFX
Pointeur vers un objet CFieldExchange. L’infrastructure a déjà configuré cet objet pour spécifier un contexte pour l’opération d’échange de champs.

Notes

Lorsque l’extraction de lignes en bloc n’est pas implémentée, l’infrastructure appelle cette fonction membre pour échanger automatiquement des données entre les membres de données de champ de votre objet recordset et les colonnes correspondantes de l’enregistrement actif sur la source de données. DoFieldExchange lie également vos membres de données de paramètre, le cas échéant, aux espaces réservés de paramètres dans la chaîne d’instruction SQL pour la sélection du jeu d’enregistrements.

Si l’extraction de lignes en bloc est implémentée, l’infrastructure appelle DoBulkFieldExchange. Pour implémenter l’extraction de lignes en bloc, vous devez spécifier l’option CRecordset::useMultiRowFetch du dwOptions paramètre dans la Open fonction membre.

Remarque

DoFieldExchange est disponible uniquement si vous utilisez une classe dérivée de CRecordset. Si vous avez créé un objet recordset directement à partir duquel CRecordsetvous devez appeler la fonction membre GetFieldValue pour récupérer des données.

L’échange de données de champ, appelée échange de champs d’enregistrement (RFX), fonctionne dans les deux sens : des membres de données de champ de l’objet recordset aux champs de l’enregistrement sur la source de données, et de l’enregistrement de la source de données à l’objet recordset.

La seule action que vous devez normalement entreprendre pour implémenter DoFieldExchange pour votre classe recordset dérivée consiste à créer la classe avec ClassWizard et à spécifier les noms et les types de données des membres de données de champ. Vous pouvez également ajouter du code à ce que ClassWizard écrit pour spécifier des membres de données de paramètre ou pour traiter les colonnes que vous liez dynamiquement. Pour plus d’informations, consultez Recordset : Liaison dynamique de colonnes de données (ODBC)

Lorsque vous déclarez votre classe recordset dérivée avec ClassWizard, l’Assistant écrit un remplacement pour DoFieldExchange vous, qui ressemble à l’exemple suivant :

void CCustomer::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputColumn);
   // Macros such as RFX_Text() and RFX_Int() are dependent on the
   // type of the member variable, not the type of the field in the database.
   // ODBC will try to automatically convert the column value to the requested type
   RFX_Long(pFX, _T("[CustomerID]"), m_CustomerID);
   RFX_Text(pFX, _T("[ContactFirstName]"), m_ContactFirstName);
   RFX_Text(pFX, _T("[PostalCode]"), m_PostalCode);
   RFX_Text(pFX, _T("[L_Name]"), m_L_Name);
   RFX_Long(pFX, _T("[BillingID]"), m_BillingID);

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param"), m_strParam);
}

Pour plus d’informations sur les fonctions RFX, consultez Fonctions Exchange de champ d’enregistrement.

Pour obtenir d’autres exemples et détails sur DoFieldExchange, consultez Record Field Exchange : How RFX Works. Pour obtenir des informations générales sur RFX, consultez Record Field Exchange.

CRecordset::Edit

Autorise les modifications apportées à l’enregistrement actif.

virtual void Edit();

Notes

Après avoir appelé Edit, vous pouvez modifier les membres de données de champ en réinitialisant directement leurs valeurs. L’opération est terminée lorsque vous appelez la Update fonction membre pour enregistrer vos modifications sur la source de données.

Remarque

Si vous avez implémenté la récupération de lignes en bloc, vous ne pouvez pas appeler Edit. Cela entraîne une assertion ayant échoué. Bien que la classe CRecordset ne fournisse pas de mécanisme pour mettre à jour des lignes de données en bloc, vous pouvez écrire vos propres fonctions à l’aide de la fonction SQLSetPosAPI ODBC. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Edit enregistre les valeurs des membres de données du jeu d’enregistrements. Si vous appelez Edit, apportez des modifications, puis appelez Edit à nouveau, les valeurs de l’enregistrement sont restaurées sur ce qu’elles étaient avant le premier Edit appel.

Dans certains cas, vous pouvez mettre à jour une colonne en la rendant Null (contenant aucune donnée). Pour ce faire, appelez SetFieldNull avec un paramètre true pour marquer le champ Null ; cela entraîne également la mise à jour de la colonne. Si vous souhaitez qu’un champ soit écrit dans la source de données même si sa valeur n’a pas changé, appelez SetFieldDirty avec un paramètre TRUE. Cela fonctionne même si le champ a la valeur Null.

Si la source de données prend en charge les transactions, vous pouvez effectuer la Edit partie d’appel d’une transaction. Appel CDatabase::BeginTrans avant d’appeler Edit et après l’ouverture du jeu d’enregistrements. En outre, l’appel CDatabase::CommitTrans n’est pas un substitut à l’appel Update pour terminer l’opération Edit . Pour plus d’informations sur les transactions, consultez la classe CDatabase.

Selon le mode de verrouillage actuel, l’enregistrement mis à jour peut être verrouillé Edit jusqu’à ce que vous appeliez Update ou faites défiler vers un autre enregistrement, ou qu’il soit verrouillé uniquement pendant l’appel Edit . Vous pouvez modifier le mode de verrouillage avec SetLockingMode.

La valeur précédente de l’enregistrement actif est restaurée si vous faites défiler vers un nouvel enregistrement avant d’appeler Update. A CDBException est levée si vous appelez Edit un jeu d’enregistrements qui ne peut pas être mis à jour ou s’il n’y a pas d’enregistrement actif.

Pour plus d’informations, consultez les articles Transaction (ODBC) et Recordset : Locking Records (ODBC).

Exemple

// To edit a record, first set up the edit buffer
rsCustSet.Edit();

// Then edit field data members for the record
rsCustSet.m_BillingID = 2795;
rsCustSet.m_ContactFirstName = _T("Jones Mfg");

// Finally, complete the operation
if (!rsCustSet.Update())
{
   // Handle the failure to update
   AfxMessageBox(_T("Couldn't update record!"));
}

CRecordset::FlushResultSet

Récupère le jeu de résultats suivant d’une requête prédéfinie (procédure stockée), s’il existe plusieurs jeux de résultats.

BOOL FlushResultSet();

Valeur retournée

Différent de zéro s’il existe d’autres jeux de résultats à récupérer ; sinon 0.

Notes

Vous devez appeler FlushResultSet uniquement une fois le curseur terminé sur le jeu de résultats actuel. Lorsque vous récupérez le jeu de résultats suivant en appelant FlushResultSet, votre curseur n’est pas valide sur ce jeu de résultats ; vous devez appeler la MoveNext fonction membre après l’appel FlushResultSet.

Si une requête prédéfinie utilise un paramètre de sortie ou des paramètres d’entrée/sortie, vous devez appeler FlushResultSet jusqu’à ce qu’elle retourne FALSE(la valeur 0), afin d’obtenir ces valeurs de paramètre.

FlushResultSet appelle la fonction SQLMoreResultsAPI ODBC . Si SQLMoreResults cette propriété est retournée SQL_ERROR ou SQL_INVALID_HANDLE, lève FlushResultSet une exception. Pour plus d’informations sur SQLMoreResults, consultez le Kit de développement logiciel (SDK) Windows.

Votre procédure stockée doit avoir des champs liés si vous souhaitez appeler FlushResultSet.

Exemple

Le code suivant suppose qu’il COutParamRecordset s’agit d’un CRecordsetobjet dérivé basé sur une requête prédéfinie avec un paramètre d’entrée et un paramètre de sortie, et d’avoir plusieurs jeux de résultats. Notez la structure du DoFieldExchange remplacement.

// DoFieldExchange override
//
// Only necessary to handle parameter bindings.
// Don't use CRecordset-derived class with bound
// fields unless all result sets have same schema
// OR there is conditional binding code.
void CCourses::DoFieldExchange(CFieldExchange* pFX)
{
   pFX->SetFieldType(CFieldExchange::outputParam);
   RFX_Long(pFX, _T("Param1"), m_nCountParam);
   // The "Param1" name here is a dummy name 
   // that is never used

   pFX->SetFieldType(CFieldExchange::inputParam);
   RFX_Text(pFX, _T("Param2"), m_strNameParam);
   // The "Param2" name here is a dummy name 
   // that is never used
}

 

// Assume db is an already open CDatabase object
CCourses rs(&m_dbCust);
rs.m_strNameParam = _T("History");

// Get the first result set
// NOTE: SQL Server requires forwardOnly cursor 
//       type for multiple rowset returning stored 
//       procedures
rs.Open(CRecordset::forwardOnly,
   _T("{? = CALL GetCourses( ? )}"),
   CRecordset::readOnly);

// Loop through all the data in the first result set
while (!rs.IsEOF())
{
   CString strFieldValue;
   for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
   {
      rs.GetFieldValue(nIndex, strFieldValue);

      // TO DO: Use field value string.
   }
   rs.MoveNext();
}

// Retrieve other result sets...
while (rs.FlushResultSet())
{
   // must call MoveNext because cursor is invalid
   rs.MoveNext();

   while (!rs.IsEOF())
   {
      CString strFieldValue;
      for (short nIndex = 0; nIndex < rs.GetODBCFieldCount(); nIndex++)
      {
         rs.GetFieldValue(nIndex, strFieldValue);

         // TO DO: Use field value string.
      }
      rs.MoveNext();
   }
}


// All result sets have been flushed. Cannot
// use the cursor, but the output parameter,
// m_nCountParam, has now been written.
// Note that m_nCountParam is not valid until
// CRecordset::FlushResultSet has returned FALSE,
// indicating no more result sets will be returned.

// TO DO: Use m_nCountParam

// Cleanup
rs.Close();

CRecordset::GetBookmark

Obtient la valeur de signet pour l’enregistrement actif.

void GetBookmark(CDBVariant& varBookmark);

Paramètres

varBookmark
Référence à un CDBVariant objet représentant le signet sur l’enregistrement actif.

Notes

Pour déterminer si les signets sont pris en charge sur le jeu d’enregistrements, appelez CanBookmark. Pour rendre les signets disponibles s’ils sont pris en charge, vous devez définir l’option CRecordset::useBookmarks dans le paramètre de la dwOptionsOpen fonction membre.

Remarque

Si les signets ne sont pas pris en charge ou indisponibles, l’appel GetBookmark entraîne la levée d’une exception. Les signets ne sont pas pris en charge sur les jeux d’enregistrements en avant uniquement.

GetBookmark affecte la valeur du signet pour l’enregistrement actif à un CDBVariant objet. Pour revenir à cet enregistrement à tout moment après le passage à un autre enregistrement, appelez SetBookmark avec l’objet correspondant CDBVariant .

Remarque

Après certaines opérations de jeu d’enregistrements, les signets peuvent ne plus être valides. Par exemple, si vous appelez GetBookmark suivi, Requeryvous ne pourrez peut-être pas revenir à l’enregistrement avec SetBookmark. Appelez CDatabase::GetBookmarkPersistence case activée si vous pouvez appeler SetBookmarken toute sécurité .

Pour plus d’informations sur les signets et la navigation dans le jeu d’enregistrements, consultez les articles Recordset : Signets et positions absolues (ODBC) et Recordset : Défilement (ODBC).

CRecordset::GetDefaultConnect

Appelé pour obtenir la chaîne de connexion par défaut.

virtual CString GetDefaultConnect();

Valeur retournée

Qui CString contient la chaîne de connexion par défaut.

Notes

L’infrastructure appelle cette fonction membre pour obtenir la chaîne de connexion par défaut de la source de données sur laquelle le jeu d’enregistrements est basé. ClassWizard implémente cette fonction pour vous en identifiant la même source de données que celle utilisée pour ClassWizard obtenir des informations sur les tables et les colonnes. Vous trouverez probablement pratique de vous appuyer sur cette connexion par défaut lors du développement de votre application. Toutefois, la connexion par défaut peut ne pas convenir aux utilisateurs de votre application. Si c’est le cas, vous devez réexémettre cette fonction, dis carte’s ClassWizardversion. Pour plus d’informations sur les chaîne de connexion, consultez La source de données (ODBC)

CRecordset::GetDefaultSQL

Appelé pour obtenir la chaîne SQL par défaut à exécuter.

virtual CString GetDefaultSQL();

Valeur retournée

Qui CString contient l’instruction SQL par défaut.

Notes

L’infrastructure appelle cette fonction membre pour obtenir l’instruction SQL par défaut sur laquelle le jeu d’enregistrements est basé. Il peut s’agir d’un nom de table ou d’une instruction SQL SELECT .

Vous définissez indirectement l’instruction SQL par défaut en déclarant votre classe recordset avec ClassWizard, et ClassWizard effectue cette tâche pour vous.

Si vous avez besoin de la chaîne d’instruction SQL pour votre propre utilisation, appelez GetSQL, qui retourne l’instruction SQL utilisée pour sélectionner les enregistrements du jeu d’enregistrements lors de son ouverture. Vous pouvez modifier la chaîne SQL par défaut dans le remplacement de GetDefaultSQLvotre classe . Par exemple, vous pouvez spécifier un appel à une requête prédéfinie à l’aide d’une CALL instruction. (Notez toutefois que si vous modifiez GetDefaultSQL, vous devez également modifier m_nFields pour correspondre au nombre de colonnes dans la source de données.)

Pour plus d’informations, consultez Recordset : Déclaration d’une classe pour une table (ODBC).

Attention

Le nom de la table est vide si l’infrastructure n’a pas pu identifier un nom de table, si plusieurs noms de table ont été fournis ou si une CALL instruction n’a pas pu être interprétée. Lorsque vous utilisez une instruction, n’insérez pas d’espace CALL blanc entre l’accolades et le CALL mot clé, ni avant l’accolades ou avant le SELECT mot clé dans une SELECT instruction.

CRecordset::GetFieldValue

Récupère les données de champ dans l’enregistrement actif.

void GetFieldValue(
    LPCTSTR lpszName,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringA& strValue
);

void GetFieldValue(
    LPCTSTR lpszName,
    CStringW& strValue
);

void GetFieldValue(
    short nIndex,
    CDBVariant& varValue,
    short nFieldType = DEFAULT_FIELD_TYPE);

void GetFieldValue(
    short nIndex,
    CStringA& strValue);

void GetFieldValue(
    short nIndex,
    CStringW& strValue);

Paramètres

lpszName
Nom d’un champ.

varValue Référence à un CDBVariant objet qui stocke la valeur du champ.

nFieldType
Type de données ODBC C du champ. À l’aide de la valeur par défaut, DEFAULT_FIELD_TYPEforce GetFieldValue à déterminer le type de données C à partir du type de données SQL, en fonction du tableau suivant. Sinon, vous pouvez spécifier le type de données directement ou choisir un type de données compatible ; par exemple, vous pouvez stocker n’importe quel type de données dans SQL_C_CHAR.

Type de données C	Type de données SQL
SQL_C_BIT	SQL_BIT
SQL_C_UTINYINT	SQL_TINYINT
SQL_C_SSHORT	SQL_SMALLINT
SQL_C_SLONG	SQL_INTEGER
SQL_C_FLOAT	SQL_REAL
SQL_C_DOUBLE	SQL_FLOATSQL_DOUBLE
SQL_C_TIMESTAMP	SQL_DATESQL_TIMESQL_TIMESTAMP
SQL_C_CHAR	SQL_NUMERICSQL_DECIMALSQL_BIGINTSQL_CHARSQL_VARCHARSQL_LONGVARCHAR
SQL_C_BINARY	SQL_BINARYSQL_VARBINARYSQL_LONGVARBINARY

Pour plus d’informations sur les types de données ODBC, consultez les rubriques « Types de données SQL » et « Types de données C » dans l’annexe D du Kit de développement logiciel (SDK) Windows.

nIndex
Index de base zéro du champ.

strValue
Référence à un CString objet qui stocke la valeur du champ convertie en texte, quel que soit le type de données du champ.

Notes

Vous pouvez rechercher un champ par nom ou par index. Vous pouvez stocker la valeur de champ dans un CDBVariant objet ou un CString objet.

Si vous avez implémenté la récupération de lignes en bloc, l’enregistrement actif est toujours positionné sur le premier enregistrement d’un ensemble de lignes. Pour utiliser GetFieldValue un enregistrement dans un ensemble de lignes donné, vous devez d’abord appeler la SetRowsetCursorPosition fonction membre pour déplacer le curseur vers la ligne souhaitée dans cet ensemble de lignes. Appelez GetFieldValue ensuite cette ligne. Pour implémenter l’extraction de lignes en bloc, vous devez spécifier l’option CRecordset::useMultiRowFetch du dwOptions paramètre dans la Open fonction membre.

Vous pouvez utiliser GetFieldValue pour extraire dynamiquement des champs au moment de l’exécution plutôt que de les lier statiquement au moment du design. Par exemple, si vous avez déclaré un objet recordset directement à partir duquel CRecordsetvous devez l’utiliser GetFieldValue pour récupérer les données de champ ; l’échange de champs d’enregistrement (RFX) ou l’échange de champs d’enregistrement en bloc (RFX en bloc) n’est pas implémenté.

Remarque

Si vous déclarez un objet recordset sans dériver CRecordset, n’avez pas chargé la bibliothèque de curseurs ODBC. La bibliothèque de curseurs exige que le jeu d’enregistrements ait au moins une colonne liée ; toutefois, lorsque vous utilisez CRecordset directement, aucune des colonnes n’est liée. Les fonctions CDatabase::OpenEx membres et CDatabase::Open contrôlent si la bibliothèque de curseurs sera chargée.

GetFieldValue appelle la fonction SQLGetDataAPI ODBC . Si votre pilote génère la valeur SQL_NO_TOTAL pour la longueur réelle de la valeur de champ, GetFieldValue lève une exception. Pour plus d’informations sur SQLGetData, consultez le Kit de développement logiciel (SDK) Windows.

Exemple

L’exemple de code suivant illustre les appels à GetFieldValue un objet recordset déclaré directement à partir de CRecordset.

// Create and open a database object;
// do not load the cursor library
CDatabase db;
db.OpenEx(NULL, CDatabase::forceOdbcDialog);

// Create and open a recordset object
// directly from CRecordset. Note that a
// table must exist in a connected database.
// Use forwardOnly type recordset for best
// performance, since only MoveNext is required
CRecordset rs(&db);
rs.Open(CRecordset::forwardOnly, _T("SELECT * FROM Customer"));

// Create a CDBVariant object to
// store field data
CDBVariant varValue;

// Loop through the recordset,
// using GetFieldValue and
// GetODBCFieldCount to retrieve
// data in all columns
short nFields = rs.GetODBCFieldCount();
while (!rs.IsEOF())
{
   for (short index = 0; index < nFields; index++)
   {
      rs.GetFieldValue(index, varValue);
      // do something with varValue
   }
   rs.MoveNext();
}

rs.Close();
db.Close();

Remarque

Contrairement à la classe CDaoRecordsetDAO, CRecordset n’a pas de SetFieldValue fonction membre. Si vous créez un objet directement à partir de CRecordset, il est en lecture seule.

Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

CRecordset::GetODBCFieldCount

Récupère le nombre total de champs dans votre objet recordset.

short GetODBCFieldCount() const;

Valeur retournée

Nombre de champs dans le jeu d’enregistrements.

Notes

Pour plus d’informations sur la création d’recordsets, consultez Recordset : Création et fermeture de recordsets (ODBC).

CRecordset::GetODBCFieldInfo

Obtient des informations sur les champs du jeu d’enregistrements.

void GetODBCFieldInfo(
    LPCTSTR lpszName,
    CODBCFieldInfo& fieldinfo);

void GetODBCFieldInfo(
    short nIndex,
    CODBCFieldInfo& fieldinfo);

Paramètres

lpszName
Nom d’un champ.

fieldinfo
Référence à une CODBCFieldInfo structure.

nIndex
Index de base zéro du champ.

Notes

Une version de la fonction vous permet de rechercher un champ par nom. L’autre version vous permet de rechercher un champ par index.

Pour obtenir une description des informations retournées, consultez la CODBCFieldInfo structure.

Pour plus d’informations sur la création d’recordsets, consultez Recordset : Création et fermeture de recordsets (ODBC).

CRecordset::GetRecordCount

Détermine la taille du jeu d’enregistrements.

long GetRecordCount() const;

Valeur retournée

Nombre d’enregistrements dans le jeu d’enregistrements ; 0 si le jeu d’enregistrements ne contient aucun enregistrement ; ou -1 si le nombre d’enregistrements ne peut pas être déterminé.

Notes

Attention

Le nombre d’enregistrements est conservé sous la forme d’une « marque d’eau élevée », l’enregistrement numéroté le plus élevé, mais vu que l’utilisateur passe par les enregistrements. Le nombre total d’enregistrements est connu uniquement une fois que l’utilisateur a été déplacé au-delà du dernier enregistrement. Pour des raisons de performances, le nombre n’est pas mis à jour lorsque vous appelez MoveLast. Pour compter les enregistrements vous-même, appelez MoveNext à plusieurs reprises jusqu’à ce que IsEOF le retour ne soit pas différent de zéro. L’ajout d’un enregistrement et CRecordset:AddNewUpdate l’augmentation du nombre ; la suppression d’un enregistrement CRecordset::Delete diminue le nombre.

CRecordset::GetRowsetSize

Obtient le paramètre actuel pour le nombre de lignes que vous souhaitez récupérer lors d’une extraction donnée.

DWORD GetRowsetSize() const;

Valeur retournée

Nombre de lignes à récupérer lors d’une extraction donnée.

Notes

Si vous utilisez l’extraction de lignes en bloc, la taille d’ensemble de lignes par défaut lorsque le jeu d’enregistrements est ouvert est 25 ; sinon, c’est 1.

Pour implémenter l’extraction de lignes en bloc, vous devez spécifier l’option CRecordset::useMultiRowFetch dans le paramètre de la dwOptionsOpen fonction membre. Pour modifier le paramètre de la taille de l’ensemble de lignes, appelez SetRowsetSize.

Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

CRecordset::GetRowsFetched

Détermine le nombre d’enregistrements récupérés après une extraction.

DWORD GetRowsFetched() const;

Valeur retournée

Nombre de lignes récupérées à partir de la source de données après une extraction donnée.

Notes

Cela est utile lorsque vous avez implémenté la récupération de lignes en bloc. La taille de l’ensemble de lignes indique normalement le nombre de lignes récupérées à partir d’une extraction. Toutefois, le nombre total de lignes dans le jeu d’enregistrements affecte également le nombre de lignes récupérées dans un ensemble de lignes. Par exemple, si votre jeu d’enregistrements a 10 enregistrements avec un paramètre de taille d’ensemble de lignes de quatre, la boucle dans le jeu d’enregistrements en appelant entraîne l’appel MoveNext de l’ensemble de lignes final ayant seulement deux enregistrements.

Pour implémenter la récupération de lignes en bloc, vous devez spécifier l’option CRecordset::useMultiRowFetch dans le paramètre dwOptions de la Open fonction membre. Pour spécifier la taille de l’ensemble de lignes, appelez SetRowsetSize.

Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Exemple

CMultiCustomer rs(&m_dbCust);

// Set the rowset size
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// loop through the recordset by rowsets
while (!rs.IsEOF())
{
   for (int rowCount = 0; rowCount < (int)rs.GetRowsFetched(); rowCount++)
   {
      // do something
   }

   rs.MoveNext();
}

rs.Close();

CRecordset::GetRowStatus

Obtient l’état d’une ligne dans l’ensemble de lignes actuel.

WORD GetRowStatus(WORD wRow) const;

Paramètres

wRow
Position unique d’une ligne dans l’ensemble de lignes actuel. Cette valeur peut aller de 1 à la taille de l’ensemble de lignes.

Valeur retournée

Valeur d’état de la ligne. Pour plus d'informations, consultez Notes.

Notes

GetRowStatus retourne une valeur qui indique une modification de l’état de la ligne depuis sa dernière récupération à partir de la source de données, ou qu’aucune ligne correspondant à wRow elle n’a été extraite. Le tableau ci-dessous répertorie les valeurs de retour possibles.

Valeur d’état	Description
SQL_ROW_SUCCESS	La ligne n’est pas modifiée.
SQL_ROW_UPDATED	La ligne a été mise à jour.
SQL_ROW_DELETED	La ligne a été supprimée.
SQL_ROW_ADDED	La ligne a été ajoutée.
SQL_ROW_ERROR	La ligne n’est pas récursable en raison d’une erreur.
SQL_ROW_NOROW	Aucune ligne ne correspond à wRow.

Pour plus d’informations, consultez la fonction SQLExtendedFetch API ODBC dans le Kit de développement logiciel (SDK) Windows.

CRecordset::GetStatus

Détermine l’index de l’enregistrement actif dans le jeu d’enregistrements et indique si le dernier enregistrement a été vu.

void GetStatus(CRecordsetStatus& rStatus) const;

Paramètres

rStatus
Référence à un objet CRecordsetStatus. Pour plus d’informations, consultez Notes.

Notes

CRecordset tente de suivre l’index, mais dans certaines circonstances cela peut ne pas être possible. Consultez GetRecordCount une explication.

La CRecordsetStatus structure a la forme suivante :

struct CRecordsetStatus
{
    long m_lCurrentRecord;
    BOOL m_bRecordCountFinal;
};

Les deux membres ont CRecordsetStatus les significations suivantes :

• m_lCurrentRecord Contient l’index de base zéro de l’enregistrement actif dans le jeu d’enregistrements, s’il est connu. Si l’index ne peut pas être déterminé, ce membre contient AFX_CURRENT_RECORD_UNDEFINED (-2). Si IsBOF la valeur est TRUE (jeu d’enregistrements vide ou tentative de défilement avant le premier enregistrement), m_lCurrentRecord elle est définie sur AFX_CURRENT_RECORD_BOF (-1). Si sur le premier enregistrement, il est défini sur 0, le deuxième enregistrement 1, et ainsi de suite.

• m_bRecordCountFinal Différent de zéro si le nombre total d’enregistrements dans le jeu d’enregistrements a été déterminé. En règle générale, cela doit être effectué en commençant au début du jeu d’enregistrements et en appelant MoveNext jusqu’à ce que IsEOF le retour ne soit pas différent de zéro. Si ce membre est égal à zéro, le nombre d’enregistrements retourné par GetRecordCount, si ce n’est pas -1, n’est qu’un nombre de « marques d’eau élevées » des enregistrements.

CRecordset::GetSQL

Appelez cette fonction membre pour obtenir l’instruction SQL utilisée pour sélectionner les enregistrements du jeu d’enregistrements lorsqu’il a été ouvert.

const CString& GetSQL() const;

Valeur retournée

Référence const à une CString instruction SQL qui contient l’instruction SQL.

Notes

Il s’agit généralement d’une instruction SQL SELECT . La chaîne retournée par GetSQL est en lecture seule.

La chaîne retournée par GetSQL est généralement différente de n’importe quelle chaîne que vous avez peut-être passée au jeu d’enregistrements dans le lpszSQL paramètre à la Open fonction membre. Cela est dû au fait que le jeu d’enregistrements construit une instruction SQL complète en fonction de ce que vous avez passé à Open, de ce que vous avez spécifié avec ClassWizard, de ce que vous avez peut-être spécifié dans les m_strFilter membres et m_strSort de données, ainsi que tous les paramètres que vous avez spécifiés. Pour plus d’informations sur la façon dont le jeu d’enregistrements construit cette instruction SQL, consultez Recordset : How Recordsets Select Records (ODBC).

Remarque

Appelez cette fonction membre uniquement après l’appel Open.

CRecordset::GetTableName

Obtient le nom de la table SQL sur laquelle la requête du jeu d’enregistrements est basée.

const CString& GetTableName() const;

Valeur retournée

Référence const à un CString qui contient le nom de la table, si le jeu d’enregistrements est basé sur une table ; sinon, une chaîne vide.

Notes

GetTableName est valide uniquement si le jeu d’enregistrements est basé sur une table, et non sur une jointure de plusieurs tables ou une requête prédéfinie (procédure stockée). Le nom est en lecture seule.

Remarque

Appelez cette fonction membre uniquement après l’appel Open.

CRecordset::IsBOF

Retourne une valeur différente de zéro si le jeu d’enregistrements a été positionné avant le premier enregistrement. Il n’y a pas d’enregistrement actif.

BOOL IsBOF() const;

Valeur retournée

Différent de zéro si le jeu d’enregistrements ne contient aucun enregistrement ou si vous avez fait défiler vers l’arrière avant le premier enregistrement ; sinon 0.

Notes

Appelez cette fonction membre avant de faire défiler l’enregistrement vers l’enregistrement pour savoir si vous avez disparu avant le premier enregistrement du jeu d’enregistrements. Vous pouvez également utiliser IsBOF avec IsEOF pour déterminer si le jeu d’enregistrements contient des enregistrements ou est vide. Immédiatement après l’appel Open, si le jeu d’enregistrements ne contient aucun enregistrement, IsBOF retourne un nombre différent de zéro. Lorsque vous ouvrez un jeu d’enregistrements qui a au moins un enregistrement, le premier enregistrement est l’enregistrement actif et IsBOF retourne 0.

Si le premier enregistrement est l’enregistrement actif et que vous appelez MovePrev, IsBOF retourne un résultat différent de zéro. Si IsBOF elle retourne un nombre différent de zéro et que vous appelez MovePrev, une erreur se produit. Si IsBOF cette propriété renvoie une valeur différente de zéro, l’enregistrement actif n’est pas défini et toute action nécessitant un enregistrement actif entraîne une erreur.

Exemple

Cet exemple utilise IsBOF et IsEOF détecte les limites d’un jeu d’enregistrements lorsque le code fait défiler le jeu d’enregistrements dans les deux sens.

// Open a recordset; first record is current
// Open a recordset; first record is current
CCustomer rsCustSet(&m_dbCust);
rsCustSet.Open();

if(rsCustSet.IsBOF())
   return;
   // The recordset is empty

// Scroll to the end of the recordset, past
// the last record, so no record is current
while (!rsCustSet.IsEOF())
   rsCustSet.MoveNext();

// Move to the last record
rsCustSet.MoveLast();

// Scroll to beginning of the recordset, before
// the first record, so no record is current
while(!rsCustSet.IsBOF())
   rsCustSet.MovePrev();

// First record is current again
rsCustSet.MoveFirst();

CRecordset::IsDeleted

Détermine si l’enregistrement actif a été supprimé.

BOOL IsDeleted() const;

Valeur retournée

Différent de zéro si le jeu d’enregistrements est positionné sur un enregistrement supprimé ; sinon 0.

Notes

Si vous faites défiler jusqu’à un enregistrement et IsDeleted retourne TRUE (différent de zéro), vous devez faire défiler vers un autre enregistrement avant de pouvoir effectuer d’autres opérations d’ensemble d’enregistrements.

Le résultat dépend de IsDeleted nombreux facteurs, tels que le type de jeu d’enregistrements, si votre jeu d’enregistrements est mis à jour, si vous avez spécifié l’option CRecordset::skipDeletedRecords lorsque vous avez ouvert le jeu d’enregistrements, si vos packs de pilotes ont supprimé des enregistrements et s’il existe plusieurs utilisateurs.

Pour plus d’informations sur l’empaquetage CRecordset::skipDeletedRecords des pilotes, consultez la fonction De membre Open .

Remarque

Si vous avez implémenté la récupération de lignes en bloc, vous ne devez pas appeler IsDeleted. Au lieu de cela, appelez la fonction membre GetRowStatus . Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

CRecordset::IsEOF

Retourne une valeur différente de zéro si le jeu d’enregistrements a été positionné après le dernier enregistrement. Il n’y a pas d’enregistrement actif.

BOOL IsEOF() const;

Valeur retournée

Différent de zéro si le jeu d’enregistrements ne contient aucun enregistrement ou si vous avez fait défiler au-delà du dernier enregistrement ; sinon 0.

Notes

Appelez cette fonction membre lorsque vous faites défiler l’enregistrement vers l’enregistrement pour savoir si vous avez dépassé le dernier enregistrement du jeu d’enregistrements. Vous pouvez également utiliser IsEOF pour déterminer si le jeu d’enregistrements contient des enregistrements ou est vide. Immédiatement après l’appel Open, si le jeu d’enregistrements ne contient aucun enregistrement, IsEOF retourne un nombre différent de zéro. Lorsque vous ouvrez un jeu d’enregistrements qui a au moins un enregistrement, le premier enregistrement est l’enregistrement actif et IsEOF retourne 0.

Si le dernier enregistrement est l’enregistrement actif lorsque vous appelez MoveNext, IsEOF retourne un résultat différent de zéro. Si IsEOF elle retourne un nombre différent de zéro et que vous appelez MoveNext, une erreur se produit. Si IsEOF cette propriété renvoie une valeur différente de zéro, l’enregistrement actif n’est pas défini et toute action nécessitant un enregistrement actif entraîne une erreur.

Exemple

Consultez l’exemple pour IsBOF.

CRecordset::IsFieldDirty

Détermine si le membre de données de champ spécifié a été modifié depuis Edit ou AddNew a été appelé.

BOOL IsFieldDirty(void* pv);

Paramètres

pv
Pointeur vers le membre de données de champ dont l’état vous souhaitez case activée, ou NULL pour déterminer si l’un des champs est sale.

Valeur retournée

Différent de zéro si le membre de données de champ spécifié a changé depuis l’appel AddNew ou Edit; sinon 0.

Notes

Les données de tous les membres de données de champ sale sont transférées vers l’enregistrement sur la source de données lorsque l’enregistrement actif est mis à jour par un appel à la Update fonction membre de CRecordset (après un appel à ou AddNew).Edit

Remarque

Cette fonction membre n’est pas applicable sur les jeux d’enregistrements qui utilisent l’extraction de lignes en bloc. Si vous avez implémenté la récupération de lignes en bloc, retourne IsFieldDirty toujours FALSE et entraîne une assertion ayant échoué. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

L’appel IsFieldDirty réinitialise les effets des appels précédents à SetFieldDirty, car l’état sale du champ est réévalué. Dans le AddNew cas, si la valeur de champ actuelle diffère de la valeur pseudo null, l’état du champ est défini sale. Dans le Edit cas, si la valeur du champ diffère de la valeur mise en cache, l’état du champ est défini sale.

IsFieldDirty est implémenté par le biais DoFieldExchangede .

Pour plus d’informations sur l’indicateur sale, consultez Recordset : How Recordsets Select Recordsets Select Records (ODBC).

CRecordset::IsFieldNull

Retourne une valeur différente de zéro si le champ spécifié dans l’enregistrement actif est Null (n’a aucune valeur).

BOOL IsFieldNull(void* pv);

Paramètres

pv
Pointeur vers le membre de données de champ dont l’état vous souhaitez case activée, ou NULL pour déterminer si l’un des champs est Null.

Valeur retournée

Différent de zéro si le membre de données de champ spécifié est marqué comme Null ; sinon 0.

Notes

Appelez cette fonction membre pour déterminer si le membre de données de champ spécifié d’un recordset a été marqué comme Null. (Dans la terminologie de la base de données, Null signifie « sans valeur » et n’est pas identique NULL à C++.) Si un membre de données de champ est marqué comme Null, il est interprété comme une colonne de l’enregistrement actif pour laquelle il n’existe aucune valeur.

Remarque

Cette fonction membre n’est pas applicable sur les jeux d’enregistrements qui utilisent l’extraction de lignes en bloc. Si vous avez implémenté l’extraction de lignes en bloc, elle IsFieldNull retourne FALSE toujours et entraîne une assertion ayant échoué. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

IsFieldNull est implémenté par le biais DoFieldExchangede .

CRecordset::IsFieldNullable

Retourne une valeur différente de zéro si le champ spécifié dans l’enregistrement actif peut être défini sur Null (sans valeur).

BOOL IsFieldNullable(void* pv);

Paramètres

pv
Pointeur vers le membre de données de champ dont l’état vous souhaitez case activée, ou NULL pour déterminer si l’un des champs peut être défini sur une valeur Null.

Notes

Appelez cette fonction membre pour déterminer si le membre de données de champ spécifié est « nullable » (peut être défini sur une valeur Null ; C++ NULL n’est pas identique à Null, ce qui, dans la terminologie de la base de données, signifie « sans valeur »).

Remarque

Si vous avez implémenté la récupération de lignes en bloc, vous ne pouvez pas appeler IsFieldNullable. Au lieu de cela, appelez la GetODBCFieldInfo fonction membre pour déterminer si un champ peut être défini sur une valeur Null. Vous pouvez toujours appeler GetODBCFieldInfo, que vous ayez implémenté la récupération de lignes en bloc. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Un champ qui ne peut pas être Null doit avoir une valeur. Si vous tentez de définir un tel champ sur Null lors de l’ajout ou de la mise à jour d’un enregistrement, la source de données rejette l’ajout ou la mise à jour et Update lève une exception. L’exception se produit lorsque vous appelez Update, et non lorsque vous appelez SetFieldNull.

L’utilisation NULL pour le premier argument de la fonction applique la fonction uniquement aux champs, et non param aux outputColumn champs. Par exemple, l’appel

SetFieldNull(NULL);

définit uniquement outputColumn les champs NULLsur ; param les champs ne sont pas affectés.

Pour travailler sur param des champs, vous devez fournir l’adresse réelle de la personne param sur laquelle vous souhaitez travailler, par exemple :

SetFieldNull(&m_strParam);

Cela signifie que vous ne pouvez pas définir tous les param champs NULLsur , comme vous le pouvez avec outputColumn les champs.

IsFieldNullable est implémenté via DoFieldExchange.

CRecordset::IsOpen

Détermine si le jeu d’enregistrements est déjà ouvert.

BOOL IsOpen() const;

Valeur retournée

Différent de zéro si la fonction membre ou Requery l’objet Open recordset a été appelée précédemment et que le jeu d’enregistrements n’a pas été fermé ; sinon, 0.

CRecordset::m_hstmt

Contient un handle pour la structure de données d’instruction ODBC, de type HSTMT, associée au jeu d’enregistrements.

Notes

Chaque requête vers une source de données ODBC est associée à un HSTMT.

Attention

N’utilisez m_hstmt pas avant Open d’être appelée.

Normalement, vous n’avez pas besoin d’accéder directement HSTMT , mais vous en aurez peut-être besoin pour l’exécution directe d’instructions SQL. La ExecuteSQL fonction membre de classe CDatabase fournit un exemple d’utilisation m_hstmt.

CRecordset::m_nFields

Contient le nombre de membres de données de champ dans la classe recordset ; autrement dit, le nombre de colonnes sélectionnées par le jeu d’enregistrements de la source de données.

Notes

Le constructeur de la classe recordset doit initialiser m_nFields avec le nombre correct. Si vous n’avez pas implémenté la récupération de lignes en bloc, ClassWizard écrit cette initialisation lorsque vous l’utilisez pour déclarer votre classe recordset. Vous pouvez également l’écrire manuellement.

L’infrastructure utilise ce nombre pour gérer l’interaction entre les membres de données de champ et les colonnes correspondantes de l’enregistrement actif sur la source de données.

Attention

Ce nombre doit correspondre au nombre de « colonnes de sortie » inscrites ou DoFieldExchangeDoBulkFieldExchange après un appel au SetFieldType paramètre CFieldExchange::outputColumn.

Vous pouvez lier dynamiquement des colonnes, comme expliqué dans l’article « Recordset : Liaison dynamique des colonnes de données ». Si vous le faites, vous devez augmenter le nombre m_nFields pour refléter le nombre d’appels de fonction RFX ou RFX en bloc dans votre DoFieldExchangeDoBulkFieldExchange ou fonction membre pour les colonnes liées dynamiquement.

Pour plus d’informations, consultez les articles Recordset : Liaison dynamique de colonnes de données (ODBC) et recordset : extraction d’enregistrements en bloc (ODBC).

Exemple

voir Record Field Exchange : Utilisation de RFX.

CRecordset::m_nParams

Contient le nombre de membres de données de paramètre dans la classe recordset ; autrement dit, le nombre de paramètres passés avec la requête du jeu d’enregistrements.

Notes

Si votre classe recordset a des membres de données de paramètre, le constructeur de la classe doit initialiser m_nParams avec le nombre correct. m_nParams Valeur par défaut 0. Si vous ajoutez des membres de données de paramètre (que vous devez faire manuellement), vous devez également ajouter manuellement une initialisation dans le constructeur de classe pour refléter le nombre de paramètres (qui doivent être au moins aussi volumineux que le nombre d’espaces réservés « » dans votre m_strFilter ou m_strSort chaîne).

L’infrastructure utilise ce nombre lorsqu’il paramétre la requête du jeu d’enregistrements.

Attention

Ce nombre doit correspondre au nombre de « params » inscrits dans DoFieldExchange ou DoBulkFieldExchange après un appel à avec SetFieldType une valeur de paramètre de CFieldExchange::inputParam, CFieldExchange::param, CFieldExchange::outputParamou CFieldExchange::inoutParam.

Exemple

Consultez les articles Recordset : Parameterizing a Recordset (ODBC) and Record Field Exchange : Using RFX.

CRecordset::m_pDatabase

Contient un pointeur vers l’objet CDatabase via lequel le jeu d’enregistrements est connecté à une source de données.

Notes

Cette variable est définie de deux façons. En règle générale, vous passez un pointeur vers un objet déjà connecté CDatabase lorsque vous construisez l’objet recordset. Si vous passez NULL à la place, CRecordset crée un CDatabase objet pour vous et le connecte. Dans les deux cas, CRecordset stocke le pointeur dans cette variable.

Normalement, vous n’aurez pas besoin directement d’utiliser le pointeur stocké dans m_pDatabase. Toutefois, si vous écrivez vos propres extensions CRecordset, vous devrez peut-être utiliser le pointeur. Par exemple, vous aurez peut-être besoin du pointeur si vous lèvez vos propres CDBExceptions. Vous devrez peut-être le faire si vous avez besoin d’effectuer quelque chose à l’aide du même CDatabase objet, comme l’exécution de transactions, la définition de délais d’expiration ou l’appel de la ExecuteSQL fonction membre de classe CDatabase pour exécuter des instructions SQL directement.

CRecordset::m_strFilter

Après avoir construit l’objet recordset, mais avant d’appeler sa Open fonction membre, utilisez ce membre de données pour stocker une CString clause SQL WHERE contenant.

Notes

Le jeu d’enregistrements utilise cette chaîne pour limiter (ou filtrer) les enregistrements qu’il sélectionne pendant l’appel ou Requery l’appelOpen. Cela est utile pour sélectionner un sous-ensemble d’enregistrements, tel que « tous les vendeurs basés en Californie » (« state = CA »). La syntaxe ODBC SQL pour une WHERE clause est

WHERE search-condition

N’incluez pas les WHERE mot clé dans votre chaîne. Le framework le fournit.

Vous pouvez également paramétrer votre chaîne de filtre en plaçant des espaces réservés « » dans celui-ci, en déclarant un membre de données de paramètre dans votre classe pour chaque espace réservé et en passant des paramètres au jeu d’enregistrements au moment de l’exécution. Cela vous permet de construire le filtre au moment de l’exécution. Pour plus d’informations, consultez Recordset : Paramétrage d’un recordset (ODBC).

Pour plus d’informations sur les clauses SQL WHERE , consultez SQL. Pour plus d’informations sur la sélection et le filtrage des enregistrements, consultez Recordset : Filtrage des enregistrements (ODBC)

Exemple

CCustomer rsCustSet(&m_dbCust);

// Set the filter
rsCustSet.m_strFilter = _T("L_Name = 'Flanders'");

// Run the filtered query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

CRecordset::m_strSort

Après avoir construit l’objet recordset, mais avant d’appeler sa Open fonction membre, utilisez ce membre de données pour stocker une CString clause SQL ORDER BY contenant.

Notes

Le jeu d’enregistrements utilise cette chaîne pour trier les enregistrements qu’il sélectionne pendant l’appel ou Requery l’appelOpen. Vous pouvez utiliser cette fonctionnalité pour trier un jeu d’enregistrements sur une ou plusieurs colonnes. La syntaxe ODBC SQL pour une ORDER BY clause est

ORDER BY sort-specification [, sort-specification]...

où une spécification de tri est un entier ou un nom de colonne. Vous pouvez également spécifier l’ordre croissant ou décroissant (l’ordre est croissant par défaut) en ajoutant « ASC » ou « DESC » à la liste de colonnes dans la chaîne de tri. Les enregistrements sélectionnés sont triés en premier par la première colonne répertoriée, puis par la seconde, et ainsi de suite. Par exemple, vous pouvez commander un recordset « Customers » par nom, puis prénom. Le nombre de colonnes que vous pouvez répertorier dépend de la source de données. Pour plus d’informations, consultez le Kit de développement logiciel (SDK) Windows.

N’incluez pas les ORDER BY mot clé dans votre chaîne. Le framework le fournit.

Pour plus d’informations sur les clauses SQL, consultez SQL. Pour plus d’informations sur le tri des enregistrements, consultez Recordset : Tri d’enregistrements (ODBC).

Exemple

CCustomer rsCustSet(&m_dbCust);

// Set the sort string
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");

// Run the sorted query
rsCustSet.Open(CRecordset::snapshot, _T("Customer"));

CRecordset::Move

Déplace le pointeur d’enregistrement actif dans le jeu d’enregistrements, vers l’avant ou vers l’arrière.

virtual void Move(
    long nRows,
    WORD wFetchType = SQL_FETCH_RELATIVE);

Paramètres

nRows
Nombre de lignes à déplacer vers l’avant ou vers l’arrière. Les valeurs positives avancent vers la fin du jeu d’enregistrements. Les valeurs négatives se déplacent vers l’arrière, vers le début.

wFetchType
Détermine l’ensemble de lignes à Move extraire. Pour plus d'informations, consultez Notes.

Notes

Si vous passez une valeur de 0 pour nRows, Move actualise l’enregistrement actif ; Move met fin à tout mode ou Edit actuel AddNew et restaure la valeur de l’enregistrement actif avant AddNew ou Edit a été appelée.

Remarque

Lorsque vous parcourez un jeu d’enregistrements, vous ne pouvez pas ignorer les enregistrements supprimés. Consultez la rubrique CRecordset::IsDeleted (éventuellement en anglais) pour plus d'informations. Lorsque vous ouvrez un jeu d’options CRecordset avec l’option skipDeletedRecords définie, Move affirme si le nRows paramètre est 0. Ce comportement empêche l’actualisation des lignes supprimées par d’autres applications clientes à l’aide des mêmes données. Consultez le dwOption paramètre dans Open pour obtenir une description de skipDeletedRecords.

Move repositionne le jeu d’enregistrements par ensembles de lignes. En fonction des valeurs pour nRows et wFetchType, Move extrait l’ensemble de lignes approprié, puis effectue le premier enregistrement dans cet ensemble de lignes l’enregistrement actif. Si vous n’avez pas implémenté la récupération de lignes en bloc, la taille de l’ensemble de lignes est toujours 1. Lors de l’extraction d’un ensemble de lignes, Move appelle directement la CheckRowsetError fonction membre pour gérer les erreurs résultant de la récupération.

Selon les valeurs que vous transmettez, Move équivaut à d’autres CRecordset fonctions membres. En particulier, la valeur de wFetchType peut indiquer une fonction membre plus intuitive et souvent la méthode préférée pour déplacer l’enregistrement actif.

Le tableau suivant répertorie les valeurs possibles pour wFetchType, l’ensemble de lignes qui Move va extraire en wFetchType fonction et nRows, et toute fonction membre équivalente correspondant à wFetchType.

wFetchType	Ensemble de lignes extrait	Fonction membre équivalente
SQL_FETCH_RELATIVE (valeur par défaut)	Ensemble de lignes commençant nRows la ou les lignes de la première ligne de l’ensemble de lignes actuel.
SQL_FETCH_NEXT	Ensemble de lignes suivant ; nRows est ignoré.	MoveNext
SQL_FETCH_PRIOR	Ensemble de lignes précédent ; nRows est ignoré.	MovePrev
SQL_FETCH_FIRST	Premier ensemble de lignes dans le jeu d’enregistrements ; nRows est ignoré.	MoveFirst
SQL_FETCH_LAST	Dernier ensemble de lignes complet dans le jeu d’enregistrements ; nRows est ignoré.	MoveLast
SQL_FETCH_ABSOLUTE	Si nRows> 0, le ou les lignes de départ nRows de l’ensemble de lignes à partir du début du jeu d’enregistrements. Si nRows< 0, le ou les lignes de départ nRows de l’ensemble de lignes à partir de la fin du jeu d’enregistrements. Si nRows = 0, une condition de début de fichier (BOF) est retournée.	SetAbsolutePosition
SQL_FETCH_BOOKMARK	Ensemble de lignes commençant à la ligne dont la valeur de signet correspond à nRows.	SetBookmark

Remarque

Pour les jeux d’enregistrements en avant uniquement, Move n’est valide qu’avec une valeur de SQL_FETCH_NEXTwFetchType.

Attention

L’appel Move lève une exception si le jeu d’enregistrements n’a pas d’enregistrements. Pour déterminer si le jeu d’enregistrements a des enregistrements, appelez IsBOF et IsEOF.

Remarque

Si vous avez fait défiler le jeu d’enregistrements au-delà du début ou de la fin du jeu d’enregistrements (IsBOF ou IsEOF retourne un nombre différent de zéro), l’appel d’une Move fonction lève peut-être un CDBException. Par exemple, si IsEOF elle retourne un non-zéro et IsBOF ne lève pas d’exception, MoveNext mais MovePrev ne lève pas.

Remarque

Si vous appelez Move pendant la mise à jour ou l’ajout de l’enregistrement actif, les mises à jour sont perdues sans avertissement.

Pour plus d’informations sur la navigation dans le jeu d’enregistrements, consultez les articles Recordset : Scrolling (ODBC) et Recordset : Bookmarks and Absolute Positions (ODBC). Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC). Pour plus d’informations, consultez la fonction SQLExtendedFetch API ODBC dans le Kit de développement logiciel (SDK) Windows.

Exemple

// rs is a CRecordset or a CRecordset-derived object

// Change the rowset size to 5
rs.SetRowsetSize(5);

// Open the recordset
rs.Open(CRecordset::dynaset, NULL, CRecordset::useMultiRowFetch);

// Move to the first record in the recordset
rs.MoveFirst();

// Move to the sixth record
rs.Move(5);
// Other equivalent ways to move to the sixth record:
rs.Move(6, SQL_FETCH_ABSOLUTE);
rs.SetAbsolutePosition(6);
// In this case, the sixth record is the first record in the next rowset,
// so the following are also equivalent:
rs.MoveFirst();
rs.Move(1, SQL_FETCH_NEXT);

rs.MoveFirst();
rs.MoveNext();

CRecordset::MoveFirst

Fait du premier enregistrement du premier ensemble de lignes l’enregistrement actif.

void MoveFirst();

Notes

Que l’extraction de lignes en bloc ait été implémentée, il s’agit toujours du premier enregistrement dans le jeu d’enregistrements.

Vous n’avez pas besoin d’appeler MoveFirst immédiatement après avoir ouvert le jeu d’enregistrements. À ce stade, le premier enregistrement (le cas échéant) est automatiquement l’enregistrement actif.

Remarque

Cette fonction membre n’est pas valide pour les jeux d’enregistrements en avant uniquement.

Remarque

Lorsque vous parcourez un jeu d’enregistrements, vous ne pouvez pas ignorer les enregistrements supprimés. Pour plus d’informations, consultez la IsDeleted fonction membre.

Attention

L’appel d’une des Move fonctions lève une exception si le jeu d’enregistrements n’a pas d’enregistrements. Pour déterminer si le jeu d’enregistrements a des enregistrements, appelez IsBOF et IsEOF.

Remarque

Si vous appelez l’une des Move fonctions pendant que l’enregistrement actif est mis à jour ou ajouté, les mises à jour sont perdues sans avertissement.

Pour plus d’informations sur la navigation dans le jeu d’enregistrements, consultez les articles Recordset : Scrolling (ODBC) et Recordset : Bookmarks and Absolute Positions (ODBC). Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Exemple

Consultez l’exemple pour IsBOF.

CRecordset::MoveLast

Fait du premier enregistrement du dernier ensemble de lignes complet l’enregistrement actif.

void MoveLast();

Notes

Si vous n’avez pas implémenté la récupération de lignes en bloc, votre jeu d’enregistrements a une taille d’ensemble de lignes de 1, donc MoveLast passe au dernier enregistrement dans le jeu d’enregistrements.

Remarque

Cette fonction membre n’est pas valide pour les jeux d’enregistrements en avant uniquement.

Remarque

Lorsque vous parcourez un jeu d’enregistrements, vous ne pouvez pas ignorer les enregistrements supprimés. Pour plus d’informations, consultez la IsDeleted fonction membre.

Attention

L’appel d’une des Move fonctions lève une exception si le jeu d’enregistrements n’a pas d’enregistrements. Pour déterminer si le jeu d’enregistrements a des enregistrements, appelez IsBOF et IsEOF.

Remarque

Si vous appelez l’une des Move fonctions pendant que l’enregistrement actif est mis à jour ou ajouté, les mises à jour sont perdues sans avertissement.

Pour plus d’informations sur la navigation dans le jeu d’enregistrements, consultez les articles Recordset : Scrolling (ODBC) et Recordset : Bookmarks and Absolute Positions (ODBC). Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Exemple

Consultez l’exemple pour IsBOF.

CRecordset::MoveNext

Rend le premier enregistrement dans l’ensemble de lignes suivant l’enregistrement actif.

void MoveNext();

Notes

Si vous n’avez pas implémenté la récupération de lignes en bloc, votre jeu d’enregistrements a une taille d’ensemble de lignes de 1, donc MoveNext passe à l’enregistrement suivant.

Remarque

Lorsque vous parcourez un jeu d’enregistrements, vous ne pouvez pas ignorer les enregistrements supprimés. Pour plus d’informations, consultez la IsDeleted fonction membre.

Attention

L’appel d’une des Move fonctions lève une exception si le jeu d’enregistrements n’a pas d’enregistrements. Pour déterminer si le jeu d’enregistrements a des enregistrements, appelez IsBOF et IsEOF.

Remarque

Il est également recommandé d’appeler avant d’appeler IsEOFMoveNext. Par exemple, si vous avez fait défiler l’objet d’un défilement au-delà de la fin du jeu d’enregistrements, IsEOF retourne un non-zéro ; un appel suivant lève MoveNext une exception.

Remarque

Si vous appelez l’une des Move fonctions pendant que l’enregistrement actif est mis à jour ou ajouté, les mises à jour sont perdues sans avertissement.

Pour plus d’informations sur la navigation dans le jeu d’enregistrements, consultez les articles Recordset : Scrolling (ODBC) et Recordset : Bookmarks and Absolute Positions (ODBC). Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Exemple

Consultez l’exemple pour IsBOF.

CRecordset::MovePrev

Fait du premier enregistrement de l’ensemble de lignes précédent l’enregistrement actif.

void MovePrev();

Notes

Si vous n’avez pas implémenté la récupération de lignes en bloc, votre jeu d’enregistrements a une taille d’ensemble de lignes de 1, donc MovePrev passe à l’enregistrement précédent.

Remarque

Cette fonction membre n’est pas valide pour les jeux d’enregistrements en avant uniquement.

Remarque

Lorsque vous parcourez un jeu d’enregistrements, vous ne pouvez pas ignorer les enregistrements supprimés. Pour plus d’informations, consultez la IsDeleted fonction membre.

Attention

L’appel d’une des Move fonctions lève une exception si le jeu d’enregistrements n’a pas d’enregistrements. Pour déterminer si le jeu d’enregistrements a des enregistrements, appelez IsBOF et IsEOF.

Remarque

Il est également recommandé d’appeler avant d’appeler IsBOFMovePrev. Par exemple, si vous avez fait défiler le jeu d’enregistrements avant le début du jeu d’enregistrements, IsBOF retourne un non-zéro ; un appel ultérieur pour MovePrev lever une exception.

Remarque

Si vous appelez l’une des Move fonctions pendant que l’enregistrement actif est mis à jour ou ajouté, les mises à jour sont perdues sans avertissement.

Pour plus d’informations sur la navigation dans le jeu d’enregistrements, consultez les articles Recordset : Scrolling (ODBC) et Recordset : Bookmarks and Absolute Positions (ODBC). Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Exemple

Consultez l’exemple pour IsBOF.

CRecordset::OnSetOptions

Appelé pour définir des options (utilisées sur la sélection) pour l’instruction ODBC spécifiée.

virtual void OnSetOptions(HSTMT hstmt);

Paramètres

hstmt
Instruction HSTMT ODBC dont les options doivent être définies.

Notes

Appelez OnSetOptions les options de définition (utilisées lors de la sélection) pour l’instruction ODBC spécifiée. L’infrastructure appelle cette fonction membre pour définir les options initiales du jeu d’enregistrements. OnSetOptions détermine la prise en charge de la source de données pour les curseurs défilants et pour la concurrence des curseurs et définit les options du jeu d’enregistrements en conséquence. (Alors qu’elle OnSetOptions est utilisée pour les opérations de sélection, OnSetUpdateOptions est utilisée pour les opérations de mise à jour.)

Remplacez le paramètre OnSetOptions pour définir des options spécifiques au pilote ou à la source de données. Par exemple, si votre source de données prend en charge l’ouverture d’un accès exclusif, vous pouvez remplacer OnSetOptions pour tirer parti de cette capacité.

Pour plus d’informations sur les curseurs, consultez ODBC.

CRecordset::OnSetUpdateOptions

Appelé pour définir les options (utilisées lors de la mise à jour) pour l’instruction ODBC spécifiée.

virtual void OnSetUpdateOptions(HSTMT hstmt);

Paramètres

hstmt
Instruction HSTMT ODBC dont les options doivent être définies.

Notes

Appelez OnSetUpdateOptions les options de définition (utilisées lors de la mise à jour) pour l’instruction ODBC spécifiée. L’infrastructure appelle cette fonction membre après avoir créé un HSTMT enregistrement pour mettre à jour les enregistrements dans un jeu d’enregistrements. (Alors qu’elle OnSetOptions est utilisée pour les opérations de sélection, OnSetUpdateOptions est utilisée pour les opérations de mise à jour.) OnSetUpdateOptions détermine la prise en charge de la source de données pour les curseurs défilants et pour la concurrence des curseurs et définit les options du jeu d’enregistrements en conséquence.

Remplacez OnSetUpdateOptions les options d’une instruction ODBC avant que cette instruction ne soit utilisée pour accéder à une base de données.

Pour plus d’informations sur les curseurs, consultez ODBC.

CRecordset::Open

Ouvre le jeu d’enregistrements en récupérant la table ou en effectuant la requête que représente le jeu d’enregistrements.

virtual BOOL Open(
    UINT nOpenType = AFX_DB_USE_DEFAULT_TYPE,
    LPCTSTR lpszSQL = NULL,
    DWORD dwOptions = none);

Paramètres

nOpenType
Acceptez la valeur par défaut, AFX_DB_USE_DEFAULT_TYPEou utilisez l’une des valeurs suivantes à partir de :enum OpenType

• CRecordset::dynaset Jeu d’enregistrements avec défilement bidirectionnel. L’ouverture du jeu d’enregistrements détermine l’appartenance et l’ordre des enregistrements, mais les modifications apportées par d’autres utilisateurs aux valeurs de données sont visibles en suivant une opération d’extraction. Les jeux de feuilles de réponse dynamique sont également appelés jeux d’enregistrements pilotés par des jeux de clés.

• CRecordset::snapshot Jeu d’enregistrements statique avec défilement bidirectionnel. L’ouverture du jeu d’enregistrements détermine l’appartenance et l’ordre des enregistrements. L’extraction d’un enregistrement détermine les valeurs de données. Les modifications apportées par d’autres utilisateurs ne sont pas visibles tant que le jeu d’enregistrements n’est pas fermé, puis rouvert.

• CRecordset::dynamic Jeu d’enregistrements avec défilement bidirectionnel. Les modifications apportées par d’autres utilisateurs aux valeurs d’appartenance, de classement et de données sont visibles après une opération d’extraction. De nombreux pilotes ODBC ne prennent pas en charge ce type d’ensemble d’enregistrements.

• CRecordset::forwardOnly Jeu d’enregistrements en lecture seule avec défilement vers l’avant uniquement.

  Pour CRecordset, la valeur par défaut est CRecordset::snapshot. Le mécanisme par défaut permet aux Assistants Visual C++ d’interagir avec ODBC CRecordset et DAO CDaoRecordset, qui ont des valeurs par défaut différentes.

Pour plus d’informations sur ces types d’recordsets, consultez Recordset (ODBC). Pour plus d’informations, consultez « Utilisation des curseurs bloc et défilement » dans le Kit de développement logiciel (SDK) Windows.

Attention

Si le type demandé n’est pas pris en charge, l’infrastructure lève une exception.

lpszSQL
Pointeur de chaîne contenant l’un des éléments suivants :

• Pointeur NULL .

• Nom d'une table.

• Instruction SQL SELECT (éventuellement avec un sql WHERE ou ORDER BY une clause).

• Instruction CALL spécifiant le nom d’une requête prédéfinie (procédure stockée). Veillez à ne pas insérer d’espace blanc entre l’accolades et le CALL mot clé.

Pour plus d’informations sur cette chaîne, consultez le tableau et la discussion du rôle de ClassWizard dans la section Remarques .

Remarque

L’ordre des colonnes de votre jeu de résultats doit correspondre à l’ordre des appels de fonction RFX ou RFX en bloc dans votre DoFieldExchange remplacement de fonction.DoBulkFieldExchange

dwOptions
Masque de bits, qui peut spécifier une combinaison des valeurs répertoriées ci-dessous. Certains d’entre eux s’excluent mutuellement. La valeur par défaut est none.

• CRecordset::none Aucune option définie. Cette valeur de paramètre s’exclue mutuellement avec toutes les autres valeurs. Par défaut, le jeu d’enregistrements peut être mis à jour avec Edit ou Delete autorise l’ajout de nouveaux enregistrements avec AddNew. La mise à jour dépend de la source de données et de l’option nOpenType que vous spécifiez. L’optimisation des ajouts en bloc n’est pas disponible. L’extraction de lignes en bloc n’est pas implémentée. Les enregistrements supprimés ne seront pas ignorés pendant la navigation de jeu d’enregistrements. Les signets ne sont pas disponibles. Le case activée de champ de sale automatique est implémenté.

• CRecordset::appendOnly Ne pas autoriser Edit ou Delete sur le jeu d’enregistrements. Autorisez AddNew uniquement. Cette option s’exclue mutuellement avec CRecordset::readOnly.

• CRecordset::readOnly Ouvrez le jeu d’enregistrements en lecture seule. Cette option s’exclue mutuellement avec CRecordset::appendOnly.

• CRecordset::optimizeBulkAdd Utilisez une instruction SQL préparée pour optimiser l’ajout de nombreux enregistrements à la fois. S’applique uniquement si vous n’utilisez pas la fonction SQLSetPos API ODBC pour mettre à jour le jeu d’enregistrements. La première mise à jour détermine les champs marqués sale. Cette option s’exclue mutuellement avec CRecordset::useMultiRowFetch.

• CRecordset::useMultiRowFetch Implémentez l’extraction de lignes en bloc pour permettre à plusieurs lignes d’être récupérées dans une seule opération d’extraction. Il s’agit d’une fonctionnalité avancée conçue pour améliorer les performances ; toutefois, l’échange de champs d’enregistrement en bloc n’est pas pris en charge par ClassWizard. Cette option s’exclue mutuellement avec CRecordset::optimizeBulkAdd. Si vous spécifiez CRecordset::useMultiRowFetch, l’option est activée automatiquement (la double mise en mémoire tampon n’est pas disponible) ; sur les jeux d’enregistrements en avant uniquement, l’option CRecordset::noDirtyFieldCheckCRecordset::useExtendedFetch est activée automatiquement. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

• CRecordset::skipDeletedRecords Ignorez tous les enregistrements supprimés lors de la navigation dans le jeu d’enregistrements. Cela ralentit les performances dans certaines extractions relatives. Cette option n’est pas valide sur les jeux d’enregistrements en avant uniquement. Si vous appelez Move avec le paramètre nRows défini sur 0 et que l’option CRecordset::skipDeletedRecords définie, Move s’affirme. CRecordset::skipDeletedRecords est similaire à la compression du pilote, ce qui signifie que les lignes supprimées sont supprimées du jeu d’enregistrements. Toutefois, si vos enregistrements packs de pilotes, il ignore uniquement les enregistrements que vous supprimez ; il n’ignore pas les enregistrements supprimés par d’autres utilisateurs pendant que le jeu d’enregistrements est ouvert. CRecordset::skipDeletedRecords ignore les lignes supprimées par d’autres utilisateurs.

• CRecordset::useBookmarks Peut utiliser des signets sur le jeu d’enregistrements, si pris en charge. Les signets ralentissent la récupération des données, mais améliorent les performances pour la navigation des données. Non valide sur les jeux d’enregistrements en transfert uniquement. Pour plus d’informations, consultez Recordset : Signets et positions absolues (ODBC).

• CRecordset::noDirtyFieldCheckDésactivez le champ de sale automatique case activée ing (double mise en mémoire tampon). Cela permettra d’améliorer les performances ; Toutefois, vous devez marquer manuellement les champs comme sale en appelant les fonctions membres et SetFieldNull les SetFieldDirty fonctions membres. La double mise en mémoire tampon dans la classe CRecordset est similaire à la double mise en mémoire tampon dans la classe CDaoRecordset. Toutefois, dans CRecordset, vous ne pouvez pas activer la mise en mémoire tampon double sur des champs individuels ; vous l’activez pour tous les champs ou désactivez-le pour tous les champs. Si vous spécifiez l’option CRecordset::useMultiRowFetch, elle CRecordset::noDirtyFieldCheck est activée automatiquement . Toutefois, SetFieldDirty elle SetFieldNull ne peut pas être utilisée sur les jeux d’enregistrements qui implémentent l’extraction de lignes en bloc.

• CRecordset::executeDirect N’utilisez pas d’instruction SQL préparée. Pour améliorer les performances, spécifiez cette option si la Requery fonction membre ne sera jamais appelée.

• CRecordset::useExtendedFetch Implémenter SQLExtendedFetch au lieu de SQLFetch. Cela est conçu pour implémenter l’extraction de lignes en bloc sur les jeux d’enregistrements en avant uniquement. Si vous spécifiez l’option CRecordset::useMultiRowFetch sur un jeu d’enregistrements en avant uniquement, elle CRecordset::useExtendedFetch est activée automatiquement.

• CRecordset::userAllocMultiRowBuffers L’utilisateur alloue des mémoires tampons de stockage pour les données. Utilisez cette option CRecordset::useMultiRowFetch si vous souhaitez allouer votre propre stockage. Sinon, l’infrastructure alloue automatiquement le stockage nécessaire. Pour plus d’informations, consultez Recordset : Extraction d’enregistrements en bloc (ODBC). La spécification CRecordset::userAllocMultiRowBuffers sans spécification de CRecordset::useMultiRowFetch résultats dans une assertion ayant échoué.

Valeur retournée

Différent de zéro si l’objet CRecordset a été correctement ouvert ; sinon, 0 si (si CDatabase::Open appelé) retourne 0.

Notes

Vous devez appeler cette fonction membre pour exécuter la requête définie par le jeu d’enregistrements. Avant d’appeler Open, vous devez construire l’objet recordset.

La connexion de ce jeu d’enregistrements à la source de données dépend de la façon dont vous construisez le jeu d’enregistrements avant d’appeler Open. Si vous transmettez un CDatabase objet au constructeur recordset qui n’a pas été connecté à la source de données, cette fonction membre utilise GetDefaultConnect pour tenter d’ouvrir l’objet de base de données. Si vous passez NULL au constructeur recordset, le constructeur construit un CDatabase objet pour vous et Open tente de connecter l’objet de base de données. Pour plus d’informations sur la fermeture du jeu d’enregistrements et de la connexion dans ces circonstances variables, consultez Close.

Remarque

L’accès à une source de données via un CRecordset objet est toujours partagé. Contrairement à la CDaoRecordset classe, vous ne pouvez pas utiliser d’objet CRecordset pour ouvrir une source de données avec un accès exclusif.

Lorsque vous appelez Open, une requête, généralement une instruction SQL SELECT , sélectionne les enregistrements en fonction des critères indiqués dans le tableau suivant.

Valeur du paramètre lpszSQL.	Les enregistrements sélectionnés sont déterminés par	Exemple
NULL	Chaîne retournée par GetDefaultSQL.
Nom de la table SQL	Toutes les colonnes de la table dans DoFieldExchange ou DoBulkFieldExchange.	"Customer"
Nom de requête prédéfinie (procédure stockée)	Les colonnes que la requête est définie pour retourner.	"{call OverDueAccts}"
SELECT column-list FROM table-list	Colonnes spécifiées à partir de la ou des tables spécifiées.	"SELECT CustId, CustName FROM Customer"

Attention

N’insérez pas d’espace blanc supplémentaire dans votre chaîne SQL. Par exemple, si vous insérez des espaces blancs entre l’accolades et le CALL mot clé, MFC interprète mal la chaîne SQL comme un nom de table et l’incorpore dans une instruction, ce qui entraîne la levée d’une SELECT exception. De même, si votre requête prédéfinie utilise un paramètre de sortie, n’insérez pas d’espace blanc entre l’accolades et le symbole « ». Enfin, vous ne devez pas insérer d’espace blanc avant l’accolades dans une CALL instruction ou avant le SELECT mot clé dans une SELECT instruction.

La procédure habituelle consiste à passer NULL à Open; dans ce cas, Open appelle GetDefaultSQL. Si vous utilisez une classe dérivée CRecordset , GetDefaultSQL donne le ou les noms de table que vous avez spécifiés dans ClassWizard. Vous pouvez à la place spécifier d’autres informations dans le lpszSQL paramètre.

Tout ce que vous passez, Open construit une chaîne SQL finale pour la requête (la chaîne peut avoir SQL WHERE et ORDER BY les clauses ajoutées à la lpszSQL chaîne que vous avez passée), puis exécute la requête. Vous pouvez examiner la chaîne construite en appelant après l’appel GetSQLOpen. Pour plus d’informations sur la façon dont le jeu d’enregistrements construit une instruction SQL et sélectionne des enregistrements, consultez Recordset : How Recordsets Select Records (ODBC).

Les membres de données de champ de votre classe recordset sont liés aux colonnes des données sélectionnées. Si des enregistrements sont retournés, le premier enregistrement devient l’enregistrement actif.

Si vous souhaitez définir des options pour le jeu d’enregistrements, telles qu’un filtre ou un tri, spécifiez-les après avoir construit l’objet recordset, mais avant d’appeler Open. Si vous souhaitez actualiser les enregistrements dans le jeu d’enregistrements une fois que le jeu d’enregistrements est déjà ouvert, appelez Requery.

Pour plus d’informations, notamment d’autres exemples, consultez Recordset (ODBC),Recordset : How Recordsets Select Recordsets (ODBC), and Recordset : Creating and Closing Recordsets (ODBC).

Exemple

Les exemples de code suivants montrent différentes formes d’appel Open .

// rsSnap, rsLName, and rsDefault are CRecordset or CRecordset-derived 
// objects

// Open rs using the default SQL statement, implement bookmarks, and turn 
// off automatic dirty field checking
rsSnap.Open(CRecordset::snapshot, NULL, CRecordset::useBookmarks |
   CRecordset::noDirtyFieldCheck);

// Pass a complete SELECT statement and open as a dynaset
rsLName.Open(CRecordset::dynaset, _T("Select L_Name from Customer"));

// Accept all defaults
rsDefault.Open();

CRecordset::RefreshRowset

Mises à jour les données et l’état d’une ligne dans l’ensemble de lignes actuel.

void RefreshRowset(
    WORD wRow,
    WORD wLockType = SQL_LOCK_NO_CHANGE);

Paramètres

wRow
Position unique d’une ligne dans l’ensemble de lignes actuel. Cette valeur peut aller de zéro à la taille de l’ensemble de lignes.

wLockType
Valeur indiquant comment verrouiller la ligne après son actualisation. Pour plus d'informations, consultez Notes.

Notes

Si vous passez une valeur égale à zéro, wRowchaque ligne de l’ensemble de lignes sera actualisée.

Pour utiliser RefreshRowset, vous devez avoir implémenté l’extraction de lignes en bloc en spécifiant l’option CRecordset::useMulitRowFetch dans la Open fonction membre.

RefreshRowset appelle la fonction SQLSetPosAPI ODBC . Le wLockType paramètre spécifie l’état de verrouillage de la ligne après SQLSetPos l’exécution. Le tableau suivant décrit les valeurs possibles pour wLockType.

wLockType	Description
SQL_LOCK_NO_CHANGE (valeur par défaut)	Le pilote ou la source de données garantit que la ligne est dans le même état verrouillé ou déverrouillé qu’avant RefreshRowset d’être appelée.
SQL_LOCK_EXCLUSIVE	Le pilote ou la source de données verrouille la ligne exclusivement. Toutes les sources de données ne prennent pas en charge ce type de verrou.
SQL_LOCK_UNLOCK	Le pilote ou la source de données déverrouille la ligne. Toutes les sources de données ne prennent pas en charge ce type de verrou.

Pour plus d’informations sur SQLSetPos, consultez le Kit de développement logiciel (SDK) Windows. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

CRecordset::Requery

Reconstruit (actualise) un jeu d’enregistrements.

virtual BOOL Requery();

Valeur retournée

Différent de zéro si le jeu d’enregistrements a été reconstruit avec succès ; sinon 0.

Notes

Si des enregistrements sont retournés, le premier enregistrement devient l’enregistrement actif.

Pour que le jeu d’enregistrements reflète les ajouts et suppressions que vous ou d’autres utilisateurs effectuez à la source de données, vous devez reconstruire le jeu d’enregistrements en appelant Requery. Si le jeu d’enregistrements est un jeu de données dynamique, il reflète automatiquement les mises à jour que vous ou d’autres utilisateurs apportez à ses enregistrements existants (mais pas aux ajouts). Si le jeu d’enregistrements est un instantané, vous devez appeler Requery pour refléter les modifications par d’autres utilisateurs et ajouts et suppressions.

Pour une feuille de réponse dynamique ou une instantané, appelez Requery chaque fois que vous souhaitez reconstruire le jeu d’enregistrements à l’aide d’un nouveau filtre ou d’un nouveau tri, ou de nouvelles valeurs de paramètre. Définissez la nouvelle propriété de filtre ou de tri en affectant de nouvelles valeurs à m_strFilter et m_strSort avant d’appeler Requery. Définissez de nouveaux paramètres en affectant de nouvelles valeurs aux membres de données de paramètres avant d’appeler Requery. Si les chaînes de filtre et de tri sont inchangées, vous pouvez réutiliser la requête, ce qui améliore les performances.

Si la tentative de reconstruction du jeu d’enregistrements échoue, le jeu d’enregistrements est fermé. Avant d’appeler Requery, vous pouvez déterminer si le jeu d’enregistrements peut être réappliqué en appelant la CanRestart fonction membre. CanRestart ne garantit pas que cela Requery réussira.

Attention

Appelez Requery uniquement une fois que vous avez appelé Open.

Exemple

Cet exemple reconstruit un jeu d’enregistrements pour appliquer un ordre de tri différent.

CCustomer rsCustSet(&m_dbCust);

// Open the recordset
rsCustSet.Open();

// Use the recordset ...

// Set the sort order and Requery the recordset
rsCustSet.m_strSort = _T("L_Name, ContactFirstName");
if (!rsCustSet.CanRestart())
return;    // Unable to requery

if (!rsCustSet.Requery())
// Requery failed, so take action
AfxMessageBox(_T("Requery failed!"));

CRecordset::SetAbsolutePosition

Positionne le jeu d’enregistrements sur l’enregistrement correspondant au numéro d’enregistrement spécifié.

void SetAbsolutePosition(long nRows);

Paramètres

nRows
Position ordinale unique pour l’enregistrement actif dans le jeu d’enregistrements.

Notes

SetAbsolutePosition déplace le pointeur d’enregistrement actif en fonction de cette position ordinale.

Remarque

Cette fonction membre n’est pas valide sur les jeux d’enregistrements en transfert uniquement.

Pour les jeux d’enregistrements ODBC, un paramètre de position absolu de 1 fait référence au premier enregistrement du jeu d’enregistrements ; un paramètre de 0 fait référence à la position de début de fichier (BOF).

Vous pouvez également transmettre des valeurs négatives à SetAbsolutePosition. Dans ce cas, la position du jeu d’enregistrements est évaluée à partir de la fin du jeu d’enregistrements. Par exemple, SetAbsolutePosition( -1 ) déplace le pointeur d’enregistrement actif vers le dernier enregistrement du jeu d’enregistrements.

Remarque

La position absolue n’est pas destinée à être utilisée comme numéro d’enregistrement de substitution. Les signets sont toujours le moyen recommandé de conserver et de revenir à une position donnée, car la position d’un enregistrement change lorsque les enregistrements précédents sont supprimés. En outre, vous ne pouvez pas être assuré qu’un enregistrement donné aura la même position absolue si le jeu d’enregistrements est recréé, car l’ordre des enregistrements individuels au sein d’un jeu d’enregistrements n’est pas garanti, sauf s’il est créé avec une instruction SQL à l’aide d’une ORDER BY clause.

Pour plus d’informations sur la navigation et les signets de jeu d’enregistrements, consultez les articles Recordset : Scrolling (ODBC) et Recordset : Bookmarks and Absolute Positions (ODBC).

CRecordset::SetBookmark

Positionne le jeu d’enregistrements sur l’enregistrement contenant le signet spécifié.

void SetBookmark(const CDBVariant& varBookmark);

Paramètres

varBookmark
Référence à un CDBVariant objet contenant la valeur de signet d’un enregistrement spécifique.

Notes

Pour déterminer si les signets sont pris en charge sur le jeu d’enregistrements, appelez CanBookmark. Pour rendre les signets disponibles s’ils sont pris en charge, vous devez définir l’option CRecordset::useBookmarks dans le paramètre de la dwOptionsOpen fonction membre.

Remarque

Si les signets ne sont pas pris en charge ou indisponibles, l’appel SetBookmark entraîne la levée d’une exception. Les signets ne sont pas pris en charge sur les jeux d’enregistrements en avant uniquement.

Pour récupérer d’abord le signet de l’enregistrement actif, appelez GetBookmark, qui enregistre la valeur du signet dans un CDBVariant objet. Plus tard, vous pouvez revenir à cet enregistrement en appelant SetBookmark à l’aide de la valeur de signet enregistrée.

Remarque

Après certaines opérations de jeu d’enregistrements, vous devez case activée la persistance des signets avant d’appeler SetBookmark. Par exemple, si vous récupérez un signet avec GetBookmark , puis appelez Requery, le signet peut ne plus être valide. Appelez CDatabase::GetBookmarkPersistence case activée si vous pouvez appeler SetBookmarken toute sécurité .

Pour plus d’informations sur les signets et la navigation dans le jeu d’enregistrements, consultez les articles Recordset : Signets et positions absolues (ODBC) et Recordset : Défilement (ODBC).

CRecordset::SetFieldDirty

Signale un membre de données de champ du jeu d’enregistrements tel qu’il a été modifié ou inchangé.

void SetFieldDirty(void* pv, BOOL bDirty = TRUE);

Paramètres

pv
Contient l’adresse d’un membre de données de champ dans le jeu d’enregistrements ou NULL. Si NULL, tous les membres de données de champ dans le jeu d’enregistrements sont marqués. (C++ NULL n’est pas identique à La valeur Null dans la terminologie de la base de données, ce qui signifie « n’ayant aucune valeur. »)

bDirty
TRUEsi le membre de données de champ doit être marqué comme « sale » (modifié). SinonFALSE, si le membre de données de champ doit être marqué comme « propre » (inchangé).

Notes

Le marquage des champs comme inchangés garantit que le champ n’est pas mis à jour et génère moins de trafic SQL.

Remarque

Cette fonction membre n’est pas applicable sur les jeux d’enregistrements qui utilisent l’extraction de lignes en bloc. Si vous avez implémenté la récupération de lignes en bloc, SetFieldDirty une assertion échoue. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Le framework marque les membres de données de champ modifiés pour s’assurer qu’ils seront écrits dans l’enregistrement sur la source de données par le mécanisme d’échange de champs d’enregistrement (RFX). La modification de la valeur d’un champ définit généralement le champ sale automatiquement. Vous devrez donc rarement vous appelerSetFieldDirty, mais vous pouvez parfois vous assurer que les colonnes seront explicitement mises à jour ou insérées indépendamment de la valeur du membre de données de champ.

Attention

Appelez cette fonction membre uniquement après avoir appelé Edit ou AddNew.

L’utilisation NULL pour le premier argument de la fonction applique la fonction uniquement aux champs, et non param aux outputColumn champs. Par exemple, l’appel

SetFieldNull(NULL);

définit uniquement outputColumn les champs NULLsur ; param les champs ne sont pas affectés.

Pour travailler sur param des champs, vous devez fournir l’adresse réelle de la personne param sur laquelle vous souhaitez travailler, par exemple :

SetFieldNull(&m_strParam);

Cela signifie que vous ne pouvez pas définir tous les param champs NULLsur , comme vous le pouvez avec outputColumn les champs.

CRecordset::SetFieldNull

Signale un membre de données de champ du jeu d’enregistrements comme Null (en particulier sans valeur) ou comme non Null.

void SetFieldNull(void* pv, BOOL bNull = TRUE);

Paramètres

pv
Contient l’adresse d’un membre de données de champ dans le jeu d’enregistrements ou NULL. Si NULL, tous les membres de données de champ dans le jeu d’enregistrements sont marqués. (C++ NULL n’est pas identique à La valeur Null dans la terminologie de la base de données, ce qui signifie « n’ayant aucune valeur. »)

bNull
Différent de zéro si le membre de données de champ doit être marqué comme n’ayant aucune valeur (Null). Sinon, 0 si le membre de données de champ doit être marqué comme non Null.

Notes

Lorsque vous ajoutez un nouvel enregistrement à un jeu d’enregistrements, tous les membres de données de champ sont initialement définis sur une valeur Null et marqués comme « sale » (modifié). Lorsque vous récupérez un enregistrement à partir d’une source de données, ses colonnes ont déjà des valeurs ou sont Null.

Remarque

N’appelez pas cette fonction membre sur les jeux d’enregistrements qui utilisent l’extraction de lignes en bloc. Si vous avez implémenté la récupération de lignes en bloc, l’appel SetFieldNull entraîne une assertion ayant échoué. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Si vous souhaitez spécifiquement désigner un champ de l’enregistrement actif comme n’ayant pas de valeur, appelez SetFieldNull avec bNull la valeur définie pour TRUE l’marquer comme Null. Si un champ a été précédemment marqué Null et que vous souhaitez maintenant lui donner une valeur, définissez sa nouvelle valeur. Vous n’avez pas besoin de supprimer l’indicateur Null avec SetFieldNull. Pour déterminer si le champ est autorisé à être Null, appelez IsFieldNullable.

Attention

Appelez cette fonction membre uniquement après avoir appelé Edit ou AddNew.

L’utilisation NULL pour le premier argument de la fonction applique la fonction uniquement aux champs, et non param aux outputColumn champs. Par exemple, l’appel

SetFieldNull(NULL);

définit uniquement outputColumn les champs NULLsur ; param les champs ne sont pas affectés.

Pour travailler sur param des champs, vous devez fournir l’adresse réelle de la personne param sur laquelle vous souhaitez travailler, par exemple :

SetFieldNull(&m_strParam);

Cela signifie que vous ne pouvez pas définir tous les param champs NULLsur , comme vous le pouvez avec outputColumn les champs.

Remarque

Lorsque vous définissez des paramètres sur Null, un appel avant SetFieldNull l’ouverture du jeu d’enregistrements entraîne une assertion. Dans ce cas, appelez SetParamNull.

SetFieldNull est implémenté par le biais DoFieldExchangede .

CRecordset::SetLockingMode

Définit le mode de verrouillage sur le verrouillage « optimiste » (la valeur par défaut) ou le verrouillage « pessimiste ». Détermine comment les enregistrements sont verrouillés pour les mises à jour.

void SetLockingMode(UINT nMode);

Paramètres

nMode
Contient l’une des valeurs suivantes à partir des enum LockModeéléments suivants :

• optimistic Le verrouillage optimiste verrouille l’enregistrement mis à jour uniquement pendant l’appel à Update.

• pessimistic Le verrouillage pessimiste verrouille l’enregistrement dès qu’il Edit est appelé et le conserve jusqu’à ce que l’appel Update se termine ou que vous passez à un nouvel enregistrement.

Notes

Appelez cette fonction membre si vous devez spécifier les deux stratégies de verrouillage d’enregistrement que le jeu d’enregistrements utilise pour les mises à jour. Par défaut, le mode de verrouillage d’un jeu d’enregistrements est optimistic. Vous pouvez le modifier en une stratégie de verrouillage plus prudente pessimistic . Appel SetLockingMode après avoir construit et ouvert l’objet recordset, mais avant d’appeler Edit.

CRecordset::SetParamNull

Signale un paramètre comme Null (en particulier sans valeur) ou comme non Null.

void SetParamNull(
    int nIndex,
    BOOL bNull = TRUE);

Paramètres

nIndex
Index de base zéro du paramètre.

bNull
Si TRUE (valeur par défaut), le paramètre est marqué comme Null. Sinon, le paramètre est marqué comme non Null.

Notes

Contrairement SetFieldNullà , vous pouvez appeler SetParamNull avant d’ouvrir le jeu d’enregistrements.

SetParamNull est généralement utilisé avec des requêtes prédéfinies (procédures stockées).

CRecordset::SetRowsetCursorPosition

Déplace le curseur vers une ligne dans l’ensemble de lignes actuel.

void SetRowsetCursorPosition(WORD wRow, WORD wLockType = SQL_LOCK_NO_CHANGE);

Paramètres

wRow
Position unique d’une ligne dans l’ensemble de lignes actuel. Cette valeur peut aller de 1 à la taille de l’ensemble de lignes.

wLockType
Valeur indiquant comment verrouiller la ligne après son actualisation. Pour plus d'informations, consultez Notes.

Notes

Lors de l’implémentation de la récupération de lignes en bloc, les enregistrements sont récupérés par des ensembles de lignes, où le premier enregistrement de l’ensemble de lignes extrait est l’enregistrement actif. Pour créer un autre enregistrement dans l’ensemble de lignes, appelez SetRowsetCursorPosition. Par exemple, vous pouvez combiner SetRowsetCursorPosition avec la GetFieldValue fonction membre pour récupérer dynamiquement les données à partir de n’importe quel enregistrement de votre jeu d’enregistrements.

Pour utiliser SetRowsetCursorPosition, vous devez avoir implémenté l’extraction de lignes en bloc en spécifiant l’option CRecordset::useMultiRowFetch du dwOptions paramètre dans la Open fonction membre.

SetRowsetCursorPosition appelle la fonction SQLSetPosAPI ODBC . Le wLockType paramètre spécifie l’état de verrouillage de la ligne après SQLSetPos l’exécution. Le tableau suivant décrit les valeurs possibles pour wLockType.

wLockType	Description
SQL_LOCK_NO_CHANGE (valeur par défaut)	Le pilote ou la source de données garantit que la ligne est dans le même état verrouillé ou déverrouillé qu’avant SetRowsetCursorPosition d’être appelée.
SQL_LOCK_EXCLUSIVE	Le pilote ou la source de données verrouille la ligne exclusivement. Toutes les sources de données ne prennent pas en charge ce type de verrou.
SQL_LOCK_UNLOCK	Le pilote ou la source de données déverrouille la ligne. Toutes les sources de données ne prennent pas en charge ce type de verrou.

Pour plus d’informations sur SQLSetPos, consultez le Kit de développement logiciel (SDK) Windows. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

CRecordset::SetRowsetSize

Spécifie le nombre d’enregistrements que vous souhaitez récupérer lors d’une extraction.

virtual void SetRowsetSize(DWORD dwNewRowsetSize);

Paramètres

dwNewRowsetSize
Nombre de lignes à récupérer lors d’une extraction donnée.

Notes

Cette fonction membre virtuelle spécifie le nombre de lignes que vous souhaitez récupérer lors d’une extraction unique lors de l’utilisation de la récupération de lignes en bloc. Pour implémenter l’extraction de lignes en bloc, vous devez définir l’option CRecordset::useMultiRowFetch dans le paramètre de la dwOptionsOpen fonction membre.

Remarque

L’appel SetRowsetSize sans implémentation de la récupération de lignes en bloc entraîne une assertion ayant échoué.

Appelez avant d’appeler SetRowsetSizeOpen pour définir initialement la taille de l’ensemble de lignes pour le jeu d’enregistrements. La taille d’ensemble de lignes par défaut lors de l’implémentation de la récupération de lignes en bloc est 25.

Remarque

Utilisez la prudence lors de l’appel SetRowsetSize. Si vous allouez manuellement le stockage pour les données (comme spécifié par l’option CRecordset::userAllocMultiRowBuffers du paramètre dwOptions dans Open), vous devez case activée si vous devez réallouer ces mémoires tampons de stockage après l’appelSetRowsetSize, mais avant d’effectuer une opération de navigation au curseur.

Pour obtenir le paramètre actuel de la taille de l’ensemble de lignes, appelez GetRowsetSize.

Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

CRecordset::Update

Termine une AddNew opération en Edit enregistrant les données nouvelles ou modifiées sur la source de données.

virtual BOOL Update();

Valeur retournée

Différent de zéro si un enregistrement a été correctement mis à jour ; sinon, 0 si aucune colonne n’a changé. Si aucun enregistrement n’a été mis à jour ou si plusieurs enregistrements ont été mis à jour, une exception est levée. Une exception est également levée pour toute autre défaillance sur la source de données.

Notes

Appelez cette fonction membre après un appel à la fonction ou Edit à la AddNew fonction membre. Cet appel est nécessaire pour terminer l’opération ou Edit l’opérationAddNew.

Remarque

Si vous avez implémenté la récupération de lignes en bloc, vous ne pouvez pas appeler Update. Cela entraîne une assertion ayant échoué. Bien que la classe CRecordset ne fournisse pas de mécanisme pour mettre à jour des lignes de données en bloc, vous pouvez écrire vos propres fonctions à l’aide de la fonction SQLSetPosAPI ODBC. Pour plus d’informations sur l’extraction de lignes en bloc, consultez Recordset : Extraction d’enregistrements en bloc (ODBC).

Préparez à la fois AddNew une Edit mémoire tampon de modification dans laquelle les données ajoutées ou modifiées sont placées pour l’enregistrement dans la source de données. Update enregistre les données. Seuls ces champs marqués ou détectés comme modifiés sont mis à jour.

Si la source de données prend en charge les transactions, vous pouvez effectuer l’appel Update (et sa partie correspondante AddNew ou Edit appel) d’une transaction. Pour plus d’informations sur les transactions, consultez Transaction (ODBC).

Attention

Si vous appelez Update sans appeler l’un ou l’autreAddNew, EditUpdate lève un CDBException. Si vous appelez ou Edit, vous devez appeler AddNewUpdate avant d’appeler une Move opération ou avant de fermer le jeu d’enregistrements ou la connexion de source de données. Sinon, vos modifications sont perdues sans notification.

Pour plus d’informations sur la gestion des Update échecs, consultez Recordset : How Recordsets Update Records (ODBC).

Exemple

voir Transaction : exécution d’une transaction dans un recordset (ODBC)

Voir aussi

CObject, classe
Graphique hiérarchique
CDatabase, classe
CRecordView, classe