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
SQLSetEnvAttr define atributos que governam aspetos dos ambientes.
Syntax
SQLRETURN SQLSetEnvAttr(
SQLHENV EnvironmentHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Arguments
EnvironmentHandle
[Entrada] Controlo 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.
StringLength
[Entrada] Se o ValuePtr apontar para uma cadeia de caracteres ou um buffer binário, este argumento deve corresponder ao comprimento de *ValuePtr. Para dados de cadeia de caracteres, este argumento deve conter o número de bytes na cadeia.
Se ValuePtr for um inteiro, StringLength é ignorado.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLSetEnvAttr devolve 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 seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLSetEnvAttr 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. Se um driver não suportar um atributo de ambiente, o erro só pode ser devolvido durante o tempo de ligação.
| SQLSTATE | Erro | Description |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica para o condutor. (Função devolve SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Valor da opção alterado | O condutor não suportou o valor especificado no ValuePtr e substituiu-o por um valor semelhante. (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. |
| HY009 | Uso inválido do ponteiro nulo | O argumento Atributo identificava um atributo ambiente que requeria um valor de cadeia, e o argumento ValuePtr era um ponteiro nulo. |
| HY010 | Erro de sequência de funções | (DM) Foi atribuído um handle de ligação no EnvironmentHandle. (DM) SQL_ATTR_ODBC_VERSION não foi definido com SQLSetEnvAttr e Attribute não é igual a SQL_ATTR_ODBC_VERSION. 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. |
| HY024 | Valor de atributo inválido | Dado o valor especificado do Atributo , foi especificado um valor inválido no ValuePtr. |
| HY090 | Comprimento inválido da corda ou do buffer | O argumento StringLength era inferior a 0, mas não era SQL_NTS. |
| HY092 | Identificador de atributo/opção inválido | (DM) 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 não era suportado pelo driver. (DM) O argumento do Atributo foi SQL_ATTR_OUTPUT_NTS, e o ValuePtr foi SQL_FALSE. |
Comments
Uma aplicação só pode chamar SQLSetEnvAttr se não for alocado nenhum handle de ligação no ambiente. Todos os atributos do ambiente definidos com sucesso pela aplicação para o ambiente persistem até que o SQLFreeHandle seja chamado no ambiente. Mais do que um handle de ambiente pode ser alocado simultaneamente no ODBC 3.x.
O formato da informação definida através do ValuePtr depende do Atributo especificado. O SQLSetEnvAttr aceita informação 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 é indicado na descrição do atributo.
Não existem atributos de ambiente específicos para o condutor.
Os atributos de ligação não podem ser definidos por uma chamada ao SQLSetEnvAttr. Ao tentar fazer isto, devolve SQLSTATE HY092 (identificador de atributo/opção inválido).
| Atributo | Conteúdos do ValuePtr |
|---|---|
| SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) | Um valor SQLUINTEGER de 32 bits que permite ou desativa o pooling de ligações ao nível do ambiente. Os seguintes valores são utilizados: SQL_CP_OFF = O pooling de ligações está desligado. Este é o padrão. SQL_CP_ONE_PER_DRIVER = É suportado um único pool de ligação para cada driver. Cada ligação num pool está associada a um driver. SQL_CP_ONE_PER_HENV = É suportado um único pool de ligação para cada ambiente. Cada ligação numa piscina está associada a um único ambiente. SQL_CP_DRIVER_AWARE = Utilizar a funcionalidade de conhecimento do pool de ligação do driver, se estiver disponível. Se o driver não suportar a consciência do pool de ligações, SQL_CP_DRIVER_AWARE é ignorado e SQL_CP_ONE_PER_HENV é utilizado. Para mais informações, consulte Driver-Aware Pooling de Ligações. Num ambiente onde alguns drivers suportam e outros não suportam a consciência do pool-SQL_CP_DRIVER_AWARE de conexão, pode ativar a funcionalidade de consciência do pool-de de ligação nos que suportam os drivers, mas é equivalente a definir para SQL_CP_ONE_PER_HENV nos drivers que não suportam a funcionalidade de awareness-pool. O pooling de ligações é ativado ao chamar SQLSetEnvAttr para definir o atributo SQL_ATTR_CONNECTION_POOLING como SQL_CP_ONE_PER_DRIVER ou SQL_CP_ONE_PER_HENV. Esta chamada deve ser feita antes de a aplicação alocar o ambiente partilhado para o qual o pooling de conexões deve ser ativado. O handle de ambiente na chamada para SQLSetEnvAttr está definido como null, o que SQL_ATTR_CONNECTION_POOLING torna um atributo ao nível do processo. Depois de ativado o pooling de ligações, a aplicação aloca então um ambiente partilhado implícito chamando SQLAllocHandle com o argumento InputHandle definido para SQL_HANDLE_ENV. Depois de o pooling de ligações ter sido ativado e de um ambiente partilhado ter sido selecionado para uma aplicação, SQL_ATTR_CONNECTION_POOLING não pode ser reiniciado para esse ambiente, porque SQLSetEnvAttr é chamado com um handle de ambiente nulo ao definir este atributo. Se este atributo estiver definido enquanto o pool de ligação já está ativado num ambiente partilhado, o atributo afeta apenas ambientes partilhados que são alocados posteriormente. Também é possível permitir o pooling de ligações num ambiente. Note o seguinte sobre o agrupamento de conexões ao ambiente: - Ativar o pool de ligação num handle NULL é um atributo ao nível do processo. Os ambientes subsequentemente atribuídos serão um ambiente partilhado e herdarão a configuração de pooling de ligação ao nível do processo. - Depois de um ambiente ser alocado, uma aplicação ainda pode alterar a definição do seu pool de ligações. - Se o agrupamento de conexões de ambiente estiver ativado e o driver da ligação usar pooling de drivers, o pooling de ambiente tem preferência. SQL_ATTR_CONNECTION_POOLING é implementado dentro do Gestor de Drivers. Um driver não precisa de implementar SQL_ATTR_CONNECTION_POOLING. As aplicações ODBC 2.0 e 3.0 podem definir este atributo do ambiente. Para mais informações, consulte ODBC Connection Pooling. |
| SQL_ATTR_CP_MATCH (ODBC 3.0) | Um valor SQLUINTEGER de 32 bits que determina como uma ligação é escolhida de um pool de ligações. Quando o SQLConnect ou SQLDriverConnect é chamado, o Gestor de Drivers determina qual a ligação que é reutilizada do pool. O Driver Manager tenta associar as opções de ligação na chamada e os atributos de ligação definidos pela aplicação com as palavras-chave e atributos de ligação das ligações no pool. O valor deste atributo determina o nível de precisão dos critérios de correspondência. Os seguintes valores são usados para definir o valor deste atributo: SQL_CP_STRICT_MATCH = Apenas as ligações que correspondem exatamente às opções de ligação na chamada e aos atributos de ligação definidos pela aplicação são reutilizadas. Este é o padrão. SQL_CP_RELAXED_MATCH = Podem ser usadas ligações com cadeia de ligação palavras-chave correspondentes. As palavras-chave têm de coincidir, mas nem todos os atributos de ligação têm de coincidir. Para mais informações sobre como o Gestor de Drivers realiza a correspondência ao ligar-se a uma ligação em pool, consulte SQLConnect. Para mais informações sobre agrupamento de ligações, consulte ODBC Connection Pooling. |
| SQL_ATTR_ODBC_VERSION (ODBC 3.0) | Um inteiro de 32 bits que determina se certas funcionalidades apresentam comportamento ODBC 2.x ou ODBC 3.x . Os seguintes valores são usados para definir o valor deste atributo: SQL_OV_ODBC3_80 = O Gestor de Drivers e o driver exibem o seguinte comportamento ODBC 3.8: - O driver retorna e espera códigos ODBC 3.x para data, hora e carimbo temporal. - O driver devolve códigos ODBC 3.x SQLSTATE quando é chamado SQLError, SQLGetDiagField ou SQLGetDiagRec . - O argumento CatalogName numa chamada a SQLTables aceita um padrão de pesquisa. - O Driver Manager suporta extensibilidade do tipo de dados C. Para mais informações sobre a extensibilidade dos tipos de dados C, veja Tipos de Dados C no ODBC. Para mais informações, consulte O que há de novo no ODBC 3.8. SQL_OV_ODBC3 = O Gestor de Drivers 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 temporal. - O driver devolve códigos ODBC 3.x SQLSTATE quando é chamado SQLError, SQLGetDiagField ou SQLGetDiagRec . - O argumento CatalogName numa chamada a SQLTables aceita um padrão de pesquisa. - O Driver Manager não suporta extensibilidade de tipos de dados C. SQL_OV_ODBC2 = O Gestor de Drivers e o driver apresentam o seguinte comportamento ODBC 2.x . Isto é especialmente útil para uma aplicação ODBC 2.x a trabalhar com um driver ODBC 3.x . - O driver devolve e espera códigos ODBC 2.x para data, hora e carimbo temporal. - O driver devolve códigos ODBC 2.x SQLSTATE quando é chamado SQLError, SQLGetDiagField ou SQLGetDiagRec . - O argumento CatalogName numa chamada para SQLTables não aceita um padrão de pesquisa. - O Driver Manager não suporta extensibilidade de tipos de dados C. Uma aplicação deve definir este atributo de ambiente antes de chamar qualquer função que tenha um argumento SQLHENV, caso contrário a chamada retornará SQLSTATE HY010 (erro de sequência de funções). Depende de cada condutor se existem comportamentos adicionais para estas bandeiras ambientais. - Para mais informações, veja Declarar a Versão ODBC da Aplicação e Alterações Comportamentais. |
| SQL_ATTR_OUTPUT_NTS (ODBC 3.0) | Um inteiro de 32 bits que determina como o driver devolve os dados da cadeia. Se SQL_TRUE, o driver devolve dados de string terminados por null. Se SQL_FALSE, o driver não devolve dados de string terminados por null-terminado. Este atributo é o SQL_TRUE por defeito. Uma chamada ao SQLSetEnvAttr para o definir para SQL_TRUE retorna SQL_SUCCESS. Uma chamada ao SQLSetEnvAttr para o definir para SQL_FALSE retorna SQL_ERROR e SQLSTATE HYC00 (funcionalidade opcional não implementada). |
Funções relacionadas
| Para obter informações sobre | Veja |
|---|---|
| Atribuição de uma alça | Função SQLAllocHandle |
| Devolver a configuração de um atributo de ambiente | Função SQLGetEnvAttr |