Função SQLDataSources
Conformidade
Versão introduzida: ODBC 1.0 Standards Compliance: ISO 92
Resumo
SQLDataSources retorna informações sobre uma fonte de dados. Essa função é implementada apenas pelo Gerenciador de Driver.
Sintaxe
SQLRETURN SQLDataSources(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * ServerName,
SQLSMALLINT BufferLength1,
SQLSMALLINT * NameLength1Ptr,
SQLCHAR * Description,
SQLSMALLINT BufferLength2,
SQLSMALLINT * NameLength2Ptr);
Argumentos
EnvironmentHandle
[Entrada] Identificador de ambiente.
Direção
[Entrada] Determina sobre qual fonte de dados o Gerenciador de Driver retorna informações. Pode ser:
SQL_FETCH_NEXT (para buscar o próximo nome da fonte de dados na lista), SQL_FETCH_FIRST (buscar desde o início da lista), SQL_FETCH_FIRST_USER (buscar o primeiro DSN de usuário) ou SQL_FETCH_FIRST_SYSTEM (para buscar o primeiro DSN do sistema).
Quando Direction é definido como SQL_FETCH_FIRST, chamadas subsequentes para SQLDataSources com Direction definidas como SQL_FETCH_NEXT retornam DSNs do usuário e do sistema. Quando Direction é definido como SQL_FETCH_FIRST_USER, todas as chamadas subsequentes para SQLDataSources com Direction definidas como SQL_FETCH_NEXT retornam apenas DSNs de usuário. Quando Direction é definido como SQL_FETCH_FIRST_SYSTEM, todas as chamadas subsequentes para SQLDataSources com Direction definidas como SQL_FETCH_NEXT retornam apenas DSNs do sistema.
ServerName
[Saída] Ponteiro para um buffer no qual retornar 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 caractere) disponíveis para retornar no buffer apontado por ServerName.
BufferLength1
[Entrada] Comprimento do buffer *ServerName , em caracteres; isso não precisa ser maior do que SQL_MAX_DSN_LENGTH mais o caractere de terminação nula.
NameLength1Ptr
[Saída] Ponteiro para um buffer no qual retornar o número total de caracteres (excluindo o caractere de terminação nula) disponível para retornar em *ServerName. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength1, o nome da fonte de dados em *ServerName será truncado para BufferLength1 menos o comprimento de um caractere de terminação nula.
Descrição
[Saída] Ponteiro para um buffer no qual retornar 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 caractere) disponíveis para retornar no buffer apontado por Description.
BufferLength2
[Entrada] Comprimento em caracteres do buffer *Descrição .
NameLength2Ptr
[Saída] Ponteiro para um buffer no qual retornar o número total de caracteres (excluindo o caractere de terminação nula) disponível para retornar em *Descrição. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength2, a descrição do driver em *Description será truncada para BufferLength2 menos o comprimento de um caractere de terminação nula.
Retornos
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, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_ENV e um Handle of EnvironmentHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLDataSources e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | (DM) Mensagem informativa específica do Gerenciador de Driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia de caracteres, truncados à direita | (DM) O buffer *ServerName não era grande o suficiente para retornar o nome completo da fonte de dados. Portanto, 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 *A descrição 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 confiável é retornado em *NameLength2Ptr. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | (DM) Ocorreu um erro para o qual não havia nenhum 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 Driver não pôde alocar memória necessária para dar suporte à execução ou à conclusão da função. |
| HY010 | Erro de sequência de funções | (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o StatementHandle e retornou SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem 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 | Comprimento de buffer ou cadeia de caracteres inválida | (DM) O valor especificado para o argumento BufferLength1 foi menor que 0. (DM) O valor especificado para o argumento BufferLength2 foi menor que 0. |
| HY103 | Código de recuperação inválido | (DM) O valor especificado para o argumento Direction não era igual a SQL_FETCH_FIRST, SQL_FETCH_FIRST_USER, SQL_FETCH_FIRST_SYSTEM ou SQL_FETCH_NEXT. |
| HY117 | A conexão é suspensa devido ao estado de transação desconhecido. 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. |
Comentários
Como o SQLDataSources é implementado no Gerenciador de Driver, há suporte para todos os drivers, independentemente da conformidade de padrões de um driver específico.
Um aplicativo pode chamar SQLDataSources várias vezes para recuperar todos os nomes de fonte de dados. O Gerenciador de Driver recupera essas informações das informações do sistema. Quando não há mais nomes de fonte de dados, o Gerenciador de Driver 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 obter informações sobre como um aplicativo usa as informações retornadas por SQLDataSources, consulte Escolhendo uma fonte de dados ou driver.
Se SQL_FETCH_NEXT for passado para SQLDataSources na primeira vez em que for chamado, ele retornará o nome da primeira fonte de dados.
O driver determina como os nomes da fonte de dados são mapeados para fontes de dados reais.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Descobrir e listar 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 de driver | Função SQLDrivers |