Classe CDaoDatabase

Artigo
06/16/2023

Representa uma conexão com um banco de dados do Access usando DAO (Objetos de Acesso a Dados). O DAO tem suporte por meio do Office 2013. O DAO 3.6 é a versão final e é considerado obsoleto.

Sintaxe

class CDaoDatabase : public CObject

Membros

Construtores públicos

Nome	Descrição
CDaoDatabase::CDaoDatabase	Constrói um objeto `CDaoDatabase`. Chame `Open` para conectar o objeto a um banco de dados.

Métodos públicos

Nome	Descrição
CDaoDatabase::CanTransact	Retornará diferente de zero se o banco de dados der suporte a transações.
CDaoDatabase::CanUpdate	Retornará diferente de zero se o objeto `CDaoDatabase` for atualizável (não somente leitura).
CDaoDatabase::Close	Fecha a conexão de banco de dados.
CDaoDatabase::Create	Cria o objeto de banco de dados DAO subjacente e inicializa o objeto `CDaoDatabase`.
CDaoDatabase::CreateRelation	Define uma nova relação entre as tabelas no banco de dados.
CDaoDatabase::DeleteQueryDef	Exclui um objeto querydef salvo na coleção QueryDefs do banco de dados.
CDaoDatabase::DeleteRelation	Exclui uma relação existente entre tabelas no banco de dados.
CDaoDatabase::DeleteTableDef	Exclui a definição de uma tabela no banco de dados. Isso exclui a tabela propriamente dita e todos os dados dela.
CDaoDatabase::Execute	Executa uma consulta de ação. Chamar `Execute` para uma consulta que retorna resultados gera uma exceção.
CDaoDatabase::GetConnect	Retorna a cadeia de conexão usada para conectar o objeto `CDaoDatabase` a um banco de dados. Usado para ODBC.
CDaoDatabase::GetName	Retorna o nome do banco de dados atualmente em uso.
CDaoDatabase::GetQueryDefCount	Retorna o número de consultas definidas para o banco de dados.
CDaoDatabase::GetQueryDefInfo	Retorna informações sobre uma consulta especificada definida no banco de dados.
CDaoDatabase::GetQueryTimeout	Retorna o número de segundos após o qual as operações de consulta de banco de dados acabarão. Afeta todas as operações de abertura, adição, atualização e edição subsequentes e outras operações em fontes de dados ODBC (somente), como chamadas para `Execute`.
CDaoDatabase::GetRecordsAffected	Retorna o número de registros afetados pela última atualização, edição ou adição de operação ou por uma chamada para `Execute`.
CDaoDatabase::GetRelationCount	Retorna o número de relações definidas entre tabelas no banco de dados.
CDaoDatabase::GetRelationInfo	Retorna informações sobre uma relação especificada definida entre tabelas no banco de dados.
CDaoDatabase::GetTableDefCount	Retorna o número de tabelas definidas no banco de dados.
CDaoDatabase::GetTableDefInfo	Retorna informações sobre uma tabela especificada no banco de dados.
CDaoDatabase::GetVersion	Retorna a versão do mecanismo de banco de dados associado ao banco de dados.
CDaoDatabase::IsOpen	Retornará diferente de zero se o objeto `CDaoDatabase` estiver conectado a uma fonte de dados no momento.
CDaoDatabase::Open	Estabelece uma conexão com um banco de dados.
CDaoDatabase::SetQueryTimeout	Define o número de segundos após o qual as operações de consulta de banco de dados (somente em fontes de dados ODBC) atingirão o tempo limite. Afeta todas as operações de abertura, adição, atualização e exclusão subsequentes.

Membros de Dados Públicos

Nome	Descrição
CDaoDatabase::m_pDAODatabase	Um ponteiro para o objeto de banco de dados DAO subjacente.
CDaoDatabase::m_pWorkspace	Um ponteiro para o objeto CDaoWorkspace que contém o banco de dados e define o espaço de transação dele.

Comentários

Para obter informações sobre os formatos de banco de dados compatíveis, confira a função membro GetName. Você pode ter um ou mais objetos CDaoDatabase ativos por vez em um determinado "workspace", representado por um objeto CDaoWorkspace. O workspace mantém uma coleção de objetos de banco de dados abertos, chamada de coleção de bancos de dados.

Uso

Você pode criar objetos de banco de dados implicitamente ao criar objetos de conjunto de registros. Mas você também pode criar objetos de banco de dados explicitamente. Para usar um banco de dados existente explicitamente com CDaoDatabase, faça um dos seguintes procedimentos:

Construa um objeto CDaoDatabase, passando um ponteiro para um objeto CDaoWorkspace aberto.
Ou construa um objeto CDaoDatabase sem especificar o workspace (o MFC cria um objeto de workspace temporário).

Para criar um banco de dados Microsoft Jet (.MDB), construa um objeto CDaoDatabase e chame a respectiva função membro Create. Não chame Open após Create.

Para abrir um banco de dados existente, construa um objeto CDaoDatabase e chame a respectiva função membro Open.

Qualquer uma dessas técnicas acrescenta o objeto de banco de dados DAO à coleção de bancos de dados do workspace e abre uma conexão com os dados. Quando você construir objetos CDaoRecordset, CDaoTableDef ou CDaoQueryDef para operar no banco de dados conectado, passe um ponteiro para o objeto CDaoDatabase aos construtores para esses objetos. Quando terminar de usar a conexão, chame a função membro Close e destrua o objeto CDaoDatabase. Close fecha todos os conjuntos de registros que você não fechou anteriormente.

Transações

O processamento de transações de banco de dados é fornecido no nível do espaço de trabalho — consulte as funções de membro BeginTrans, CommitTrans e Rollback da classe CDaoWorkspace.

Conexões ODBC

A maneira recomendada de trabalhar com fontes de dados ODBC é anexar tabelas externas a um banco de dados do Microsoft Jet (.MDB).

Coleções

Cada banco de dados mantém as próprias coleções de objetos tabledef, querydef, recordset e relation. A classe CDaoDatabase fornece funções membro para manipular esses objetos.

Observação

Os objetos são armazenados no DAO, não no objeto de banco de dados MFC. O MFC fornece classes para objetos tabledef, querydef e recordset, mas não para objetos de relação.

Hierarquia de herança

CObject

CDaoDatabase

Requisitos

Cabeçalho: afxdao.h

CDaoDatabase::CanTransact

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

BOOL CanTransact();

Valor de Devolução

Diferente de zero se o banco de dados der suporte a transações; caso contrário, 0.

Comentários

As transações são gerenciadas no workspace do banco de dados.

CDaoDatabase::CanUpdate

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

BOOL CanUpdate();

Valor de Devolução

Diferente de zero se o objeto CDaoDatabase permitir atualizações; caso contrário, 0, indicando que você passou TRUE em bReadOnly quando abriu o objeto CDaoDatabase ou que o banco de dados propriamente dito é somente leitura. Confira a função membro Open.

Comentários

Para obter informações sobre a capacidade de atualização do banco de dados, confira o tópico "Propriedade Updatable" na Ajuda do DAO.

CDaoDatabase::CDaoDatabase

Constrói um objeto CDaoDatabase.

CDaoDatabase(CDaoWorkspace* pWorkspace = NULL);

Parâmetros

pWorkspace
Um ponteiro para o objeto CDaoWorkspace que conterá o novo objeto de banco de dados. Se você aceitar o valor padrão de NULL, o construtor criará um objeto temporário CDaoWorkspace que usa o workspace DAO padrão. Você pode obter um ponteiro para o objeto de workspace por meio do membro de dados m_pWorkspace.

Comentários

Depois de construir o objeto, se você estiver criando um banco de dados do Microsoft Jet (.MDB), chame a função membro Create do objeto. Se você estiver, em vez disso, abrindo um banco de dados existente, chame a função membro Open do objeto.

Quando terminar o procedimento com o objeto, você deverá chamar a função membro Close dele e destruir o objeto CDaoDatabase.

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

Observação

Um objeto CDaoDatabase também será criado implicitamente se você abrir um objeto CDaoRecordset sem passar um ponteiro para um objeto CDaoDatabase existente. Esse objeto de banco de dados é fechado quando você fecha o objeto de conjunto de registros.

CDaoDatabase::Close

Chame essa função membro para se desconectar de um banco de dados e fechar todos os conjuntos de registros, tabelas e querydefs abertos associados ao banco de dados.

virtual void Close();

Comentários

É uma boa prática fechar esses objetos você mesmo antes de chamar essa função membro. Fechar um objeto CDaoDatabase o remove da coleção de bancos de dados no workspace associado. Como Close não destrói o objeto CDaoDatabase, você pode reutilizar o objeto abrindo o mesmo banco de dados ou um banco de dados diferente.

Cuidado

Chame a função membro Update (se houver edições pendentes) e a função membro Close em todos os objetos de conjunto de registros abertos antes de fechar um banco de dados. Se você sair de uma função que declara objetos CDaoDatabase ou CDaoRecordset na pilha, o banco de dados será fechado, quaisquer alterações não salvas serão perdidas, todas as transações pendentes serão revertidas e todas as edições pendentes para seus dados serão perdidas.

Cuidado

Se você tentar fechar um objeto de banco de dados enquanto qualquer objeto de conjunto de registros estiver aberto ou se tentar fechar um objeto de workspace enquanto quaisquer objetos de banco de dados pertencentes a esse workspace específico estiverem abertos, esses objetos de conjunto de registros serão fechados e atualizações ou edições pendentes serão revertidas. Se você tentar fechar um objeto de workspace enquanto objetos de banco de dados pertencentes a ele estiverem abertos, a operação fechará todos os objetos de banco de dados pertencentes a esse objeto de workspace específico, o que pode resultar no fechamento de objetos de conjunto de registros não fechados. Se você não fechar o objeto de banco de dados, o MFC relatará uma falha de asserção em builds de depuração.

Se o objeto de banco de dados for definido fora do escopo de uma função e você sair da função sem fechá-lo, o objeto de banco de dados permanecerá aberto até que seja explicitamente fechado ou até que o módulo no qual ele está definido esteja fora do escopo.

CDaoDatabase::Create

Para criar um banco de dados do Microsoft Jet (.MDB), chame essa função membro depois de construir um objeto CDaoDatabase.

virtual void Create(
    LPCTSTR lpszName,
    LPCTSTR lpszLocale = dbLangGeneral,
    int dwOptions = 0);

Parâmetros

