Função SQLCreateDataSource

Conformidade
Versão introduzida: ODBC 2.0

Resumo
SQLCreateDataSource exibe uma caixa de diálogo com a qual o usuário pode adicionar uma fonte de dados.

Sintaxe

  
BOOL SQLCreateDataSource(  
     HWND    hwnd,  
     LPSTR   lpszDS);  

Argumentos

hwnd
[Entrada] Identificador de janela pai.

lpszDS
[Entrada] Nome da fonte de dados. lpszDS pode ser um ponteiro nulo ou uma cadeia de caracteres vazia.

Retornos

SQLCreateDataSource retornará TRUE se a fonte de dados for criada. Caso contrário, retornará FALSE.

Diagnósticos

Quando SQLCreateDataSource retorna FALSE, um valor *pfErrorCode associado pode ser obtido chamando SQLInstallerError. A tabela a seguir lista os valores *pfErrorCode que podem ser retornados por SQLInstallerError e explica cada um deles no contexto dessa função.

*pfErrorCode	Erro	Descrição
ODBC_ERROR_GENERAL_ERR	Erro geral do instalador	Ocorreu um erro para o qual não houve nenhum erro específico do instalador.
ODBC_ERROR_INVALID_HWND	Identificador de janela inválido	O argumento hwnd era inválido ou NULL.
ODBC_ERROR_INVALID_DSN	DSN inválido	O argumento lpszDS continha uma cadeia de caracteres inválida para um DSN.
ODBC_ERROR_REQUEST_FAILED	Falha na solicitação	Falha na chamada para ConfigDSN com a opção ODBC_ADD_DSN.
ODBC_ERROR_LOAD_LIBRARY_FAILED	Não foi possível carregar o driver ou a biblioteca de configuração do tradutor	Não foi possível carregar a biblioteca de configuração do driver.
ODBC_ERROR_USER_CANCELED	Operação cancelada pelo usuário	O usuário cancelou a criação de uma nova fonte de dados.
ODBC_ERROR_CREATE_DSN_FAILED	Não foi possível criar o DSN solicitado	Não foi possível se conectar ao banco de dados; a chamada para SQLDriverConnect para um DSN de Arquivo não retornou uma conexão bem-sucedida. Não foi possível gravar no arquivo.
ODBC_ERROR_OUT_OF_MEM	Memória insuficiente	O instalador não pôde executar a função devido à falta de memória.

Comentários

Se hwnd for nulo, SQLCreateDataSource retornará FALSE. Caso contrário, ele exibirá a caixa de diálogo Criar Nova Fonte de Dados com uma página do assistente para escolher o tipo de fonte de dados a ser configurado, conforme mostrado na ilustração a seguir.

A opção padrão é Fonte de Dados de Arquivo. Quando uma fonte de dados é escolhida e Avançar clicado, a página do assistente a seguir que contém uma lista de drivers instalados é exibida.

Se Cancelar for clicado, a caixa de diálogo desaparecerá e SQLCreateDataSource retornará FALSE com o código de erro de ODBC_ERROR_USER_CANCELED. Se a opção Fonte de Dados do Usuário ou Fonte de Dados do Sistema tiver sido selecionada, o botão Avançado não estará disponível.

Quando o botão Avançar for clicado, ocorrerá um dos seguintes procedimentos, dependendo de qual tipo de fonte de dados foi selecionado:

• Se a Fonte de Dados do Arquivo tiver sido selecionada, uma página do assistente será exibida para que o usuário insira um nome de arquivo.

• Se a Fonte de Dados do Usuário ou a Fonte de Dados do Sistema tiver sido selecionada, uma página do assistente exibindo o tipo de fonte de dados e o driver será exibida para revisão e, quando Concluir for clicado, a fonte de dados será configurada.

Se Avançado for clicado na página do assistente Criar Nova Fonte de Dados, uma página do assistente será exibida para o usuário inserir informações específicas do driver. Na caixa de texto dessa caixa de diálogo, digite o driver e as palavras-chave separados por returns, conforme mostrado na ilustração a seguir.

Caixa de diálogo

Palavras-chave adicionais específicas do driver podem ser encontradas na descrição de SQLDriverConnect. Todos, exceto DSN , são permitidos.

