Função SQLGetEnvAttr
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.
Funções relacionadas
| 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 |