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