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
SQLSetEnvAttr estabelece atributos que governam aspectos dos ambientes.
Sintaxe
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Argumentos
EnvironmentHandle
[Entrada] Controle ambiental.
Atributo
[Entrada] Atributo ao conjunto, listado em "Comentários."
ValuePtr
[Entrada] Apontar para o valor a ser associado ao Atributo. Dependendo do valor de Attribute, ValuePtr será um valor inteiro de 32 bits ou aponta para uma cadeia de caracteres terminada por nulo.
Comprimento da cadeia de caracteres
[Entrada] Se ValuePtr aponta para uma string de caracteres ou um buffer binário, esse argumento deve ser o comprimento de *ValuePtr. Para dados de cadeia de caracteres, esse argumento deve conter o número de bytes na cadeia.
Se ValuePtr for um inteiro, StringLength é ignorado.
Returns
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnostics
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 de EnvironmentHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados pelo SQLSetEnvAttr 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. Se um driver não suportar um atributo de ambiente, o erro só pode ser retornado durante o tempo de conexão.
| SQLSTATE | Erro | Description |
|---|---|---|
| 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 suportava o valor especificado no ValuePtr e substituiu por um valor semelhante. (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. |
| HY009 | Uso inválido de ponteiro nulo | O argumento Atributo identificava um atributo ambiente que exigia um valor de string, e o argumento ValuePtr era um ponteiro nulo. |
| HY010 | Erro de sequência de função | (DM) Um handle de conexão foi alocado no 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 | Cadeia de caracteres ou comprimento de buffer 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 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 atributo do argumento Attribute era um atributo válido do ambiente ODBC para a versão de ODBC suportada pelo driver, mas não era suportado pelo driver. (DM) O argumento do Atributo era SQL_ATTR_OUTPUT_NTS, e o ValuePtr era SQL_FALSE. |
Comments
Uma aplicação pode chamar SQLSetEnvAttr somente se nenhum handle de conexão for alocado no ambiente. Todos os atributos do ambiente definidos com sucesso pela aplicação para o ambiente persistem até que SQLFreeHandle seja chamado no ambiente. Mais de um handle de ambiente pode ser alocado simultaneamente no ODBC 3.x.
O formato da informação definida via ValuePtr depende do Atributo especificado. SQLSetEnvAttr aceitará informações de atributos em dois formatos diferentes: uma cadeia de caracteres terminada por nulo ou um valor inteiro de 32 bits. O formato de cada um é anotado na descrição do atributo.
Não existem atributos específicos do ambiente para o motorista.
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 do ValuePtr |
|---|---|
| SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) | Um valor SQLUINTEGER de 32 bits que permite ou desativa o pooling de conexões no nível do ambiente. Os seguintes valores são usados: SQL_CP_OFF = O pooling de conexão está desligado. Este é o padrão. SQL_CP_ONE_PER_DRIVER = Um único pool de conexão é suportado para cada driver. Cada conexão em um pool está associada a um driver. SQL_CP_ONE_PER_HENV = Um único pool de conexão é suportado para cada ambiente. Cada conexão em um pool está associada a um único ambiente. SQL_CP_DRIVER_AWARE = Use o recurso de conscientização do pool de conexão do driver, se estiver disponível. Se o driver não suportar consciência do pool de conexão, SQL_CP_DRIVER_AWARE é ignorado e SQL_CP_ONE_PER_HENV é usado. Para obter mais informações, confira Pool de conexões com reconhecimento de driver. Em um ambiente onde alguns motoristas suportam e outros não suportam consciência do pool, SQL_CP_DRIVER_AWARE pode ativar o recurso de conscientização do pool-de conexões para os motoristas que suportam, mas isso equivale a configurar para SQL_CP_ONE_PER_HENV para aqueles que não suportam o recurso de conscientização do pool. O pooling de conexão é habilitado chamando SQLSetEnvAttr para definir o atributo SQL_ATTR_CONNECTION_POOLING para 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 handle do ambiente na chamada para SQLSetEnvAttr é definido como null, o que SQL_ATTR_CONNECTION_POOLING torna um atributo em nível de processo. Após a habilitação do pool de conexões, a aplicação aloca um ambiente compartilhado implícito chamando SQLAllocHandle com o argumento InputHandle definido como SQL_HANDLE_ENV. Após o pooling de conexão ser ativado e um ambiente compartilhado selecionado para uma aplicação, SQL_ATTR_CONNECTION_POOLING não pode ser resetado para esse ambiente, pois SQLSetEnvAttr é chamado com um handle de ambiente nulo ao definir esse atributo. Se esse atributo for definido enquanto o pool de conexão já está ativado em um ambiente compartilhado, o atributo afeta apenas ambientes compartilhados que são alocados posteriormente. Também é possível habilitar o pooling de conexões em um ambiente. Note o seguinte sobre o pooling de conexões de ambientes: - Habilitar o pool de conexão em um handle NULL é um atributo em nível de processo. Os ambientes subsequentemente alocados serão um ambiente compartilhado e herdarão a configuração de pooling de conexões em nível de processo. - Após a alocação de um ambiente, uma aplicação ainda pode alterar a configuração do seu pool de conexão. - Se o pool de conexão ambiental estiver ativado e o driver da conexão usar pooling de drivers, o pooling ambiental tem preferência. SQL_ATTR_CONNECTION_POOLING é implementado dentro do Gerenciador de Drivers. Um driver não precisa implementar SQL_ATTR_CONNECTION_POOLING. Aplicações 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ão. Quando SQLConnect ou SQLDriverConnect é chamado, o Gerenciador de Drivers determina qual conexão é reutilizada do pool. O Driver Manager tenta combinar as opções de conexão na chamada e os atributos de conexão definidos pela aplicação com as palavras-chave e atributos de conexão das conexões no pool. O valor desse atributo determina o nível de precisão dos critérios de correspondência. Os seguintes valores são usados para definir o valor desse atributo: SQL_CP_STRICT_MATCH = Apenas conexões que correspondem exatamente às opções de conexão na chamada e aos atributos de conexão definidos pela aplicação são reutilizadas. Este é o padrão. SQL_CP_RELAXED_MATCH = Conexões com cadeia de conexão palavras-chave correspondentes podem ser usadas. As palavras-chave precisam corresponder, mas nem todos os atributos de conexão devem corresponder. Para mais informações sobre como o Driver Manager realiza a correspondência ao conectar a uma conexão em pool, veja SQLConnect. Para obter mais informações sobre o pool de conexões, consulte ODBC Connection Pooling. |
| SQL_ATTR_ODBC_VERSION (ODBC 3.0) | Um inteiro de 32 bits que determina se certa funcionalidade apresenta comportamento ODBC 2.x ou ODBC 3.x . Os seguintes valores são usados para definir o valor desse atributo: SQL_OV_ODBC3_80 = O Gerenciador de Driver e o driver apresentam o seguinte comportamento ODBC 3.8: - O driver retorna e espera códigos ODBC 3.x para data, hora e carimbo temporal. - O driver retorna códigos ODBC 3.x SQLSTATE quando SQLError, SQLGetDiagField ou SQLGetDiagRec é chamado. - O argumento CatalogName em uma chamada para SQLTables aceita um padrão de busca. - O Driver Manager suporta extensibilidade do tipo de dado C. Para mais informações sobre extensibilidade do tipo de dado C, veja Tipos de Dados C no ODBC. Para mais informações, veja O que há de novo no ODBC 3.8. SQL_OV_ODBC3 = O Gerenciador de Driver e o driver apresentam o seguinte comportamento ODBC 3.x : - O driver retorna e espera códigos ODBC 3.x para data, hora e carimbo temporal. - O driver retorna códigos ODBC 3.x SQLSTATE quando SQLError, SQLGetDiagField ou SQLGetDiagRec é chamado. - O argumento CatalogName em uma chamada para SQLTables aceita um padrão de busca. - O Driver Manager não suporta extensibilidade do tipo de dado C. SQL_OV_ODBC2 = O Gerenciador de Drivers e o driver apresentam o seguinte comportamento ODBC 2.x . Isso é especialmente útil para uma aplicação 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 temporal. - O driver retorna códigos ODBC 2.x SQLSTATE quando SQLError, SQLGetDiagField ou SQLGetDiagRec são chamados. - O argumento CatalogName em uma chamada para SQLTables não aceita um padrão de busca. - O Driver Manager não suporta extensibilidade do tipo de dado C. Uma aplicação 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). Depende de cada motorista se existem comportamentos adicionais para esses sinais ambientais. - Para mais informações, veja Declarando a Versão ODBC da Aplicação e Mudanças de Comportamento. |
| SQL_ATTR_OUTPUT_NTS (ODBC 3.0) | Um inteiro de 32 bits que determina como o driver retorna os dados da string. Se SQL_TRUE, o driver retorna dados da string terminados por null. Se SQL_FALSE, o driver não retorna dados de string terminados por null. Esse atributo é o SQL_TRUE por padrão. Uma chamada para SQLSetEnvAttr para configurá-lo como SQL_TRUE retorna SQL_SUCCESS. Uma chamada para SQLSetEnvAttr para configurá-lo para SQL_FALSE retorna SQL_ERROR e SQLSTATE HYC00 (recurso opcional não implementado). |
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Alocação de uma alça | Função SQLAllocHandle |
| Retornar a configuração de um atributo de ambiente | Função SQLGetEnvAttr |