Share via

La classe CDatabase

  • Article

Représente une connexion à une source de données, par l'intermédiaire de laquelle vous pouvez utiliser la source de données.

Syntaxe

class CDatabase : public CObject

Membres

Constructeurs publics

Nom Description
CDatabase::CDatabase Construit un objet CDatabase. Vous devez initialiser l’objet en appelant OpenEx ou Open.

Méthodes publiques

Nom Description
CDatabase::BeginTrans Démarre une « transaction » ( une série d’appels réversibles aux fonctions membres , et UpdateEditDeleteles AddNewfonctions membres de la classe CRecordset ) sur la source de données connectée. La source de données doit prendre en charge les transactions pour BeginTrans qu’elles aient un effet quelconque.
CDatabase::BindParameters Vous permet de lier des paramètres avant d’appeler CDatabase::ExecuteSQL.
CDatabase::Cancel Annule une opération asynchrone ou un processus à partir d’un deuxième thread.
CDatabase::CanTransact Retourne une valeur différente de zéro si la source de données prend en charge les transactions.
CDatabase::CanUpdate Renvoie une valeur différente de zéro si l’objet CDatabase est pouvant être mis à jour (pas en lecture seule).
CDatabase::Close Ferme la connexion de la source de données.
CDatabase::CommitTrans Termine une transaction commencée par BeginTrans. Les commandes de la transaction qui modifient la source de données sont effectuées.
CDatabase::ExecuteSQL Exécute une instruction SQL. Aucun enregistrement de données n’est retourné.
CDatabase::GetBookmarkPersistence Identifie les opérations par le biais des signets persistants sur les objets recordset.
CDatabase::GetConnect Retourne le chaîne de connexion ODBC utilisé pour connecter l’objet CDatabase à une source de données.
CDatabase::GetCursorCommitBehavior Identifie l’effet de la validation d’une transaction sur un objet recordset ouvert.
CDatabase::GetCursorRollbackBehavior Identifie l’effet de la restauration d’une transaction sur un objet recordset ouvert.
CDatabase::GetDatabaseName Retourne le nom de la base de données en cours d’utilisation.
CDatabase::IsOpen Retourne une valeur différente de zéro si l’objet CDatabase est actuellement connecté à une source de données.
CDatabase::OnSetOptions Appelé par l’infrastructure pour définir les options de connexion standard. L’implémentation par défaut définit la valeur du délai d’expiration de la requête. Vous pouvez établir ces options à l’avance en appelant SetQueryTimeout.
CDatabase::Open Établit une connexion à une source de données (via un pilote ODBC).
CDatabase::OpenEx Établit une connexion à une source de données (via un pilote ODBC).
CDatabase::Rollback Inverse les modifications apportées pendant la transaction actuelle. La source de données retourne à son état précédent, tel que défini au niveau de l’appel BeginTrans , sans modification.
CDatabase::SetLoginTimeout Définit le nombre de secondes après lesquelles une tentative de connexion de source de données expire.
CDatabase::SetQueryTimeout Définit le nombre de secondes après lesquelles les opérations de requête de base de données expirent. Affecte tous les jeux d’enregistrements Opensuivants, , AddNewEditet Delete les appels.

Membres de données publics

Nom Description
CDatabase::m_hdbc Open Database Connecter ivity (ODBC) handle de connexion à une source de données. Tapez HDBC.

Notes

Une source de données est une instance spécifique des données hébergées par un système de gestion de base de données (SGBD). Les exemples incluent Microsoft SQL Server, Microsoft Access, Borland dBASE et xBASE. Vous pouvez avoir un ou plusieurs CDatabase objets actifs à la fois 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 classeCDaoDatabase. Pour plus d’informations, consultez l’article Vue d’ensemble : Programmation de base de données.

Pour utiliser CDatabase, construisez un CDatabase objet et appelez sa OpenEx fonction membre. Cela ouvre une connexion. Lorsque vous construisez CRecordset ensuite des objets pour fonctionner sur la source de données connectée, transmettez le constructeur de jeu d’enregistrements à votre CDatabase objet. Lorsque vous avez terminé d’utiliser la connexion, appelez la Close fonction membre et détruisez l’objet CDatabase . Close ferme tous les jeux d’enregistrements que vous n’avez pas fermés précédemment.

Pour plus d’informations sur CDatabase, consultez les articles sur la source de données (ODBC) et vue d’ensemble : Programmation de base de données.

