Classe CDatabase

Rappresenta una connessione a un'origine dati attraverso la quale è possibile utilizzare l'origine dati.

Sintassi

class CDatabase : public CObject

Membri

Costruttori pubblici

Nome	Descrizione
CDatabase::CDatabase	Costruisce un oggetto CDatabase. È necessario inizializzare l'oggetto chiamando OpenEx o Open.

Metodi pubblici

Nome	Descrizione
CDatabase::BeginTrans	Avvia una "transazione", una serie di chiamate reversibili alle AddNewfunzioni membro , Delete, e Update della classe CRecordset , Editnell'origine dati connessa. L'origine dati deve supportare le transazioni per BeginTrans avere alcun effetto.
CDatabase::BindParameters	Consente di associare i parametri prima di chiamare CDatabase::ExecuteSQL.
CDatabase::Cancel	Annulla un'operazione asincrona o un processo da un secondo thread.
CDatabase::CanTransact	Restituisce un valore diverso da zero se l'origine dati supporta le transazioni.
CDatabase::CanUpdate	Restituisce un valore diverso da zero se l'oggetto CDatabase è aggiornabile (non di sola lettura).
CDatabase::Close	Chiude la connessione all'origine dati.
CDatabase::CommitTrans	Completa una transazione avviata da BeginTrans. Vengono eseguiti comandi nella transazione che modificano l'origine dati.
CDatabase::ExecuteSQL	Esegue un'istruzione SQL. Non vengono restituiti record di dati.
CDatabase::GetBookmarkPersistence	Identifica le operazioni tramite cui i segnalibri vengono mantenuti negli oggetti recordset.
CDatabase::GetConnect	Restituisce il stringa di connessione ODBC utilizzato per connettere l'oggetto a un'origine CDatabase dati.
CDatabase::GetCursorCommitBehavior	Identifica l'effetto del commit di una transazione in un oggetto recordset aperto.
CDatabase::GetCursorRollbackBehavior	Identifica l'effetto del rollback di una transazione in un oggetto recordset aperto.
CDatabase::GetDatabaseName	Restituisce il nome del database attualmente in uso.
CDatabase::IsOpen	Restituisce un valore diverso da zero se l'oggetto è attualmente connesso a un'origine CDatabase dati.
CDatabase::OnSetOptions	Chiamato dal framework per impostare le opzioni di connessione standard. L'implementazione predefinita imposta il valore di timeout della query. È possibile stabilire queste opzioni in anticipo chiamando SetQueryTimeout.
CDatabase::Open	Stabilisce una connessione a un'origine dati (tramite un driver ODBC).
CDatabase::OpenEx	Stabilisce una connessione a un'origine dati (tramite un driver ODBC).
CDatabase::Rollback	Inverte le modifiche apportate durante la transazione corrente. L'origine dati torna allo stato precedente, come definito nella BeginTrans chiamata, non modificata.
CDatabase::SetLoginTimeout	Imposta il numero di secondi dopo il quale si verifica il timeout di un tentativo di connessione all'origine dati.
CDatabase::SetQueryTimeout	Imposta il numero di secondi dopo il quale si verifica il timeout delle operazioni di query del database. Influisce su tutti i recordset Opensuccessivi, AddNew, Edit, e Delete chiamate.

Membri dati pubblici

Nome	Descrizione
CDatabase::m_hdbc	Handle di connessione ODBC (Database Connectivity) aperto a un'origine dati. Digitare HDBC.

Osservazioni:

Un'origine dati è un'istanza specifica dei dati ospitati da un sistema di gestione di database (DBMS). Alcuni esempi includono Microsoft SQL Server, Microsoft Access, Borland dBASE e xBASE. È possibile avere uno o più CDatabase oggetti attivi alla volta nell'applicazione.

Nota

Se si usano le classi DAO (Data Access Objects) anziché le classi ODBC (Open Database Connectivity), usare invece la classe CDaoDatabase . Per altre informazioni, vedere l'articolo Panoramica: Programmazione del database.

