Função SQLDrivers

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.

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

Conteúdo relacionado

• Referência da API ODBC
• Ficheiros de Cabeçalho ODBC