Compartilhar via


Função SQLDrivers

Conformidade
Versão introduzida: ODBC 2.0 Standards Compliance: ODBC

Resumo
SQLDrivers lista descrições de driver e palavras-chave de atributo de driver. Essa função é implementada apenas pelo Gerenciador de Driver.

Sintaxe

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

Argumentos

EnvironmentHandle
[Entrada] Identificador de ambiente.

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

DriverDescription
[Saída] Ponteiro para um buffer no qual retornar a descrição do driver.

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

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

DescriptionLengthPtr
[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 *DriverDescription. Se o número de caracteres disponíveis para retornar for maior ou igual a BufferLength1, a descrição do driver em *DriverDescription será truncada para BufferLength1 menos o comprimento de um caractere de terminação nula.

DriverAttributes
[Saída] Ponteiro para um buffer no qual retornar a lista de pares de valores de atributo de driver (consulte "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 caractere) disponíveis para retornar no buffer apontado por DriverAttributes.

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

AttributesLengthPtr
[Saída] Ponteiro para um buffer no qual retornar o número total de bytes (excluindo o byte de terminação nula) disponível para retornar em *DriverAttributes. Se o número de bytes disponíveis para retornar for maior ou igual a BufferLength2, a lista de pares de valores de atributo em *DriverAttributes será truncada para BufferLength2 menos o comprimento do caractere de terminação nula.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

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 Identificador de EnvironmentHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLDrivers 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 *DriverDescription 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 completa do driver é retornado em *DescriptionLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.)

(DM) O buffer *DriverAttributes não era grande o suficiente para retornar a lista completa de pares de valores de atributo. Portanto, a lista foi truncada. O comprimento da lista não confiável de pares de valor de atributo é retornado em *AttributesLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.)
HY000 Erro geral 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 era menor que 0 ou igual a 1.
HY103 Código de recuperação inválido (DM) O valor especificado para o argumento Direction não era igual a SQL_FETCH_FIRST 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

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 chave-valor. Todas as palavras-chave listadas nas informações do sistema para drivers serão retornadas para todos os drivers, exceto para CreateDSN, que é usado para solicitar a criação de fontes de dados e, portanto, é opcional. Cada par é encerrado com um byte nulo e a lista completa é encerrada com um byte nulo (ou seja, dois bytes nulos marcam o final da lista). Por exemplo, um driver baseado em arquivo usando a 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 manter toda a lista, a lista será truncada, SQLDrivers retornará SQLSTATE 01004 (Dados truncados) e o comprimento da lista (excluindo o byte final de terminação nula) será retornado em *AttributesLengthPtr.

As palavras-chave do atributo driver são adicionadas a partir das informações do sistema quando o driver é instalado. Para obter mais informações, consulte Instalando componentes ODBC.

Um aplicativo pode chamar SQLDrivers várias vezes para recuperar todas as descrições do driver. O Gerenciador de Driver recupera essas informações das informações do sistema. Quando não há mais descrições de driver, o SQLDrivers retorna SQL_NO_DATA. Se SQLDrivers for chamado com SQL_FETCH_NEXT imediatamente após retornar SQL_NO_DATA, ele retornará a primeira descrição do driver. Para obter informações sobre como um aplicativo usa as informações retornadas por SQLDrivers, consulte Escolhendo uma fonte de dados ou driver.

Se SQL_FETCH_NEXT for passado para SQLDrivers na primeira vez que for chamado, SQLDrivers retornará o nome da primeira fonte de dados.

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

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
Retornando nomes de fonte de dados Função SQLDataSources
Conectando-se a uma fonte de dados usando uma cadeia de conexão ou caixa de diálogo Função SQLDriverConnect

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC