Compartilhar via


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.

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

Consulte Também

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