Função ConfigDSN

Conformidade
Versão introduzida: ODBC 1.0

Resumo
O ConfigDSN adiciona, modifica ou exclui fontes de dados das informações do sistema. Ele pode solicitar ao usuário informações de conexão. Ele pode estar na DLL do driver ou em uma DLL de configuração separada.

Sintaxe

  
BOOL ConfigDSN(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszAttributes);  

Argumentos

hwndParent
[Entrada] Identificador de janela pai. A função não exibirá nenhuma caixa de diálogo se o identificador for nulo.

fRequest
[Entrada] Tipo de solicitação. O argumento fRequest deve conter um dos seguintes valores:

ODBC_ADD_DSN: adicionar uma nova fonte de dados.

ODBC_CONFIG_DSN: configure (modifique) uma fonte de dados existente.

ODBC_REMOVE_DSN: remover uma fonte de dados existente.

lpszDriver
[Entrada] Descrição do driver (geralmente o nome do DBMS associado) apresentada aos usuários em vez do nome do driver físico.

lpszAttributes
[Entrada] Uma lista duplamente terminada em nulo de atributos na forma de pares chave-valor. Para obter mais informações, confira "Comentários".

Retornos

A função retornará TRUE se for bem-sucedida, FALSE se falhar.

Diagnósticos

Quando ConfigDSN retorna FALSE, um valor *pfErrorCode associado é postado no buffer de erros do instalador por uma chamada para SQLPostInstallerError e 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_INVALID_HWND	Identificador de janela inválido	O argumento hwndParent era inválido.
ODBC_ERROR_INVALID_KEYWORD_VALUE	Pares de palavra-chave-valor inválidos	O argumento lpszAttributes continha um erro de sintaxe.
ODBC_ERROR_INVALID_NAME	Nome do driver ou tradutor inválido	O argumento lpszDriver era inválido. Não foi possível encontrá-lo no registro.
ODBC_ERROR_INVALID_REQUEST_TYPE	Tipo inválido de solicitação	O argumento fRequest não foi um dos seguintes: ODBC_ADD_DSN ODBC_CONFIG_DSN ODBC_REMOVE_DSN
ODBC_ERROR_REQUEST_FAILED	Falha na solicitação	Não foi possível executar a operação solicitada pelo argumento fRequest .
ODBC_ERROR_DRIVER_SPECIFIC	Erro específico do driver ou do tradutor	Um erro específico do driver para o qual não há nenhum erro definido do instalador ODBC. O argumento SzError em uma chamada para a função SQLPostInstallerError deve conter a mensagem de erro específica do driver.

Comentários

O ConfigDSN recebe informações de conexão da DLL do instalador como uma lista de atributos na forma de pares chave-valor. Cada par é encerrado com um byte nulo e toda a lista é encerrada com um byte nulo. (Ou seja, dois bytes nulos marcam o final da lista.) Espaços não são permitidos em torno do sinal de igual no par palavra-chave-valor. O ConfigDSN pode aceitar palavras-chave que não são palavras-chave válidas para SQLBrowseConnect e SQLDriverConnect. O ConfigDSN não dá suporte necessariamente a todas as palavras-chave válidas para SQLBrowseConnect e SQLDriverConnect. (O ConfigDSN não aceita a palavra-chave DRIVER .) As palavras-chave usadas pela função ConfigDSN devem dar suporte a todas as opções necessárias para recriar a fonte de dados usando o recurso de instalação AUTOMÁTICA do instalador. Quando os usos dos valores ConfigDSN e os valores de cadeia de conexão forem os mesmos, as mesmas palavras-chave deverão ser usadas.

Assim como em SQLBrowseConnect e SQLDriverConnect, as palavras-chave e seus valores não devem conter o []{}();? Os caracteres *=!@ e o valor da palavra-chave DSN não podem consistir apenas em espaços em branco. Devido à gramática do Registro, palavras-chave e nomes de fonte de dados não podem conter o caractere de barra invertida (\).

O ConfigDSN deve chamar SQLValidDSN para verificar o comprimento do nome da fonte de dados e verificar se nenhum caractere inválido está incluído no nome. Se o nome da fonte de dados for maior que SQL_MAX_DSN_LENGTH ou incluir caracteres inválidos, SQLValidDSN retornará um erro e ConfigDSN retornará um erro. O comprimento do nome da fonte de dados também é verificado por SQLWriteDSNToIni.

Por exemplo, para configurar uma fonte de dados que requer uma ID de usuário, uma senha e um nome de banco de dados, um aplicativo de instalação pode passar os seguintes pares chave-valor:

DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0  

