Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Conformidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92
Summary
SQLDataSources retorna informações sobre uma fonte de dados. Essa função é implementada apenas pelo Gerenciador de Drivers.
Sintaxe
SQLRETURN SQLDataSources(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT * NameLength1Ptr,
SQLCHAR * Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT * NameLength2Ptr);
Argumentos
EnvironmentHandle
[Entrada] Controle ambiental.
Direção
[Entrada] Determina sobre qual fonte de dados o Driver Manager retorna informações. Pode ser:
SQL_FETCH_NEXT (para buscar o próximo nome da fonte de dados na lista), SQL_FETCH_FIRST (buscar do início da lista), SQL_FETCH_FIRST_USER (buscar o primeiro DSN do usuário) ou SQL_FETCH_FIRST_SYSTEM (buscar o primeiro DSN do sistema).
Quando Direction está definida como SQL_FETCH_FIRST, chamadas subsequentes para SQLDataSources com Direction definida para SQL_FETCH_NEXT retornam tanto DSN do usuário quanto do sistema. Quando a Direção está definida como SQL_FETCH_FIRST_USER, todas as chamadas subsequentes para SQLDataSources com a Direção definida para SQL_FETCH_NEXT retornam apenas DSNs de usuário. Quando a Direção está definida para SQL_FETCH_FIRST_SYSTEM, todas as chamadas subsequentes para Fontes SQLDataSource com a Direção definida para SQL_FETCH_NEXT retornam apenas DSNs do sistema.
ServerName
[Saída] Apontar para um buffer no qual retorna o nome da fonte de dados.
Se ServerName for NULL, NameLength1Ptr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caracteres) disponíveis para retorno no buffer apontado pelo ServerName.
BufferLength1
[Entrada] Comprimento do buffer *NomeServidor , em caracteres; isso não precisa ser maior que SQL_MAX_DSN_LENGTH mais o caractere de terminação nula.
NomeComprimento1Ptr
[Saída] Apontador para um buffer no qual retorna o número total de caracteres (excluindo o caractere de terminação nula) disponíveis para retorno em *NomeServidor. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength1, o nome da fonte de dados em *ServerName é truncado para BufferLength1 menos o comprimento de um caractere de terminação nula.
Description
[Saída] Apontador para um buffer no qual retorna a descrição do driver associado à fonte de dados. Por exemplo, dBASE ou SQL Server.
Se Description for NULL, NameLength2Ptr ainda retornará o número total de caracteres (excluindo o caractere de terminação nula para dados de caracteres) disponíveis para serem retornados no buffer apontado por Description.
BufferLength2
[Entrada] Comprimento em caracteres do *Description buffer.
NomeComprimento2Ptr
[Saída] Apontador para um buffer no qual devolver o número total de caracteres (excluindo o caractere de terminação nula) disponíveis para retorno em *Description. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength2, a descrição do driver em *Description é truncada para BufferLength2 menos o comprimento de um caractere de terminação nula.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
Quando SQLDataSources retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_ENV e um Handle de EnvironmentHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados pelo SQLDataSources e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | (DM) Mensagem informativa específica do Driver Manager. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia de caracteres, truncados à direita | (DM) O buffer *NomeServidor não era grande o suficiente para retornar o nome completo da fonte de dados. Por isso, o nome foi truncado. O comprimento de todo o nome da fonte de dados é retornado em *NameLength1Ptr. (A função retorna SQL_SUCCESS_WITH_INFO.) (DM) O buffer *Description não era grande o suficiente para retornar a descrição completa do driver. Portanto, a descrição foi truncada. O comprimento da descrição da fonte de dados não arrunada é retornado em *NameLength2Ptr. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | (DM) Ocorreu um erro para o qual não havia SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | (DM) O Gerenciador de Drivers não conseguiu alocar a memória necessária para suportar a execução ou conclusão da função. |
| HY010 | Erro de sequência de função | (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes que os dados fossem recuperados para todos os parâmetros transmitidos. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY090 | Cadeia de caracteres ou comprimento de buffer inválido | (DM) O valor especificado para o argumento BufferLength1 era menor que 0. (DM) O valor especificado para o argumento BufferLength2 era menor que 0. |
| HY103 | Código de recuperação inválido | (DM) O valor especificado para o argumento Direção não era igual a SQL_FETCH_FIRST, SQL_FETCH_FIRST_USER, SQL_FETCH_FIRST_SYSTEM ou SQL_FETCH_NEXT. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. Somente funções de desconexão e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
Comments
Como o SQLDataSources é implementado no Driver Manager, ele é suportado para todos os drivers, independentemente da conformidade com os padrões de um driver específico.
Uma aplicação pode chamar SQLDataSources várias vezes para recuperar todos os nomes das fontes de dados. O Driver Manager recupera essas informações a partir das informações do sistema. Quando não há mais nomes de fontes de dados, o Driver Manager retorna SQL_NO_DATA. Se SQLDataSources for chamado com SQL_FETCH_NEXT imediatamente após retornar SQL_NO_DATA, ele retornará o primeiro nome da fonte de dados. Para informações sobre como uma aplicação utiliza as informações retornadas pelo SQLDataSources, veja Escolha de uma Fonte de Dados ou Driver.
Se SQL_FETCH_NEXT for passado para SQLDataSources na primeira vez que for chamado, ele retornará o primeiro nome da fonte de dados.
O driver determina como os nomes das fontes de dados são mapeados para fontes de dados reais.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Descobrir e listar os valores necessários para se conectar a uma fonte de dados | Função SQLBrowseConnect |
| Conectando-se a uma fonte de dados | Função SQLConnect |
| Conectando-se a uma fonte de dados usando uma cadeia de conexão ou caixa de diálogo | função SQLDriverConnect |
| Retornando descrições e atributos do driver | Função SQLDrivers |