Hiérarchie d'héritage

CObject

CDatabase

Spécifications

En-têteafxdb.h:

CDatabase::BeginTrans

Appelez cette fonction membre pour commencer une transaction avec la source de données connectée.

BOOL BeginTrans();

Valeur de retour

Différent de zéro si l’appel a réussi et que les modifications sont validées manuellement ; sinon 0.

Notes

Une transaction se compose d’un ou plusieurs appels aux fonctions membres , , et Deletede l’objetAddNewEditCRecordset.Update Avant de commencer une transaction, l’objet CDatabase doit déjà être connecté à la source de données en appelant sa fonction membre ou Open son OpenEx nom. Pour mettre fin à la transaction, appelez CommitTrans pour accepter toutes les modifications apportées à la source de données (et effectuez-les) ou appelez-les Rollback pour abandonner toute la transaction. Appelez BeginTrans après avoir ouvert tous les jeux d’enregistrements impliqués dans la transaction et aussi près des opérations de mise à jour réelles que possible.

Attention

Selon votre pilote ODBC, l’ouverture d’un jeu d’enregistrements avant l’appel BeginTrans peut entraîner des problèmes lors de l’appel Rollback. Vous devez case activée le pilote spécifique que vous utilisez. Par exemple, lorsque vous utilisez le pilote Microsoft Access inclus dans microsoft ODBC Desktop Driver Pack 3.0, vous devez tenir compte de l’exigence du moteur de base de données Jet que vous ne devez pas commencer une transaction sur une base de données qui a un curseur ouvert. Dans les classes de base de données MFC, un curseur ouvert signifie un objet ouvert CRecordset . Pour plus d’informations, consultez la Note technique 68.

BeginTrans peut également verrouiller les enregistrements de données sur le serveur, en fonction de la concurrence demandée et des fonctionnalités de la source de données. Pour plus d’informations sur le verrouillage des données, consultez l’article Recordset : Locking Records (ODBC).

Les transactions définies par l’utilisateur sont expliquées dans l’article Transaction (ODBC) .

BeginTrans établit l’état auquel la séquence de transactions peut être restaurée (inversée). Pour établir un nouvel état pour les restaurations, validez toute transaction actuelle, puis appelez BeginTrans à nouveau.

Attention

Appeler BeginTrans à nouveau sans appeler CommitTrans ou Rollback est une erreur.

Appelez la CanTransact fonction membre pour déterminer si votre pilote prend en charge les transactions pour une base de données donnée. Vous devez également appeler GetCursorCommitBehavior et GetCursorRollbackBehavior déterminer la prise en charge de la conservation des curseurs.

Pour plus d’informations sur les transactions, consultez l’article Transaction (ODBC) .

Exemple

Consultez l’article Transaction : Exécution d’une transaction dans un recordset (ODBC).

CDatabase::BindParameters

Remplacez BindParameters quand vous devez lier des paramètres avant d’appeler CDatabase::ExecuteSQL.

virtual void BindParameters(HSTMT hstmt);

Paramètres

hstmt
Handle d’instruction ODBC pour lequel vous souhaitez lier des paramètres.

Notes

Cette approche est utile lorsque vous n’avez pas besoin du jeu de résultats à partir d’une procédure stockée.

Dans votre remplacement, appelez SQLBindParameters et les fonctions ODBC associées pour lier les paramètres. MFC appelle votre remplacement avant votre appel à ExecuteSQL. Vous n’avez pas besoin d’appeler SQLPrepare; ExecuteSQL appelle SQLExecDirect et détruit le hstmt, qui n’est utilisé qu’une seule fois.

CDatabase::Cancel

Appelez cette fonction membre pour demander 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

Notez que 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.

CDatabase::CanTransact

Appelez cette fonction membre pour déterminer si la base de données autorise les transactions.

BOOL CanTransact() const;

Valeur de retour

Différent de zéro si les recordsets utilisant cet CDatabase objet autorisent les transactions ; sinon, 0.

Notes

Pour plus d’informations sur les transactions, consultez l’article Transaction (ODBC).

CDatabase::CanUpdate

Appelez cette fonction membre pour déterminer si l’objet autorise les CDatabase mises à jour.

BOOL CanUpdate() const;

Valeur de retour

Différent de zéro si l’objet autorise les CDatabase mises à jour ; sinon 0, indiquant que vous avez passé bReadOnlyTRUE lorsque vous avez ouvert l’objet CDatabase ou que la source de données elle-même est en lecture seule. La source de données est en lecture seule si un appel à la fonction SQLGetInfo API ODBC pour SQL_DATASOURCE_READ_ONLY les retours y.