O padrão para a opção Verificar Esta Conexão é TRUE. Esse padrão se aplica se esta página do assistente está ativada ou não. Se OK for clicado, a cadeia de caracteres especificada na caixa de texto e o valor da opção Verificar Esta Conexão serão armazenados em cache. (Se o botão Fechar ou Cancelar for clicado, todas as informações específicas do driver recém-inseridas serão perdidas porque a cadeia de caracteres especificada na caixa de texto e o valor da opção Verificar Esta Conexão não serão armazenados em cache.)

Se a Fonte de Dados do Arquivo tiver sido selecionada na primeira página do assistente, depois que um driver tiver sido selecionado e os valores de palavra-chave tiverem sido inseridos na página Assistente avançado, o usuário será solicitado a inserir um nome de arquivo. Clique em Procurar para pesquisar um nome de arquivo; nesse caso, o diretório padrão na caixa Procurar é especificado por uma combinação do caminho especificado por CommonFileDir em HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion e "ODBC\DataSources". (Se CommonFileDir fosse "C:\Program Files\Common Files", o diretório padrão seria "C:\Program Files\Common Files\ODBC\Data Sources".)

Quando um nome de arquivo é inserido e Avançar é clicado, o nome do arquivo inserido é verificado quanto à validade em relação às regras de nomenclatura de arquivo padrão do sistema operacional. Se o nome do arquivo for inválido, uma caixa de mensagem de erro notificará o usuário de que um nome de arquivo inválido foi inserido. Depois que o usuário reconhece a caixa de mensagem, o foco é retornado para a página do assistente na qual o nome do arquivo é inserido. Se o nome do arquivo for válido, uma página do assistente que mostra os pares chave-valor selecionado será exibida para revisão, conforme mostrado na ilustração a seguir.

Se Concluir for clicado e a Fonte de Dados de Arquivo tiver sido selecionada como o tipo de fonte de dados e se a opção Verificar essa conexão for TRUE, SQLDriverConnect será chamado com as palavras-chave SAVEFILE e DRIVER . O argumento DriverCompletion é definido como SQL_DRIVER_COMPLETE. O nome do arquivo para a palavra-chave SAVEFILE é o nome que foi inserido ou escolhido e o nome do driver para a palavra-chave DRIVER é o nome escolhido. Se uma cadeia de conexão específica do driver tiver sido especificada na página Assistente avançado, essa cadeia de caracteres será acrescentada após a palavra-chave DRIVER .

Se SQLDriverConnect retornar SQL_SUCCESS, o Gerenciador de Driver criará o DSN de Arquivo. SQLCreateDataSource retorna TRUE. Se SQLDriverConnect não retornar SQL_SUCCESS, uma caixa de mensagem de aviso indicará que não foi possível fazer uma conexão com a fonte de dados. Um DSN com informações de conexão mínimas ainda pode ser criado. Essa caixa de mensagem permite que o usuário cancele ou continue com a criação do DSN de Arquivo.

Se o usuário optar por continuar criando o DSN, esse processo continuará como se a opção Verificar essa conexão estivesse definida como FALSE. Se o usuário optar por cancelar, FALSE será retornado para SQLCreateDataSource com um código de erro de ODBC_ERROR_CREATE_DSN_FAILED.

Se a Fonte de Dados do Arquivo tiver sido selecionada como o tipo de fonte de dados e a opção Verificar essa conexão for FALSE, um DSN de Arquivo será criado com a palavra-chave DRIVER e a cadeia de conexão especificada pelo usuário (se houver) na página Assistente avançado. Se a criação do arquivo tiver sido bem-sucedida, TRUE será retornado para SQLCreateDataSource. Se a criação do arquivo não tiver sido bem-sucedida, uma caixa de mensagem de erro notificará o usuário com qualquer erro retornado do sistema operacional. FALSE é retornado para SQLCreateDataSource com um código de erro de ODBC_ERROR_CREATE_DSN_FAILED. Para obter mais informações sobre fontes de dados de arquivo, consulte Conectando-se usando fontes de dados de arquivo ou consulte SQLDriverConnect.

Se a Fonte de Dados do Usuário ou do Sistema tiver sido selecionada como o tipo de fonte de dados, ConfigDSN na biblioteca de configuração do driver será chamado com o ODBC_ADD_DSN fRequest. Para obter mais informações, consulte ConfigDSN.

Funções relacionadas

Para obter informações sobre	Consulte
Gerenciar fontes de dados	SQLManageDataSources