Para obter mais informações sobre essas palavras-chave, consulte SQLDriverConnect e a documentação de cada driver.

Para exibir uma caixa de diálogo, hwndParent não deve ser nulo.

Adicionando uma fonte de dados

Se um nome de fonte de dados for passado para ConfigDSN em lpszAttributes, ConfigDSN verificará se o nome é válido. Se o nome da fonte de dados corresponder a um nome de fonte de dados existente e hwndParent for nulo, ConfigDSN substituirá o nome existente. Se ele corresponder a um nome existente e hwndParent não for nulo, o ConfigDSN solicitará que o usuário substitua o nome existente.

Se lpszAttributes contiver informações suficientes para se conectar a uma fonte de dados, o ConfigDSN poderá adicionar a fonte de dados ou exibir uma caixa de diálogo com a qual o usuário pode alterar as informações de conexão. Se lpszAttributes não contiver informações suficientes para se conectar a uma fonte de dados, o ConfigDSN deverá determinar as informações necessárias; se hwndParent não for nulo, ele exibirá uma caixa de diálogo para recuperar as informações do usuário.

Se ConfigDSN exibir uma caixa de diálogo, ela deverá exibir todas as informações de conexão passadas para ela em lpszAttributes. Em particular, se um nome de fonte de dados tiver sido passado para ele, ConfigDSN exibirá esse nome, mas não permitirá que o usuário o altere. O ConfigDSN pode fornecer valores padrão para informações de conexão não passadas para ele em lpszAttributes.

Se ConfigDSN não puder obter informações completas de conexão para uma fonte de dados, ela retornará FALSE.

Se o ConfigDSN puder obter informações completas de conexão para uma fonte de dados, ele chamará SQLWriteDSNToIni na DLL do instalador para adicionar a nova especificação de fonte de dados ao arquivo de Odbc.ini (ou registro). SQLWriteDSNToIni adiciona o nome da fonte de dados à seção [Fontes de Dados ODBC], cria a seção de especificação da fonte de dados e adiciona a palavra-chave DRIVER com a descrição do driver como seu valor. ConfigDSN chama SQLWritePrivateProfileString na DLL do instalador para adicionar quaisquer palavras-chave e valores adicionais usados pelo driver.

Modificando uma fonte de dados

Para modificar uma fonte de dados, um nome de fonte de dados deve ser passado para ConfigDSN em lpszAttributes. O ConfigDSN verifica se o nome da fonte de dados está no arquivo de Odbc.ini (ou registro).

Se hwndParent for nulo, ConfigDSN usará as informações em lpszAttributes para modificar as informações no arquivo de Odbc.ini (ou registro). Se hwndParent não for nulo, ConfigDSN exibirá uma caixa de diálogo usando as informações em lpszAttributes; para obter informações que não estão em lpszAttributes, ele usa informações das informações do sistema. O usuário pode modificar as informações antes que o ConfigDSN as armazene nas informações do sistema.

Se o nome da fonte de dados tiver sido alterado, o ConfigDSN primeiro chamará SQLRemoveDSNFromIni na DLL do instalador para remover a especificação de fonte de dados existente do arquivo de Odbc.ini (ou registro). Em seguida, ele segue as etapas na seção anterior para adicionar a nova especificação de fonte de dados. Se o nome da fonte de dados não tiver sido alterado, ConfigDSN chamará SQLWritePrivateProfileString na DLL do instalador para fazer outras alterações. ConfigDSN não pode excluir ou alterar o valor da palavra-chave Driver .

Excluindo uma fonte de dados

Para excluir uma fonte de dados, um nome de fonte de dados deve ser passado para ConfigDSN em lpszAttributes. O ConfigDSN verifica se o nome da fonte de dados está no arquivo de Odbc.ini (ou registro). Em seguida, ele chama SQLRemoveDSNFromIni na DLL do instalador para remover a fonte de dados.

Observação

Se estiver escrevendo uma versão Unicode dessa rotina, ela deverá ser chamada de ConfigDSNW, com argumentos LPCWSTR em vez de LPCSTR.

Funções relacionadas

Para obter informações sobre	Consulte
Adicionar, modificar ou remover uma fonte de dados	SQLConfigDataSource
Obtendo um valor do arquivo Odbc.ini ou do registro	SQLGetPrivateProfileString
Removendo a fonte de dados padrão	SQLRemoveDefaultDataSource
Removendo um nome de fonte de dados de Odbc.ini (ou registro)	SQLRemoveDSNFromIni
Adicionando um nome de fonte de dados a Odbc.ini (ou registro)	SQLWriteDSNToIni
Gravando um valor no arquivo Odbc.ini ou no registro	SQLWritePrivateProfileString