Notes

Tous les pilotes ne prennent pas en charge les mises à jour.

CDatabase::CDatabase

Construit un objet CDatabase.

CDatabase();

Notes

Après avoir construit l’objet, vous devez appeler sa OpenEx fonction ou Open membre pour établir une connexion à une source de données spécifiée.

Vous trouverez peut-être pratique d’incorporer l’objet CDatabase dans votre classe de document.

Exemple

Cet exemple illustre l’utilisation CDatabase dans une CDocumentclasse dérivée de -.

// This fragment is taken from the declaration for CMyDatabaseDoc
// CMyDatabaseDoc is derived from CDocument.
public:
// Declare a CDatabase embedded in the document
CDatabase m_dbCust;

 

// Initialize when needed
CDatabase *CMyDatabaseDoc::GetDatabase()
{
   // Connect the object to a data source
   if (!m_dbCust.IsOpen() && !m_dbCust.OpenEx(NULL))
      return NULL;

   return &m_dbCust;
}

CDatabase::Close

Appelez cette fonction membre si vous souhaitez vous déconnecter d’une source de données.

virtual void Close();

Notes

Vous devez fermer tous les jeux d’enregistrements associés à l’objet CDatabase avant d’appeler cette fonction membre. Étant donné que Close ne détruit pas l’objet CDatabase , vous pouvez réutiliser l’objet en ouvrant une nouvelle connexion à la même source de données ou à une autre source de données.

Toutes les instructions ou Edit en attente AddNew des jeux d’enregistrements utilisant la base de données sont annulées et toutes les transactions en attente sont restaurées. Tous les recordsets dépendant de l’objet CDatabase sont laissés dans un état non défini.

Exemple

// Close the current connection
m_dbCust.Close();

// Perhaps connect the object to a
// different data source
m_dbCust.OpenEx(_T("DSN=MFC_ODBCTest;UID=JOES"));

CDatabase::CommitTrans

Appelez cette fonction membre lors de la fin des transactions.

BOOL CommitTrans();

Valeur de retour

Différent de zéro si les mises à jour ont été correctement validées ; sinon 0. En CommitTrans cas d’échec, l’état de la source de données n’est pas défini. Vous devez case activée les données pour déterminer son état.

Notes

Une transaction se compose d’une série d’appels aux AddNewfonctions membres , et DeleteUpdate aux Editfonctions membres d’un CRecordset objet qui a commencé par un appel à la BeginTrans fonction membre. CommitTrans valide la transaction. Par défaut, les mises à jour sont validées immédiatement ; l’appel BeginTrans entraîne le retard des mises à jour jusqu’à ce qu’elles CommitTrans soient appelées.

Jusqu’à ce que vous appeliez CommitTrans pour mettre fin à une transaction, vous pouvez appeler la Rollback fonction membre pour abandonner la transaction et laisser la source de données dans son état d’origine. Pour commencer une nouvelle transaction, appelez BeginTrans à nouveau.

Pour plus d’informations sur les transactions, consultez l’article Transaction (ODBC) .

Exemple

Consultez l’article Transaction : Exécution d’une transaction dans un recordset (ODBC).

CDatabase::ExecuteSQL

Appelez cette fonction membre lorsque vous devez exécuter une commande SQL directement.

void ExecuteSQL(LPCTSTR lpszSQL);

Paramètres

lpszSQL
Pointeur vers une chaîne terminée par null contenant une commande SQL valide à exécuter. Vous pouvez passer un CString.

Notes

Créez la commande en tant que chaîne terminée par null. ExecuteSQL ne retourne pas d’enregistrements de données. Si vous souhaitez utiliser des enregistrements, utilisez plutôt un objet recordset.

La plupart de vos commandes pour une source de données sont émises via des objets recordset, qui prennent en charge les commandes de sélection des données, l’insertion de nouveaux enregistrements, la suppression d’enregistrements et la modification d’enregistrements. Toutefois, toutes les fonctionnalités ODBC ne sont pas directement prises en charge par les classes de base de données. Vous devrez peut-être parfois effectuer un appel SQL direct avec ExecuteSQL.

Exemple

