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

Méthodes publiques

Membres de données publiques

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és. Une feuille de réponse dynamique reste synchronisée avec les mises à jour des données effectuées par d’autres utilisateurs. Un 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.

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 un 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 ODBC (Open Database Connectivity) 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 un focus sur les feuilles de réponse dynamiques et les instantanés, consultez les articles Dynaset et Snapshot.

Hiérarchie d’héritage

CObject

CRecordset

Spécifications

En-tête :afxdb.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.

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.

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.

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.

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

Si la vérification automatique des champs incorrects est activée, 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, la vérification automatique des champs est activée 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.

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 CDatabase l’objet Open 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 NULL objet est construit et connecté pour vous à l’aide des informations de source de données que vous avez spécifiées CDatabaselorsque 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.

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).

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.

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.

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.

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.

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 .

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, en ignorant ClassWizardla version de 's. 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).

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.

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é.

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();

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

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.

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).

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.

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 .

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 vous souhaitez vérifier l’état, ou NULL pour déterminer si l’un des champs est incorrect.

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 Edit).AddNew

L’appel IsFieldDirty réinitialise les effets des appels précédents à SetFieldDirty , car l’état incorrect 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 incorrect. Dans le Edit cas, si la valeur du champ diffère de la valeur mise en cache, l’état du champ est incorrect.

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 vous souhaitez vérifier l’état, 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.

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 vous souhaitez vérifier l’état, 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 »).

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 outputColumn aux param 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 Open l’objet Requery 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.

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.

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.

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 Open l’appelRequery. 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 le 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 Open l’appelRequery. 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 le 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 AddNew actuel Edit et restaure la valeur de l’enregistrement actif avant AddNew ou Edit a été appelée.

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.

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.

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.

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.

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.

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.

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 .

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. La vérification automatique des champs sales est implémentée.

• 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 comme incorrects. 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::noDirtyFieldCheck Désactivez la vérification automatique des champs sales (double mise en mémoire tampon). Cela permettra d’améliorer les performances ; Toutefois, vous devez marquer manuellement les champs comme étant incorrects en appelant les fonctions membres et SetFieldDirty les SetFieldNull 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.

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.

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

Met à 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.

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 un instantané, appelez Requery chaque fois que vous souhaitez reconstruire le jeu d’enregistrements à l’aide d’un nouveau filtre ou d’un 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.

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.

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.

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.

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.

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
TRUE si le membre de données de champ doit être marqué comme étant « sale » (modifié). Sinon FALSE , 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.

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 appeler SetFieldDirty , 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.

L’utilisation NULL pour le premier argument de la fonction applique la fonction uniquement aux champs, et non outputColumn aux param 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 « dirty » (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.

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.

L’utilisation NULL pour le premier argument de la fonction applique la fonction uniquement aux champs, et non outputColumn aux param 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.

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.

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.

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.

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 AddNew à la Edit fonction membre. Cet appel est nécessaire pour terminer l’opération ou AddNew l’opérationEdit.

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).

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