Per usare CDatabase, costruire un CDatabase oggetto e chiamare la relativa OpenEx funzione membro. Verrà aperta una connessione. Quando si costruiscono CRecordset quindi oggetti per operare sull'origine dati connessa, passare il costruttore del recordset a un puntatore all'oggetto CDatabase . Al termine dell'utilizzo della connessione, chiamare la Close funzione membro ed eliminare definitivamente l'oggetto CDatabase . Close chiude tutti i recordset non chiusi in precedenza.

Per altre informazioni su CDatabase, vedere gli articoli Origine dati (ODBC) e Panoramica: Programmazione di database.

Gerarchia di ereditarietà

CObject

CDatabase

Requisiti

Intestazione: afxdb.h

CDatabase::BeginTrans

Chiamare questa funzione membro per avviare una transazione con l'origine dati connessa.

BOOL BeginTrans();

Valore restituito

Diverso da zero se la chiamata ha avuto esito positivo e le modifiche vengono eseguite solo manualmente; in caso contrario, 0.

Osservazioni:

Una transazione è costituita da una o più chiamate alle AddNewfunzioni membro , EditDelete, e Update di un CRecordset oggetto . Prima di iniziare una transazione, l'oggetto CDatabase deve essere già stato connesso all'origine dati chiamando la relativa OpenEx funzione membro o Open . Per terminare la transazione, chiamare CommitTrans per accettare tutte le modifiche all'origine dati (ed eseguirle) o chiamare Rollback per interrompere l'intera transazione. Chiamare BeginTrans dopo aver aperto tutti i recordset coinvolti nella transazione e il più vicino possibile alle operazioni di aggiornamento effettive.

Attenzione

A seconda del driver ODBC, aprire un recordset prima di chiamare BeginTrans può causare problemi durante la chiamata a Rollback. È consigliabile controllare il driver specifico in uso. Ad esempio, quando si usa il driver di Microsoft Access incluso in Microsoft ODBC Desktop Driver Pack 3.0, è necessario tenere conto del requisito del motore di database Jet che non deve iniziare una transazione in qualsiasi database con un cursore aperto. Nelle classi di database MFC un cursore aperto indica un oggetto aperto CRecordset . Per altre informazioni, vedere La nota tecnica 68.

BeginTrans può anche bloccare i record di dati nel server, a seconda della concorrenza richiesta e delle funzionalità dell'origine dati. Per informazioni sul blocco dei dati, vedere l'articolo Recordset: Locking Records (ODBC).

Le transazioni definite dall'utente sono illustrate nell'articolo Transazione (ODBC).

BeginTrans stabilisce lo stato in cui è possibile eseguire il rollback della sequenza di transazioni (invertito). Per stabilire un nuovo stato per i rollback, eseguire il commit di qualsiasi transazione corrente, quindi chiamare BeginTrans di nuovo.

Attenzione

Chiamare BeginTrans di nuovo senza chiamare CommitTrans o Rollback è un errore.

Chiamare la CanTransact funzione membro per determinare se il driver supporta le transazioni per un determinato database. È anche necessario chiamare GetCursorCommitBehavior e GetCursorRollbackBehavior per determinare il supporto per la conservazione del cursore.

Per altre informazioni sulle transazioni, vedere l'articolo Transazione (ODBC).For more information about transactions, see the article Transaction (ODBC).

Esempio

Vedere l'articolo Transazione: Esecuzione di una transazione in un oggetto Recordset (ODBC).

CDatabase::BindParameters

Eseguire l'override BindParameters quando è necessario associare i parametri prima di chiamare CDatabase::ExecuteSQL.

virtual void BindParameters(HSTMT hstmt);

Parametri

hstmt
Handle di istruzione ODBC per il quale si desidera associare i parametri.

Osservazioni:

Questo approccio è utile quando non è necessario il set di risultati da una stored procedure.

Nell'override chiamare SQLBindParameters e le funzioni ODBC correlate per associare i parametri. MFC chiama l'override prima della chiamata a ExecuteSQL. Non è necessario chiamare SQLPrepare; ExecuteSQL chiama SQLExecDirect ed elimina definitivamente l'oggetto hstmt, che viene usato una sola volta.

CDatabase::Cancel