try
{
   m_dbCust.ExecuteSQL(
       _T("UPDATE Taxes ")
       _T("SET Rate = '36' ")
       _T("WHERE Name = 'Federal'"));
}
catch (CDBException *pe)
{
   // The error code is in pe->m_nRetCode
   pe->ReportError();
   pe->Delete();
}

CDatabase::GetBookmarkPersistence

Appelez cette fonction membre pour déterminer la persistance des signets sur un objet recordset après certaines opérations.

DWORD GetBookmarkPersistence() const;

Valeur de retour

Un masque de bits qui identifie les opérations par lesquelles les signets persistent sur un objet recordset. Pour plus d'informations, consultez Notes.

Notes

Par exemple, si vous appelez CRecordset::GetBookmark, puis CRecordset::Requery, le signet obtenu à partir de GetBookmark risque de ne plus être valide. Vous devez appeler GetBookmarkPersistence avant d'appeler CRecordset::SetBookmark.

Le tableau suivant liste les valeurs de masque de bits qui peuvent être combinées pour la valeur de retour de GetBookmarkPersistence.

Valeur du masque de bits Persistance des signets
SQL_BP_CLOSE Les signets sont valides après une Requery opération.
SQL_BP_DELETE Le signet d’une ligne est valide après une Delete opération sur cette ligne.
SQL_BP_DROP Les signets sont valides après une Close opération.
SQL_BP_SCROLL Les signets sont valides après toute Move opération. Permet simplement de déterminer si les signets sont pris en charge sur le recordset, comme cela est retourné par CRecordset::CanBookmark.
SQL_BP_TRANSACTION Les signets sont valides après qu'une transaction est validée ou restaurée.
SQL_BP_UPDATE Le signet d’une ligne est valide après une Update opération sur cette ligne.
SQL_BP_OTHER_HSTMT Les signets associés à un objet recordset sont valides sur un deuxième recordset.

Pour plus d’informations sur cette valeur de retour, consultez la fonction SQLGetInfo API ODBC dans le Kit de développement logiciel (SDK) Windows. Pour plus d’informations sur les signets, consultez l’article Recordset : Signets et positions absolues (ODBC).

CDatabase::GetConnect

Appelez cette fonction membre pour récupérer le chaîne de connexion utilisé pendant l’appel ou OpenExOpen qui a connecté l’objet CDatabase à une source de données.

const CString GetConnect() const;

Valeur de retour

Contenant constCString le chaîne de connexion si OpenEx ou Open a été appelé ; sinon, une chaîne vide.

Notes

Consultez CDatabase::Open la description de la création de la chaîne de connexion.

CDatabase::GetCursorCommitBehavior

Appelez cette fonction membre pour déterminer comment une CommitTrans opération affecte les curseurs sur les objets recordset ouverts.

int GetCursorCommitBehavior() const;

Valeur de retour

Valeur indiquant l’effet des transactions sur les objets recordset ouverts. Pour plus d'informations, consultez Notes.

Notes

Le tableau suivant répertorie les valeurs de retour possibles pour GetCursorCommitBehavior et l’effet correspondant sur le jeu d’enregistrements ouvert.

Valeur retournée Effet sur CRecordset les objets
SQL_CB_CLOSE Appelez CRecordset::Requery immédiatement après la validation de transaction.
SQL_CB_DELETE Appelez CRecordset::Close immédiatement après la validation de transaction.
SQL_CB_PRESERVE Poursuivez normalement avec CRecordset les opérations.

Pour plus d’informations sur cette valeur de retour, consultez la fonction SQLGetInfo API ODBC dans le Kit de développement logiciel (SDK) Windows. Pour plus d’informations sur les transactions, consultez l’article Transaction (ODBC) .

CDatabase::GetCursorRollbackBehavior

Appelez cette fonction membre pour déterminer comment une Rollback opération affecte les curseurs sur les objets recordset ouverts.

int GetCursorRollbackBehavior() const;

Valeur de retour

Valeur indiquant l’effet des transactions sur les objets recordset ouverts. Pour plus d'informations, consultez Notes.

Notes

Le tableau suivant répertorie les valeurs de retour possibles pour GetCursorRollbackBehavior et l’effet correspondant sur le jeu d’enregistrements ouvert.

Valeur retournée Effet sur CRecordset les objets
SQL_CB_CLOSE Appelez CRecordset::Requery immédiatement après la restauration de la transaction.
SQL_CB_DELETE Appelez CRecordset::Close immédiatement après la restauration de la transaction.
SQL_CB_PRESERVE Poursuivez normalement avec CRecordset les opérations.

