Funzione SQLAllocHandle

Conformità
Versione introdotta: Conformità agli standard ODBC 3.0: ISO 92

Riepilogo
SQLAllocHandle alloca un handle di ambiente, connessione, istruzione o descrittore.

Sintassi

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

Argomenti

HandleType
[Input] Tipo di handle da allocare da SQLAllocHandle. Deve essere uno dei valori seguenti:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handle viene usato solo da Gestione driver e driver. Le applicazioni non devono usare questo tipo di handle. Per altre informazioni sulle SQL_HANDLE_DBC_INFO_TOKEN, vedere Sviluppo di consapevolezza del pool di connessioni in un driver ODBC.

InputHandle
[Input] Handle di input nel cui contesto deve essere allocato il nuovo handle. Se HandleType è SQL_HANDLE_ENV, si tratta di SQL_NULL_HANDLE. Se HandleType è SQL_HANDLE_DBC, deve trattarsi di un handle di ambiente e, se è SQL_HANDLE_STMT o SQL_HANDLE_DESC, deve essere un handle di connessione.

OutputHandlePtr
[Output] Puntatore a un buffer in cui restituire l'handle alla struttura di dati appena allocata.

Valori restituiti

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE o SQL_ERROR.

Quando si alloca un handle diverso da un handle di ambiente, se SQLAllocHandle restituisce SQL_ERROR, imposta OutputHandlePtr su SQL_NULL_HDBC, SQL_NULL_HSTMT o SQL_NULL_HDESC, a seconda del valore di HandleType, a meno che l'argomento di output non sia un puntatore Null. L'applicazione può quindi ottenere informazioni aggiuntive dalla struttura dei dati di diagnostica associata all'handle nell'argomento InputHandle .

Errori di allocazione dell'handle dell'ambiente

L'allocazione dell'ambiente avviene sia all'interno di Gestione driver che all'interno di ogni driver. L'errore restituito da SQLAllocHandle con handleType di SQL_HANDLE_ENV dipende dal livello in cui si è verificato l'errore.

Se Gestione driver non può allocare memoria per *OutputHandlePtr quando viene chiamato SQLAllocHandle con handleType di SQL_HANDLE_ENV oppure l'applicazione fornisce un puntatore Null per OutputHandlePtr, SQLAllocHandle restituisce SQL_ERROR. Gestione driver imposta *OutputHandlePtr su SQL_NULL_HENV (a meno che l'applicazione non disponga di un puntatore Null, che restituisce SQL_ERROR). Non esiste alcun handle con cui associare informazioni di diagnostica aggiuntive.

Gestione driver non chiama la funzione di allocazione dell'ambiente a livello di driver finché l'applicazione non chiama SQLConnect, SQLBrowseConnect o SQLDriverConnect. Se si verifica un errore nella funzione SQLAllocHandle a livello di driver, la funzione SQLConnect, SQLBrowseConnect o SQLDriverConnect a livello di driver restituisce SQL_ERROR. La struttura dei dati di diagnostica contiene SQLSTATE IM004 (SQLAllocHandle del driver non riuscito). L'errore viene restituito su un handle di connessione.

Per altre informazioni sul flusso delle chiamate di funzione tra Gestione driver e un driver, vedere Funzione SQLConnect.

Diagnostica

Quando SQLAllocHandle restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleType e Handle appropriati impostati sul valore di InputHandle. SQL_SUCCESS_WITH_INFO (ma non SQL_ERROR) può essere restituito per l'argomento OutputHandle . La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLAllocHandle e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Commenti

SQLAllocHandle viene usato per allocare handle per ambienti, connessioni, istruzioni e descrittori, come descritto nelle sezioni seguenti. Per informazioni generali sugli handle, vedere Handle.

È possibile allocare più di un ambiente, una connessione o un handle di istruzione da un'applicazione alla volta se più allocazioni sono supportate dal driver. In ODBC non è definito alcun limite per il numero di handle di ambiente, connessione, istruzione o descrittore che possono essere allocati in qualsiasi momento. I driver possono imporre un limite al numero di un determinato tipo di handle che può essere allocato alla volta; per altre informazioni, vedere la documentazione del driver.

