Classe `CDatabase`

Artigo
06/16/2023

Representa uma conexão com uma fonte de dados, por meio da qual você pode operar na fonte de dados.

Sintaxe

class CDatabase : public CObject

Membros

Construtores públicos

Nome	Descrição
`CDatabase::CDatabase`	Constrói um objeto `CDatabase`. Você deve inicializar o objeto chamando `OpenEx` ou `Open`.

Métodos públicos

Nome	Descrição
`CDatabase::BeginTrans`	Inicia uma "transação" – uma série de chamadas reversíveis para as funções de membro `AddNew`, `Edit`, `Delete` e `Update` da classe `CRecordset` – na fonte de dados conectada. A fonte de dados deve dar suporte a transações para `BeginTrans` para que tenham qualquer efeito.
`CDatabase::BindParameters`	Permite associar parâmetros antes de chamar `CDatabase::ExecuteSQL`.
`CDatabase::Cancel`	Cancela uma operação assíncrona ou um processo de um segundo thread.
`CDatabase::CanTransact`	Retornará diferente de zero se a fonte de dados der suporte a transações.
`CDatabase::CanUpdate`	Retornará diferente de zero se o objeto `CDatabase` for atualizável (não somente leitura).
`CDatabase::Close`	Fecha a conexão de fonte de dados.
`CDatabase::CommitTrans`	Conclui uma transação iniciada por `BeginTrans`. Os comandos na transação que alteram a fonte de dados são realizados.
`CDatabase::ExecuteSQL`	Executa uma instrução SQL. Nenhum registro de dados é retornado.
`CDatabase::GetBookmarkPersistence`	Identifica as operações por meio das quais os indicadores persistem em objetos de conjunto de registros.
`CDatabase::GetConnect`	Retorna a cadeia de conexão ODBC usada para conectar o objeto `CDatabase` a uma fonte de dados.
`CDatabase::GetCursorCommitBehavior`	Identifica o efeito de confirmar uma transação em um objeto de conjunto de registros aberto.
`CDatabase::GetCursorRollbackBehavior`	Identifica o efeito de reverter uma transação em um objeto de conjunto de registros aberto.
`CDatabase::GetDatabaseName`	Retorna o nome do banco de dados atualmente em uso.
`CDatabase::IsOpen`	Retornará diferente de zero se o objeto `CDatabase` estiver conectado a uma fonte de dados no momento.
`CDatabase::OnSetOptions`	Chamado pela estrutura para definir opções de conexão padrão. A implementação padrão define o valor do tempo limite da consulta. Você pode estabelecer essas opções antecipadamente chamando `SetQueryTimeout`.
`CDatabase::Open`	Estabelece uma conexão com uma fonte de dados (por meio de um driver ODBC).
`CDatabase::OpenEx`	Estabelece uma conexão com uma fonte de dados (por meio de um driver ODBC).
`CDatabase::Rollback`	Inverte as alterações feitas durante a transação atual. A fonte de dados retorna ao estado anterior, conforme definido na chamada `BeginTrans`, sem alteração.
`CDatabase::SetLoginTimeout`	Define o número de segundos após o qual uma tentativa de conexão de fonte de dados atingirão o tempo limite.
`CDatabase::SetQueryTimeout`	Define o número de segundos após o qual as operações de consulta de banco de dados atingirão o tempo limite. Afeta todas as chamadas `Open`, `AddNew`, `Edit` e `Delete` do conjunto de registros.

Membros de Dados Públicos

Nome	Descrição
`CDatabase::m_hdbc`	Abra o identificador de conexão ODBC (Conectividade de Banco de Dados) com uma fonte de dados. Digite HDBC.

Comentários

Uma fonte de dados é uma instância específica dos dados hospedados por algum DBMS (sistema de gerenciamento de banco de dados). Exemplos incluem Microsoft SQL Server, Microsoft Access, Borland dBASE e xBASE. Você pode ter um ou mais objetos CDatabase ativos por vez em seu aplicativo.

Observação

Se você estiver trabalhando com as classes DAO (Objetos de Acesso a Dados) em vez das classes ODBC (Open Database Connectivity), use a classe CDaoDatabase. Para obter mais informações, confira o artigo Visão geral: programação de banco de dados.