Pour plus d’informations sur cette valeur de retour, consultez la fonction SQLGetInfo API ODBC dans le Kit de développement logiciel (SDK) Windows. Pour plus d’informations sur les transactions, consultez l’article Transaction (ODBC) .

CDatabase::GetDatabaseName

Appelez cette fonction membre pour récupérer le nom de la base de données actuellement connectée (à condition que la source de données définit un objet nommé appelé « base de données »).

CString GetDatabaseName() const;

Valeur de retour

Contenant CString le nom de la base de données en cas de réussite ; sinon, vide CString.

Notes

Ce n’est pas le même que le nom de source de données (DSN) spécifié dans l’appel ou Open l’appelOpenEx. Ce qui GetDatabaseName retourne dépend d’ODBC. En général, une base de données est une collection de tables. Si cette entité a un nom, GetDatabaseName retourne-la.

Vous pouvez, par exemple, afficher ce nom dans un titre. Si une erreur se produit lors de la récupération du nom à partir d’ODBC, GetDatabaseName retourne une valeur vide CString.

CDatabase::IsOpen

Appelez cette fonction membre pour déterminer si l’objet CDatabase est actuellement connecté à une source de données.

BOOL IsOpen() const;

Valeur de retour

Différent de zéro si l’objet CDatabase est actuellement connecté ; sinon 0.

CDatabase::m_hdbc

Contient un handle public vers une connexion de source de données ODBC , un « handle de connexion ».

Notes

Normalement, vous n’aurez pas besoin d’accéder directement à cette variable membre. Au lieu de cela, l’infrastructure alloue le handle lorsque vous appelez OpenEx ou Open. L’infrastructure désalloue le handle lorsque vous appelez l’opérateur delete sur l’objet CDatabase . Notez que la Close fonction membre ne désalloue pas le handle.

Toutefois, dans certaines circonstances, vous devrez peut-être utiliser le handle directement. Par exemple, si vous devez appeler directement des fonctions d’API ODBC plutôt que via une classe CDatabase, vous devrez peut-être passer un handle de connexion en tant que paramètre. Consultez l’exemple de code ci-dessous.

Exemple

// Using m_hdbc for a direct ODBC API call.
// m_dbCust is the CDatabase object; m_hdbc is
// its HDBC member variable
nRetCode = ::SQLGetInfo(m_dbCust.m_hdbc, SQL_ODBC_SQL_CONFORMANCE,
                        &nValue, sizeof(nValue), &cbValue);

CDatabase::OnSetOptions

L’infrastructure appelle cette fonction membre lors de l’exécution directe d’une instruction SQL avec la ExecuteSQL fonction membre.

virtual void OnSetOptions(HSTMT hstmt);

Paramètres

hstmt
Handle d’instruction ODBC pour lequel les options sont définies.

Notes

CRecordset::OnSetOptions appelle également cette fonction membre.

OnSetOptions définit la valeur du délai d’expiration de connexion. S’il existe des appels précédents à la fonction membre et à la SetQueryTimeout fonction membre, OnSetOptions reflète les valeurs actuelles ; sinon, elle définit les valeurs par défaut.

Remarque

Avant MFC 4.2, OnSetOptions définissez également le mode de traitement sur snychronous ou asynchrone. À compter de MFC 4.2, toutes les opérations sont synchrones. Pour effectuer une opération asynchrone, vous devez effectuer un appel direct à la fonction SQLSetPosAPI ODBC.

Vous n’avez pas besoin de remplacer OnSetOptions pour modifier la valeur du délai d’expiration. Au lieu de cela, pour personnaliser la valeur du délai d’expiration de la requête, appelez SetQueryTimeout avant de créer un jeu d’enregistrements ; OnSetOptions utilisez la nouvelle valeur. Les valeurs définies s’appliquent aux opérations suivantes sur tous les jeux d’enregistrements ou appels SQL directs.

Remplacez OnSetOptions si vous souhaitez définir des options supplémentaires. Votre remplacement doit appeler la classe OnSetOptions de base avant ou après l’appel de la fonction SQLSetStmtOptionAPI ODBC. Suivez la méthode illustrée dans l’implémentation par défaut de l’infrastructure .OnSetOptions

CDatabase::Open

Appelez cette fonction membre pour initialiser un objet nouvellement construit CDatabase .

