Função SQLGetEnvAttr

  • Artigo

Conformidade
Versão introduzida: Conformidade de padrões do ODBC 3.0: ISO 92

Resumo
SQLGetEnvAttr retorna a configuração atual de um atributo de ambiente.

Sintaxe

  
SQLRETURN SQLGetEnvAttr(  
     SQLHENV        EnvironmentHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);

Argumentos

EnvironmentHandle
[Entrada] Identificador de ambiente.

Atributo
[Entrada] Atributo a ser recuperado.

ValuePtr
[Saída] Ponteiro para um buffer no qual retornar o valor atual do atributo especificado por Attribute.

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 ValuePtr apontar para uma cadeia de caracteres, esse argumento deverá ter o comprimento de *ValuePtr. Se *ValuePtr for um inteiro, BufferLength será ignorado. Se *ValuePtr for uma cadeia de caracteres Unicode (ao chamar SQLGetEnvAttrW), o argumento BufferLength deverá ser um número par. Se o valor do atributo não for uma cadeia de caracteres, BufferLength não será utilizado.

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 ou igual a BufferLength, os dados em *ValuePtr serão truncados para BufferLength menos o comprimento de um 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 SQLGetEnvAttr retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_ENV e um Identificador de EnvironmentHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLGetEnvAttr 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 o contrário.

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 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.)
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 por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa.
HY001 Erro de alocação de memória O driver não pôde alocar a memória necessária para dar suporte à execução ou à conclusão da função.
HY010 Erro de sequência de funções (DM) SQL_ATTR_ODBC_VERSION ainda não foi definido por meio de SQLSetEnvAttr. Você não precisa definir SQL_ATTR_ODBC_VERSION explicitamente se estiver usando SQLAllocHandleStd.
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.
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.
HY117 A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar 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 ambiente ODBC válido para a versão do ODBC compatível com o driver, mas não era compatível com o driver.
IM001 O driver não dá suporte a essa função (DM) O driver correspondente ao EnvironmentHandle não dá suporte à função .

Comentários

Para obter uma lista de atributos, consulte SQLSetEnvAttr. Não há atributos de ambiente específicos do driver. Se Attribute especificar um atributo que retorna uma cadeia de caracteres, ValuePtr deverá ser um ponteiro para um buffer no qual retornar a cadeia de caracteres. O comprimento máximo da cadeia de caracteres, incluindo o byte de terminação nula, será BufferLength bytes.

SQLGetEnvAttr pode ser chamado a qualquer momento entre a alocação e a liberação de um identificador de ambiente. Todos os atributos de ambiente definidos com êxito pelo aplicativo para o ambiente persistem até que SQLFreeHandle seja chamado no EnvironmentHandle com um HandleType de SQL_HANDLE_ENV. Mais de um identificador de ambiente pode ser alocado simultaneamente no ODBC 3*.x*. Um atributo de ambiente em um ambiente não é afetado quando outro ambiente é alocado.

Observação

O atributo de ambiente SQL_ATTR_OUTPUT_NTS é compatível com aplicativos compatíveis com padrões. Quando SQLGetEnvAttr é chamado, o Gerenciador de Driver ODBC 3*.x* sempre retorna SQL_TRUE para esse atributo. SQL_ATTR_OUTPUT_NTS pode ser definido como SQL_TRUE somente por uma chamada para SQLSetEnvAttr.

Para obter informações sobre Consulte
Retornando a configuração de um atributo de conexão Função SQLGetConnectAttr
Retornando a configuração de um atributo de instrução Função SQLGetStmtAttr
Definindo um atributo de conexão Função SQLSetConnectAttr
Definindo um atributo de ambiente Função SQLSetEnvAttr
Definindo um atributo de instrução Função SQLSetStmtAttr

Consulte Também

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