Função SQLAllocHandle

Conformidade
Versão Introduzida: Normas ODBC 3.0 Conformidade: ISO 92

Summary
O SQLAllocHandle aloca um handler de ambiente, ligação, instrução ou descriptor.

Syntax

  
SQLRETURN SQLAllocHandle(  
      SQLSMALLINT   HandleType,  
      SQLHANDLE     InputHandle,  
      SQLHANDLE *   OutputHandlePtr);  

Arguments

HandleType
[Entrada] O tipo de handle a ser atribuído pelo SQLAllocHandle. Deve ser um dos seguintes valores:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN alça é usada apenas pelo Gerenciador de Driver e pelo driver. Os aplicativos não devem usar esse tipo de identificador. Para mais informações sobre SQL_HANDLE_DBC_INFO_TOKEN, consulte Desenvolvimento da Consciência Connection-Pool num Condutor ODBC.

InputHandle
[Entrada] A alavanca de entrada em cujo contexto a nova alça deve ser alocada. Se o HandleType for SQL_HANDLE_ENV, isto é SQL_NULL_HANDLE. Se o HandleType for SQL_HANDLE_DBC, este deve ser um handle de ambiente, e se for SQL_HANDLE_STMT ou SQL_HANDLE_DESC, deve ser um handle de conexão.

OutputHandlePtr
[Saída] Apontador para um buffer onde devolver o handle à nova estrutura de dados atribuída.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE ou SQL_ERROR.

Ao alocar um handle diferente do de ambiente, se o SQLAllocHandle devolver SQL_ERROR, define o OutputHandlePtr para SQL_NULL_HDBC, SQL_NULL_HSTMT ou SQL_NULL_HDESC, dependendo do valor de HandleType, a menos que o argumento de saída seja um ponteiro nulo. A aplicação pode então obter informações adicionais a partir da estrutura de dados de diagnóstico associada ao handle no argumento InputHandle .

Erros de Alocação no Handle do Ambiente

A alocação de ambientes ocorre tanto dentro do Gestor de Drivers como em cada driver. O erro devolvido pelo SQLAllocHandle com um HandleType de SQL_HANDLE_ENV depende do nível em que o erro ocorreu.

Se o Gestor de Drivers não conseguir alocar memória para *OutputHandlePtr quando é chamado SQLAllocHandle com um HandleType de SQL_HANDLE_ENV, ou se a aplicação fornecer um ponteiro nulo para OutputHandlePtr, SQLAllocHandle devolve SQL_ERROR. O Gestor de Drivers define *OutputHandlePtr para SQL_NULL_HENV (a menos que a aplicação forneça um ponteiro nulo, que devolve SQL_ERROR). Não existe um handle com o qual associar informações diagnósticas adicionais.

O Gestor de Drivers não chama a função de alocação do controlador ao nível do ambiente até que a aplicação chame SQLConnect, SQLBrowseConnect ou SQLDriverConnect. Se ocorrer um erro na função SQLAllocHandle ao nível do driver, então a função SQLConnect, SQLBrowseConnect ou SQLDriverConnect ao nível do Driver Manager devolve SQL_ERROR. A estrutura de dados de diagnóstico contém SQLSTATE IM004 (Driver SQLAllocHandle falhou). O erro é devolvido numa alavanca de ligação.

Para mais informações sobre o fluxo de chamadas de função entre o Gestor de Drivers e um driver, consulte Função SQLConnect.

Diagnósticos

Quando o SQLAllocHandle devolve SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com o HandleType e Handle apropriados definidos para o valor de InputHandle. SQL_SUCCESS_WITH_INFO (mas não SQL_ERROR) podem ser devolvidos para o argumento OutputHand . A tabela seguinte lista os valores SQLSTATE normalmente devolvidos pelo SQLAllocHandle 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.

Comments

O SQLAllocHandle é usado para alocar alças para ambientes, ligações, instruções e descritores, conforme descrito nas secções seguintes. Para informações gerais sobre alças, consulte Alças.