Se l'applicazione chiama SQLAllocHandle con *OutputHandlePtr impostato su un ambiente, una connessione, un'istruzione o un handle descrittore già esistente, il driver sovrascrive le informazioni associate all'handle, a meno che l'applicazione non usi il pool di connessioni (vedere "Allocazione di un attributo di ambiente per il pool di connessioni" più avanti in questa sezione). Gestione driver non verifica se l'handle immesso in *OutputHandlePtr è già in uso, né controlla il contenuto precedente di un handle prima di sovrascriverli.

Nei sistemi operativi che supportano più thread, le applicazioni possono usare lo stesso ambiente, connessione, istruzione o descrittore in thread diversi. I driver devono pertanto supportare l'accesso sicuro e multithread a queste informazioni; un modo per ottenere questo risultato, ad esempio, consiste nell'usare una sezione critica o un semaforo. Per altre informazioni sul threading, vedere Multithreading.

SQLAllocHandle non imposta l'attributo di ambiente SQL_ATTR_ODBC_VERSION quando viene chiamato per allocare un handle di ambiente. L'attributo dell'ambiente deve essere impostato dall'applicazione o SQLSTATE HY010 (errore di sequenza di funzione) verrà restituito quando viene chiamato SQLAllocHandle per allocare un handle di connessione.

Per le applicazioni conformi agli standard, SQLAllocHandle viene mappato a SQLAllocHandleStd in fase di compilazione. La differenza tra queste due funzioni è che SQLAllocHandleStd imposta l'attributo di ambiente SQL_ATTR_ODBC_VERSION su SQL_OV_ODBC3 quando viene chiamato con l'argomento HandleType impostato su SQL_HANDLE_ENV. Questa operazione viene eseguita perché le applicazioni conformi agli standard sono sempre ODBC 3.x applicazioni. Inoltre, gli standard non richiedono la registrazione della versione dell'applicazione. Questa è l'unica differenza tra queste due funzioni; in caso contrario, sono identici. SQLAllocHandleStd viene mappato a SQLAllocHandle all'interno di Gestione driver. Pertanto, i driver di terze parti non devono implementare SQLAllocHandleStd.

Le applicazioni ODBC 3.8 devono usare:

• SQLAllocHandle e non SQLAllocHandleStd per allocare un handle di ambiente.

• SQLSetEnvAttr per impostare l'attributo dell'ambiente SQL_ATTR_ODBC_VERSION su SQL_OV_ODBC3_80.

Allocazione di un handle di ambiente

Un handle di ambiente fornisce l'accesso a informazioni globali, ad esempio handle di connessione validi e handle di connessione attivi. Per informazioni generali sugli handle di ambiente, vedere Handle di ambiente.

Per richiedere un handle di ambiente, un'applicazione chiama SQLAllocHandle con handleType di SQL_HANDLE_ENV e InputHandle di SQL_NULL_HANDLE. Il driver alloca memoria per le informazioni sull'ambiente e passa di nuovo il valore dell'handle associato nell'argomento *OutputHandlePtr . L'applicazione passa il valore *OutputHandle in tutte le chiamate successive che richiedono un argomento handle di ambiente. Per altre informazioni, vedere Allocazione dell'handle di ambiente.

Nell'handle dell'ambiente di Gestione driver, se esiste già un handle di ambiente di un driver, SQLAllocHandle con handleType di SQL_HANDLE_ENV non viene chiamato in tale driver quando viene stabilita una connessione, solo SQLAllocHandle con handleType di SQL_HANDLE_DBC. Se l'handle di ambiente di un driver non esiste nell'handle dell'ambiente di Gestione driver, sqlAllocHandle con handleType di SQL_HANDLE_ENV e SQLAllocHandle con handleType di SQL_HANDLE_DBC vengono chiamati nel driver quando il primo handle di connessione dell'ambiente è connesso al driver.

Quando Gestione driver elabora la funzione SQLAllocHandle con handleType di SQL_HANDLE_ENV, controlla la parola chiave Trace nella sezione [ODBC] delle informazioni di sistema. Se è impostato su 1, Gestione driver abilita la traccia per l'applicazione corrente. Se il flag di traccia è impostato, la traccia viene avviata quando viene allocato il primo handle di ambiente e termina quando viene liberato l'ultimo handle di ambiente. Per altre informazioni, vedere Configurazione delle origini dati.