Chiamare questa funzione membro per richiedere che l'origine dati annulla un'operazione asincrona in corso o un processo da un secondo thread.

void Cancel();

Osservazioni:

Si noti che le classi ODBC MFC non usano più l'elaborazione asincrona; per eseguire un'operazione asincrona, è necessario chiamare direttamente la funzione SQLSetConnectOptionAPI ODBC . Per altre informazioni, vedere Esecuzione asincrona.

CDatabase::CanTransact

Chiamare questa funzione membro per determinare se il database consente transazioni.

BOOL CanTransact() const;

Valore restituito

Diverso da zero se i recordset che usano questo CDatabase oggetto consentono transazioni; in caso contrario, 0.

Osservazioni:

Per informazioni sulle transazioni, vedere l'articolo Transazione (ODBC).For information about transactions, see the article Transaction (ODBC).

CDatabase::CanUpdate

Chiamare questa funzione membro per determinare se l'oggetto CDatabase consente gli aggiornamenti.

BOOL CanUpdate() const;

Valore restituito

Diverso da zero se l'oggetto CDatabase consente aggiornamenti; in caso contrario, 0, che indica che è stato passato TRUE bReadOnly quando è stato aperto l'oggetto o che l'origine CDatabase dati stessa è di sola lettura. L'origine dati è di sola lettura se una chiamata alla funzione SQLGetInfo API ODBC per SQL_DATASOURCE_READ_ONLY restituisce y.

Osservazioni:

Non tutti i driver supportano gli aggiornamenti.

CDatabase::CDatabase

Costruisce un oggetto CDatabase.

CDatabase();

Osservazioni:

Dopo aver costruito l'oggetto, è necessario chiamare la relativa OpenEx funzione membro o Open per stabilire una connessione a un'origine dati specificata.

È possibile che sia utile incorporare l'oggetto CDatabase nella classe del documento.

Esempio

Questo esempio illustra l'uso CDatabase di in una CDocumentclasse derivata da .

// 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

Chiamare questa funzione membro se si vuole disconnettersi da un'origine dati.

virtual void Close();

Osservazioni:

È necessario chiudere tutti i recordset associati all'oggetto CDatabase prima di chiamare questa funzione membro. Poiché Close non elimina definitivamente l'oggetto CDatabase , è possibile riutilizzare l'oggetto aprendo una nuova connessione alla stessa origine dati o a un'origine dati diversa.

Tutte le istruzioni o Edit in sospeso AddNew dei recordset che usano il database vengono annullate e viene eseguito il rollback di tutte le transazioni in sospeso. Tutti i recordset dipendenti dall'oggetto CDatabase vengono lasciati in uno stato non definito.

Esempio

// 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

Chiamare questa funzione membro al completamento delle transazioni.

BOOL CommitTrans();

Valore restituito

Diverso da zero se è stato eseguito correttamente il commit degli aggiornamenti; in caso contrario, 0. Se CommitTrans ha esito negativo, lo stato dell'origine dati non è definito. È necessario controllare i dati per determinarne lo stato.

Osservazioni:

Una transazione è costituita da una serie di chiamate alle AddNewfunzioni membro , EditDelete, e Update di un CRecordset oggetto che ha iniziato con una chiamata alla BeginTrans funzione membro. CommitTrans esegue il commit della transazione. Per impostazione predefinita, gli aggiornamenti vengono sottoposti immediatamente a commit; la chiamata BeginTrans fa sì che l'impegno degli aggiornamenti venga ritardato fino a quando CommitTrans non viene chiamato.

Fino a quando non si chiama CommitTrans per terminare una transazione, è possibile chiamare la Rollback funzione membro per interrompere la transazione e lasciare l'origine dati nello stato originale. Per avviare una nuova transazione, chiamare BeginTrans di nuovo.

Per altre informazioni sulle transazioni, vedere l'articolo Transazione (ODBC).For more information about transactions, see the article Transaction (ODBC).

Esempio

Vedere l'articolo Transazione: Esecuzione di una transazione in un oggetto Recordset (ODBC).

CDatabase::ExecuteSQL

Chiamare questa funzione membro quando è necessario eseguire direttamente un comando SQL.

