Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Normas ODBC 1.0 Conformidade: ISO 92
Summary
SQLDataSources devolve informação sobre uma fonte de dados. Esta função é implementada apenas pelo Gestor de Drivers.
Syntax
SQLRETURN SQLDataSources(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT * NameLength1Ptr,
SQLCHAR * Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT * NameLength2Ptr);
Arguments
EnvironmentHandle
[Entrada] Controlo ambiental.
Direção
[Entrada] Determina sobre qual fonte de dados o Gestor de Condutores devolve informações. Pode ser:
SQL_FETCH_NEXT (para obter 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 de utilizador) ou SQL_FETCH_FIRST_SYSTEM (buscar o primeiro DSN do sistema).
Quando a Direção está definida para SQL_FETCH_FIRST, chamadas subsequentes para SQLDataSources com a Direção definida para SQL_FETCH_NEXT retornam tanto DSN do utilizador como do sistema. Quando a Direção está definida para SQL_FETCH_FIRST_USER, todas as chamadas subsequentes para SQLDataSources com a Direção definida para SQL_FETCH_NEXT retornam apenas DSNs do utilizador. Quando a Direção está definida para SQL_FETCH_FIRST_SYSTEM, todas as chamadas subsequentes para SQLDataSources com a Direção definida para SQL_FETCH_NEXT retornam apenas DSNs do sistema.
ServerName
[Saída] Apontador para um buffer onde devolver o nome da fonte de dados.
Se ServerName for NULL, NameLength1Ptr devolverá o número total de caracteres (excluindo o carácter de terminação nula para dados de caracteres) disponíveis para devolver no buffer apontado por ServerName.
BufferLength1
[Entrada] Comprimento do buffer *ServerName , em caracteres; isto não precisa de ser mais longo do que SQL_MAX_DSN_LENGTH mais o carácter de terminação nula.
NomeComprimento1Ptr
[Saída] Apontador para um buffer onde se deve devolver o número total de caracteres (excluindo o carácter de terminação nula) disponíveis para devolver em *Nomedo do Servidor. Se o número de caracteres disponíveis para devolver for maior ou igual a BufferLength1, o nome da fonte de dados em *ServerName é truncado para BufferLength1 menos o comprimento de um carácter de terminação nula.
Description
[Saída] Apontador para um buffer onde deveria devolver a descrição do driver associado à fonte de dados. Por exemplo, dBASE ou SQL Server.
Se Description for NULL, NameLength2Ptr continuará a devolver o número total de caracteres (excluindo o carácter de terminação nula para dados de caracteres) disponíveis para devolver no buffer apontado por Description.
BufferLength2
[Entrada] Comprimento em caracteres do *Description buffer.
NomeComprimento2Ptr
[Saída] Apontador para um buffer onde deveria o número total de caracteres (excluindo o carácter de terminação nula) disponível para devolver em *Description. Se o número de caracteres disponíveis para devolver for maior ou igual a BufferLength2, a descrição do driver em *Description é truncada para BufferLength2 menos o comprimento de um carácter de terminação nula.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLDataSources retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado ao chamar SQLGetDiagRec com um HandleType de SQL_HANDLE_ENV e um Handle de EnvironmentHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLDataSources e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | (DM) Mensagem informativa específica do Driver Manager. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia, truncados à direita | (DM) O buffer *ServerName não era suficientemente grande para devolver o nome completo da fonte de dados. Por isso, o nome foi truncado. O comprimento de todo o nome da fonte de dados é devolvido em *NameLength1Ptr. (Função devolve SQL_SUCCESS_WITH_INFO.) (DM) O buffer *Description não era suficientemente grande para devolver a descrição completa do driver. Por isso, a descrição foi truncada. O comprimento da descrição da fonte de dados não arruinada é devolvido em *NameLength2Ptr. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | (DM) Ocorreu um erro para o qual não existiu um SQLSTATE específico e para o qual não foi definido um SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *MessageText descreve o erro e a sua causa. |
| HY001 | Erro de alocação de memória | (DM) O Gestor 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ções | (DM) SQLExecute, SQLExecDirect ou SQLMoreResults era chamado para o StatementHandle e devolvido SQL_PARAM_DATA_AVAILABLE. Esta função era chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. |
| HY013 | Erro de gestão de memória | A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória. |
| HY090 | Comprimento inválido da corda ou do buffer | (DM) O valor especificado para o argumento BufferLength1 era inferior a 0. (DM) O valor especificado para o argumento BufferLength2 era inferior a 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 ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. | (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran. |
Comments
Como o SQLDataSources está implementado no Gestor de Drivers, é suportado para todos os drivers independentemente da conformidade com os padrões de cada driver.
Uma aplicação pode chamar SQLDataSources várias vezes para recuperar todos os nomes das fontes de dados. O Driver Manager recupera esta informação a partir da informação do sistema. Quando já não existem nomes de fontes de dados, o Driver Manager devolve SQL_NO_DATA. Se o SQLDataSources for chamado com SQL_FETCH_NEXT imediatamente após devolver SQL_NO_DATA, devolverá o primeiro nome da fonte de dados. Para informações sobre como uma aplicação utiliza a informação devolvida pelo SQLDataSources, veja Escolher uma Fonte de Dados ou Driver.
Se SQL_FETCH_NEXT for passado para SQLDataSources na primeira vez que é chamado, devolverá 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 ligar a uma fonte de dados | Função SQLBrowseConnect |
| Conectando-se a uma fonte de dados | Função SQLConnect |
| Ligar a uma fonte de dados usando uma cadeia de ligação ou caixa de diálogo | Função SQLDriverConnect |
| Devolução das descrições e atributos dos pilotos | Função SQLDrivers |