Para usar CDatabase, construa um objeto CDatabase e chame sua função de membro OpenEx. Isso abre uma conexão. Quando você construir objetos CRecordset para operar na fonte de dados conectada, passe um ponteiro para o construtor do conjunto de registros para o objeto CDatabase. Quando terminar de usar a conexão, chame a função de membro Close e destrua o objeto CDatabase. Close fecha todos os conjuntos de registros que você não fechou anteriormente.

Para mais informações sobre CDatabase, confira os artigos Fonte de dados (ODBC) e Visão geral: programação de banco de dados.

Hierarquia de herança

CObject

CDatabase

Requisitos

Cabeçalho: afxdb.h

`CDatabase::BeginTrans`

Chame essa função de membro para iniciar uma transação com a fonte de dados conectada.

BOOL BeginTrans();

Valor de retorno

Não zero se a chamada tiver sido bem-sucedida e as alterações forem confirmadas apenas manualmente; caso contrário, 0.

Comentários

Uma transação consiste em uma ou mais chamadas para as funções de membro AddNew, Edit, Delete e Update de um objeto CRecordset. Antes de iniciar uma transação, o objeto CDatabase já deve ter sido conectado à fonte de dados chamando sua função de membro OpenEx ou Open. Para encerrar a transação, chame CommitTrans para aceitar todas as alterações na fonte de dados (e executá-las) ou chame Rollback para anular toda a transação. Chame BeginTrans depois de abrir todos os conjuntos de registros envolvidos na transação e o mais próximo possível das operações de atualização reais.

Cuidado

Dependendo do driver ODBC, abrir um conjunto de registros antes da chamada BeginTrans pode causar problemas ao chamar Rollback. Você deve verificar o driver específico que está usando. Por exemplo, ao usar o driver do Microsoft Access incluído no Microsoft ODBC Desktop Driver Pack 3.0, você deve responder pelo requisito do mecanismo de banco de dados Jet de que você não deve iniciar uma transação em qualquer banco de dados que tenha um cursor aberto. Nas classes de banco de dados MFC, um cursor aberto significa um objeto CRecordset aberto. Para mais informações, confira Nota Técnica 68.

BeginTrans também pode bloquear registros de dados no servidor, dependendo da simultaneidade solicitada e dos recursos da fonte de dados. Para informações sobre como bloquear dados, confira o artigo Conjunto de registros: bloqueando registros (ODBC).

As transações definidas pelo usuário são explicadas no artigo Transação (ODBC).

BeginTrans estabelece o estado para o qual a sequência de transações pode ser revertida. Para estabelecer um novo estado para reversões, faça o commit de qualquer transação atual e chame BeginTrans novamente.

Cuidado

Chamar BeginTrans novamente sem chamar CommitTrans ou Rollback é um erro.

Chame a função de membro CanTransact para determinar se o driver dá suporte a transações para um determinado banco de dados. Você também deve chamar GetCursorCommitBehavior e GetCursorRollbackBehavior para determinar o suporte para preservação do cursor.

Para mais informações sobre transações, confira o artigo Transação (ODBC).

Exemplo

Confira o artigo Transação: como realizar uma transação em um conjunto de registros (ODBC).

`CDatabase::BindParameters`

Substitua BindParameters quando você precisar associar parâmetros antes de chamar CDatabase::ExecuteSQL.

virtual void BindParameters(HSTMT hstmt);

Parâmetros

hstmt
O identificador de instrução ODBC para o qual você deseja associar parâmetros.

Comentários

Essa abordagem é útil quando você não precisa do conjunto de resultados de um procedimento armazenado.

Em sua substituição, chame SQLBindParameters e as funções ODBC relacionadas para associar os parâmetros. O MFC chama sua substituição antes da chamada para ExecuteSQL. Você não precisa chamar SQLPrepare; ExecuteSQL chama SQLExecDirect e destrói hstmt, que é usado apenas uma vez.

`CDatabase::Cancel`

Chame essa função de membro para solicitar que a fonte de dados cancele uma operação assíncrona em andamento ou um processo de um segundo thread.

void Cancel();

Comentários

Observe que as classes ODBC MFC não usam mais processamento assíncrono; para executar uma operação assíncrona, você deve chamar diretamente a função de API ODBC SQLSetConnectOption. Para obter mais informações, consulte Execução assíncrona.

