Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Conformidade com as Normas ODBC 3.0: ISO 92
Summary
SQLGetEnvAttr retorna a configuração atual de um atributo do ambiente.
Sintaxe
SQLRETURN SQLGetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Argumentos
EnvironmentHandle
[Entrada] Controle ambiental.
Atributo
[Entrada] Atributo para recuperar.
ValuePtr
[Saída] Apontar para um buffer no qual devolver 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 caracteres) disponíveis para retorno no buffer apontado pelo ValuePtr.
BufferLength
[Entrada] Se ValuePtr apontar para uma cadeia de caracteres, esse argumento deve ter o comprimento de *ValuePtr. Se *ValuePtr for um inteiro, BufferLength é ignorado. Se *ValuePtr for uma string Unicode (ao chamar SQLGetEnvAttrW), o argumento BufferLength deve ser um número par. Se o valor do atributo não for uma string de caracteres, BufferLength não é utilizado.
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 retornar for maior ou igual ao BufferLength, os dados em *ValuePtr são truncados para BufferLength menos o comprimento de um 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 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 Handle de EnvironmentHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados pelo SQLGetEnvAttr 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.
| SQLSTATE | Erro | Description |
|---|---|---|
| 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 ser BufferLength menos o caractere de terminação nula. O comprimento do valor da string não arrunada é retornado em *StringLengthPtr. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia 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ção | (DM) SQL_ATTR_ODBC_VERSION ainda não foi definido via 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 atributo do argumento não era válido para a versão do ODBC suportada pelo driver. |
| HY117 | A conexão está suspensa devido ao estado desconhecido da transação. 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 Atributo era um atributo válido do ambiente ODBC para a versão de ODBC suportada pelo driver, mas que não era suportada pelo driver. |
| IM001 | O driver não suporta esta função | (DM) O driver correspondente ao EnvironmentHandle não suporta essa função. |
Comments
Para uma lista de atributos, veja SQLSetEnvAttr. Não existem atributos específicos do ambiente para o motorista. Se o Atributo especificar um atributo que retorna uma string, o ValuePtr deve ser um ponteiro para um buffer no qual a string deve ser retornada. O comprimento máximo da string, incluindo o byte de terminação nula, será bytes BufferLength .
SQLGetEnvAttr pode ser chamado a qualquer momento entre a alocação e a liberação de um handle de ambiente. Todos os atributos do ambiente definidos com sucesso pela aplicação para o ambiente persistem até que SQLFreeHandle seja chamado no EnvironmentHandle com um HandleType de SQL_HANDLE_ENV. Mais de um handle de ambiente pode ser alocado simultaneamente em ODBC 3*.x*. Um atributo de ambiente em um ambiente não é afetado quando outro ambiente foi alocado.
Note
O atributo SQL_ATTR_OUTPUT_NTS ambiente é suportado por aplicações que compatem padrões. Quando SQLGetEnvAttr é chamado, o Gerenciador de Drivers ODBC 3*.x* sempre retorna SQL_TRUE para esse atributo. SQL_ATTR_OUTPUT_NTS só pode ser definido para SQL_TRUE por meio de uma chamada para SQLSetEnvAttr.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| 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 ambiente | Função SQLSetEnvAttr |
| Configurando um atributo de instrução | Função SQLSetStmtAttr |