virtual BOOL Open(
    LPCTSTR lpszDSN,
    BOOL bExclusive = FALSE,
    BOOL bReadOnly = FALSE,
    LPCTSTR lpszConnect = _T("ODBC;"),
    BOOL bUseCursorLib = TRUE);

Paramètres

lpszDSN
Spécifie un nom de source de données : nom inscrit auprès d’ODBC via le programme ODBC Administration istrator. Si une valeur DSN est spécifiée lpszConnect dans (sous la forme « DSN=<data-source> »), elle ne doit pas être spécifiée à nouveau dans lpszDSN. Dans ce cas, lpszDSN doit être NULL. Sinon, vous pouvez passer NULL si vous souhaitez présenter l’utilisateur à une boîte de dialogue Source de données dans laquelle l’utilisateur peut sélectionner une source de données. Pour plus d’informations, consultez Remarques.

bExclusive
Non pris en charge dans cette version de la bibliothèque de classes. Actuellement, une assertion échoue si ce paramètre est TRUE. La source de données est toujours ouverte en tant que partage (non exclusif).

bReadOnly
TRUE si vous envisagez que la connexion soit en lecture seule et pour interdire les mises à jour de la source de données. Tous les jeux d’enregistrements dépendants héritent de cet attribut. La valeur par défaut est FALSE.

lpszConnect
Spécifie un chaîne de connexion. Le chaîne de connexion concatène des informations, éventuellement y compris un nom de source de données, un ID d’utilisateur valide sur la source de données, une chaîne d’authentification utilisateur (mot de passe, si la source de données en a besoin) et d’autres informations. L’ensemble chaîne de connexion doit être précédé de la chaîne "ODBC;" (majuscules ou minuscules). La "ODBC;" chaîne est utilisée pour indiquer que la connexion est à une source de données ODBC ; il s’agit d’une compatibilité ascendante lorsque les futures versions de la bibliothèque de classes peuvent prendre en charge les sources de données non ODBC.

bUseCursorLib
TRUE si vous souhaitez que la DLL de la bibliothèque de curseurs ODBC soit chargée. La bibliothèque de curseurs masque certaines fonctionnalités du pilote ODBC sous-jacent, empêchant efficacement l’utilisation des feuilles de réponse dynamique (si le pilote les prend en charge). Les seuls curseurs pris en charge si la bibliothèque de curseurs est chargée sont des instantané statiques et des curseurs vers l’avant uniquement. La valeur par défaut est TRUE. Si vous envisagez de créer un objet recordset directement à partir de CRecordset celui-ci sans en dériver, vous ne devez pas charger la bibliothèque de curseurs.

Valeur de retour

Différent de zéro si la connexion est établie avec succès ; sinon, 0 si l’utilisateur choisit Annuler lorsqu’il présente une boîte de dialogue demandant plus d’informations de connexion. Dans tous les autres cas, le framework lève une exception.

Notes

Votre objet de base de données doit être initialisé avant de pouvoir l’utiliser pour construire un objet recordset.

Remarque

L’appel de la OpenEx fonction membre est le moyen par défaut de se connecter à une source de données et d’initialiser votre objet de base de données.

Si les paramètres de votre Open appel ne contiennent pas suffisamment d’informations pour établir la connexion, le pilote ODBC ouvre une boîte de dialogue pour obtenir les informations nécessaires de l’utilisateur. Lorsque vous appelez Open, votre chaîne de connexion, lpszConnectest stocké en privé dans l’objet CDatabase et est disponible en appelant la GetConnect fonction membre.

Si vous le souhaitez, vous pouvez ouvrir votre propre boîte de dialogue avant d’appeler Open pour obtenir des informations de l’utilisateur, telles qu’un mot de passe, puis ajouter ces informations au chaîne de connexion à laquelle vous passez Open. Vous pouvez également enregistrer le chaîne de connexion que vous passez afin de pouvoir le réutiliser la prochaine fois que votre application appelle Open sur un CDatabase objet.

Vous pouvez également utiliser le chaîne de connexion pour plusieurs niveaux d’autorisation de connexion (chacun pour un objet différentCDatabase) ou pour transmettre d’autres informations spécifiques à la source de données. Pour plus d’informations sur les chaîne de connexion, consultez le chapitre 5 dans le Kit de développement logiciel (SDK) Windows.

Il est possible qu’une tentative de connexion expire si, par exemple, l’hôte SGBD n’est pas disponible. Si la tentative de connexion échoue, Open lève un CDBException.

Exemple