`CDatabase::CanTransact`

Chame essa função de membro para determinar se o banco de dados permite transações.

BOOL CanTransact() const;

Valor de retorno

Não zero se os conjuntos de registros que usam esse objeto CDatabase permitem transações; caso contrário, 0.

Comentários

Para informações sobre transações, confira o artigo Transação (ODBC).

`CDatabase::CanUpdate`

Chame essa função membro para determinar se o objeto CDatabase permite atualizações.

BOOL CanUpdate() const;

Valor de retorno

Não zero se o objeto CDatabase permitir atualizações; caso contrário, 0, indicando que você passou TRUE em bReadOnly quando abriu o objeto CDatabase ou que a própria fonte de dados é somente leitura. A fonte de dados será somente leitura se uma chamada para a função de API ODBC SQLGetInfo para SQL_DATASOURCE_READ_ONLY retornar y.

Comentários

Nem todos os drivers dão suporte a atualizações.

`CDatabase::CDatabase`

Constrói um objeto CDatabase.

CDatabase();

Comentários

Depois de construir o objeto, você deve chamar sua função de membro OpenEx ou Open para estabelecer uma conexão com uma fonte de dados especificada.

Você pode achar conveniente inserir o objeto CDatabase em sua classe de documento.

Exemplo

Este exemplo ilustra o uso de CDatabase em uma classe derivada de CDocument.

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

Chame essa função de membro se você quiser se desconectar de uma fonte de dados.

virtual void Close();

Comentários

Você deve fechar todos os conjuntos de registros associados ao objeto CDatabase antes de chamar essa função de membro. Como Close não destrói o objeto CDatabase, você pode reutilizar o objeto abrindo uma nova conexão com a mesma fonte de dados ou uma fonte de dados diferente.

Todas as instruções AddNew ou Edit pendentes de conjuntos de registros usando o banco de dados são canceladas e todas as transações pendentes são revertidas. Todos os conjuntos de registros dependentes do objeto CDatabase são deixados em um estado indefinido.

Exemplo

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

Chame essa função de membro ao concluir transações.

BOOL CommitTrans();

Valor de retorno

Não zero se as atualizações foram confirmadas com êxito; caso contrário, 0. Se CommitTrans falhar, o estado da fonte de dados será indefinido. Você deve verificar os dados para determinar seu estado.

Comentários

Uma transação consiste em uma série de chamadas para as funções de membro AddNew, Edit, Delete e Update de um objeto CRecordset que começou com uma chamada para a função de membro BeginTrans. CommitTrans faz commit da transação. Por padrão, as atualizações são confirmadas imediatamente; chamar BeginTrans faz com que o compromisso de atualizações seja adiado até CommitTrans que seja chamado.

Até que você chame CommitTrans para encerrar uma transação, pode chamar a função de membro Rollback para anular a transação e deixar a fonte de dados em seu estado original. Para iniciar uma transação, chame BeginTrans novamente.

Para mais informações sobre transações, confira o artigo Transação (ODBC).

Exemplo

Confira o artigo Transação: como realizar uma transação em um conjunto de registros (ODBC).

`CDatabase::ExecuteSQL`

Chame essa função de membro quando precisar executar um comando SQL diretamente.

void ExecuteSQL(LPCTSTR lpszSQL);

Parâmetros

lpszSQL
Ponteiro para uma cadeia de caracteres terminada em nulo que contém um comando SQL válido a ser executado. Você pode passar um CString.

Comentários

Crie o comando como uma cadeia de caracteres terminada em nulo. ExecuteSQL não retorna registros de dados. Se você quiser operar em registros, use um objeto de conjunto de registros em vez disso.

A maioria dos comandos para uma fonte de dados é emitida por meio de objetos de conjunto de registros, que dão suporte a comandos para selecionar dados, inserir registros, excluir registros e editar registros. No entanto, nem todas as funcionalidades do ODBC têm suporte direto nas classes de banco de dados, assim, às vezes pode ser necessário fazer uma chamada SQL direta com ExecuteSQL.