lpszName
Uma expressão de cadeia de caracteres que é o nome do arquivo de banco de dados que você está criando. Pode ser o caminho completo e o nome do arquivo, como "C:\\MYDB.MDB". Você precisa fornecer um nome. Se você não fornecer uma extensão de nome de arquivo, a extensão .MDB será acrescentada. Se a sua rede der suporte à UNC (convenção de nomenclatura uniforme), você também poderá especificar um caminho de rede, como "\\\\MEUSERVIDOR\\MEUCOMPARTILHAMENTO\\MEUDIRETÓRIO\\MEUBD". Somente arquivos de banco de dados do Microsoft Jet (.MDB) podem ser criados usando essa função membro. (As barras invertidas duplas são necessárias em literais de cadeia de caracteres porque "\" é o caractere de escape do C++.)

lpszLocale
Uma expressão de cadeia de caracteres usada para especificar a ordenação para criação do banco de dados. O valor padrão é dbLangGeneral. Os valores possíveis são:

dbLangGeneral Inglês, alemão, francês, português, italiano e espanhol moderno
dbLangArabic Árabe
dbLangCyrillic Russo
dbLangCzech Tcheco
dbLangDutch Holandês
dbLangGreek Grego
dbLangHebrew Hebraico
dbLangHungarian Húngaro
dbLangIcelandic Islandês
dbLangNordic Idiomas nórdicos (somente versão 1.0 do mecanismo de banco de dados do Microsoft Jet)
dbLangNorwdan Norueguês e dinamarquês
dbLangPolish Polonês
dbLangSpanish Espanhol tradicional
dbLangSwedfin Sueco e finlandês
dbLangTurkish Turco

dwOptions
Um inteiro que indica uma ou mais opções. Os valores possíveis são:

dbEncrypt Criar um banco de dados criptografado.
dbVersion10 Criar um banco de dados com o banco de dados do Microsoft Jet versão 1.0.
dbVersion11 Criar um banco de dados com o banco de dados do Microsoft Jet versão 1.1.
dbVersion20 Criar um banco de dados com o banco de dados do Microsoft Jet versão 2.0.
dbVersion30 Criar um banco de dados com o banco de dados do Microsoft Jet versão 3.0.

Se você omitir a constante de criptografia, um banco de dados não criptografado será criado. Você pode especificar apenas uma constante de versão. Se você omitir uma constante de versão, um banco de dados que usa o banco de dados do Microsoft Jet versão 3.0 será criado.

Cuidado

Se um banco de dados não for criptografado, será possível, mesmo que você implemente a segurança de usuário/senha, ler diretamente o arquivo de disco binário que constitui o banco de dados.

Comentários

Create cria o arquivo de banco de dados e o objeto de banco de dados DAO subjacente e inicializa o objeto C++. O objeto é acrescentado à coleção de bancos de dados do workspace associado. O objeto de banco de dados está em um estado aberto; não chame Open* após Create.

Observação

Com Create, você pode criar apenas bancos de dados do Microsoft Jet (.MDB). Não é possível criar bancos de dados ISAM ou bancos de dados ODBC.

CDaoDatabase::CreateRelation

Chame essa função membro para estabelecer uma relação entre um ou mais campos em uma tabela primária no banco de dados e um ou mais campos em uma tabela estrangeira (outra tabela no banco de dados).

void CreateRelation(
    LPCTSTR lpszName,
    LPCTSTR lpszTable,
    LPCTSTR lpszForeignTable,
    long lAttributes,
    LPCTSTR lpszField,
    LPCTSTR lpszForeignField);

void CreateRelation(CDaoRelationInfo& relinfo);

Parâmetros

lpszName
O nome exclusivo do objeto de relação. O nome precisa começar com uma letra e pode conter no máximo 40 caracteres. Ele pode incluir números e caracteres sublinhados, mas não pode incluir pontuação nem espaços.

lpszTable
O nome da tabela primária na relação. Se a tabela não existir, o MFC gerará uma exceção do tipo CDaoException.

lpszForeignTable
O nome da tabela estrangeira na relação. Se a tabela não existir, o MFC gerará uma exceção do tipo CDaoException.

lAttributes
Um valor longo que contém informações sobre o tipo de relação. Você pode usar esse valor para impor a integridade referencial, entre outras coisas. Você pode usar o operador OR bit a bit (|) para combinar qualquer um dos seguintes valores (contanto que a combinação faça sentido):

dbRelationUnique A relação é de um para um.
dbRelationDontEnforce A relação não é imposta (não há integridade referencial).
dbRelationInherited A relação existe em um banco de dados não recorrente que contém as duas tabelas anexadas.
dbRelationUpdateCascade As atualizações ocorrerão em cascata (para saber mais sobre cascatas, confira Comentários).
dbRelationDeleteCascade As exclusões serão em cascata.

lpszField
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome de um campo na tabela primária (nomeada por lpszTable).

lpszForeignField
Um ponteiro para uma cadeia de caracteres terminada em nulo que contém o nome de um campo na tabela estrangeira (nomeada por lpszForeignTable).

relinfo
Uma referência a um objeto CDaoRelationInfo que contém informações sobre a relação que você deseja criar.

Comentários

A relação não pode envolver uma consulta ou uma tabela anexada de um banco de dados externo.

Use a primeira versão da função quando a relação envolver um campo em cada uma das duas tabelas. Use a segunda versão quando a relação envolver vários campos. O número máximo de campos em uma relação é 14.

Essa ação cria um objeto de relação DAO subjacente, mas este é um detalhe de implementação do MFC, pois o encapsulamento de objetos de relação do MFC está contido na classe CDaoDatabase. O MFC não fornece uma classe para relações.

Se você definir os atributos do objeto de relação para ativar operações em cascata, o mecanismo de banco de dados atualizará ou excluirá automaticamente registros em uma ou mais outras tabelas quando alterações forem feitas em tabelas de chaves primárias relacionadas.

Por exemplo, suponha que você estabeleça uma relação de exclusão em cascata entre uma tabela Clientes e uma tabela Pedidos. Quando você exclui registros da tabela Clientes, os registros na tabela Pedidos relacionados a esse cliente também são excluídos. Além disso, se você estabelecer relações de exclusão em cascata entre a tabela Pedidos e outras tabelas, os registros dessas tabelas serão excluídos automaticamente quando você excluir registros da tabela Clientes.

Para obter informações relacionadas, confira o tópico "Método CreateRelation" na ajuda do DAO.

CDaoDatabase::DeleteQueryDef

Chame essa função membro para excluir o querydef especificado (consulta salva) da coleção QueryDefs do objeto CDaoDatabase.

void DeleteQueryDef(LPCTSTR lpszName);

Parâmetros

lpszName
O nome da consulta salva a ser excluída.

Comentários

Posteriormente, essa consulta não é mais definida no banco de dados.

Para obter informações sobre como criar objetos querydef, confira a classe CDaoQueryDef. Um objeto querydef torna-se associado a um objeto específico CDaoDatabase quando você constrói o objeto CDaoQueryDef, passando um ponteiro para o objeto de banco de dados.

CDaoDatabase::DeleteRelation

Chame essa função membro para excluir uma relação existente da coleção Relações do objeto de banco de dados.

void DeleteRelation(LPCTSTR lpszName);

Parâmetros

lpszName
O nome da relação a ser excluída.

Comentários

Posteriormente, a relação não existe mais.

Para obter informações relacionadas, confira o tópico "Método Delete" na ajuda do DAO.

CDaoDatabase::DeleteTableDef

Chame essa função membro para excluir a tabela especificada e todos os dados dela da coleção TableDefs do objeto CDaoDatabase.

void DeleteTableDef(LPCTSTR lpszName);

Parâmetros

lpszName
O nome do tabledef a ser excluído.

Comentários

Posteriormente, essa tabela não é mais definida no banco de dados.

Observação

Tenha muito cuidado para não excluir tabelas do sistema.

Para obter informações sobre como criar objetos tabledef, confira a classe CDaoTableDef. Um objeto tabledef torna-se associado a um objeto específico CDaoDatabase quando você constrói o objeto CDaoTableDef, passando um ponteiro para o objeto de banco de dados.

Para obter informações relacionadas, confira o tópico "Método Delete" na ajuda do DAO.

CDaoDatabase::Execute

Chame essa função membro para executar uma consulta de ação ou executar uma instrução SQL no banco de dados.

void Execute(
    LPCTSTR lpszSQL,
    int nOptions = dbFailOnError);

Parâmetros

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

nOptions
Um inteiro que especifica opções relacionadas à integridade da consulta. Você pode usar o operador OR bit a bit (|) para combinar qualquer uma das seguintes constantes (desde que a combinação faça sentido, por exemplo, você não combinaria dbInconsistent com dbConsistent):

dbDenyWrite Negar permissão de gravação para outros usuários.
dbInconsistent (Padrão) Atualizações inconsistentes.
dbConsistent Atualizações consistentes.
dbSQLPassThrough Passagem do SQL. Faz com que a instrução SQL seja passada para uma fonte de dados ODBC para processamento.
dbFailOnError Reverter atualizações se ocorrer um erro.
dbSeeChanges Gerar um erro em tempo de execução se outro usuário estiver alterando os dados que você está editando.

Observação

Se ambos dbInconsistent e dbConsistent estiverem incluídos ou se nenhum for incluído, o resultado será o padrão. Para obter uma explicação dessas constantes, confira o tópico "Método Execute" na Ajuda do DAO.

Comentários

Execute funciona apenas para consultas de ação ou consultas de passagem SQL que não retornam resultados. Ele não funciona para consultas selecionadas, que retornam registros.

Para obter uma definição e informações sobre consultas de ação, confira os tópicos "Consulta de Ação" e "Método Execute" na Ajuda do DAO.

Dica

Considerando uma instrução SQL sintaticamente correta e permissões adequadas, a função membro Execute não falhará mesmo que nenhuma linha possa ser modificada ou excluída. Portanto, sempre use a opção dbFailOnError ao usar a função membro Execute para executar uma consulta de atualização ou exclusão. Essa opção faz com que o MFC gere uma exceção do tipo CDaoException e reverta todas as alterações bem-sucedidas se qualquer um dos registros afetados estiver bloqueado e não puder ser atualizado ou excluído. Observe que você sempre pode chamar GetRecordsAffected para ver quantos registros foram afetados.

Chame a função membro GetRecordsAffected do objeto de banco de dados para determinar o número de registros afetados pela chamada mais recente para Execute. Por exemplo, GetRecordsAffected retorna informações sobre o número de registros excluídos, atualizados ou inseridos ao executar uma consulta de ação. A contagem retornada não refletirá alterações em tabelas relacionadas quando as atualizações ou exclusões em cascata estiverem em vigor.

Execute não retorna um conjunto de registros. Usar Execute em uma consulta que seleciona registros faz com que o MFC gere uma exceção do tipo CDaoException. (Não há nenhuma função membro ExecuteSQL análoga a CDatabase::ExecuteSQL.)

CDaoDatabase::GetConnect

Chame essa função membro para recuperar a cadeia de conexão usada para conectar o objeto CDaoDatabase a um banco de dados ODBC ou ISAM.

CString GetConnect();

Valor de Devolução

A cadeia de conexão se Open tiver sido chamado com êxito em uma fonte de dados ODBC; caso contrário, uma cadeia de caracteres vazia. Para um banco de dados do Microsoft Jet (.MDB), a cadeia de caracteres está sempre vazia, a menos que você a defina para uso com a opção dbSQLPassThrough usada com a função membro Execute ou usada na abertura de um conjunto de registros.

Comentários

A cadeia de caracteres fornece informações sobre a origem de um banco de dados aberto ou um banco de dados usado em uma consulta de passagem. A cadeia de conexão é composta por um especificador de tipo de banco de dados e zero ou mais parâmetros separados por ponto e vírgula.

Observação

Usar as classes DAO do MFC para se conectar a uma fonte de dados por meio do ODBC é menos eficiente do que conectar-se por meio de uma tabela anexada.

Observação

A cadeia de conexão é usada para passar informações adicionais para ODBC e determinados drivers ISAM, conforme necessário. Ela não é usada para bancos de dados .MDB. Para tabelas base de banco de dados do Microsoft Jet, a cadeia de conexão é uma cadeia de caracteres vazia ("") exceto quando você a usa para uma consulta de passagem do SQL, conforme descrito em Valor Retornado acima.

Consulte a função membro Open para obter uma descrição de como a cadeia de conexão é criada. Depois que a cadeia de conexão tiver sido definida na chamada Open, você poderá usá-la posteriormente para verificar a configuração para determinar o tipo, o caminho, a ID do usuário, a senha ou a fonte de dados ODBC do banco de dados.

CDaoDatabase::GetName

Chame essa função membro para recuperar o nome do banco de dados aberto no momento, que é o nome de um arquivo de banco de dados existente ou o nome de uma fonte de dados ODBC registrada.

CString GetName();

Valor de Devolução

O caminho completo e o nome do arquivo do banco de dados, se bem-sucedido; caso contrário, uma CString vazia.

Comentários

Se a sua rede der suporte à UNC (convenção de nomenclatura uniforme), você também poderá especificar um caminho de rede, como "\\\\MEUSERVIDOR\\MEUCOMPARTILHAMENTO\\MEUDIRETÓRIO\\MEUBD.MDB". (As barras invertidas duplas são necessárias em literais de cadeia de caracteres porque "\" é o caractere de escape do C++.)

Você pode, por exemplo, querer exibir esse nome em um título. Se ocorrer um erro enquanto o nome estiver sendo recuperado, o MFC lançará uma exceção do tipo CDaoException.

Observação

Para melhor desempenho quando bancos de dados externos estão sendo acessados, recomendamos que você anexe tabelas de banco de dados externas a um banco de dados do Microsoft Jet (.MDB) em vez de se conectar diretamente à fonte de dados.

O tipo de banco de dados é indicado pelo arquivo ou diretório para o qual o caminho aponta, da seguinte maneira:

Pathname aponta para...	Tipo de banco de dados
Arquivo .MDB	Banco de dados do Microsoft Jet (Microsoft Access)
Diretório que contém arquivos .DBF	Banco de dados dBASE
Diretório que contém um arquivo .XLS	Banco de dados do Microsoft Excel
Diretório que contém arquivos .PDX	Banco de dados Paradox
Diretório que contém arquivos de banco de dados de texto formatados adequadamente	Banco de dados de formato de texto

Para bancos de dados ODBC, como SQL Server e Oracle, a cadeia de conexão do banco de dados identifica um DSN (nome da fonte de dados) registrado pelo ODBC.

CDaoDatabase::GetQueryDefCount

Chame essa função membro para recuperar o número de consultas definidas na coleção QueryDefs do banco de dados.

short GetQueryDefCount();

Valor de Devolução

O número de consultas definidas no banco de dados.

Comentários

GetQueryDefCount será útil se você precisar fazer loop por todos os querydefs na coleção QueryDefs. Para obter informações sobre uma determinada consulta na coleção, confira GetQueryDefInfo.

CDaoDatabase::GetQueryDefInfo

Chame essa função membro para obter vários tipos de informações sobre uma consulta definida no banco de dados.

void GetQueryDefInfo(
    int nIndex,
    CDaoQueryDefInfo& querydefinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

void GetQueryDefInfo(
    LPCTSTR lpszName,
    CDaoQueryDefInfo& querydefinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

Parâmetros

nIndex
O índice da consulta predefinida na coleção QueryDefs do banco de dados, para pesquisa por índice.

querydefinfo
Uma referência a um objeto CDaoQueryDefInfo que retorna as informações solicitadas.

dwInfoOptions
Opções que especificam quais informações sobre o conjunto de registros a recuperar. As opções disponíveis estão listadas aqui, junto com o que elas fazem que a função retorne sobre o conjunto de registros:

AFX_DAO_PRIMARY_INFO (Default) Nome, Tipo
AFX_DAO_SECONDARY_INFO Informações primárias mais: Data da criação, Data da última atualização, Registros de devoluções, Atualizável
AFX_DAO_ALL_INFO Informações primárias e secundárias mais: SQL, Conexão, ODBCTimeout

lpszName
Uma cadeia de caracteres que contém o nome de uma consulta definida no banco de dados, para pesquisa por nome.

Comentários

Duas versões da função são fornecidas para que você possa selecionar uma consulta por índice na coleção QueryDefs do banco de dados ou pelo nome da consulta.

Para obter uma descrição das informações retornadas em querydefinfo, confira a estrutura CDaoQueryDefInfo. Essa estrutura tem membros que correspondem aos itens de informações listados acima na descrição de dwInfoOptions. Se você solicitar um determinado nível de informações, também obterá os níveis anteriores, se houver.

CDaoDatabase::GetQueryTimeout

Chame essa função membro para recuperar o número atual de segundos a ser permitido antes que as operações subsequentes no banco de dados conectado atinjam o tempo limite.

short GetQueryTimeout();

Valor de Devolução

Um inteiro curto que contém o valor do tempo limite em segundos.

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. Embora a configuração esteja em vigor, ela afeta todas as operações abertas, adicionais novas, atualizadas e de exclusão em todos os conjuntos de registros associados a esse objeto CDaoDatabase. Você pode alterar a configuração de tempo limite atual chamando SetQueryTimeout. 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 é definido inicialmente quando o mecanismo de banco de dados é inicializado.

O valor padrão para tempos limite de consulta é obtido do Registro do Windows. Se não houver nenhuma configuração do Registro, o padrão será 60 segundos. Nem todos os bancos de dados dão suporte à capacidade de definir um valor de tempo limite da consulta. Se você definir um valor de tempo limite de consulta de 0, nenhum tempo limite ocorrerá; e a comunicação com o banco de dados poderá parar de responder. Esse comportamento pode ser útil durante o desenvolvimento. Se a chamada falhar, o MFC lançará uma exceção do tipo CDaoException.

Para obter informações relacionadas, confira o tópico "Propriedade QueryTimeout" na ajuda do DAO.

CDaoDatabase::GetRecordsAffected

Chame essa função membro para determinar o número de registros afetados pela chamada mais recente da função membro Execute.

long GetRecordsAffected();

Valor de Devolução

Um inteiro longo que contém o número de registros afetados.

Comentários

O valor retornado inclui o número de registros excluídos, atualizados ou inseridos por uma execução de consulta de ação com Execute. A contagem retornada não refletirá alterações em tabelas relacionadas quando as atualizações ou exclusões em cascata estiverem em vigor.

Para obter informações relacionadas, confira o tópico "Propriedade RecordsAffected" na ajuda do DAO.

CDaoDatabase::GetRelationCount

Chame essa função membro para obter o número de relações definidas entre tabelas no banco de dados.

short GetRelationCount();

Valor de Devolução

O número de relações definidas entre tabelas no banco de dados.

Comentários

GetRelationCount será útil se você precisar fazer loop de todas as relações definidas na coleção Relações do banco de dados. Para obter informações sobre uma determinada relação na coleção, confira GetRelationInfo.

Para ilustrar o conceito de uma relação, considere uma tabela Fornecedores e uma tabela Produtos, que podem ter uma relação um-para-muitos. Nessa relação, um fornecedor pode fornecer mais de um produto. Outras relações são um para um e muitos para muitos.

CDaoDatabase::GetRelationInfo

Chame essa função membro para obter informações sobre uma relação especificada na coleção Relações do banco de dados.

void GetRelationInfo(
    int nIndex,
    CDaoRelationInfo& relinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

void GetRelationInfo(
    LPCTSTR lpszName,
    CDaoRelationInfo& relinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

Parâmetros

nIndex
O índice do objeto de relação na coleção Relações do banco de dados, para pesquisa por índice.

relinfo
Uma referência a um objeto CDaoRelationInfo que retorna as informações solicitadas.

dwInfoOptions
Opções que especificam quais informações sobre a relação a recuperar. As opções disponíveis estão listadas aqui junto com o que elas fazem com que a função retorne sobre a relação:

AFX_DAO_PRIMARY_INFO (Default) Nome, Tabela, Tabela Estrangeira
AFX_DAO_SECONDARY_INFO Atributos, Informações de Campo

As Informações de Campo são um objeto CDaoRelationFieldInfo que contém os campos da tabela primária envolvida na relação.

lpszName
Uma cadeia de caracteres que contém o nome do objeto de relação, para pesquisa por nome.

Comentários

Duas versões dessa função fornecem acesso por índice ou por nome. Para obter uma descrição das informações retornadas em relinfo, confira a estrutura CDaoRelationInfo. Essa estrutura tem membros que correspondem aos itens de informações listados acima na descrição de dwInfoOptions. Se você solicitar informações em um nível, também obterá informações em qualquer nível anterior.

Observação

Se você definir os atributos do objeto de relação para ativar operações em cascata (dbRelationUpdateCascades ou dbRelationDeleteCascades), o mecanismo de banco de dados do Microsoft Jet atualizará ou excluirá automaticamente registros em uma ou mais outras tabelas quando alterações forem feitas em tabelas de chaves primárias relacionadas. Por exemplo, suponha que você estabeleça uma relação de exclusão em cascata entre uma tabela Clientes e uma tabela Pedidos. Quando você exclui registros da tabela Clientes, os registros na tabela Pedidos relacionados a esse cliente também são excluídos. Além disso, se você estabelecer relações de exclusão em cascata entre a tabela Pedidos e outras tabelas, os registros dessas tabelas serão excluídos automaticamente quando você excluir registros da tabela Clientes.

CDaoDatabase::GetTableDefCount

Chame essa função membro para recuperar o número de tabelas definidas no banco de dados.

short GetTableDefCount();

Valor de Devolução

O número de tabledefs definidos no banco de dados.

Comentários

GetTableDefCount será útil se você precisar fazer loop em todos os tabledefs na coleção TableDefs do banco de dados. Para obter informações sobre uma determinada tabela na coleção, confira GetTableDefInfo.

CDaoDatabase::GetTableDefInfo

Chame essa função membro para obter vários tipos de informações sobre uma tabela definida no banco de dados.

void GetTableDefInfo(
    int nIndex,
    CDaoTableDefInfo& tabledefinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

void GetTableDefInfo(
    LPCTSTR lpszName,
    CDaoTableDefInfo& tabledefinfo,
    DWORD dwInfoOptions = AFX_DAO_PRIMARY_INFO);

Parâmetros

nIndex
O índice do objeto tabledef na coleção TableDefs do banco de dados, para pesquisa por índice.

tabledefinfo
Uma referência a um objeto CDaoTableDefInfo que retorna as informações solicitadas.

dwInfoOptions
Opções que especificam quais informações sobre a tabela devem ser recuperadas. As opções disponíveis estão listadas aqui junto com o que elas fazem com que a função retorne sobre a relação:

AFX_DAO_PRIMARY_INFO (padrão) Nome, Atualizável, Atributos
AFX_DAO_SECONDARY_INFO Informações primárias mais: Data da criação, Data da última atualização, Nome da tabela de origem, Conexão
AFX_DAO_ALL_INFO Informações primárias e secundárias mais: regra de validação, texto de validação, contagem de registros

lpszName
O nome do objeto tabledef para pesquisa por nome.

Comentários

Duas versões da função são fornecidas para que você possa selecionar uma tabela por índice na coleção TableDefs do banco de dados ou pelo nome da tabela.

Para obter uma descrição das informações retornadas em tabledefinfo, confira a estrutura CDaoTableDefInfo. Essa estrutura tem membros que correspondem aos itens de informações listados acima na descrição de dwInfoOptions. Se você solicitar informações em um nível, também obterá informações para níveis anteriores, se houver.

Observação

A opção AFX_DAO_ALL_INFO fornece informações que podem demorar para serem obtidas. Nesse caso, contar os registros na tabela poderá ser muito demorado se houver muitos registros.

CDaoDatabase::GetVersion

Chame essa função membro para determinar a versão do arquivo de banco de dados do Microsoft Jet.

CString GetVersion();

Valor de Devolução

Um CString que indica a versão do arquivo de banco de dados associada ao objeto.

Comentários

O valor retornado representa o número da versão no formato "principal.secundária"; por exemplo, "3.0". O número da versão do produto (por exemplo, 3.0) consiste no número da versão (3), um ponto e o número do lançamento (0). As versões até o momento são 1.0, 1.1, 2.0 e 3.0.

Para obter informações relacionadas, confira o tópico "Propriedade Version" na ajuda do DAO.

CDaoDatabase::IsOpen

Chame essa função membro para determinar se o objeto CDaoDatabase está aberto no momento em um banco de dados.

BOOL IsOpen() const;

Valor de Devolução

Diferente de zero se o objeto CDaoDatabase estiver aberto no momento; caso contrário, 0.

Comentários

CDaoDatabase::m_pDAODatabase

Contém um ponteiro para a interface OLE para o objeto de banco de dados DAO subjacente ao objeto CDaoDatabase.

Comentários

Use este ponteiro se precisar acessar a interface do DAO diretamente.

Para obter informações sobre como chamar o DAO diretamente, confira a Nota Técnica 54.

CDaoDatabase::m_pWorkspace

Contém um ponteiro para o objeto CDaoWorkspace que contém o objeto de banco de dados.

Comentários

Use esse ponteiro se precisar acessar o workspace diretamente – por exemplo, para obter ponteiros para outros objetos de banco de dados na coleção Bancos de Dados do workspace.

CDaoDatabase::Open

Você precisa chamar essa função membro para inicializar um objeto recém-construído CDaoDatabase que representa um banco de dados existente.

virtual void Open(
    LPCTSTR lpszName,
    BOOL bExclusive = FALSE,
    BOOL bReadOnly = FALSE,
    LPCTSTR lpszConnect = _T(""));

Parâmetros

lpszName
Uma expressão de cadeia de caracteres que é o nome de um arquivo de banco de dados do Microsoft Jet (.MDB) existente. Se o nome do arquivo tiver uma extensão, ela será necessária. Se a sua rede der suporte à UNC (convenção de nomenclatura uniforme), você também poderá especificar um caminho de rede, como "\\\\MEUSERVIDOR\\MEUCOMPARTILHAMENTO\\MEUDIRETÓRIO\\MEUBD.MDB". (As barras invertidas duplas são necessárias em literais de cadeia de caracteres porque "\" é o caractere de escape do C++.)

Algumas considerações se aplicam ao usar lpszName. Se ele:

Refere-se a um banco de dados que já está aberto para acesso exclusivo por outro usuário, o MFC gera uma exceção do tipo CDaoException. Intercepte essa exceção para informar ao usuário que o banco de dados não está disponível.
É uma cadeia de caracteres vazia ("") e lpszConnect é "ODBC;", uma caixa de diálogo que lista todos os nomes de fonte de dados ODBC registrados é exibida para que o usuário possa selecionar um banco de dados. Você deve evitar conexões diretas com fontes de dados ODBC; em vez disso, use uma tabela anexada.
Não se refere a um banco de dados existente ou nome de fonte de dados ODBC válido, o MFC gera uma exceção do tipo CDaoException.

Observação

Para obter detalhes sobre códigos de erro DAO, confira o arquivo DAOERR.H. Para obter informações relacionadas, confira o tópico "Erros de acesso a dados interceptáveis" na ajuda do DAO.

bExclusive
Um valor booliano que será TRUE se o banco de dados for aberto para acesso exclusivo (não compartilhado) e FALSE se o banco de dados for aberto para acesso compartilhado. Se você omitir esse argumento, o banco de dados será aberto para acesso compartilhado.

bReadOnly
Um valor booliano que será TRUE se o banco de dados for aberto para acesso somente leitura e FALSE se o banco de dados for aberto para acesso de leitura/gravação. Se você omitir esse argumento, o banco de dados será aberto para acesso de leitura/gravação. Todos os conjuntos de registros dependentes herdam esse atributo.

lpszConnect
Uma expressão de cadeia de caracteres usada para abrir o banco de dados. Essa cadeia de caracteres constitui os argumentos de conexão ODBC. Você precisa fornecer os argumentos exclusivos e somente leitura para fornecer uma cadeia de caracteres de origem. Se o banco de dados é um banco de dados do Microsoft Jet (.MDB), essa cadeia de caracteres está vazia (""). A sintaxe para o valor padrão — _T("") — fornece portabilidade para Unicode, bem como builds ANSI do seu aplicativo.

Comentários

Open associa o banco de dados ao objeto DAO subjacente. Você não pode usar o objeto de banco de dados para construir objetos recordset, tabledef ou querydef até que ele seja inicializado. Open acrescenta o objeto de banco de dados à coleção Bancos de dados do workspace associado.

Use os parâmetros da seguinte maneira:

Se você estiver abrindo um banco de dados do Microsoft Jet (.MDB), use o parâmetro lpszName e passe uma cadeia de caracteres vazia para o parâmetro lpszConnect ou passe uma cadeia de caracteres de senha no formato ";PWD=senha" se o banco de dados estiver protegido por senha (somente bancos de dados .MDB).
Se você estiver abrindo uma fonte de dados ODBC, passe uma cadeia de conexão ODBC válida em lpszConnect e uma cadeia de caracteres vazia em lpszName.

Para obter informações relacionadas, consulte o tópico "Método OpenDatabase" na ajuda do DAO.

Observação

Para obter um melhor desempenho ao acessar bancos de dados externos, incluindo bancos de dados ISAM e fontes de dados ODBC, é recomendável anexar tabelas de banco de dados externas a um banco de dados do mecanismo do Microsoft Jet (.MDB) em vez de se conectar diretamente à fonte de dados.

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á uma exceção do tipo CDaoException.

As observações restantes se aplicam somente aos bancos de dados ODBC:

Se o banco de dados no banco de dados ODBC e 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 fica disponível chamando a função 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 (talvez no Registro do Windows) para reutilizá-la na próxima vez que o aplicativo chamar Open em um objeto CDaoDatabase.

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 CDaoDatabase diferente) ou para transmitir outras informações específicas a um banco de dados.

CDaoDatabase::SetQueryTimeout

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

void SetQueryTimeout(short nSeconds);

Parâmetros

nSeconds
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 membro AddNew, Update ou Delete do conjunto de registros se você quiser alterar o valor do tempo limite da consulta. A configuração afeta todas as chamadas abrir, AddNew, Update, e Delete subsequentes para todos os conjuntos de registros associados a esse objeto CDaoDatabase. 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 60 segundos. Nem todos os bancos de dados dão suporte à capacidade de definir um valor de tempo limite da consulta. Se você definir um valor de tempo limite de consulta de 0, nenhum tempo limite ocorrerá; a comunicação com o banco de dados poderá parar de responder. Esse comportamento pode ser útil durante o desenvolvimento.

Para obter informações relacionadas, confira o tópico "Propriedade QueryTimeout" na ajuda do DAO.

Confira também

Classe CObject
Gráfico da hierarquia
Classe CDaoWorkspace
Classe CDaoRecordset
Classe CDaoTableDef
Classe CDaoQueryDef
Classe CDatabase
Classe CDaoException

Compartilhar via

Classe CDaoDatabase

Sintaxe

Membros

Construtores públicos

Métodos públicos

Membros de Dados Públicos

Comentários

Uso

Transações

Conexões ODBC

Coleções

Hierarquia de herança

Requisitos

CDaoDatabase::CanTransact

Valor de Devolução

Comentários

CDaoDatabase::CanUpdate

Valor de Devolução

Comentários

CDaoDatabase::CDaoDatabase

Parâmetros

Comentários

CDaoDatabase::Close

Comentários

CDaoDatabase::Create

Parâmetros

Comentários

CDaoDatabase::CreateRelation

Parâmetros

Comentários

CDaoDatabase::DeleteQueryDef

Parâmetros

Comentários

CDaoDatabase::DeleteRelation

Parâmetros

Comentários

CDaoDatabase::DeleteTableDef

Parâmetros

Comentários

CDaoDatabase::Execute

Parâmetros

Comentários

CDaoDatabase::GetConnect

Valor de Devolução

Comentários

CDaoDatabase::GetName

Valor de Devolução

Comentários

CDaoDatabase::GetQueryDefCount

Valor de Devolução

Comentários

CDaoDatabase::GetQueryDefInfo

Parâmetros

Comentários

CDaoDatabase::GetQueryTimeout

Valor de Devolução

Comentários

CDaoDatabase::GetRecordsAffected

Valor de Devolução

Comentários

CDaoDatabase::GetRelationCount

Valor de Devolução

Comentários

CDaoDatabase::GetRelationInfo

Parâmetros

Comentários

CDaoDatabase::GetTableDefCount

Valor de Devolução

Comentários

CDaoDatabase::GetTableDefInfo

Parâmetros

Comentários

CDaoDatabase::GetVersion

Valor de Devolução

Comentários

CDaoDatabase::IsOpen

Valor de Devolução

Comentários

CDaoDatabase::m_pDAODatabase