Função SQLSetEnvAttr

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

Resumo
SQLSetEnvAttr define atributos que regem aspectos de ambientes.

Sintaxe

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);  

Argumentos

EnvironmentHandle
[Entrada] Identificador de ambiente.

Atributo
[Entrada] Atributo a ser definido, listado em "Comentários".

ValuePtr
[Entrada] Ponteiro para o valor a ser associado ao Atributo. Dependendo do valor de Attribute, ValuePtr será um valor inteiro de 32 bits ou apontará para uma cadeia de caracteres terminada em nulo.

Stringlength
[Entrada] Se ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, esse argumento deverá ter o comprimento de *ValuePtr. Para dados de cadeia de caracteres, esse argumento deve conter o número de bytes na cadeia de caracteres.

Se ValuePtr for um inteiro, StringLength será ignorado.

Retornos

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando SQLSetEnvAttr 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 of EnvironmentHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLSetEnvAttr 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. Se um driver não der suporte a um atributo de ambiente, o erro poderá ser retornado somente durante o tempo de conexão.

SQLSTATE	Erro	Descrição
01000	Aviso geral	Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.)
01S02	Valor da opção alterado	O driver não deu suporte ao valor especificado em ValuePtr e substituiu um valor semelhante. (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.
HY009	Uso inválido de ponteiro nulo	O argumento Attribute identificou um atributo de ambiente que exigia um valor de cadeia de caracteres e o argumento ValuePtr era um ponteiro nulo.
HY010	Erro de sequência de funções	(DM) Um identificador de conexão foi alocado em EnvironmentHandle. (DM) SQL_ATTR_ODBC_VERSION não foi definido com SQLSetEnvAttr e Attribute não é igual a SQL_ATTR_ODBC_VERSION. 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.
HY024	Valor de atributo inválido	Dado o valor de Atributo especificado, um valor inválido foi especificado em ValuePtr.
HY090	Comprimento de buffer ou cadeia de caracteres inválido	O argumento StringLength era menor que 0, mas não era SQL_NTS.
HY092	Identificador de atributo/opção inválido	(DM) 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. (DM) O argumento Attribute foi SQL_ATTR_OUTPUT_NTS e ValuePtr foi SQL_FALSE.

Comentários

Um aplicativo só poderá chamar SQLSetEnvAttr se nenhum identificador de conexão for alocado no ambiente. Todos os atributos de ambiente definidos com êxito pelo aplicativo para o ambiente persistem até que SQLFreeHandle seja chamado no ambiente. Mais de um identificador de ambiente pode ser alocado simultaneamente no ODBC 3.x.

O formato das informações definidas por meio de ValuePtr depende do Atributo especificado. SQLSetEnvAttr aceitará informações de atributo em um dos dois formatos diferentes: uma cadeia de caracteres terminada em nulo ou um valor inteiro de 32 bits. O formato de cada um é indicado na descrição do atributo.

Não há atributos de ambiente específicos do driver.

Os atributos de conexão não podem ser definidos por uma chamada para SQLSetEnvAttr. Tentar fazer isso retornará SQLSTATE HY092 (identificador de atributo/opção inválido).

Atributo	Conteúdo de ValuePtr
SQL_ATTR_CONNECTION_POOLING (ODBC 3.8)	Um valor SQLUINTEGER de 32 bits que habilita ou desabilita o pool de conexões no nível do ambiente. Os seguintes valores são usados: SQL_CP_OFF = O pool de conexões está desativado. Esse é o padrão. SQL_CP_ONE_PER_DRIVER = Há suporte para um único pool de conexões para cada driver. Cada conexão em um pool está associada a um driver. SQL_CP_ONE_PER_HENV = Há suporte para um único pool de conexões para cada ambiente. Cada conexão em um pool está associada a um ambiente. SQL_CP_DRIVER_AWARE = Use o recurso de reconhecimento do pool de conexões do driver, se ele estiver disponível. Se o driver não der suporte à conscientização do pool de conexões, SQL_CP_DRIVER_AWARE será ignorado e SQL_CP_ONE_PER_HENV será usado. Para obter mais informações, consulte Pooling de conexões com reconhecimento de driver. Em um ambiente em que alguns drivers dão suporte e alguns drivers não dão suporte à conscientização do pool de conexões, SQL_CP_DRIVER_AWARE pode habilitar o recurso de reconhecimento do pool de conexões nesses drivers de suporte, mas é equivalente a configurar para SQL_CP_ONE_PER_HENV nesses drivers que não dão suporte ao recurso de conscientização do pool de conexões. O pool de conexões é habilitado chamando SQLSetEnvAttr para definir o atributo SQL_ATTR_CONNECTION_POOLING como SQL_CP_ONE_PER_DRIVER ou SQL_CP_ONE_PER_HENV. Essa chamada deve ser feita antes que o aplicativo aloque o ambiente compartilhado para o qual o pool de conexões deve ser habilitado. O identificador de ambiente na chamada para SQLSetEnvAttr é definido como nulo, o que torna SQL_ATTR_CONNECTION_POOLING um atributo no nível do processo. Depois que o pool de conexões é habilitado, o aplicativo aloca um ambiente compartilhado implícito chamando SQLAllocHandle com o argumento InputHandle definido como SQL_HANDLE_ENV. Depois que o pool de conexões tiver sido habilitado e um ambiente compartilhado tiver sido selecionado para um aplicativo, SQL_ATTR_CONNECTION_POOLING não poderá ser redefinido para esse ambiente, pois SQLSetEnvAttr é chamado com um identificador de ambiente nulo ao definir esse atributo. Se esse atributo for definido enquanto o pool de conexões já estiver habilitado em um ambiente compartilhado, o atributo afetará apenas ambientes compartilhados alocados posteriormente. Também é possível habilitar o pool de conexões em um ambiente. Observe o seguinte sobre o pool de conexões de ambiente: – Habilitar o pool de conexões em um identificador NULL é um atributo no nível do processo. Os ambientes alocados posteriormente serão um ambiente compartilhado e herdarão a configuração de pooling de conexões no nível do processo. – Depois que um ambiente é alocado, um aplicativo ainda pode alterar a configuração do pool de conexões. – Se o pool de conexões de ambiente estiver habilitado e o driver da conexão usar o pool de driver, o pool de ambientes será preferencial. SQL_ATTR_CONNECTION_POOLING é implementado dentro do Gerenciador de Driver. Um driver não precisa implementar SQL_ATTR_CONNECTION_POOLING. Os aplicativos ODBC 2.0 e 3.0 podem definir esse atributo de ambiente. Para obter mais informações, consulte ODBC Connection Pooling.
SQL_ATTR_CP_MATCH (ODBC 3.0)	Um valor SQLUINTEGER de 32 bits que determina como uma conexão é escolhida de um pool de conexões. Quando SQLConnect ou SQLDriverConnect é chamado, o Gerenciador de Driver determina qual conexão é reutilizado do pool. O Gerenciador de Driver tenta corresponder as opções de conexão na chamada e os atributos de conexão definidos pelo aplicativo com as palavras-chave e os atributos de conexão das conexões no pool. O valor desse atributo determina o nível de precisão dos critérios correspondentes. Os seguintes valores são usados para definir o valor desse atributo: SQL_CP_STRICT_MATCH = Somente as conexões que correspondem exatamente às opções de conexão na chamada e os atributos de conexão definidos pelo aplicativo são reutilizados. Esse é o padrão. SQL_CP_RELAXED_MATCH = Conexões com palavras-chave de cadeia de conexão correspondentes podem ser usadas. As palavras-chave devem corresponder, mas nem todos os atributos de conexão devem corresponder. Para obter mais informações sobre como o Gerenciador de Driver executa a correspondência na conexão com uma conexão em pool, consulte SQLConnect. Para obter mais informações sobre o pool de conexões, consulte Pooling de Conexões ODBC.
SQL_ATTR_ODBC_VERSION (ODBC 3.0)	Um inteiro de 32 bits que determina se determinadas funcionalidades exibem o comportamento do ODBC 2.x ou o comportamento do ODBC 3.x . Os seguintes valores são usados para definir o valor desse atributo: SQL_OV_ODBC3_80 = O Driver Manager e o driver exibem o seguinte comportamento do ODBC 3.8: – O driver retorna e espera códigos ODBC 3.x para data, hora e carimbo de data/hora. – O driver retorna códigos SQLSTATE ODBC 3.x quando SQLError, SQLGetDiagField ou SQLGetDiagRec é chamado. – O argumento CatalogName em uma chamada para SQLTables aceita um padrão de pesquisa. – O Gerenciador de Driver dá suporte à extensibilidade de tipo de dados C. Para obter mais informações sobre extensibilidade de tipo de dados C, consulte Tipos de dados C no ODBC. Para obter mais informações, consulte Novidades no ODBC 3.8. SQL_OV_ODBC3 = O Driver Manager e o driver exibem o seguinte comportamento ODBC 3.x : – O driver retorna e espera códigos ODBC 3.x para data, hora e carimbo de data/hora. – O driver retorna códigos SQLSTATE ODBC 3.x quando SQLError, SQLGetDiagField ou SQLGetDiagRec é chamado. – O argumento CatalogName em uma chamada para SQLTables aceita um padrão de pesquisa. – O Gerenciador de Driver não dá suporte à extensibilidade de tipo de dados C. SQL_OV_ODBC2 = O Driver Manager e o driver exibem o comportamento ODBC 2.x a seguir . Isso é especialmente útil para um aplicativo ODBC 2.x que trabalha com um driver ODBC 3.x . – O driver retorna e espera códigos ODBC 2.x para data, hora e carimbo de data/hora. – O driver retorna códigos SQLSTATE ODBC 2.x quando SQLError, SQLGetDiagField ou SQLGetDiagRec é chamado. – O argumento CatalogName em uma chamada para SQLTables não aceita um padrão de pesquisa. – O Gerenciador de Driver não dá suporte à extensibilidade de tipo de dados C. Um aplicativo deve definir esse atributo de ambiente antes de chamar qualquer função que tenha um argumento SQLHENV ou a chamada retornará SQLSTATE HY010 (erro de sequência de funções). É específico do driver se existe um comportamento adicional para esses sinalizadores ambientais. – Para obter mais informações, consulte Declarando a versão ODBC do aplicativo e alterações comportamentais.
SQL_ATTR_OUTPUT_NTS (ODBC 3.0)	Um inteiro de 32 bits que determina como o driver retorna dados de cadeia de caracteres. Se SQL_TRUE, o driver retornará dados de cadeia de caracteres encerrados em nulo. Se SQL_FALSE, o driver não retornará dados de cadeia de caracteres encerrados em nulo. Esse atributo usa como padrão SQL_TRUE. Uma chamada para SQLSetEnvAttr para defini-la como SQL_TRUE retorna SQL_SUCCESS. Uma chamada para SQLSetEnvAttr para defini-lo como SQL_FALSE retorna SQL_ERROR e SQLSTATE HYC00 (recurso opcional não implementado).

Funções relacionadas

Para obter informações sobre	Consulte
Alocando um identificador	Função SQLAllocHandle
Retornando a configuração de um atributo de ambiente	Função SQLGetEnvAttr

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC
Novidades no ODBC 3.8