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: Normas ODBC 3.0 Conformidade: ISO 92
Summary
SQLGetConnectAttr devolve a definição atual de um atributo de ligação.
Note
Para mais informações sobre o que o Gestor de Drivers mapeia esta função quando uma aplicação ODBC 3*.x* está a trabalhar com um driver ODBC 2*.x*, consulte Mapeamento de Funções de Substituição para Compatibilidade Retrocedora de Aplicações.
Syntax
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
ConnectionHandle
[Entrada] Alavanca de ligação.
Atributo
[Entrada] Atributo para recuperar.
ValuePtr
[Saída] Um apontador para a memória onde se deve devolver o valor atual do atributo especificado pelo Atributo. Para atributos do tipo inteiro, alguns drivers podem escrever apenas os 32 ou 16 bits inferiores de um buffer e deixar o bit de ordem superior inalterado. Portanto, as aplicações devem usar um buffer de SQLULEN e inicializar o valor a 0 antes de chamar esta função.
Se o ValuePtr for NULL, o StringLengthPtr continuará a devolver o número total de bytes (excluindo o carácter de terminação nula para dados de caracteres) disponíveis para devolver no buffer apontado pelo ValuePtr.
BufferLength
[Entrada] Se o Atributo for um atributo definido por ODBC e o ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, este argumento deve corresponder ao comprimento de *ValuePtr. Se o Atributo for definido por ODBC e *ValuePtr for um inteiro, o BufferLength é ignorado. Se o valor em *ValuePtr for uma cadeia Unicode (ao chamar SQLGetConnectAttrW), o argumento BufferLength deve ser um número par.
Se o Atributo for um atributo definido pelo driver, a aplicação indica a natureza do atributo ao Driver Manager definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:
Se *ValuePtr for um ponteiro para uma cadeia de caracteres, BufferLength é o comprimento da cadeia.
Se *ValuePtr for um ponteiro para um buffer binário, a aplicação coloca o resultado da macro SQL_LEN_BINARY_ATTR(comprimento) em BufferLength. Isto coloca um valor negativo no BufferLength.
Se *ValuePtr for um ponteiro para um valor diferente de uma cadeia de caracteres ou binária, BufferLength deve ter o valor SQL_IS_POINTER.
Se *ValuePtr contiver um tipo de dado de comprimento fixo, BufferLength é SQL_IS_INTEGER ou SQL_IS_UINTEGER, conforme apropriado.
StringLengthPtr
[Saída] Um apontador para um buffer onde deves o número total de bytes (excluindo o carácter de terminação nula) disponíveis para devolver em *ValuePtr. Se o valor do atributo for uma cadeia de caracteres e o número de bytes disponíveis para devolver for maior que BufferLength menos o comprimento do carácter de terminação nula, os dados em *ValuePtr são truncados para BufferLength menos o comprimento do carácter de terminação nula e são terminados por null pelo driver.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLGetConnectAttr devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado a partir da estrutura de dados de diagnóstico chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_DBC e um Handle de ConnectionHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLGetConnectAttr 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 | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia, truncados à direita | Os dados devolvidos em *ValuePtr foram truncados para ser BufferLength menos o comprimento de um carácter de terminação nula. O comprimento do valor da cadeia não arrunada é devolvido em *StringLengthPtr. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 08003 | Ligação não aberta | (DM) Foi especificado um valor de Atributo que exigia uma ligação aberta. |
| 08S01 | Falha da ligação de comunicação | A ligação de comunicação entre o driver e a fonte de dados à qual o driver estava ligado falhou antes de a função concluir o processamento. |
| 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 pela estrutura de dados de diagnóstico pelo argumento MessageText em SQLGetDiagField descreve o erro e a sua causa. |
| HY001 | Erro de alocação de memória | O controlador 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) SQLBrowseConnect foi chamado para o ConnectionHandle e retornou SQL_NEED_DATA. Esta função era chamada antes do SQLBrowseConnect devolver SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults era chamado para o ConnectionHandle 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) *ValuePtr é uma cadeia de caracteres, e BufferLength era inferior a zero mas não igual a SQL_NTS. |
| HY092 | Identificador de atributo/opção inválido | O valor especificado para o argumento Atributo não era válido para a versão de ODBC suportada pelo driver. |
| HY114 | O driver não suporta a execução de funções assíncronas a nível de ligação | (DM) Uma aplicação tentou permitir a execução de funções assíncronas com SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE para um driver que não suporta operações de ligação assíncronas. |
| 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. |
| HYC00 | Funcionalidade opcional não implementada | O valor especificado para o atributo do argumento Attribute era um atributo válido de ligação ODBC para a versão de ODBC suportada pelo driver, mas que não era suportado pelo driver. |
| HYT01 | Expirou o tempo limite de ligação | O período de timeout da ligação expirou antes de a fonte de dados responder ao pedido. O período de tempo de expiração da ligação é definido através do SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O driver que corresponde ao ConnectionHandle não suporta a função. |
Comments
Para informações gerais sobre atributos de ligação, veja Atributos de Conexão.
Para uma lista de atributos que podem ser definidos, veja SQLSetConnectAttr. Note que, se o Atributo especificar um atributo que devolve uma cadeia, o ValuePtr deve ser um apontador para um buffer da cadeia. O comprimento máximo da cadeia devolvida, incluindo o carácter de terminação nula, será bytes BufferLength .
Dependendo do atributo, uma aplicação não precisa de estabelecer uma ligação antes de chamar SQLGetConnectAttr. No entanto, se o SQLGetConnectAttr for chamado e o atributo especificado não tiver um padrão e não tiver sido definido por uma chamada anterior ao SQLSetConnectAttr, o SQLGetConnectAttr devolverá SQL_NO_DATA.
Se o Atributo for SQL_ATTR_ TRACE ou SQL_ATTR_ TRACEFILE, o ConnectionHandle não tem de ser válido, e o SQLGetConnectAttr não devolverá SQL_ERROR ou SQL_INVALID_HANDLE se o ConnectionHandle for inválido. Estas características aplicam-se a todas as ligações. SQLGetConnectAttr devolverá SQL_ERROR ou SQL_INVALID_HANDLE se outro argumento for inválido.
Embora uma aplicação possa definir atributos de instrução usando SQLSetConnectAttr, uma aplicação não pode usar SQLGetConnectAttr para recuperar valores de atributos de instruções; deve chamar SQLGetStmtAttr para recuperar a definição dos atributos da instrução.
Tanto SQL_ATTR_AUTO_IPD como SQL_ATTR_CONNECTION_DEAD atributos de ligação podem ser devolvidos por uma chamada ao SQLGetConnectAttr , mas não podem ser definidos por uma chamada ao SQLSetConnectAttr.
Note
Não existe suporte assíncrono para SQLGetConnectAttr. Ao implementar SQLGetConnectAttr, um driver pode melhorar o desempenho ao minimizar o número de vezes que essa informação é enviada ou solicitada ao servidor.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Devolver a definição de um atributo de instrução | Função SQLGetStmtAttr |
| Definir um atributo de ligação | Função SQLSetConnectAttr |
| Definir um atributo ambiente | Função SQLSetEnvAttr |
| Definir um atributo de instrução | Função SQLSetStmtAttr |