void ExecuteSQL(LPCTSTR lpszSQL);

Parametri

lpszSQL
Puntatore a una stringa con terminazione Null contenente un comando SQL valido da eseguire. È possibile passare un oggetto CString.

Osservazioni:

Creare il comando come stringa con terminazione Null. ExecuteSQL non restituisce record di dati. Se si desidera operare sui record, utilizzare invece un oggetto recordset.

La maggior parte dei comandi per un'origine dati viene eseguita tramite oggetti recordset, che supportano i comandi per la selezione dei dati, l'inserimento di nuovi record, l'eliminazione di record e la modifica dei record. Tuttavia, non tutte le funzionalità ODBC sono supportate direttamente dalle classi di database, pertanto a volte potrebbe essere necessario effettuare una chiamata SQL diretta con ExecuteSQL.

Esempio

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

Chiamare questa funzione membro per determinare la persistenza dei segnalibri in un oggetto Recordset dopo determinate operazioni.

DWORD GetBookmarkPersistence() const;

Valore restituito

Maschera di bit che identifica le operazioni tramite cui si ottiene la persistenza dei segnalibri in un oggetto Recordset. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

Ad esempio, se si chiama CRecordset::GetBookmark e quindi si chiama CRecordset::Requery, è possibile che il segnalibro ottenuto da GetBookmark non sia più valido. È consigliabile chiamare GetBookmarkPersistence prima di chiamare CRecordset::SetBookmark.

Nella tabella seguente sono elencati i valori di maschera di bit che possono essere combinati per il valore restituito di GetBookmarkPersistence.

Valore di maschera di bit	Persistenza del segnalibro
SQL_BP_CLOSE	I segnalibri sono validi dopo un'operazione Requery .
SQL_BP_DELETE	Il segnalibro per una riga è valido dopo un'operazione Delete su tale riga.
SQL_BP_DROP	I segnalibri sono validi dopo un'operazione Close .
SQL_BP_SCROLL	I segnalibri sono validi dopo qualsiasi Move operazione. Indica semplicemente se i segnalibri sono supportati nell'oggetto Recordset, come restituito da CRecordset::CanBookmark.
SQL_BP_TRANSACTION	I segnalibri sono validi dopo il commit o il rollback di un'operazione.
SQL_BP_UPDATE	Il segnalibro per una riga è valido dopo un'operazione Update su tale riga.
SQL_BP_OTHER_HSTMT	I segnalibri associati a un oggetto Recordset sono validi in un secondo oggetto Recordset.

Per altre informazioni su questo valore restituito, vedere la funzione SQLGetInfo API ODBC in Windows SDK. Per altre informazioni sui segnalibri, vedere l'articolo Recordset: Segnalibri e posizioni assolute (ODBC).

CDatabase::GetConnect

Chiamare questa funzione membro per recuperare il stringa di connessione utilizzato durante la chiamata a OpenEx o Open che ha connesso l'oggetto a un'origine CDatabase dati.

const CString GetConnect() const;

Valore restituito

Oggetto constCString contenente il stringa di connessione se OpenEx è stato chiamato o Open ; in caso contrario, una stringa vuota.

Osservazioni:

Per CDatabase::Open una descrizione del modo in cui viene creato il stringa di connessione.

CDatabase::GetCursorCommitBehavior

Chiamare questa funzione membro per determinare in che modo un'operazione CommitTrans influisce sui cursori sugli oggetti recordset aperti.

int GetCursorCommitBehavior() const;

Valore restituito

Valore che indica l'effetto delle transazioni sugli oggetti recordset aperti. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

Nella tabella seguente sono elencati i possibili valori restituiti per GetCursorCommitBehavior e l'effetto corrispondente sul recordset aperto.

Valore restituito	Effetto sugli CRecordset oggetti
SQL_CB_CLOSE	Chiamare CRecordset::Requery immediatamente dopo il commit della transazione.
SQL_CB_DELETE	Chiamare CRecordset::Close immediatamente dopo il commit della transazione.
SQL_CB_PRESERVE	Procedere normalmente con CRecordset le operazioni.

