Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Conformidade
Versão Introduzida: Normas ODBC 3.0 Conformidade: ISO 92
Summary
SQLGetEnvAttr devolve a definição atual de um atributo do ambiente.
Syntax
SQLRETURN SQLGetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
EnvironmentHandle
[Entrada] Controlo ambiental.
Atributo
[Entrada] Atributo para recuperar.
ValuePtr
[Saída] Apontar para um buffer onde devolver o valor atual do atributo especificado pelo Atributo.
Se o ValuePtr for NULL, o StringLengthPtr continuará a devolver o número total de bytes (excluindo o carácter de terminação nula para dados de caracteres) disponíveis para devolver no buffer apontado pelo ValuePtr.
BufferLength
[Entrada] Se o ValuePtr apontar para uma cadeia de caracteres, este argumento deve ter o comprimento de *ValuePtr. Se *ValuePtr for um inteiro, BufferLength é ignorado. Se *ValuePtr for uma cadeia Unicode (ao chamar SQLGetEnvAttrW), o argumento BufferLength deve ser um número par. Se o valor do atributo não for uma cadeia de caracteres, BufferLength não é utilizado.
StringLengthPtr
[Saída] Um apontador para um buffer onde deves o número total de bytes (excluindo o carácter de terminação nula) disponíveis para devolver em *ValuePtr. Se o valor do atributo for uma cadeia de caracteres e o número de bytes disponíveis para devolver for maior ou igual ao BufferLength, os dados em *ValuePtr são truncados para BufferLength menos o comprimento de um carácter de terminação nula e são terminados por null pelo driver.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando o SQLGetEnvAttr devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, pode ser obtido um valor SQLSTATE associado chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_ENV e um Handle de EnvironmentHandle. A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLGetEnvAttr e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 01004 | Dados de cadeia, truncados à direita | Os dados devolvidos em *ValuePtr foram truncados para ser BufferLength menos o carácter de terminação nula. O comprimento do valor da cadeia não arrunada é devolvido em *StringLengthPtr. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| HY000 | Erro geral | Ocorreu um erro para o qual não existia um SQLSTATE específico e para o qual não estava definido nenhum SQLSTATE específico da implementação. A mensagem de erro devolvida pelo SQLGetDiagRec no buffer *MessageText descreve o erro e a sua causa. |
| HY001 | Erro de alocação de memória | O driver não conseguia alocar a memória necessária para suportar a 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 via SQLSetEnvAttr. Não precisa de definir SQL_ATTR_ODBC_VERSION explicitamente se estiver a usar SQLAllocHandleStd. |
| HY013 | Erro de gestão de memória | A chamada de função não podia ser processada porque os objetos de memória subjacentes não podiam ser acedidos, possivelmente devido a condições de baixa memória. |
| HY092 | Identificador de atributo/opção inválido | O valor especificado para o argumento Atributo não era válido para a versão de ODBC suportada pelo driver. |
| HY117 | A ligação é suspensa devido ao estado desconhecido da transação. Apenas funções de desconexão e de leitura são permitidas. | (DM) Para mais informações sobre o estado suspenso, veja Função SQLEndTran. |
| HYC00 | Funcionalidade opcional não implementada | O valor especificado para o atributo do argumento Attribute 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 a função. |
Comments
Para uma lista de atributos, veja SQLSetEnvAttr. Não existem atributos de ambiente específicos para o condutor. Se o Atributo especificar um atributo que devolve uma cadeia, o ValuePtr deve ser um ponteiro para um buffer onde devolver a cadeia. O comprimento máximo da string, incluindo o byte de terminação nula, será bytes BufferLength .
O SQLGetEnvAttr pode ser chamado a qualquer momento entre a alocação e a libertaçã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 do que um handle de ambiente pode ser alocado simultaneamente em ODBC 3*.x*. Um atributo de ambiente num ambiente não é afetado quando outro ambiente foi alocado.
Note
O atributo ambiente SQL_ATTR_OUTPUT_NTS é suportado por aplicações compatíveis com normas. Quando o SQLGetEnvAttr é chamado, o Gestor de Drivers ODBC 3*.x* devolve sempre SQL_TRUE para este atributo. SQL_ATTR_OUTPUT_NTS só pode ser definido para SQL_TRUE através de uma chamada ao SQLSetEnvAttr.
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Devolver a definição de um atributo de conexão | Função SQLGetConnectAttr |
| Devolver a definição de um atributo de instrução | Função SQLGetStmtAttr |
| Definir um atributo de ligação | Função SQLSetConnectAttr |
| Definir um atributo ambiente | Função SQLSetEnvAttr |
| Definir um atributo de instrução | Função SQLSetStmtAttr |