Dopo l'allocazione di un handle di ambiente, un'applicazione deve chiamare SQLSetEnvAttr nell'handle di ambiente per impostare l'attributo di ambiente SQL_ATTR_ODBC_VERSION. Se questo attributo non è impostato prima che SQLAllocHandle venga chiamato per allocare un handle di connessione nell'ambiente, la chiamata per allocare la connessione restituirà SQLSTATE HY010 (errore della sequenza di funzioni). Per altre informazioni, vedere Dichiarazione della versione ODBC dell'applicazione.

Allocazione di ambienti condivisi per il pool di connessioni

Gli ambienti possono essere condivisi tra più componenti in un singolo processo. Un ambiente condiviso può essere usato contemporaneamente da più componenti. Quando un componente usa un ambiente condiviso, può usare connessioni in pool, che consentono di allocare e usare una connessione esistente senza creare nuovamente tale connessione.

Prima di allocare un ambiente condiviso che può essere usato per il pool di connessioni, un'applicazione deve chiamare SQLSetEnvAttr per impostare l'attributo dell'ambiente SQL_ATTR_CONNECTION_POOLING su SQL_CP_ONE_PER_DRIVER o SQL_CP_ONE_PER_HENV. SQLSetEnvAttr in questo caso viene chiamato con EnvironmentHandle impostato su null, che rende l'attributo un attributo a livello di processo.

Dopo aver abilitato il pool di connessioni, un'applicazione chiama SQLAllocHandle con l'argomento HandleType impostato su SQL_HANDLE_ENV. L'ambiente allocato da questa chiamata sarà un ambiente condiviso implicito perché il pool di connessioni è stato abilitato.

Quando viene allocato un ambiente condiviso, l'ambiente che verrà usato non viene determinato fino a quando non viene chiamato SQLAllocHandle con handleType di SQL_HANDLE_DBC. A questo punto, Gestione driver tenta di trovare un ambiente esistente che corrisponda agli attributi di ambiente richiesti dall'applicazione. Se tale ambiente non esiste, ne viene creato uno come ambiente condiviso. Gestione driver mantiene un conteggio dei riferimenti per ogni ambiente condiviso; il conteggio è impostato su 1 quando l'ambiente viene creato per la prima volta. Se viene trovato un ambiente corrispondente, l'handle di tale ambiente viene restituito all'applicazione e il conteggio dei riferimenti viene incrementato. Un handle di ambiente allocato in questo modo può essere usato in qualsiasi funzione ODBC che accetta un handle di ambiente come argomento di input.

Allocazione di un handle di connessione

Un handle di connessione fornisce l'accesso a informazioni quali l'istruzione e gli handle del descrittore validi nella connessione e se una transazione è attualmente aperta. Per informazioni generali sugli handle di connessione, vedere Handle di connessione.

Per richiedere un handle di connessione, un'applicazione chiama SQLAllocHandle con handleType di SQL_HANDLE_DBC. L'argomento InputHandle è impostato sull'handle di ambiente restituito dalla chiamata a SQLAllocHandle che ha allocato tale handle. Il driver alloca memoria per le informazioni di connessione e passa di nuovo il valore dell'handle associato in *OutputHandlePtr. L'applicazione passa il valore *OutputHandlePtr in tutte le chiamate successive che richiedono un handle di connessione. Per altre informazioni, vedere Allocazione di un handle di connessione.

Gestione driver elabora la funzione SQLAllocHandle e chiama la funzione SQLAllocHandle del driver quando l'applicazione chiama SQLConnect, SQLBrowseConnect o SQLDriverConnect. Per altre informazioni, vedere Funzione SQLConnect.

Se l'attributo di ambiente SQL_ATTR_ODBC_VERSION non è impostato prima che SQLAllocHandle venga chiamato per allocare un handle di connessione nell'ambiente, la chiamata per allocare la connessione restituirà SQLSTATE HY010 (errore della sequenza di funzioni).

Quando un'applicazione chiama SQLAllocHandle con l'argomento InputHandle impostato su SQL_HANDLE_DBC e impostato anche su un handle di ambiente condiviso, Gestione driver tenta di trovare un ambiente condiviso esistente che corrisponda agli attributi di ambiente impostati dall'applicazione. Se tale ambiente non esiste, ne viene creato uno con un conteggio di riferimento (conservato dal driver manager) pari a 1. Se viene trovato un ambiente condiviso corrispondente, tale handle viene restituito all'applicazione e il relativo conteggio dei riferimenti viene incrementato.