Per altre informazioni su questo valore restituito, vedere la funzione SQLGetInfo API ODBC in Windows SDK. Per altre informazioni sulle transazioni, vedere l'articolo Transazione (ODBC).For more information about transactions, see the article Transaction (ODBC).

CDatabase::GetCursorRollbackBehavior

Chiamare questa funzione membro per determinare in che modo un'operazione Rollback influisce sui cursori sugli oggetti recordset aperti.

int GetCursorRollbackBehavior() const;

Valore restituito

Valore che indica l'effetto delle transazioni sugli oggetti recordset aperti. Per informazioni dettagliate, vedere la sezione Osservazioni.

Osservazioni:

Nella tabella seguente sono elencati i possibili valori restituiti per GetCursorRollbackBehavior e l'effetto corrispondente sul recordset aperto.

Valore restituito	Effetto sugli CRecordset oggetti
SQL_CB_CLOSE	Chiamare CRecordset::Requery immediatamente dopo il rollback della transazione.
SQL_CB_DELETE	Chiamare CRecordset::Close immediatamente dopo il rollback della transazione.
SQL_CB_PRESERVE	Procedere normalmente con CRecordset le operazioni.

Per altre informazioni su questo valore restituito, vedere la funzione SQLGetInfo API ODBC in Windows SDK. Per altre informazioni sulle transazioni, vedere l'articolo Transazione (ODBC).For more information about transactions, see the article Transaction (ODBC).

CDatabase::GetDatabaseName

Chiamare questa funzione membro per recuperare il nome del database attualmente connesso, a condizione che l'origine dati definisca un oggetto denominato "database".

CString GetDatabaseName() const;

Valore restituito

Oggetto CString contenente il nome del database se ha esito positivo; in caso contrario, un oggetto vuoto CString.

Osservazioni:

Non corrisponde al nome dell'origine dati (DSN) specificato nella OpenEx chiamata o Open . Il risultato GetDatabaseName dipende da ODBC. In generale, un database è una raccolta di tabelle. Se questa entità ha un nome, GetDatabaseName la restituisce.

È possibile, ad esempio, visualizzare questo nome in un'intestazione. Se si verifica un errore durante il recupero del nome da ODBC, GetDatabaseName restituisce un oggetto vuoto CString.

CDatabase::IsOpen

Chiamare questa funzione membro per determinare se l'oggetto è attualmente connesso a un'origine CDatabase dati.

BOOL IsOpen() const;

Valore restituito

Diverso da zero se l'oggetto CDatabase è attualmente connesso; in caso contrario, 0.

CDatabase::m_hdbc

Contiene un handle pubblico per una connessione all'origine dati ODBC, ovvero un "handle di connessione".

Osservazioni:

In genere, non sarà necessario accedere direttamente a questa variabile membro. Al contrario, il framework alloca l'handle quando si chiama OpenEx o Open. Il framework dealloca l'handle quando si chiama l'operatore delete sull'oggetto CDatabase . Si noti che la Close funzione membro non dealloca l'handle.

In alcune circostanze, tuttavia, potrebbe essere necessario usare direttamente l'handle. Ad esempio, se è necessario chiamare le funzioni API ODBC direttamente anziché tramite la classe CDatabase, potrebbe essere necessario un handle di connessione da passare come parametro. Vedere l'esempio di codice seguente.

Esempio

// 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

Il framework chiama questa funzione membro quando si esegue direttamente un'istruzione SQL con la ExecuteSQL funzione membro.

virtual void OnSetOptions(HSTMT hstmt);

Parametri

hstmt
Handle di istruzione ODBC per cui vengono impostate le opzioni.

Osservazioni:

CRecordset::OnSetOptions chiama anche questa funzione membro.

OnSetOptions imposta il valore di timeout di accesso. Se sono state eseguite chiamate precedenti alla SetQueryTimeout funzione membro e , OnSetOptions riflette i valori correnti. In caso contrario, imposta i valori predefiniti.

Nota

Prima di MFC 4.2, OnSetOptions impostare anche la modalità di elaborazione su snychronous o asincrona. A partire da MFC 4.2, tutte le operazioni sono sincrone. Per eseguire un'operazione asincrona, è necessario effettuare una chiamata diretta alla funzione SQLSetPosAPI ODBC .

