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.

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.

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.

Funções relacionadas

Consulte Também

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