Função SQLGetConnectAttr

Conformidade
Versão Introduzida: Conformidade com as Normas ODBC 3.0: ISO 92

Summary
SQLGetConnectAttr retorna a configuração atual de um atributo de conexão.

Sintaxe

  
SQLRETURN SQLGetConnectAttr(  
     SQLHDBC        ConnectionHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);  

Argumentos

Identificador de conexão
[Entrada] Identificador de conexão.

Atributo
[Entrada] Atributo para recuperar.

ValuePtr
[Saída] Um ponteiro para a memória no qual deveria retornar o valor atual do atributo especificado por Attribute. 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 em 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 caracteres) disponíveis para retorno no buffer apontado pelo 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 Atributo for um atributo definido por ODBC e *ValuePtr for um inteiro, BufferLength é ignorado. Se o valor em *ValuePtr for uma string Unicode (ao chamar SQLGetConnectAttrW), o argumento BufferLength deve ser um número par.

Se o Atributo for 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 é um ponteiro para uma string de caracteres, BufferLength é o comprimento da string.

• 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. Isso coloca um valor negativo no BufferLength.

• Se *ValuePtr for um ponteiro para um valor diferente de uma string de caracteres ou binária, BufferLength deve ter o valor SQL_IS_POINTER.

• Se *ValuePtr contém um tipo de dado de comprimento fixo, BufferLength é SQL_IS_INTEGER ou SQL_IS_UINTEGER, conforme apropriado.

StringLengthPtr
[Saída] Um ponteiro para um buffer no qual deveria retornar o número total de bytes (excluindo o caractere de terminação nula) disponíveis para retorno em *ValuePtr. Se o valor do atributo for uma string de caracteres e o número de bytes disponíveis para retorno for maior que BufferLength menos o comprimento do caractere de terminação nula, os dados em *ValuePtr são truncados para BufferLength menos o comprimento do caractere de terminação nula e são terminados por null pelo driver.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Quando SQLGetConnectAttr retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido 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 a seguir lista os valores SQLSTATE normalmente retornados pelo SQLGetConnectAttr 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

Para informações gerais sobre atributos de conexã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 retorna uma string, o ValuePtr deve ser um ponteiro para um buffer para a cadeia. O comprimento máximo da string retornada, incluindo o caractere de terminação nula, será bytes BufferLength .

Dependendo do atributo, uma aplicação não precisa estabelecer uma conexão antes de chamar SQLGetConnectAttr. No entanto, se SQLGetConnectAttr for chamado e o atributo especificado não tiver padrão e não tiver sido definido por uma chamada anterior para SQLSetConnectAttr, SQLGetConnectAttr retornará SQL_NO_DATA.

Se o Atributo for SQL_ATTR_ TRACE ou SQL_ATTR_ TRACEFILE, o ConnectionHandle não precisa ser válido, e o SQLGetConnectAttr não retornará SQL_ERROR ou SQL_INVALID_HANDLE se o 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 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ção; ele deve chamar SQLGetStmtAttr para recuperar a configuração dos atributos da instrução.

Tanto os atributos de conexão SQL_ATTR_AUTO_IPD quanto SQL_ATTR_CONNECTION_DEAD podem ser retornados por uma chamada para SQLGetConnectAttr , mas não podem ser definidos por uma chamada para SQLSetConnectAttr.

Funções relacionadas

Conteúdo relacionado

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