Mais do que um ambiente, ligação ou handle de instruções podem ser alocados por uma aplicação ao mesmo tempo se o driver suportar múltiplas alocações. No ODBC, não é definido nenhum limite para o número de handles de ambiente, ligação, instrução ou descriptor que podem ser alocados em qualquer momento. Os maquinistas podem impor um limite ao número de um determinado tipo de alvo que pode ser atribuído de cada vez; Para mais informações, consulte a documentação do condutor.

Se a aplicação chamar SQLAllocHandle com *OutputHandlePtr definido para um ambiente, ligação, instrução ou handle de descritor que já existe, o driver sobreescreve a informação associada ao handle, a menos que a aplicação esteja a usar pooling de ligações (ver "Alalocar um Atributo de Ambiente para Pool de Conexões" mais adiante nesta secção). O Gestor de Drivers não verifica se o handle inserido em *OutputHandlePtr já está a ser usado, nem verifica o conteúdo anterior de um handle antes de os sobrescrever.

Em sistemas operativos que suportam múltiplas threads, as aplicações podem usar o mesmo ambiente, ligação, instrução ou handler de descritor em diferentes threads. Os drivers devem, portanto, suportar acesso seguro e multithread a esta informação; Uma forma de conseguir isto, por exemplo, é usando uma secção crítica ou um semáforo. Para mais informações sobre threading, consulte Multithreading.

O SQLAllocHandle não define o atributo de ambiente SQL_ATTR_ODBC_VERSION quando é chamado para alocar um handle de ambiente; o atributo ambiente deve ser definido pela aplicação, ou o SQLSTATE HY010 (Function sequence error) será devolvido quando o SQLAllocHandle for chamado para alocar um handle de ligação.

Para aplicações compatíveis com normas, SQLAllocHandle é mapeado para SQLAllocHandleStd em tempo de compilação. A diferença entre estas duas funções é que o SQLAllocHandleStd define o atributo SQL_ATTR_ODBC_VERSION ambiente para SQL_OV_ODBC3 quando é chamado, com o argumento HandleType definido para SQL_HANDLE_ENV. Isto acontece porque as aplicações compatíveis com normas são sempre ODBC 3. x aplicações. Além disso, as normas não exigem que a versão da aplicação seja registada. Esta é a única diferença entre estas duas funções; caso contrário, são idênticos. SQLAllocHandleStd é mapeado para SQLAllocHandle dentro do gestor de drivers. Portanto, os drivers de terceiros não têm de implementar SQLAllocHandleStd.

As aplicações ODBC 3.8 devem utilizar:

• SQLAllocHandle e não SQLAllocHandleStd para alocar um handle de ambiente.

• SQLSetEnvAttr para definir o atributo SQL_ATTR_ODBC_VERSION ambiente para SQL_OV_ODBC3_80.

Alocação de um identificador de ambiente

Um handle de ambiente fornece acesso a informação global, como handles de ligação válidos e handles de ligação ativos. Para informações gerais sobre handles de ambiente, consulte Handle de Ambiente.

Para solicitar um handle de ambiente, uma aplicação chama SQLAllocHandle com um HandleType de SQL_HANDLE_ENV e um InputHandle de SQL_NULL_HANDLE. O driver aloca memória para a informação do ambiente e passa o valor do handle associado de volta ao argumento *OutputHandlePtr . A aplicação passa o valor *OutputHandle em todas as chamadas subsequentes que requerem um argumento de handle de ambiente. Para mais informações, consulte Alocação do Controlador de Ambiente.

No handle de ambiente de um Gestor de Drivers, se já existir um handle de ambiente do driver, então SQLAllocHandle com um HandleType de SQL_HANDLE_ENV não é chamado nesse driver quando uma ligação é feita, apenas SQLAllocHandle com um HandleType de SQL_HANDLE_DBC. Se o handle do ambiente de um driver não existir sob o handle do Driver Manager, tanto o SQLAllocHandle com um HandleType de SQL_HANDLE_ENV como o SQLAllocHandle com um HandleType de SQL_HANDLE_DBC são chamados no driver quando o primeiro handle de ligação do ambiente é ligado ao driver.