// m_dbCust is a CDatabase object embedded in a CDocument class

if (bDefault)
{
   // Connect the object to a data source (no password)
   // the ODBC connection dialog box will always remain hidden
   m_dbCust.Open(_T("MFC_ODBCTest"), FALSE, FALSE, _T("ODBC;UID=JOES"));
}
else
{
   // ...Or, query the user for all connection information
   m_dbCust.Open(NULL);
}

CDatabase::OpenEx

Appelez cette fonction membre pour initialiser un objet nouvellement construit CDatabase .

virtual BOOL OpenEx(
    LPCTSTR lpszConnectString,
    DWORD dwOptions = 0);

Paramètres

lpszConnectString
Spécifie un chaîne de connexion ODBC. Cela inclut le nom de la source de données ainsi que d’autres informations facultatives, telles qu’un ID d’utilisateur et un mot de passe. Par exemple, "DSN=SQLServer_Source;UID=SA;PWD=abc123" il s’agit d’une chaîne de connexion possible. Notez que si vous passez NULLlpszConnectString, une boîte de dialogue Source de données invite l’utilisateur à sélectionner une source de données.

dwOptions
Masque de bits qui spécifie une combinaison des valeurs suivantes. La valeur par défaut est 0, ce qui signifie que la base de données sera ouverte en tant qu’accès en écriture, la DLL de bibliothèque de curseurs ODBC ne sera pas chargée et la boîte de dialogue de connexion ODBC s’affiche uniquement s’il n’y a pas suffisamment d’informations pour établir la connexion.

  • CDatabase::openExclusive Non pris en charge dans cette version de la bibliothèque de classes. Une source de données est toujours ouverte en tant que partage (non exclusif). Actuellement, une assertion échoue si vous spécifiez cette option.

  • CDatabase::openReadOnly Ouvrez la source de données en lecture seule.

  • CDatabase::useCursorLib Chargez la DLL de la bibliothèque de curseurs ODBC. La bibliothèque de curseurs masque certaines fonctionnalités du pilote ODBC sous-jacent, empêchant efficacement l’utilisation des feuilles de réponse dynamique (si le pilote les prend en charge). Les seuls curseurs pris en charge si la bibliothèque de curseurs est chargée sont des instantané statiques et des curseurs vers l’avant uniquement. Si vous envisagez de créer un objet recordset directement à partir de CRecordset celui-ci sans en dériver, vous ne devez pas charger la bibliothèque de curseurs.

  • CDatabase::noOdbcDialog N’affichez pas la boîte de dialogue connexion ODBC, que les informations de connexion suffisantes soient fournies.

  • CDatabase::forceOdbcDialog Affichez toujours la boîte de dialogue connexion ODBC.

Valeur de retour

Différent de zéro si la connexion est établie avec succès ; sinon, 0 si l’utilisateur choisit Annuler lorsqu’il présente une boîte de dialogue demandant plus d’informations de connexion. Dans tous les autres cas, le framework lève une exception.

Notes

Votre objet de base de données doit être initialisé avant de pouvoir l’utiliser pour construire un objet recordset.

Si le lpszConnectString paramètre de votre OpenEx appel ne contient pas suffisamment d’informations pour établir la connexion, le pilote ODBC ouvre une boîte de dialogue pour obtenir les informations nécessaires de l’utilisateur, à condition que vous n’ayez pas défini CDatabase::noOdbcDialog ou CDatabase::forceOdbcDialog dans le dwOptions paramètre. Lorsque vous appelez OpenEx, votre chaîne de connexion, lpszConnectStringest stocké en privé dans l’objet CDatabase et est disponible en appelant la GetConnect fonction membre.

Si vous le souhaitez, vous pouvez ouvrir votre propre boîte de dialogue avant d’appeler OpenEx pour obtenir des informations de l’utilisateur, telles qu’un mot de passe, puis ajouter ces informations au chaîne de connexion à laquelle vous passez OpenEx. Vous pouvez également enregistrer le chaîne de connexion que vous passez afin de pouvoir le réutiliser la prochaine fois que votre application appelle OpenEx sur un CDatabase objet.

Vous pouvez également utiliser le chaîne de connexion pour plusieurs niveaux d’autorisation de connexion (chacun pour un objet différentCDatabase) ou pour transmettre d’autres informations spécifiques à la source de données. Pour plus d’informations sur les chaîne de connexion, consultez le chapitre 6 dans la référence du programmeur ODBC.

