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: Conformidade com as Normas ODBC 2.0: ODBC
Summary
SQLDrivers lista descrições de drivers e palavras-chave de atributos de drivers. Esta função é implementada apenas pelo Gestor de Drivers.
Syntax
SQLRETURN SQLDrivers(
SQLHENV EnvironmentHandle,
SQLUSMALLINT Direction,
SQLCHAR * DriverDescription,
SQLSMALLINT BufferLength1,
SQLSMALLINT * DescriptionLengthPtr,
SQLCHAR * DriverAttributes,
SQLSMALLINT BufferLength2,
SQLSMALLINT * AttributesLengthPtr);
Arguments
EnvironmentHandle
[Entrada] Controlo ambiental.
Direção
[Entrada] Determina se o Driver Manager obtém a próxima descrição do driver na lista (SQL_FETCH_NEXT) ou se a pesquisa começa pelo início da lista (SQL_FETCH_FIRST).
DriverDescription
[Saída] Apontar para um buffer onde deveria devolver a descrição do driver.
Se o DriverDescription for NULL, o DescriptionLengthPtr 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 pelo DriverDescription.
BufferLength1
[Entrada] Comprimento do buffer *DriverDescription , em caracteres.
DescriçãoComprimentoPtr
[Saída] Apontador para um buffer onde devolver o número total de caracteres (excluindo o carácter de terminação nula) disponível para devolver em *DriverDescription. Se o número de caracteres disponíveis para devolver for maior ou igual a BufferLength1, a descrição do driver em *DriverDescription é truncada para BufferLength1 menos o comprimento de um carácter de terminação nula.
DriverAttributes
[Saída] Apontar para um buffer onde devolver a lista de pares de valor dos atributos do driver (ver "Comentários").
Se DriverAttributes for NULL, AttributesLengthPtr continuará a devolver o número total de bytes (excluindo o carácter null-termination para dados de caracteres) disponíveis para devolver no buffer apontado pelos DriverAttributes.
BufferLength2
[Entrada] Comprimento do buffer *DriverAttributes , em caracteres. Se o valor *DriverDescription for uma cadeia Unicode (ao chamar SQLDriversW), o argumento BufferLength deve ser um número par.
AtributosComprimentoPtr
[Saída] Apontar para um buffer onde dever o número total de bytes (excluindo o byte de terminação nula) disponíveis para devolver em *DriverAttributes. Se o número de bytes disponíveis para devolver for maior ou igual a BufferLength2, a lista de pares de valor de atributos em *DriverAttributes é truncada para BufferLength2 menos o comprimento do 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 o SQLDrivers retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_ENV e um Handle de EnvironmentHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLDrivers 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 *DriverDescription 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 completa do driver é devolvido em *DescriptionLengthPtr. (Função devolve SQL_SUCCESS_WITH_INFO.) (DM) O buffer *DriverAttributes não era suficientemente grande para devolver a lista completa de pares de valor de atributos. Por isso, a lista foi truncada. O comprimento da lista não arrunada de pares de valor de atributos é devolvido em *AttributesLengthPtr. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum 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 ou igual a 1. |
| 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 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
SQLDrivers devolve a descrição do driver no buffer *DriverDescription . Devolve informações adicionais sobre o driver no buffer *DriverAttributes como uma lista de pares palavra-chave-valor. Todas as palavras-chave listadas na informação do sistema para drivers serão devolvidas para todos os drivers, exceto para o CreateDSN, que é usado para sugerir a criação de fontes de dados e, por isso, é opcional. Cada par termina com um byte nulo, e a lista completa termina com um byte nulo (ou seja, dois bytes nulos marcam o fim da lista). Por exemplo, um driver baseado em ficheiros usando sintaxe C pode devolver a seguinte lista de atributos ("\0" representa um carácter nulo):
FileUsage=1\0FileExtns=*.dbf\0\0
Se *DriverAttributes não for suficientemente grande para conter toda a lista, a lista é truncada, SQLDrivers devolve SQLSTATE 01004 (Dados truncados) e o comprimento da lista (excluindo o último byte de terminação nula) é devolvido em *AttributesLengthPtr.
As palavras-chave dos atributos do driver são adicionadas a partir da informação do sistema quando o driver é instalado. Para mais informações, consulte Instalação de Componentes ODBC.
Uma aplicação pode chamar SQLDrivers várias vezes para recuperar todas as descrições dos drivers. O Driver Manager recupera esta informação a partir da informação do sistema. Quando não há mais descrições de drivers, o SQLDrivers devolve SQL_NO_DATA. Se o SQLDrivers for chamado com SQL_FETCH_NEXT imediatamente após devolver SQL_NO_DATA, devolve a primeira descrição do driver. Para informações sobre como uma aplicação utiliza a informação devolvida pelo SQLDrivers, consulte Escolher uma Fonte de Dados ou Driver.
Se SQL_FETCH_NEXT for passado para SQLDrivers na primeira vez que é chamado, SQLDrivers devolve o nome da primeira fonte de dados.
Como o SQLDrivers está implementado no Gestor de Drivers, é suportado para todos os drivers, independentemente da conformidade com os padrões de cada driver.
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 |
| Retorno dos nomes das fontes de dados | Função SQLDataSources |
| Ligar a uma fonte de dados usando uma cadeia de ligação ou caixa de diálogo | Função SQLDriverConnect |