Função SQLGetConnectAttr
Conformidade
Versão introduzida: ODBC 3.0 Standards Compliance: ISO 92
Resumo
SQLGetConnectAttr retorna a configuração atual de um atributo de conexão.
Observação
Para obter mais informações sobre como o Gerenciador de Driver mapeia essa função para quando um aplicativo ODBC 3*.x* está trabalhando com um driver ODBC 2*.x*, consulte Mapeando funções de substituição para compatibilidade com versões anteriores de aplicativos.
Sintaxe
SQLRETURN SQLGetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Argumentos
ConnectionHandle
[Entrada] Identificador de conexão.
Atributo
[Entrada] Atributo a ser recuperado.
ValuePtr
[Saída] Um ponteiro para a memória na qual retornar o valor atual do atributo especificado por Attribute. Para atributos de tipo inteiro, alguns drivers só podem gravar os 32 bits inferiores ou 16 bits de um buffer e deixar o bit de ordem superior inalterado. Portanto, os aplicativos devem usar um buffer de SQLULEN e inicializar o valor como 0 antes de chamar essa função.
Se ValuePtr for NULL, StringLengthPtr 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 ValuePtr.
BufferLength
[Entrada] Se Attribute for um atributo definido por ODBC e ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, esse argumento deverá ter o comprimento de *ValuePtr. Se Attribute for um atributo definido por ODBC e *ValuePtr for um inteiro, BufferLength será ignorado. Se o valor em *ValuePtr for uma cadeia de caracteres Unicode (ao chamar SQLGetConnectAttrW), o argumento BufferLength deverá ser um número par.
Se Attribute for um atributo definido pelo driver, o aplicativo indicará a natureza do atributo para o Gerenciador de Driver definindo o argumento BufferLength . BufferLength pode ter os seguintes valores:
Se *ValuePtr for um ponteiro para uma cadeia de caracteres, BufferLength será o comprimento da cadeia de caracteres.
Se *ValuePtr for um ponteiro para um buffer binário, o aplicativo colocará o resultado da macro SQL_LEN_BINARY_ATTR(length) em BufferLength. Isso coloca um valor negativo em BufferLength.
Se *ValuePtr for um ponteiro para um valor diferente de uma cadeia de caracteres ou uma cadeia de caracteres binária, BufferLength deverá ter o valor SQL_IS_POINTER.
Se *ValuePtr contiver um tipo de dados de comprimento fixo, BufferLength será SQL_IS_INTEGER ou SQL_IS_UINTEGER, conforme apropriado.
StringLengthPtr
[Saída] Um ponteiro para um buffer no qual retornar o número total de bytes (excluindo o caractere de terminação nula) disponível para retornar em *ValuePtr. Se o valor do atributo for uma cadeia de caracteres e o número de bytes disponíveis para retornar for maior que BufferLength menos o comprimento do caractere de terminação nula, os dados em *ValuePtr serão truncados para BufferLength menos o comprimento do caractere de terminação nula e serão encerrados em nulo pelo driver.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLGetConnectAttr retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido da estrutura de dados de diagnóstico chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_DBC e um Identificador de ConnectionHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLGetConnectAttr 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 | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia de caracteres, truncados à direita | Os dados retornados em *ValuePtr foram truncados para serem BufferLength menos o comprimento de um caractere de terminação nula. O comprimento do valor da cadeia de caracteres não confiável é retornado em *StringLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08003 | Conexão não aberta | (DM) Um valor de atributo que exigia uma conexão aberta foi especificado. |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver foi conectado falhou antes da conclusão do processamento da função. |
| 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 da estrutura de dados de diagnóstico pelo argumento MessageText em SQLGetDiagField descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O 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) SQLBrowseConnect foi chamado para o ConnectionHandle e retornou SQL_NEED_DATA. Essa função foi chamada antes de SQLBrowseConnect retornar SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para o ConnectionHandle 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) *ValuePtr é uma cadeia de caracteres e BufferLength era menor que zero, mas não igual a SQL_NTS. |
| HY092 | Identificador de atributo/opção inválido | O valor especificado para o argumento Attribute não era válido para a versão do ODBC compatível com o driver. |
| HY114 | O driver não dá suporte à execução de função assíncrona no nível da conexão | (DM) Um aplicativo tentou habilitar a execução de função assíncrona com SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE para um driver que não dá suporte a operações de conexão assíncronas. |
| 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. |
| HYC00 | Recurso opcional não implementado | O valor especificado para o argumento Attribute era um atributo de conexão ODBC válido para a versão do ODBC compatível com o driver, mas não era compatível com o driver. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes da fonte de dados responder à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não dá suporte a essa função | (DM) O driver que corresponde ao ConnectionHandle não dá suporte à função. |
Comentários
Para obter informações gerais sobre atributos de conexão, consulte Atributos de conexão.
Para obter uma lista de atributos que podem ser definidos, consulte SQLSetConnectAttr. Observe que, se Attribute especificar um atributo que retorna uma cadeia de caracteres, ValuePtr deverá ser um ponteiro para um buffer para a cadeia de caracteres. O comprimento máximo da cadeia de caracteres retornada, incluindo o caractere de terminação nula, será BufferLength bytes.
Dependendo do atributo, um aplicativo não precisa estabelecer uma conexão antes de chamar SQLGetConnectAttr. No entanto, se SQLGetConnectAttr for chamado e o atributo especificado não tiver um padrão e não tiver sido definido por uma chamada anterior para SQLSetConnectAttr, SQLGetConnectAttr retornará SQL_NO_DATA.
Se Attribute for SQL_ATTR_ TRACE ou SQL_ATTR_ TRACEFILE, ConnectionHandle não precisará ser válido e SQLGetConnectAttr não retornará SQL_ERROR ou SQL_INVALID_HANDLE se ConnectionHandle for inválido. Esses atributos se aplicam a todas as conexões. SQLGetConnectAttr retornará SQL_ERROR ou SQL_INVALID_HANDLE se outro argumento for inválido.
Embora um aplicativo possa definir atributos de instrução usando SQLSetConnectAttr, um aplicativo não pode usar SQLGetConnectAttr para recuperar valores de atributo de instrução; ele deve chamar SQLGetStmtAttr para recuperar a configuração de atributos de instrução.
Os atributos de conexão SQL_ATTR_AUTO_IPD e SQL_ATTR_CONNECTION_DEAD podem ser retornados por uma chamada para SQLGetConnectAttr , mas não podem ser definidos por uma chamada para SQLSetConnectAttr.
Observação
Não há suporte assíncrono para SQLGetConnectAttr. Ao implementar o SQLGetConnectAttr, um driver pode melhorar o desempenho minimizando o número de vezes que as informações são enviadas ou solicitadas do servidor.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Retornando a configuração de um atributo de instrução | Função SQLGetStmtAttr |
| Configurando um atributo de conexão | Função SQLSetConnectAttr |
| Configurando um atributo de ambiente | Função SQLSetEnvAttr |
| Configurando um atributo de instrução | Função SQLSetStmtAttr |