Il est possible qu’une tentative de connexion expire si, par exemple, l’hôte SGBD n’est pas disponible. Si la tentative de connexion échoue, OpenEx lève un CDBException.

Exemple

// m_dbCust is a CDatabase object embedded in a CDocument class.

// Connect the object to a read-only data source where
// the ODBC connection dialog box will always remain hidden
m_dbCust.OpenEx(_T("DSN=MFC_ODBCTest;UID=JOES"),
                CDatabase::openReadOnly | CDatabase::noOdbcDialog);

CDatabase::Rollback

Appelez cette fonction membre pour inverser les modifications apportées pendant une transaction.

BOOL Rollback();

Valeur de retour

Différent de zéro si la transaction a été correctement inversée ; sinon 0. En cas d’échec d’un Rollback appel, la source de données et les états de transaction ne sont pas définis. Si Rollback la valeur est renvoyée 0, vous devez case activée la source de données pour déterminer son état.

Notes

Tous les appelsDeleteEdit, et Update tous CRecordsetAddNewles appels exécutés depuis le dernier BeginTrans sont restaurés à l’état qui existait au moment de cet appel.

Après un appel à Rollback, la transaction est terminée et vous devez appeler BeginTrans à nouveau pour une autre transaction. L’enregistrement qui était actif avant d’appeler BeginTrans devient à nouveau l’enregistrement actif après Rollback.

Après une restauration, l’enregistrement qui était actif avant la restauration reste actif. Pour plus d’informations sur l’état du jeu d’enregistrements et de la source de données après une restauration, consultez l’article Transaction (ODBC) .

Exemple

Consultez l’article Transaction : Exécution d’une transaction dans un recordset (ODBC).

CDatabase::SetLoginTimeout

Appelez cette fonction membre avant d’appeler OpenEx ou Open pour remplacer le nombre de secondes par défaut autorisé avant qu’une tentative de connexion à la source de données expire.

void SetLoginTimeout(DWORD dwSeconds);

Paramètres

dwSeconds
Nombre de secondes à autoriser avant qu’une tentative de connexion expire.

Notes

Une tentative de connexion peut expirer si, par exemple, le SGBD n’est pas disponible. Appel SetLoginTimeout après avoir construit l’objet non initialisé CDatabase , mais avant d’appeler OpenEx ou Open.

La valeur par défaut des délais d’expiration de connexion est de 15 secondes. Toutes les sources de données ne prennent pas en charge la possibilité de spécifier une valeur de délai d’expiration de connexion. Si la source de données ne prend pas en charge le délai d’expiration, vous obtenez une sortie de trace, mais pas une exception. La valeur 0 signifie « infini ».

CDatabase::SetQueryTimeout

Appelez cette fonction membre pour remplacer le nombre de secondes par défaut à autoriser avant les opérations suivantes sur le délai d’expiration de la source de données connectée.

void SetQueryTimeout(DWORD dwSeconds);

Paramètres

dwSeconds
Nombre de secondes à autoriser avant qu’une tentative de requête expire.

Notes

Une opération peut expirer en raison de problèmes d’accès réseau, de temps de traitement excessif des requêtes, et ainsi de suite. Appel SetQueryTimeout avant d’ouvrir votre jeu d’enregistrements ou avant d’appeler les fonctions membres AddNewou UpdateDelete de l’ensemble d’enregistrements si vous souhaitez modifier la valeur du délai d’expiration de la requête. Le paramètre affecte tous les jeux d’enregistrements suivantsOpen, et DeleteAddNewUpdateappelle tous les jeux d’enregistrements associés à cet CDatabase objet. La modification de la valeur du délai d’expiration de la requête pour un jeu d’enregistrements après l’ouverture ne modifie pas la valeur du jeu d’enregistrements. Par exemple, les opérations suivantes Move n’utilisent pas la nouvelle valeur.

La valeur par défaut des délais d’expiration de requête est de 15 secondes. Toutes les sources de données ne prennent pas en charge la possibilité de définir une valeur de délai d’expiration de requête. Si vous définissez une valeur de délai d’expiration de requête de 0, aucun délai d’expiration ne se produit ; la communication avec la source de données peut cesser de répondre. Ce comportement peut être utile pendant le développement. Si la source de données ne prend pas en charge le délai d’expiration, vous obtenez une sortie de trace, mais pas une exception.

Voir aussi

CObject Classe
Graphique hiérarchique
CRecordset Classe