La connessione effettiva che verrà usata non è determinata da Gestione driver fino a quando non viene chiamato SQLConnect o SQLDriverConnect. Il driver manager usa le opzioni di connessione nella chiamata a SQLConnect (o le parole chiave di connessione nella chiamata a SQLDriverConnect) e gli attributi di connessione impostati dopo l'allocazione della connessione per determinare la connessione che deve essere usata all’interno del pool. Per altre informazioni, vedere Funzione SQLConnect.

Allocazione di un handle di istruzione

Un handle di istruzione fornisce l'accesso alle informazioni sull'istruzione, ad esempio messaggi di errore, nome del cursore e informazioni sullo stato per l'elaborazione dell'istruzione SQL. Per informazioni generali sugli handle di istruzioni, vedere Handle di istruzioni.

Per richiedere un handle di istruzione, un'applicazione si connette a un'origine dati e quindi chiama SQLAllocHandle prima di inviare istruzioni SQL. In questa chiamata, HandleType deve essere impostato su SQL_HANDLE_STMT e InputHandle deve essere impostato sull'handle di connessione restituito dalla chiamata a SQLAllocHandle che ha allocato tale handle. Il driver alloca memoria per le informazioni sull'istruzione, associa l'handle di istruzione alla connessione specificata e passa di nuovo il valore dell'handle associato in *OutputHandlePtr. L'applicazione passa il valore *OutputHandlePtr in tutte le chiamate successive che richiedono un handle di istruzione. Per altre informazioni, vedere Allocazione di un handle di istruzione.

Quando l'handle di istruzione viene allocato, il driver alloca automaticamente un set di quattro descrittori e assegna gli handle per questi descrittori ai SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC e SQL_ATTR_IMP_PARAM_DESC attributi dell'istruzione. Questi vengono definiti descrittori allocati in modo implicito. Per allocare in modo esplicito un descrittore dell'applicazione, vedere la sezione seguente "Allocazione di un handle descrittore".

Allocazione di un handle descrittore

Quando un'applicazione chiama SQLAllocHandle con handleType di SQL_HANDLE_DESC, il driver alloca un descrittore dell'applicazione. Questi vengono definiti descrittori allocati in modo esplicito . L'applicazione indirizza un driver a usare un descrittore dell'applicazione allocato in modo esplicito anziché uno allocato automaticamente per un handle di istruzione specifico chiamando la funzione SQLSetStmtAttr con l'attributo SQL_ATTR_APP_ROW_DESC o SQL_ATTR_APP_PARAM_DESC. Un descrittore di implementazione non può essere allocato in modo esplicito, né può essere specificato un descrittore di implementazione in una chiamata di funzione SQLSetStmtAttr .

I descrittori allocati in modo esplicito sono associati a un handle di connessione anziché a un handle di istruzione (come descrittori allocati automaticamente). I descrittori rimangono allocati solo quando un'applicazione è effettivamente connessa al database. Poiché i descrittori allocati in modo esplicito sono associati a un handle di connessione, un'applicazione può associare un descrittore allocato in modo esplicito a più istruzioni all'interno di una connessione. Un descrittore dell'applicazione allocato in modo implicito, d'altra parte, non può essere associato a più di un handle di istruzione. Non può essere associato a un handle di istruzione diverso da quello per cui è stato allocato. Gli handle del descrittore allocati in modo esplicito possono essere liberati in modo esplicito dall'applicazione o chiamando SQLFreeHandle con handleType di SQL_HANDLE_DESC oppure in modo implicito quando la connessione viene chiusa.

Quando il descrittore allocato in modo esplicito viene liberato, il descrittore allocato in modo implicito viene nuovamente associato all'istruzione . L'attributo SQL_ATTR_APP_ROW_DESC o SQL_ATTR_APP_PARAM_DESC per tale istruzione viene nuovamente impostato sull'handle del descrittore allocato in modo implicito. Questo vale per tutte le istruzioni associate al descrittore allocato in modo esplicito nella connessione.

Per altre informazioni sui descrittori, vedere Descrittori.

Esempio di codice

Vedere Programma ODBC di esempio, funzione SQLBrowseConnect, funzione SQLConnect e funzione SQLSetCursorName.

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC