Função SQLDrivers

Conformidade
Versão introduzida: ODBC 2.0 Conformidade com os padrões: ODBC

Summary
SQLDrivers lista descrições de drivers e palavras-chave de atributos de drivers. Essa função é implementada apenas pelo Gerenciador de Drivers.

Sintaxe

  
SQLRETURN SQLDrivers(  
     SQLHENV         EnvironmentHandle,  
     SQLUSMALLINT    Direction,  
     SQLCHAR *       DriverDescription,  
     SQLSMALLINT     BufferLength1,  
     SQLSMALLINT *   DescriptionLengthPtr,  
     SQLCHAR *       DriverAttributes,  
     SQLSMALLINT     BufferLength2,  
     SQLSMALLINT *   AttributesLengthPtr);  

Argumentos

EnvironmentHandle
[Entrada] Controle ambiental.

Direção
[Entrada] Determina se o Driver Manager busca a próxima descrição do driver na lista (SQL_FETCH_NEXT) ou se a busca começa do início da lista (SQL_FETCH_FIRST).

DriverDescription
[Saída] Apontador para um buffer onde retorna a descrição do driver.

Se o DriverDescription for NULL, o DescriptionLengthPtr 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 pelo DriverDescription.

BufferLength1
[Entrada] Comprimento do buffer *DriverDescription , em caracteres.

DescriçãoComprimentoPtr
[Saída] Apontador para um buffer no qual retorna o número total de caracteres (excluindo o caractere de término nulo) disponíveis para retorno em *DriverDescription. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength1, a descrição do driver em *DriverDescription é truncada para BufferLength1 menos o comprimento de um caractere de terminação nula.

Atributos do Piloto
[Saída] Apontar para um buffer onde retornar a lista de pares de valor dos atributos do driver (veja "Comentários").

Se DriverAttributes for NULL, AttributesLengthPtr ainda retornará o número total de bytes (excluindo o caractere de terminação nula para dados de caracteres) disponíveis para retorno no buffer apontado pelos DriverAttributes.

BufferLength2
[Entrada] Comprimento do buffer *DriverAttributes , em caracteres. Se o valor *DriverDescription for uma string Unicode (ao chamar SQLDriversW), o argumento BufferLength deve ser um número par.

AtributosComprimentoPtr
[Saída] Apontador para um buffer no qual deveria devolver o número total de bytes (excluindo o byte de terminação nula) disponíveis para retorno em *DriverAttributes. Se o número de bytes disponíveis para retornar for maior ou igual a BufferLength2, a lista de pares de atributos em *DriverAttributes é truncada para BufferLength2 menos o comprimento do caractere de terminação nula.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Quando SQLDrivers 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 SQLDrivers 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.

Comments

SQLDrivers retorna a descrição do driver no buffer *DriverDescription . Ele retorna informações adicionais sobre o driver no buffer *DriverAttributes como uma lista de pares palavra-chave-valor. Todas as palavras-chave listadas nas informações do sistema para drivers serão retornadas para todos os drivers, exceto para o CreateDSN, que é usado para sugerir a criação de fontes de dados e, portanto, é opcional. Cada par é terminado com um byte nulo, e a lista completa é terminada com um byte nulo (ou seja, dois bytes nulos marcam o fim da lista). Por exemplo, um driver baseado em arquivos usando sintaxe C pode retornar a seguinte lista de atributos ("\0" representa um caractere nulo):

FileUsage=1\0FileExtns=*.dbf\0\0  

Se *DriverAttributes não for grande o suficiente para conter toda a lista, a lista é truncada, SQLDrivers retorna SQLSTATE 01004 (Dados truncados) e o comprimento da lista (excluindo o byte final de terminação nula) é retornado em *AttributesLengthPtr.

Palavras-chave de atributos do driver são adicionadas a partir das informações do sistema quando o driver é instalado. Para mais informações, veja 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 essas informações a partir das informações do sistema. Quando não há mais descrições de drivers, SQLDrivers retorna SQL_NO_DATA. Se SQLDrivers for chamado com SQL_FETCH_NEXT imediatamente após retornar SQL_NO_DATA, ele retorna a primeira descrição do driver. Para informações sobre como uma aplicação utiliza as informações retornadas pelo SQLDrivers, veja Escolhendo uma Fonte de Dados ou Driver.

Se SQL_FETCH_NEXT for passado para SQLDrivers na primeira vez que é chamado, SQLDrivers retorna o primeiro nome da fonte de dados.

Como o SQLDrivers é implementado no Gerenciador de Drivers, ele é suportado para todos os drivers, independentemente da conformidade com os padrões de um driver específico.

Funções relacionadas

Conteúdo relacionado

• Referência da API ODBC
• Arquivos de cabeçalho ODBC