Non è necessario eseguire l'override OnSetOptions per modificare il valore di timeout. Al contrario, per personalizzare il valore di timeout della query, chiamare SetQueryTimeout prima di creare un recordset; OnSetOptions userà il nuovo valore. I valori impostati si applicano alle operazioni successive su tutti i recordset o le chiamate SQL dirette.

Eseguire l'override se si desidera impostare opzioni aggiuntive OnSetOptions . L'override deve chiamare la classe OnSetOptions base prima o dopo aver chiamato la funzione SQLSetStmtOptionAPI ODBC . Seguire il metodo illustrato nell'implementazione predefinita del framework di OnSetOptions.

CDatabase::Open

Chiamare questa funzione membro per inizializzare un oggetto appena costruito CDatabase .

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

Parametri

lpszDSN
Specifica un nome di origine dati, ovvero un nome registrato con ODBC tramite il programma Amministratore ODBC. Se viene specificato un valore DSN in lpszConnect (nel formato "DSN=<data-source>"), non deve essere specificato di nuovo in lpszDSN. In questo caso, lpszDSN deve essere NULL. In caso contrario, è possibile passare NULL se si desidera presentare all'utente una finestra di dialogo Origine dati in cui l'utente può selezionare un'origine dati. Per altre informazioni, vedere Osservazioni.

bExclusive
Non supportato in questa versione della libreria di classi. Attualmente, un'asserzione non riesce se questo parametro è TRUE. L'origine dati viene sempre aperta come condivisa (non esclusiva).

bReadOnly
TRUE se si intende che la connessione sia di sola lettura e non venga consentita l'aggiornamento all'origine dati. Tutti i recordset dipendenti ereditano questo attributo. Il valore predefinito è FALSE.

lpszConnect
Specifica un stringa di connessione. Il stringa di connessione concatena informazioni, ad esempio un nome di origine dati, un ID utente valido nell'origine dati, una stringa di autenticazione utente (password, se l'origine dati ne richiede una) e altre informazioni. L'intero stringa di connessione deve essere preceduto dalla stringa "ODBC;" (maiuscola o minuscola). La "ODBC;" stringa viene utilizzata per indicare che la connessione è a un'origine dati ODBC. Ciò è dovuto alla compatibilità verso l'alto quando le versioni future della libreria di classi potrebbero supportare origini dati non ODBC.

bUseCursorLib
TRUE se si desidera caricare la DLL della libreria di cursori ODBC. La libreria di cursori maschera alcune funzionalità del driver ODBC sottostante, impedendo in modo efficace l'uso di dynaset (se il driver li supporta). Gli unici cursori supportati se la libreria di cursori viene caricata sono snapshot statici e cursori forward-only. Il valore predefinito è TRUE. Se si prevede di creare un oggetto recordset direttamente da CRecordset senza derivare da esso, non è consigliabile caricare la libreria di cursori.

Valore restituito

Diverso da zero se la connessione viene stabilita correttamente; in caso contrario, 0 se l'utente sceglie Annulla quando viene visualizzata una finestra di dialogo che richiede altre informazioni di connessione. In tutti gli altri casi, il framework genera un'eccezione.

Osservazioni:

L'oggetto di database deve essere inizializzato prima di poterlo utilizzare per costruire un oggetto recordset.

Nota

La chiamata alla OpenEx funzione membro è il modo preferito per connettersi a un'origine dati e inizializzare l'oggetto di database.

Se i parametri nella Open chiamata non contengono informazioni sufficienti per stabilire la connessione, il driver ODBC apre una finestra di dialogo per ottenere le informazioni necessarie dall'utente. Quando si chiama Open, il stringa di connessione, lpszConnect, viene archiviato privatamente nell'oggetto CDatabase ed è disponibile chiamando la GetConnect funzione membro.

Se si desidera, è possibile aprire una finestra di dialogo personalizzata prima di chiamare Open per ottenere informazioni dall'utente, ad esempio una password, quindi aggiungere tali informazioni al stringa di connessione si passa a Open. In alternativa, è possibile salvare il stringa di connessione passato in modo da poterlo riutilizzare alla successiva chiamata dell'applicazione Open a un CDatabase oggetto .