Exemplo

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`

Chame essa função de membro para determinar a persistência de indicadores em um objeto Recordset depois de determinadas operações.

DWORD GetBookmarkPersistence() const;

Valor de retorno

Uma bitmask que identifica as operações através das quais persistem os indicadores em um objeto recordset. Para obter detalhes, consulte Observações.

Comentários

Por exemplo, se você chamar CRecordset::GetBookmark e chamar CRecordset::Requery, o indicador obtido a partir de GetBookmark pode não ser mais válido. Você deve chamar GetBookmarkPersistence antes de chamar CRecordset::SetBookmark.

A tabela a seguir lista os valores de bitmask que podem ser combinados para o valor retornado de GetBookmarkPersistence.

Valor de bitmask	Persistência de indicador
`SQL_BP_CLOSE`	Os indicadores são válidos após uma operação `Requery`.
`SQL_BP_DELETE`	O indicador de uma linha é válido depois da operação `Delete` dessa linha.
`SQL_BP_DROP`	Os indicadores são válidos após uma operação `Close`.
`SQL_BP_SCROLL`	Os indicadores são válidos após qualquer operação `Move`. Isso simplesmente identifica se os indicadores são compatíveis com o conjunto de registros, como retornado por `CRecordset::CanBookmark`.
`SQL_BP_TRANSACTION`	Os indicadores são válidos depois que uma transação é confirmada ou revertida.
`SQL_BP_UPDATE`	O indicador de uma linha é válido depois da operação `Update` dessa linha.
`SQL_BP_OTHER_HSTMT`	Indicadores associados a um objeto recordset são válidos em um segundo conjunto de registros.

Para mais informações sobre este valor retornado, confira a função da API ODBC SQLGetInfo no SDK do Windows. Para mais informações sobre os indicadores, confira o artigo Recordset: Bookmarks and Absolute Positions (ODBC).

`CDatabase::GetConnect`

Chame essa função de membro para recuperar a cadeia de conexão usada durante a chamada a OpenEx ou Open que conectou o objeto CDatabase a uma fonte de dados.

const CString GetConnect() const;

Valor de retorno

Um constCString contendo a cadeia de conexão se OpenEx ou Open tiver sido chamado; caso contrário, uma cadeia de caracteres vazia.

Comentários

Confira CDatabase::Open para uma descrição de como a cadeia de conexão é criada.

`CDatabase::GetCursorCommitBehavior`

Chame essa função de membro para determinar como uma operação CommitTrans afeta cursores em objetos de conjunto de registros abertos.

int GetCursorCommitBehavior() const;

Valor de retorno

Um valor que indica o efeito das transações em objetos de conjunto de registros abertos. Para obter detalhes, consulte Observações.

Comentários

A tabela a seguir lista os valores retornados possíveis para GetCursorCommitBehavior e o efeito correspondente no conjunto de registros aberto.

Valor retornado	Efeito sobre objetos `CRecordset`
`SQL_CB_CLOSE`	Chame `CRecordset::Requery` imediatamente após o commit da transação.
`SQL_CB_DELETE`	Chame `CRecordset::Close` imediatamente após o commit da transação.
`SQL_CB_PRESERVE`	Prossiga normalmente com operações `CRecordset`.

Para mais informações sobre este valor retornado, confira a função da API ODBC SQLGetInfo no SDK do Windows. Para mais informações sobre transações, confira o artigo Transação (ODBC).

`CDatabase::GetCursorRollbackBehavior`

Chame essa função de membro para determinar como uma operação Rollback afeta cursores em objetos de conjunto de registros abertos.

int GetCursorRollbackBehavior() const;

Valor de retorno

Um valor que indica o efeito das transações em objetos de conjunto de registros abertos. Para obter detalhes, consulte Observações.

Comentários

A tabela a seguir lista os valores retornados possíveis para GetCursorRollbackBehavior e o efeito correspondente no conjunto de registros aberto.

Valor retornado	Efeito sobre objetos `CRecordset`
`SQL_CB_CLOSE`	Chame `CRecordset::Requery` imediatamente após a reversão da transação.
`SQL_CB_DELETE`	Chame `CRecordset::Close` imediatamente após a reversão da transação.
`SQL_CB_PRESERVE`	Prossiga normalmente com operações `CRecordset`.

Para mais informações sobre este valor retornado, confira a função da API ODBC SQLGetInfo no SDK do Windows. Para mais informações sobre transações, confira o artigo Transação (ODBC).

`CDatabase::GetDatabaseName`

Chame essa função de membro para recuperar o nome do banco de dados conectado no momento (desde que a fonte de dados defina um objeto nomeado chamado "banco de dados").

CString GetDatabaseName() const;

Valor de retorno

Um CString que contém o nome do banco de dados se tiver êxito; caso contrário, um CString vazio.

Comentários

Isso não é o mesmo que o DSN (nome da fonte de dados) especificado na chamada OpenEx ou Open. O que GetDatabaseName retorna depende do ODBC. Em geral, um banco de dados é uma coleção de tabelas. Se essa entidade tiver um nome, GetDatabaseName a retornará.

Você pode, por exemplo, querer exibir esse nome em um título. Se ocorrer um erro ao recuperar o nome do ODBC, GetDatabaseName retornará um CString vazio.

`CDatabase::IsOpen`

Chame essa função de membro para determinar se o objeto CDatabase está conectado atualmente a uma fonte de dados.

BOOL IsOpen() const;

Valor de retorno

Não zero se o objeto CDatabase estiver conectado no momento; caso contrário, 0.

`CDatabase::m_hdbc`

Contém um identificador público para uma conexão de fonte de dados ODBC – um "identificador de conexão".

Comentários

Em geral, você não precisará acessar essa variável de membro diretamente. Em vez disso, a estrutura aloca o identificador quando você chama OpenEx ou Open. A estrutura desaloca o identificador quando você chama o operador delete no objeto CDatabase. Observe que a função de membro Close não desaloca o identificador.

Em algumas circunstâncias, no entanto, talvez seja necessário usar o identificador diretamente. Por exemplo, se você precisar chamar funções de API ODBC diretamente em vez de por meio da classe CDatabase, talvez seja necessário um identificador de conexão para passar como um parâmetro. Confira o exemplo de código abaixo.

Exemplo

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

A estrutura chama essa função de membro ao executar diretamente uma instrução SQL com a função de membro ExecuteSQL.

virtual void OnSetOptions(HSTMT hstmt);

Parâmetros

hstmt
O identificador da instrução ODBC para quais opções estão sendo definidas.

Comentários

CRecordset::OnSetOptions também chama essa função de membro.

OnSetOptions define o valor do tempo limite de logon. Se houve chamadas anteriores para a função e membro SetQueryTimeout, OnSetOptions reflete os valores atuais; caso contrário, ele define valores padrão.

Observação

Antes do MFC 4.2, OnSetOptions definem também o modo de processamento como snychronous ou assíncrono. Do MFC 4.2 em diante, todas as operações são síncronas. Para executar uma operação assíncrona, faça uma chamada direta para a função da API ODBC SQLSetPos.

Você não precisa substituir OnSetOptions para alterar o valor do tempo limite. Em vez disso, para personalizar o valor do tempo limite da consulta, chame SetQueryTimeout antes de criar um conjunto de registros; OnSetOptions usará o novo valor. Os valores definidos se aplicam a operações subsequentes em todos os conjuntos de registros ou chamadas SQL diretas.

Substitua OnSetOptions se você quiser definir opções adicionais. Sua substituição deve chamar a classe base OnSetOptions antes ou depois de chamar a função da API ODBC SQLSetStmtOption. Siga o método ilustrado na implementação padrão da estrutura de OnSetOptions.

`CDatabase::Open`

Chame essa função de membro para inicializar um objeto CDatabase que acaba de ser construído.

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

Parâmetros

lpszDSN
Especifica um nome de fonte de dados, um nome registrado com ODBC por meio do programa Administrador ODBC. Se um valor DSN for especificado em lpszConnect (na forma "DSN=<data-source>"), ele não deverá ser especificado novamente em lpszDSN. Nesse caso, lpszDSN deve ser NULL. Caso contrário, você poderá passar NULL se quiser apresentar ao usuário uma caixa de diálogo fonte de dados na qual ele pode selecionar uma fonte de dados. Para mais informações, confira Comentários.

bExclusive
Não há suporte nesta versão da biblioteca de classes. Atualmente, uma declaração falhará se esse parâmetro for TRUE. A fonte de dados sempre é aberta como compartilhada (não exclusiva).

bReadOnly
TRUE se você pretende que a conexão seja somente leitura e para proibir atualizações para a fonte de dados. Todos os conjuntos de registros dependentes herdam esse atributo. O valor padrão é FALSE.

lpszConnect
Especifica uma cadeia de conexão. A cadeia de conexão concatena informações, possivelmente incluindo um nome de fonte de dados, uma ID de usuário válida na fonte de dados, uma cadeia de caracteres de autenticação do usuário (senha, se a fonte de dados exigir uma) e outras informações. A cadeia de conexão inteira deve ser prefixada pela cadeia de caracteres "ODBC;" (maiúsculas ou minúsculas). A cadeia de caracteres "ODBC;" é usada para indicar que a conexão é com uma fonte de dados ODBC; isso é feito para compatibilidade com versões posteriores quando novas versões da biblioteca de classes puderem dar suporte a fontes de dados não ODBC.

bUseCursorLib
TRUE se você quiser que a DLL da Biblioteca de Cursores ODBC seja carregada. A biblioteca de cursores mascara algumas funcionalidades do driver ODBC subjacente, impedindo efetivamente o uso de dynasets (se o driver der suporte a eles). Os únicos cursores com suporte se a biblioteca de cursores for carregada são instantâneos estáticos e cursores somente de encaminhamento. O valor padrão é TRUE. Se você planeja criar um objeto de conjunto de registros CRecordset diretamente sem derivar dele, não deverá carregar a biblioteca de cursores.

Valor de retorno

Não zero se a conexão for feita com êxito; caso contrário, 0 se o usuário escolher Cancelar quando apresentada uma caixa de diálogo solicitando mais informações de conexão. Em todos os outros casos, a estrutura gera uma exceção.

Comentários

Seu objeto de banco de dados deve ser inicializado para ser usado para construir um objeto de conjunto de registros.

Observação

Chamar a função de membro OpenEx é a maneira preferencial de se conectar a uma fonte de dados e inicializar seu objeto de banco de dados.

Se os parâmetros em sua chamada Open não contiverem informações suficientes para fazer a conexão, o driver ODBC abrirá uma caixa de diálogo para obter as informações necessárias do usuário. Quando você chama Open, sua cadeia de conexão, lpszConnect, é armazenada de modo privado no objeto CDatabase e fica disponível chamando a função de membro GetConnect.

Se desejar, você pode abrir uma caixa de diálogo própria antes de chamar Open para obter informações do usuário, como uma senha, e então adicionar essas informações à cadeia de conexão que você passa para Open. Outra opção é salvar a cadeia de conexão que você passa para reutilizá-la na próxima vez que o aplicativo chamar Open em um objeto CDatabase.

Você também pode usar a cadeia de conexão para vários níveis de autorização de logon (cada um para um objeto CDatabase diferente) ou para transmitir outras informações específicas da fonte de dados. Para mais informações sobre cadeias de conexão, confira o Capítulo 5 no SDK do Windows.

Uma tentativa de conexão poderá atingir tempo limite se, por exemplo, o host DBMS não estiver disponível. Se a tentativa de conexão falhar, Open gerará um CDBException.

Exemplo

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

Chame essa função de membro para inicializar um objeto CDatabase que acaba de ser construído.

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

Parâmetros

lpszConnectString
Especifica uma cadeia de conexão ODBC. Isso inclui o nome da fonte de dados, bem como outras informações opcionais, como uma ID de usuário e uma senha. Por exemplo, "DSN=SQLServer_Source;UID=SA;PWD=abc123" é uma possível cadeia de conexão. Observe que, se você passar NULL, lpszConnectStringuma caixa de diálogo fonte de dados solicitará que o usuário selecione uma fonte de dados.

dwOptions
Uma máscara de bits que especifica uma combinação dos valores a seguir. O valor padrão é 0, o que significa que o banco de dados será aberto como compartilhado com acesso de gravação, a DLL da Biblioteca de Cursores ODBC não será carregada e a caixa de diálogo de conexão ODBC será exibida somente se não houver informações suficientes para fazer a conexão.

CDatabase::openExclusive Não há suporte nesta versão da biblioteca de classes. Uma fonte de dados sempre é aberta como compartilhada (não exclusiva). Atualmente, uma declaração falhará se você especificar essa opção.
CDatabase::openReadOnly Abra a fonte de dados como somente leitura.
CDatabase::useCursorLib Carregue a DLL da Biblioteca de Cursores ODBC. A biblioteca de cursores mascara algumas funcionalidades do driver ODBC subjacente, impedindo efetivamente o uso de dynasets (se o driver der suporte a eles). Os únicos cursores com suporte se a biblioteca de cursores for carregada são instantâneos estáticos e cursores somente de encaminhamento. Se você planeja criar um objeto de conjunto de registros CRecordset diretamente sem derivar dele, não deverá carregar a biblioteca de cursores.
CDatabase::noOdbcDialog Não exiba a caixa de diálogo de conexão ODBC, independentemente de informações de conexão suficientes serem fornecidas.
CDatabase::forceOdbcDialog Sempre exiba a caixa de diálogo de conexão ODBC.

Valor de retorno

Comentários

Seu objeto de banco de dados deve ser inicializado para ser usado para construir um objeto de conjunto de registros.

Se o parâmetro lpszConnectString em sua chamada OpenEx não contiver informações suficientes para fazer a conexão, o driver ODBC abrirá uma caixa de diálogo para obter as informações necessárias do usuário, desde que você não tenha definido CDatabase::noOdbcDialog ou CDatabase::forceOdbcDialog no parâmetro dwOptions. Quando você chama OpenEx, sua cadeia de conexão, lpszConnectString, é armazenada de modo privado no objeto CDatabase e fica disponível chamando a função de membro GetConnect.

Se desejar, você pode abrir sua própria caixa de diálogo antes de chamar OpenEx para obter informações do usuário, como uma senha, e então adicionar essas informações à cadeia de conexão que você passa para OpenEx. Outra opção é salvar a cadeia de conexão que você passa para reutilizá-la na próxima vez que o aplicativo chamar OpenEx em um objeto CDatabase.

Uma tentativa de conexão poderá atingir tempo limite se, por exemplo, o host DBMS não estiver disponível. Se a tentativa de conexão falhar, OpenEx gerará um CDBException.

Exemplo

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

Chame essa função de membro para reverter as alterações feitas durante uma transação.

BOOL Rollback();

Valor de retorno

Não zero se a transação tiver sido revertida com êxito; caso contrário, 0. Se uma chamada a Rollback falhar, a fonte de dados e os estados de transação serão indefinidos. Se Rollback retornar 0, você deverá verificar a fonte de dados para determinar seu estado.

Comentários

Todas as CRecordset AddNewchamadas , Edit, Deletee Update executadas desde a última BeginTrans são revertidas para o estado que existia no momento dessa chamada.

Após uma chamada a Rollback, a transação acabou e você deve chamar BeginTrans novamente para outra transação. O registro que era atual antes de você chamar BeginTrans se torna o registro atual novamente depois de Rollback.

Após uma reversão, o registro que era atual antes da reversão permanece atual. Para detalhes sobre o estado do conjunto de registros e a fonte de dados após uma reversão, confira o artigo Transação (ODBC).

Exemplo

Confira o artigo Transação: como realizar uma transação em um conjunto de registros (ODBC).

`CDatabase::SetLoginTimeout`

Chame essa função de membro antes de chamar OpenEx ou Open para substituir o número padrão de segundos permitido antes de uma tentativa de conexão de fonte de dados atingir o tempo limite.

void SetLoginTimeout(DWORD dwSeconds);

Parâmetros

dwSeconds
O número de segundos a serem permitidos antes de uma tentativa de conexão atingir o tempo limite.

Comentários

Uma tentativa de conexão poderá atingir o tempo limite se, por exemplo, o DBMS não estiver disponível. Chame SetLoginTimeout depois de construir o objeto CDatabase não inicializado, mas antes de chamar OpenEx ou Open.

O valor padrão para tempos limite de logon é de 15 segundos. Nem todas as fontes de dados dão suporte à capacidade de especificar um valor de tempo limite de logon. Se a fonte de dados não der suporte ao tempo limite, você obterá a saída de rastreamento, mas não uma exceção. Um valor 0 significa "infinito".

`CDatabase::SetQueryTimeout`

Chame essa função de membro para substituir o número padrão de segundos a ser permitido antes das operações subsequentes no tempo limite da fonte de dados conectada.

void SetQueryTimeout(DWORD dwSeconds);

Parâmetros

dwSeconds
O número de segundos antes de uma tentativa de consulta atingir tempo limite.

Comentários

Uma operação pode atingir tempo limite devido a problemas de acesso à rede, tempo excessivo de processamento de consulta e assim por diante. Chame SetQueryTimeout antes de abrir o conjunto de registros ou antes de chamar as funções de membro AddNew, Update ou Delete do o conjunto de registros se você quiser alterar o valor do tempo limite da consulta. A configuração afeta todas as chamadas Open, AddNew, Update e Delete subsequentes para todos os conjuntos de registros associados a esse objeto CDatabase. Alterar o valor do tempo limite da consulta para um conjunto de registros após a abertura não altera o valor do conjunto de registros. Por exemplo, as operações Move subsequentes não usam o novo valor.

O valor padrão para tempos limite de consulta é de 15 segundos. Nem todas as fontes de dados dão suporte à capacidade de definir um valor de tempo limite de consulta. Se você definir um valor de tempo limite de consulta de 0, nenhum tempo limite ocorrerá; a comunicação com a fonte de dados poderá deixar de responder. Esse comportamento pode ser útil durante o desenvolvimento. Se a fonte de dados não der suporte ao tempo limite, você obterá a saída de rastreamento, mas não uma exceção.

Confira também

Classe CObject
Gráfico da hierarquia
Classe CRecordset

Compartilhar via

Classe CDatabase

Sintaxe

Membros

Construtores públicos

Métodos públicos

Membros de Dados Públicos

Comentários

Hierarquia de herança

Requisitos

CDatabase::BeginTrans

Valor de retorno

Comentários

Exemplo

CDatabase::BindParameters

Parâmetros

Comentários

CDatabase::Cancel

Comentários

CDatabase::CanTransact

Valor de retorno

Comentários

CDatabase::CanUpdate

Valor de retorno

Comentários

CDatabase::CDatabase

Comentários

Exemplo

CDatabase::Close

Comentários

Exemplo

CDatabase::CommitTrans

Valor de retorno

Comentários

Exemplo

CDatabase::ExecuteSQL

Parâmetros

Comentários

Exemplo

CDatabase::GetBookmarkPersistence

Valor de retorno

Comentários

CDatabase::GetConnect

Valor de retorno

Comentários

CDatabase::GetCursorCommitBehavior

Valor de retorno

Comentários

CDatabase::GetCursorRollbackBehavior

Valor de retorno

Comentários

CDatabase::GetDatabaseName

Valor de retorno

Comentários

CDatabase::IsOpen

Valor de retorno

CDatabase::m_hdbc

Comentários

Exemplo

CDatabase::OnSetOptions

Parâmetros

Comentários

CDatabase::Open

Parâmetros

Valor de retorno

Comentários

Exemplo

CDatabase::OpenEx

Parâmetros

Valor de retorno

Comentários

Exemplo

CDatabase::Rollback

Valor de retorno

Comentários

Exemplo

CDatabase::SetLoginTimeout

Parâmetros

Comentários

CDatabase::SetQueryTimeout

Classe `CDatabase`

`CDatabase::BeginTrans`

`CDatabase::BindParameters`

`CDatabase::Cancel`

`CDatabase::CanTransact`

`CDatabase::CanUpdate`

`CDatabase::CDatabase`

`CDatabase::Close`

`CDatabase::CommitTrans`

`CDatabase::ExecuteSQL`

`CDatabase::GetBookmarkPersistence`

`CDatabase::GetConnect`

`CDatabase::GetCursorCommitBehavior`

`CDatabase::GetCursorRollbackBehavior`

`CDatabase::GetDatabaseName`

`CDatabase::IsOpen`

`CDatabase::m_hdbc`

`CDatabase::OnSetOptions`

`CDatabase::Open`

`CDatabase::OpenEx`

`CDatabase::Rollback`

`CDatabase::SetLoginTimeout`

`CDatabase::SetQueryTimeout`