Funzione SQLAllocHandle

  • Articolo

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

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

Nota

Questa funzione è una funzione generica per l'allocazione di handle che sostituisce le funzioni ODBC 2.0 SQLAllocConnect, SQLAllocEnv e SQLAllocStmt. Per consentire alle applicazioni che chiamano SQLAllocHandle di usare ODBC 2.X driver, viene mappata una chiamata a SQLAllocHandle in Gestione driver a SQLAllocConnect, SQLAllocEnv o SQLAllocStmt, a seconda delle esigenze. Per altre informazioni, vedere "Commenti". Per altre informazioni su ciò che Gestione driver esegue il mapping di questa funzione a quando un ODBC 3.L'applicazione x funziona con odbc 2.x driver, vedere Mapping di funzioni di sostituzione per la compatibilità con le versioni precedenti delle applicazioni.

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.

Resi

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 handleTypedi 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.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08003 Connessione non aperta (DM) L'argomento HandleType è stato SQL_HANDLE_STMT o SQL_HANDLE_DESC, ma la connessione specificata dall'argomento InputHandle non è stata aperta. Il processo di connessione deve essere completato correttamente (e la connessione deve essere aperta) affinché il driver alloca un handle di istruzione o descrittore.
HY000 Errore generale: Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa.
HY001 Errore di allocazione della memoria (DM) Gestione driver non è riuscito ad allocare memoria per l'handle specificato.

Il driver non è riuscito ad allocare memoria per l'handle specificato.
HY009 Uso non valido del puntatore Null (DM) L'argomento OutputHandlePtr è un puntatore Null.
HY010 Errore della sequenza di funzioni (DM) L'argomento HandleType è stato SQL_HANDLE_DBC e SQLSetEnvAttr non è stato chiamato per impostare l'attributo di ambiente SQL_ODBC_VERSION.

(DM) È stata chiamata una funzione in esecuzione asincrona per InputHandle ed era ancora in esecuzione quando la funzione SQLAllocHandle è stata chiamata con HandleType impostato su SQL_HANDLE_STMT o SQL_HANDLE_DESC.
HY013 Errore di gestione della memoria L'argomento HandleType è stato SQL_HANDLE_DBC, SQL_HANDLE_STMT o SQL_HANDLE_DESC e non è stato possibile elaborare la chiamata di funzione perché non è possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY014 Limite per il numero di handle superati È stato raggiunto il limite definito dal driver per il numero di handle che è possibile allocare per il tipo di handle indicato dall'argomento HandleType .
HY092 Identificatore di attributo/opzione non valido (DM) L'argomento HandleType non era: SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT o SQL_HANDLE_DESC.
HY117 La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYC00 Funzionalità facoltativa non implementata L'argomento HandleType è stato SQL_HANDLE_DESC e il driver era ODBC 2.x driver.
HYT01 Il timeout della connessione è scaduto Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Il driver non supporta questa funzione (DM) L'argomento HandleType è stato SQL_HANDLE_STMT e il driver non era un driver ODBC valido.

(DM) L'argomento HandleType è stato SQL_HANDLE_DESC e il driver non supporta l'allocazione di un handle del descrittore.

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.

Nota

La programmazione dell'applicazione ODBC non è corretta per chiamare SQLAllocHandle due volte con la stessa variabile dell'applicazione definita per *OutputHandlePtr senza chiamare SQLFreeHandle per liberare l'handle prima di riallocare l'handle. La sovrascrittura degli handle ODBC in questo modo può causare comportamenti incoerenti o errori nella parte dei driver ODBC.

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 handleTypedi SQL_HANDLE_ENV e InputHandledi 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 dei riferimenti (gestito da Gestione driver) 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. Gestione driver 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 quale connessione nel pool deve essere usata. 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 handleTypedi 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.

Per informazioni su Vedere
Esecuzione di un'istruzione SQL Funzione SQLExecDirect
Esecuzione di un'istruzione SQL preparata Funzione SQLExecute
Liberare un handle di ambiente, connessione, istruzione o descrittore Funzione SQLFreeHandle
Preparazione di un'istruzione per l'esecuzione Funzione SQLPrepare
Impostazione di un attributo di connessione Funzione SQLSetConnectAttr
Impostazione di un campo descrittore Funzione SQLSetDescField
Impostazione di un attributo di ambiente Funzione SQLSetEnvAttr
Impostazione di un attributo di istruzione Funzione SQLSetStmtAttr

Vedi anche

Riferimento API ODBC
File di intestazione ODBC