È anche possibile usare il stringa di connessione per più livelli di autorizzazione di accesso (ognuno per un oggetto diversoCDatabase) o per trasmettere altre informazioni specifiche dell'origine dati. Per altre informazioni sulle stringa di connessione, vedere capitolo 5 in Windows SDK.

È possibile che un tentativo di connessione si verifichi un timeout se, ad esempio, l'host DBMS non è disponibile. Se il tentativo di connessione non riesce, Open genera un'eccezione CDBException.

Esempio

// 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

Chiamare questa funzione membro per inizializzare un oggetto appena costruito CDatabase .

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

Parametri

lpszConnectString
Specifica un stringa di connessione ODBC. Sono inclusi il nome dell'origine dati e altre informazioni facoltative, ad esempio un ID utente e una password. Ad esempio, "DSN=SQLServer_Source;UID=SA;PWD=abc123" è un possibile stringa di connessione. Si noti che se si passa NULL per lpszConnectString, una finestra di dialogo Origine dati richiederà all'utente di selezionare un'origine dati.

dwOptions
Maschera di bit che specifica una combinazione dei valori seguenti. Il valore predefinito è 0, ovvero il database verrà aperto come condiviso con accesso in scrittura, la DLL della libreria di cursori ODBC non verrà caricata e la finestra di dialogo connessione ODBC verrà visualizzata solo se non sono presenti informazioni sufficienti per stabilire la connessione.

• CDatabase::openExclusive Non supportato in questa versione della libreria di classi. Un'origine dati viene sempre aperta come condivisa (non esclusiva). Attualmente, un'asserzione ha esito negativo se si specifica questa opzione.

• CDatabase::openReadOnly Aprire l'origine dati come di sola lettura.

• CDatabase::useCursorLib Caricare la DLL della libreria di cursori ODBC. La libreria di cursori maschera alcune funzionalità del driver ODBC sottostante, impedendo in modo efficace l'uso di dynaset (se il driver li supporta). Gli unici cursori supportati se la libreria di cursori viene caricata sono snapshot statici e cursori forward-only. Se si prevede di creare un oggetto recordset direttamente da CRecordset senza derivare da esso, non è consigliabile caricare la libreria di cursori.

• CDatabase::noOdbcDialog Non visualizzare la finestra di dialogo Connessione ODBC, indipendentemente dal fatto che vengano fornite informazioni di connessione sufficienti.

• CDatabase::forceOdbcDialog Visualizzare sempre la finestra di dialogo Connessione ODBC.

Valore restituito

Diverso da zero se la connessione viene stabilita correttamente; in caso contrario, 0 se l'utente sceglie Annulla quando viene visualizzata una finestra di dialogo che richiede altre informazioni di connessione. In tutti gli altri casi, il framework genera un'eccezione.

Osservazioni:

L'oggetto di database deve essere inizializzato prima di poterlo utilizzare per costruire un oggetto recordset.

Se il lpszConnectString parametro nella OpenEx chiamata non contiene informazioni sufficienti per stabilire la connessione, il driver ODBC apre una finestra di dialogo per ottenere le informazioni necessarie dall'utente, purché non sia stato impostato CDatabase::noOdbcDialog o CDatabase::forceOdbcDialog nel dwOptions parametro . Quando si chiama OpenEx, il stringa di connessione, lpszConnectString, viene archiviato privatamente nell'oggetto CDatabase ed è disponibile chiamando la GetConnect funzione membro.

Se si desidera, è possibile aprire una finestra di dialogo personalizzata prima di chiamare OpenEx per ottenere informazioni dall'utente, ad esempio una password, e quindi aggiungere tali informazioni al stringa di connessione passato a OpenEx. In alternativa, è possibile salvare il stringa di connessione passato in modo da poterlo riutilizzare alla successiva chiamata dell'applicazione OpenEx a un CDatabase oggetto .