Quando o Gestor de Drivers processa a função SQLAllocHandle com um HandleType de SQL_HANDLE_ENV, verifica a palavra-chave Trace na secção [ODBC] da informação do sistema. Se estiver definido para 1, o Gestor de Drivers ativa o rastreio para a aplicação atual. Se o flag de traço estiver definido, o traçado começa quando o primeiro handle de ambiente é atribuído e termina quando o último handle de ambiente é libertado. Para mais informações, consulte Configurar Fontes de Dados.

Após alocar um handle de ambiente, uma aplicação deve chamar SQLSetEnvAttr no handle de ambiente para definir o atributo de ambiente SQL_ATTR_ODBC_VERSION. Se este atributo não for definido antes de o SQLAllocHandle ser chamado para alocar um handle de ligação no ambiente, a chamada para alocar a ligação devolverá SQLSTATE HY010 (erro de sequência de funções). Para mais informações, consulte Declarar a Versão ODBC da Aplicação.

Alocação de Ambientes Partilhados para Pooling de Ligações

Os ambientes podem ser partilhados entre múltiplos componentes num único processo. Um ambiente partilhado pode ser utilizado por mais do que um componente ao mesmo tempo. Quando um componente utiliza um ambiente partilhado, pode usar ligações em pool, que lhe permitem alocar e usar uma ligação existente sem ter de a recriar.

Antes de alocar um ambiente partilhado que possa ser usado para pooling de ligações, uma aplicação deve chamar SQLSetEnvAttr para definir o atributo do ambiente SQL_ATTR_CONNECTION_POOLING como SQL_CP_ONE_PER_DRIVER ou SQL_CP_ONE_PER_HENV. SQLSetEnvAttr , neste caso, é chamado com EnvironmentHandle definido como null, o que torna o atributo um atributo ao nível do processo.

Depois de o pooling de conexões estar ativado, uma aplicação chama SQLAllocHandle com o argumento HandleType definido para SQL_HANDLE_ENV. O ambiente alocado por esta chamada será um ambiente partilhado implícito devido à ativação do pool de conexões.

Quando um ambiente partilhado é alocado, o ambiente que será utilizado não é determinado até que o SQLAllocHandle com um HandleType de SQL_HANDLE_DBC seja chamado. Nesse ponto, o Gestor de Drivers tenta encontrar um ambiente existente que corresponda aos atributos de ambiente solicitados pela aplicação. Se tal ambiente não existir, um é criado como um ambiente partilhado. O Driver Manager mantém uma contagem de referências para cada ambiente partilhado; a contagem é definida para 1 quando o ambiente é criado pela primeira vez. Se for encontrado um ambiente correspondente, o handle desse ambiente é devolvido à aplicação e a contagem de referências é incrementada. Um handle de ambiente alocado desta forma pode ser usado em qualquer função ODBC que aceite um handle de ambiente como argumento de entrada.

Alocando um identificador de conexão

Um handle de ligação fornece acesso a informações como as instruções válidas e os handles de descriptor sobre a ligação e se uma transação está atualmente aberta. Para informações gerais sobre alavancas de ligação, veja Alavancas de Ligação.

Para solicitar um handle de ligação, uma aplicação chama SQLAllocHandle com um HandleType de SQL_HANDLE_DBC. O argumento InputHandle é definido para o handle do ambiente que foi devolvido pela chamada ao SQLAllocHandle que alocou esse handle. O driver aloca memória para a informação de ligação e passa o valor do handle associado de volta em *OutputHandlePtr. A aplicação passa o valor *OutputHandlePtr em todas as chamadas subsequentes que requerem um handle de ligação. Para mais informações, consulte Alocar um Handle de Ligação.

O Gestor de Drivers processa a função SQLAllocHandle e chama a função SQLAllocHandle do driver quando a aplicação chama SQLConnect, SQLBrowseConnect ou SQLDriverConnect. (Para mais informações, veja Função SQLConnect.)

Se o atributo SQL_ATTR_ODBC_VERSION ambiente não estiver definido antes de ser chamado SQLAllocHandle para alocar um handle de ligação no ambiente, a chamada para alocar a ligação devolverá SQLSTATE HY010 (erro de sequência de funções).

