Função SQLAllocHandle
Compatibilidade
Versão introduzida: ODBC 3.0 Conformidade com os padrões: ISO 92
Resumo
SQLAllocHandle aloca um ambiente, conexão, instrução ou identificador de descritor.
Observação
Essa função é uma função genérica para alocar identificadores que substitui as funções ODBC 2.0 SQLAllocConnect, SQLAllocEnv e SQLAllocStmt. Para permitir que aplicativos que chamam SQLAllocHandle funcionem com ODBC 2.x , uma chamada para SQLAllocHandle é mapeada no Gerenciador de Drivers para SQLAllocConnect, SQLAllocEnv ou SQLAllocStmt, conforme apropriado. Para obter mais informações, consulte "Comentários". Para obter mais informações sobre o que o Gerenciador de Driver mapeia essa função quando um ODBC 3.x está funcionando com um ODBC 2.x , consulte Mapeando funções de substituição para compatibilidade com versões anteriores de aplicativos.
Sintaxe
SQLRETURN SQLAllocHandle(
SQLSMALLINT HandleType,
SQLHANDLE InputHandle,
SQLHANDLE * OutputHandlePtr);
Argumentos
Tipo de Identificador
[Entrada] O tipo de identificador a ser alocado por 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 identificador é usado apenas pelo Gerenciador de Driver e pelo driver. Os aplicativos não devem usar esse tipo de identificador. Para obter mais informações sobre SQL_HANDLE_DBC_INFO_TOKEN, consulte Desenvolvendo o reconhecimento do pool de conexões em um driver ODBC.
Identificador de entrada
[Entrada] O identificador de entrada em cujo contexto o novo identificador deve ser alocado. Se HandleType for SQL_HANDLE_ENV, isso será SQL_NULL_HANDLE. Se HandleType for SQL_HANDLE_DBC, deverá ser um identificador de ambiente e, se for SQL_HANDLE_STMT ou SQL_HANDLE_DESC, deverá ser um identificador de conexão.
OutputHandlePtr
[Saída] Ponteiro para um buffer no qual retornar o identificador para a estrutura de dados recém-alocada.
Devoluções
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE ou SQL_ERROR.
Ao alocar um identificador diferente de um identificador de ambiente, se SQLAllocHandle retornar SQL_ERROR, ele definirá OutputHandlePtr como 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. Em seguida, o aplicativo pode obter informações adicionais da estrutura de dados de diagnóstico associada ao identificador no argumento InputHandle .
Erros de alocação de tratamento de ambiente
A alocação de ambiente ocorre dentro do Gerenciador de Driver e dentro de cada driver. O erro retornado por SQLAllocHandle com um HandleType de SQL_HANDLE_ENV depende do nível em que o erro ocorreu.
Se o Gerenciador de Driver não puder alocar memória para *OutputHandlePtr quando SQLAllocHandle com um HandleType de SQL_HANDLE_ENV for chamado ou o aplicativo fornecer um ponteiro nulo para OutputHandlePtr, SQLAllocHandle retornará SQL_ERROR. O Gerenciador de Driver define *OutputHandlePtr como SQL_NULL_HENV (a menos que o aplicativo tenha fornecido um ponteiro nulo, que retorna SQL_ERROR). Não há identificador com o qual associar informações de diagnóstico adicionais.
O Gerenciador de Driver não chama a função de alocação de identificador de ambiente no nível do driver até que o aplicativo chame SQLConnect, SQLBrowseConnect ou SQLDriverConnect. Se ocorrer um erro na função SQLAllocHandle no nível do driver, a função SQLConnect, SQLBrowseConnect ou SQLDriverConnect no nível do Gerenciador de Driver retornará SQL_ERROR. A estrutura de dados de diagnóstico contém SQLSTATE IM004 (falha no SQLAllocHandle do driver). O erro é retornado em um identificador de conexão.
Para obter mais informações sobre o fluxo de chamadas de função entre o Gerenciador de Driver e um driver, consulte Função SQLConnect.
Diagnósticos
Quando SQLAllocHandle retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com o HandleType e o Handle apropriados definidos como o valor de InputHandle. SQL_SUCCESS_WITH_INFO (mas não SQL_ERROR) pode ser retornado para o argumento OutputHandle . A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLAllocHandle e explica cada um 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 de outra forma.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08003 | Conexão não aberta | (DM) O argumento HandleType foi SQL_HANDLE_STMT ou SQL_HANDLE_DESC, mas a conexão especificada pelo argumento InputHandle não estava aberta. O processo de conexão deve ser concluído com êxito (e a conexão deve estar aberta) para que o driver aloque uma instrução ou identificador de descritor. |
| 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 | (DM) O Gerenciador de Driver não pôde alocar memória para o identificador especificado. O driver não pôde alocar memória para o identificador especificado. |
| HY009 | Uso inválido de ponteiro nulo | (DM) O argumento OutputHandlePtr era um ponteiro nulo. |
| HY010 | Erro de sequência de função | (DM) O argumento HandleType foi SQL_HANDLE_DBC e SQLSetEnvAttr não foi chamado para definir o atributo de ambiente SQL_ODBC_VERSION. (DM) Uma função de execução assíncrona foi chamada para o InputHandle e ainda estava em execução quando a função SQLAllocHandle foi chamada com HandleType definido como SQL_HANDLE_STMT ou SQL_HANDLE_DESC. |
| HY013 | Erro de gerenciamento de memória | O argumento HandleType era SQL_HANDLE_DBC, SQL_HANDLE_STMT ou SQL_HANDLE_DESC; e 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. |
| HY014 | Limite do número de identificadores excedidos | O limite definido pelo driver para o número de identificadores que podem ser alocados para o tipo de identificador indicado pelo argumento HandleType foi atingido. |
| HY092 | Identificador de atributo/opção inválido | (DM) O argumento HandleType não era: SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT ou SQL_HANDLE_DESC. |
| 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 argumento HandleType foi SQL_HANDLE_DESC e o driver era um ODBC 2.x driver. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes que a fonte de dados respondesse à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | O driver não suporta esta função | (DM) O argumento HandleType foi SQL_HANDLE_STMT e o driver não era um driver ODBC válido. (DM) O argumento HandleType foi SQL_HANDLE_DESC e o driver não dá suporte à alocação de um identificador de descritor. |
Comentários
SQLAllocHandle é usado para alocar identificadores para ambientes, conexões, instruções e descritores, conforme descrito nas seções a seguir. Para obter informações gerais sobre identificadores, consulte Identificadores.
Mais de um ambiente, conexão ou identificador de instrução pode ser alocado por um aplicativo por vez se várias alocações forem compatíveis com o driver. No ODBC, nenhum limite é definido no número de identificadores de ambiente, conexão, instrução ou descritor que podem ser alocados a qualquer momento. Os drivers podem impor um limite ao número de um determinado tipo de identificador que pode ser alocado por vez; Para obter mais informações, consulte a documentação do driver.
Se o aplicativo chamar SQLAllocHandle com *OutputHandlePtr definido como um identificador de ambiente, conexão, instrução ou descritor que já existe, o driver substituirá as informações associadas ao identificador, a menos que o aplicativo esteja usando o pool de conexões (consulte "Alocando um atributo de ambiente para pool de conexões" mais adiante nesta seção). O Gerenciador de Driver não verifica se o identificador inserido em *OutputHandlePtr já está sendo usado, nem verifica o conteúdo anterior de um identificador antes de substituí-lo.
Observação
É uma programação incorreta do aplicativo ODBC chamar SQLAllocHandle duas vezes com a mesma variável de aplicativo definida para *OutputHandlePtr sem chamar SQLFreeHandle para liberar o identificador antes de realocá-lo. Substituir identificadores ODBC dessa maneira pode levar a um comportamento inconsistente ou erros por parte dos drivers ODBC.
Em sistemas operacionais que dão suporte a vários threads, os aplicativos podem usar o mesmo ambiente, conexão, instrução ou identificador de descritor em threads diferentes. Os drivers devem, portanto, dar suporte ao acesso seguro e multithread a essas informações; Uma maneira de conseguir isso, por exemplo, é usando uma seção crítica ou um semáforo. Para obter mais informações sobre threading, consulte Multithreading.
SQLAllocHandle não define o atributo de ambiente SQL_ATTR_ODBC_VERSION quando é chamado para alocar um identificador de ambiente; o atributo de ambiente deve ser definido pelo aplicativo ou SQLSTATE HY010 (erro de sequência de função) será retornado quando SQLAllocHandle for chamado para alocar um identificador de conexão.
Para aplicativos compatíveis com padrões, SQLAllocHandle é mapeado para SQLAllocHandleStd em tempo de compilação. A diferença entre essas duas funções é que SQLAllocHandleStd define o atributo de ambiente SQL_ATTR_ODBC_VERSION como SQL_OV_ODBC3 quando ele é chamado com o argumento HandleType definido como SQL_HANDLE_ENV. Isso é feito porque os aplicativos compatíveis com os padrões são sempre ODBC 3.x aplicações. Além disso, as normas não exigem que a versão do aplicativo seja registrada. Esta é a única diferença entre essas duas funções; caso contrário, eles são idênticos. SQLAllocHandleStd é mapeado para SQLAllocHandle dentro do gerenciador de driver. Portanto, os drivers de terceiros não precisam implementar SQLAllocHandleStd.
Os aplicativos ODBC 3.8 devem usar:
SQLAllocHandle e não SQLAllocHandleStd para alocar um identificador de ambiente.
SQLSetEnvAttr para definir o atributo de ambiente SQL_ATTR_ODBC_VERSION como SQL_OV_ODBC3_80.
Alocando um identificador de ambiente
Um identificador de ambiente fornece acesso a informações globais, como identificadores de conexão válidos e identificadores de conexão ativos. Para obter informações gerais sobre identificadores de ambiente, consulte Identificadores de ambiente.
Para solicitar um identificador de ambiente, um aplicativo chama SQLAllocHandle com um HandleType de SQL_HANDLE_ENV e um InputHandle de SQL_NULL_HANDLE. O driver aloca memória para as informações de ambiente e passa o valor do identificador associado de volta no argumento *OutputHandlePtr . O aplicativo passa o valor *OutputHandle em todas as chamadas subsequentes que exigem um argumento de identificador de ambiente. Para obter mais informações, consulte Alocar o identificador de ambiente.
No identificador de ambiente de um Gerenciador de Driver, se já existir um identificador de ambiente do driver, SQLAllocHandle com um HandleType de SQL_HANDLE_ENV não será chamado nesse driver quando uma conexão for feita, apenas SQLAllocHandle com um HandleType de SQL_HANDLE_DBC. Se o identificador de ambiente de um driver não existir no identificador de ambiente do Gerenciador de Driver, SQLAllocHandle com um HandleType de SQL_HANDLE_ENV e SQLAllocHandle com um HandleType de SQL_HANDLE_DBC serão chamados no driver quando o primeiro identificador de conexão do ambiente estiver conectado ao driver.
Quando o Gerenciador de Driver processa a função SQLAllocHandle com um HandleType de SQL_HANDLE_ENV, ele verifica a palavra-chave Trace na seção [ODBC] das informações do sistema. Se estiver definido como 1, o Gerenciador de Driver habilitará o rastreamento para o aplicativo atual. Se o sinalizador de rastreamento estiver definido, o rastreamento começará quando o primeiro identificador de ambiente for alocado e terminará quando o último identificador de ambiente for liberado. Para obter mais informações, consulte Configurando fontes de dados.
Depois de alocar um identificador de ambiente, um aplicativo deve chamar SQLSetEnvAttr no identificador de ambiente para definir o atributo de ambiente SQL_ATTR_ODBC_VERSION. Se esse atributo não for definido antes de SQLAllocHandle ser chamado para alocar um identificador de conexão no ambiente, a chamada para alocar a conexão retornará SQLSTATE HY010 (erro de sequência de função). Para obter mais informações, consulte Declarando a versão ODBC do aplicativo.
Alocando ambientes compartilhados para pool de conexões
Os ambientes podem ser compartilhados entre vários componentes em um único processo. Um ambiente compartilhado pode ser usado por mais de um componente ao mesmo tempo. Quando um componente usa um ambiente compartilhado, ele pode usar conexões em pool, o que permite alocar e usar uma conexão existente sem recriar essa conexão.
Antes de alocar um ambiente compartilhado que pode ser usado para pool de conexões, um aplicativo deve chamar SQLSetEnvAttr para definir o atributo de ambiente SQL_ATTR_CONNECTION_POOLING como SQL_CP_ONE_PER_DRIVER ou SQL_CP_ONE_PER_HENV. SQLSetEnvAttr , nesse caso, é chamado com EnvironmentHandle definido como nulo, o que torna o atributo um atributo de nível de processo.
Depois que o pool de conexões for habilitado, um aplicativo chamará SQLAllocHandle com o argumento HandleType definido como SQL_HANDLE_ENV. O ambiente atribuído por essa chamada será um ambiente compartilhado implícito porque o pool de conexões foi habilitado.
Quando um ambiente compartilhado é alocado, o ambiente que será usado não é determinado até que SQLAllocHandle com um HandleType de SQL_HANDLE_DBC seja chamado. Nesse ponto, o Gerenciador de Driver tenta encontrar um ambiente existente que corresponda aos atributos de ambiente solicitados pelo aplicativo. Se esse ambiente não existir, ele será criado como um ambiente compartilhado. O Gerenciador de Driver mantém uma contagem de referência para cada ambiente compartilhado; A contagem é definida como 1 quando o ambiente é criado pela primeira vez. Se um ambiente correspondente for encontrado, o identificador desse ambiente será retornado ao aplicativo e a contagem de referência será incrementada. Um identificador de ambiente alocado dessa maneira pode ser usado em qualquer função ODBC que aceite um identificador de ambiente como um argumento de entrada.
Alocar um identificador de conexão
Um identificador de conexão fornece acesso a informações como a instrução válida e os identificadores de descritor na conexão e se uma transação está aberta no momento. Para obter informações gerais sobre identificadores de conexão, consulte Identificadores de conexão.
Para solicitar um identificador de conexão, um aplicativo chama SQLAllocHandle com um HandleType de SQL_HANDLE_DBC. O argumento InputHandle é definido como o identificador de ambiente que foi retornado pela chamada para SQLAllocHandle que alocou esse identificador. O driver aloca memória para as informações de conexão e passa o valor do identificador associado de volta em *OutputHandlePtr. O aplicativo passa o valor *OutputHandlePtr em todas as chamadas subsequentes que exigem um identificador de conexão. Para obter mais informações, consulte Alocando um identificador de conexão.
O Gerenciador de Driver processa a função SQLAllocHandle e chama a função SQLAllocHandle do driver quando o aplicativo chama SQLConnect, SQLBrowseConnect ou SQLDriverConnect. (Para obter mais informações, consulte Função SQLConnect.)
Se o atributo de ambiente SQL_ATTR_ODBC_VERSION não for definido antes de SQLAllocHandle ser chamado para alocar um identificador de conexão no ambiente, a chamada para alocar a conexão retornará SQLSTATE HY010 (erro de sequência de função).
Quando um aplicativo chama SQLAllocHandle com o argumento InputHandle definido como SQL_HANDLE_DBC e também definido como um identificador de ambiente compartilhado, o Gerenciador de Driver tenta encontrar um ambiente compartilhado existente que corresponda aos atributos de ambiente definidos pelo aplicativo. Se esse ambiente não existir, um é criado, com uma contagem de referência (mantida pelo Gerenciador de Driver) de 1. Se um ambiente compartilhado correspondente for encontrado, esse identificador será retornado ao aplicativo e sua contagem de referência será incrementada.
A conexão real que será usada não é determinada pelo Gerenciador de Driver até que SQLConnect ou SQLDriverConnect seja chamado. O Gerenciador de Driver usa as opções de conexão na chamada para SQLConnect (ou as palavras-chave de conexão na chamada para SQLDriverConnect) e os atributos de conexão definidos após a alocação de conexão para determinar qual conexão no pool deve ser usada. Para obter mais informações, consulte Função SQLConnect.
Alocando um identificador de instrução
Um identificador de instrução fornece acesso a informações de instrução, como mensagens de erro, o nome do cursor e informações de status para processamento de instrução SQL. Para obter informações gerais sobre identificadores de instrução, consulte Identificadores de instrução.
Para solicitar um identificador de instrução, um aplicativo se conecta a uma fonte de dados e chama SQLAllocHandle antes de enviar instruções SQL. Nessa chamada, HandleType deve ser definido como SQL_HANDLE_STMT e InputHandle deve ser definido como o identificador de conexão que foi retornado pela chamada para SQLAllocHandle que alocou esse identificador. O driver aloca memória para as informações de instrução, associa o identificador de instrução à conexão especificada e passa o valor do identificador associado de volta em *OutputHandlePtr. O aplicativo passa o valor *OutputHandlePtr em todas as chamadas subsequentes que exigem um identificador de instrução. Para obter mais informações, consulte Alocando um identificador de instrução.
Quando o identificador de instrução é alocado, o driver aloca automaticamente um conjunto de quatro descritores e atribui os identificadores para esses descritores aos atributos de instrução SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC e SQL_ATTR_IMP_PARAM_DESC. Eles são chamados de descritores alocados implicitamente . Para alocar um descritor de aplicativo explicitamente, consulte a seção a seguir, "Alocando um identificador de descritor".
Alocando um identificador de descritor
Quando um aplicativo chama SQLAllocHandle com um HandleType de SQL_HANDLE_DESC, o driver aloca um descritor de aplicativo. Eles são chamados de descritores explicitamente alocados. O aplicativo direciona um driver para usar um descritor de aplicativo alocado explicitamente em vez de um alocado automaticamente para um determinado identificador 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 um descritor de implementação pode ser especificado em uma chamada de função SQLSetStmtAttr .
Os descritores alocados explicitamente são associados a um identificador de conexão em vez de um identificador de instrução (como os descritores alocados automaticamente). Os descritores permanecem alocados somente quando um aplicativo está realmente conectado ao banco de dados. Como os descritores alocados explicitamente estão associados a um identificador de conexão, um aplicativo pode associar um descritor alocado explicitamente a mais de uma instrução dentro de uma conexão. Um descritor de aplicativo alocado implicitamente, por outro lado, não pode ser associado a mais de um identificador de instrução. (Ele não pode ser associado a nenhum identificador de instrução diferente daquele para o qual foi alocado.) Os identificadores de descritor alocados explicitamente podem ser liberados explicitamente pelo aplicativo ou chamando SQLFreeHandle com um HandleType de SQL_HANDLE_DESC ou implicitamente quando a conexão é fechada.
Quando o descritor alocado explicitamente é liberado, o descritor alocado implicitamente é novamente associado à instrução. (O atributo SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC para essa instrução é novamente definido como o identificador de descritor alocado implicitamente.) Isso é verdadeiro para todas as instruções que foram associadas ao descritor explicitamente alocado na conexão.
Para obter mais informações sobre descritores, consulte Descritores.
Exemplo de código
Consulte Programa ODBC de exemplo, Função SQLBrowseConnect, Função SQLConnect e Função SQLSetCursorName.
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Executando uma instrução SQL | Função SQLExecDirect |
| Executando uma instrução SQL preparada | Função SQLExecute |
| Liberando um ambiente, conexão, instrução ou identificador de descritor | Função SQLFreeHandle |
| Preparando uma instrução para execução | Função SQLPrepare |
| Configurando um atributo de conexão | Função SQLSetConnectAttr |
| Definindo um campo de descritor | Função SQLSetDescField |
| Configurando um atributo de ambiente | Função SQLSetEnvAttr |
| Configurando um atributo de instrução | Função SQLSetStmtAttr |