È anche possibile usare il stringa di connessione per più livelli di autorizzazione di accesso (ognuno per un oggetto diversoCDatabase) o per trasmettere altre informazioni specifiche dell'origine dati. Per altre informazioni sulle stringa di connessione, vedere il capitolo 6 nella guida di riferimento per programmatori ODBC.

È possibile che un tentativo di connessione si verifichi un timeout se, ad esempio, l'host DBMS non è disponibile. Se il tentativo di connessione non riesce, OpenEx genera un'eccezione CDBException.

Esempio

// 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

Chiamare questa funzione membro per invertire le modifiche apportate durante una transazione.

BOOL Rollback();

Valore restituito

Diverso da zero se la transazione è stata annullata correttamente; in caso contrario, 0. Se una Rollback chiamata ha esito negativo, gli stati dell'origine dati e della transazione non sono definiti. Se Rollback restituisce 0, è necessario controllare l'origine dati per determinarne lo stato.

Osservazioni:

Tutte le CRecordset AddNewchiamate , Edit, Deletee Update eseguite dopo l'ultimo viene BeginTrans eseguito il rollback allo stato esistente al momento della chiamata.

Dopo una chiamata a Rollback, la transazione è finita ed è necessario chiamare BeginTrans di nuovo per un'altra transazione. Il record corrente prima di chiamare BeginTrans diventa nuovamente il record corrente dopo Rollback.

Dopo un rollback, il record corrente prima del rollback rimane corrente. Per informazioni dettagliate sullo stato del recordset e dell'origine dati dopo un rollback, vedere l'articolo Transazione (ODBC).

Esempio

Vedere l'articolo Transazione: Esecuzione di una transazione in un oggetto Recordset (ODBC).

CDatabase::SetLoginTimeout

Chiamare questa funzione membro, prima di chiamare OpenEx o Open , per eseguire l'override del numero predefinito di secondi consentiti prima del timeout di una connessione all'origine dati tentata.

void SetLoginTimeout(DWORD dwSeconds);

Parametri

dwSeconds
Numero di secondi da consentire prima del timeout di un tentativo di connessione.

Osservazioni:

Un tentativo di connessione potrebbe verificarsi un timeout se, ad esempio, il sistema DBMS non è disponibile. Chiamare SetLoginTimeout dopo aver costruito l'oggetto non inizializzato CDatabase , ma prima di chiamare OpenEx o Open.

Il valore predefinito per i timeout di accesso è 15 secondi. Non tutte le origini dati supportano la possibilità di specificare un valore di timeout di accesso. Se l'origine dati non supporta il timeout, si ottiene l'output di traccia ma non un'eccezione. Il valore 0 indica "infinito".

CDatabase::SetQueryTimeout

Chiamare questa funzione membro per eseguire l'override del numero predefinito di secondi consentiti prima del timeout delle operazioni successive sull'origine dati connessa.

void SetQueryTimeout(DWORD dwSeconds);

Parametri

dwSeconds
Numero di secondi consentiti prima del timeout di un tentativo di query.

Osservazioni:

Un'operazione potrebbe verificarsi un timeout a causa di problemi di accesso alla rete, tempi di elaborazione delle query eccessivi e così via. Chiamare SetQueryTimeout prima di aprire il recordset o prima di chiamare le funzioni membro del AddNewUpdate recordset se Delete si desidera modificare il valore di timeout della query. L'impostazione influisce su tutte le chiamate successive Open, AddNew, Updatee Delete a tutti i recordset associati a questo CDatabase oggetto. La modifica del valore di timeout della query per un recordset dopo l'apertura non modifica il valore per il recordset. Ad esempio, le operazioni successive Move non usano il nuovo valore.

Il valore predefinito per i timeout delle query è 15 secondi. Non tutte le origini dati supportano la possibilità di impostare un valore di timeout della query. Se si imposta un valore di timeout della query pari a 0, non si verifica alcun timeout; la comunicazione con l'origine dati potrebbe smettere di rispondere. Questo comportamento può essere utile durante lo sviluppo. Se l'origine dati non supporta il timeout, si ottiene l'output di traccia ma non un'eccezione.

Vedi anche

CObject Classe
Grafico della gerarchia
CRecordset Classe