Quando uma aplicação chama SQLAllocHandle com o argumento InputHandle definido para SQL_HANDLE_DBC e também para um handle de ambiente partilhado, o Driver Manager tenta encontrar um ambiente partilhado existente que corresponda aos atributos do ambiente definidos pela aplicação. Se tal ambiente não existir, é criado um, com uma contagem de referências (mantida pelo Gestor de Drivers) de 1. Se for encontrado um ambiente partilhado correspondente, esse handle é devolvido à aplicação e o seu número de referências é incrementado.

A ligação real que será usada não é determinada pelo Gestor de Drivers até que o SQLConnect ou SQLDriverConnect seja chamado. O Gestor de Drivers utiliza as opções de ligação na chamada para SQLConnect (ou as palavras-chave de ligação na chamada para SQLDriverConnect) e os atributos de ligação definidos após a alocação de ligação para determinar qual a ligação do pool que deve ser usada. Para mais informações, consulte Função SQLConnect.

Alocando um identificador de declaração

Um handle de instrução fornece acesso à informação da instrução, como mensagens de erro, o nome do cursor e informações de estado para o processamento de instruções SQL. Para informações gerais sobre handles de instruções, veja Handles de Statement.

Para solicitar um handle de instruções, uma aplicação liga-se a uma fonte de dados e depois chama o SQLAllocHandle antes de submeter instruções SQL. Nesta chamada, o HandleType deve ser definido para SQL_HANDLE_STMT e o InputHandle deve ser definido para o handle de ligação que foi devolvido pela chamada ao SQLAllocHandle que alocou esse handle. O driver aloca memória para a informação da instrução, associa o handle da instrução à ligação especificada e passa o valor do handle associado de volta em *OutputHandlePtr. A aplicação passa o valor *OutputHandlePtr em todas as chamadas subsequentes que requerem um handle de instrução. Para mais informações, consulte Alocar um Identificador de Instrução.

Quando o handle da instrução é atribuído, o driver aloca automaticamente um conjunto de quatro descritores e atribui os handles desses descritores aos atributos da instrução SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC e SQL_ATTR_IMP_PARAM_DESC. Estes são referidos como descritores alocados implicitamente . Para alocar explicitamente um descritor de aplicação, veja a secção seguinte, "Alocar um Identificador de Descriptor."

Atribuição de um Handle de Descriptor

Quando uma aplicação chama SQLAllocHandle com um HandleType de SQL_HANDLE_DESC, o controlador aloca um descritor de aplicação. Estes são referidos como descritores explicitamente alocados. A aplicação orienta um driver a usar um descritor de aplicação explicitamente alocado em vez de um automaticamente alocado para um determinado handle de instrução, chamando a função SQLSetStmtAttr com o atributo SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC. Um descritor de implementação não pode ser alocado explicitamente, nem pode ser especificado numa chamada de função SQLSetStmtAttr .

Os descritores explicitamente alocados estão associados a um handle de ligação em vez de um handle de instrução (como os descritores automaticamente alocados). Os descritores permanecem alocados apenas quando uma aplicação está efetivamente ligada à base de dados. Como os descritores explicitamente alocados estão associados a um handle de conexão, uma aplicação pode associar um descritor explicitamente alocado a mais do que uma instrução dentro de uma ligação. Um descritor de aplicação implicitamente atribuído, por outro lado, não pode ser associado a mais do que um handle de instrução. (Não pode ser associado a nenhum handle de instrução que não aquele para o qual foi atribuído.) Handles de descriptor explicitamente alocados podem ser libertados explicitamente pela aplicação ou chamando SQLFreeHandle com um HandleType de SQL_HANDLE_DESC, ou implicitamente quando a ligação está encerrada.

Quando o descritor explicitamente alocado é libertado, o descritor implicitamente alocado é novamente associado à afirmação. (O atributo SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC dessa afirmação é novamente definido para o handler do descritor implicitamente atribuído.) Isto é verdade para todas as instruções associadas ao descritor explicitamente alocado na ligação.

Para mais informações sobre descritores, veja Descritores.

Exemplo de código

Consulte Programa ODBC de exemplo, Função SQLBrowseConnect, Função SQLConnect e Função SQLSetCursorName.

Funções relacionadas

Conteúdo relacionado

• Referência da API ODBC
• Ficheiros de Cabeçalho ODBC