SQLAllocHandle-Funktion

Konformität
Version eingeführt: ODBC 3.0 Standards Compliance: ISO 92

Zusammenfassung
SQLAllocHandle weist eine Umgebung, Verbindung, Anweisung oder Beschreibungshandle zu.

Syntax

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

Argumente

HandleType
[Eingabe] Der Handletyp, der von SQLAllocHandle zugewiesen werden soll. Dies muss einer der folgenden Werte sein:

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN Handle wird nur vom Treiber-Manager und Treiber verwendet. Anwendungen sollten diesen Handletyp nicht verwenden. Weitere Informationen zu SQL_HANDLE_DBC_INFO_TOKEN finden Sie unter Developing Connection-Pool Awareness in an ODBC Driver.

InputHandle
[Eingabe] Das Eingabehandle, in dessen Kontext das neue Handle zugewiesen werden soll. Wenn HandleType SQL_HANDLE_ENV ist, ist dies SQL_NULL_HANDLE. Wenn HandleType SQL_HANDLE_DBC ist, muss dies ein Umgebungshandle sein, und wenn es SQL_HANDLE_STMT oder SQL_HANDLE_DESC ist, muss es sich um ein Verbindungshandle handeln.

OutputHandlePtr
[Ausgabe] Zeigen Sie auf einen Puffer, in dem das Handle an die neu zugeordnete Datenstruktur zurückgegeben werden soll.

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE oder SQL_ERROR.

Wenn sqlAllocHandle SQL_ERROR zurückgibt, wird beim Zuordnen eines anderen Handles als ein Umgebungshandle Handle SQL_NULL_HDBC, SQL_NULL_HSTMT oder SQL_NULL_HDESC festgelegt, es sei denn, das Ausgabeargument ist ein NULL-Zeiger. Die Anwendung kann dann zusätzliche Informationen aus der Diagnosedatenstruktur abrufen, die dem Handle im InputHandle-Argument zugeordnet ist.

Umgebung behandeln Zuordnungsfehler

Die Umgebungszuordnung erfolgt sowohl innerhalb des Treiber-Managers als auch innerhalb jedes Treibers. Der von SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV zurückgegebene Fehler hängt von der Ebene ab, auf der der Fehler aufgetreten ist.

Wenn der Treiber-Manager Speicher für *OutputHandlePtr nicht zuordnen kann, wenn SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV aufgerufen wird, oder die Anwendung einen Nullzeiger für OutputHandlePtr bereitstellt, gibt SQLAllocHandle SQL_ERROR zurück. Der Treiber-Manager legt *OutputHandlePtr auf SQL_NULL_HENV fest (es sei denn, die Anwendung hat einen Nullzeiger bereitgestellt, der SQL_ERROR zurückgibt). Es gibt keine Behandlung, mit der zusätzliche Diagnoseinformationen zugeordnet werden.

Der Treiber-Manager ruft die Zuordnungsfunktion auf Treiberebene erst auf, wenn die Anwendung SQLConnect, SQLBrowseConnect oder SQLDriverConnect aufruft. Wenn in der SQLAllocHandle-Funktion auf Treiberebene ein Fehler auftritt, gibt die SqlConnect-Funktion auf Treiber-Manager-Ebene, SQLBrowseConnect oder SQLDriverConnect SQL_ERROR zurück. Die Diagnosedatenstruktur enthält SQLSTATE IM004 (SqlAllocHandle-Fehler des Treibers). Der Fehler wird für ein Verbindungshandle zurückgegeben.

Weitere Informationen zum Ablauf von Funktionsaufrufen zwischen dem Treiber-Manager und einem Treiber finden Sie unter SQLConnect Function.

Diagnostik

Wenn SQLAllocHandle SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit dem entsprechenden HandleType - und Handle-Wert auf den Wert von InputHandle festgelegt wird. SQL_SUCCESS_WITH_INFO (aber nicht SQL_ERROR) kann für das OutputHandle-Argument zurückgegeben werden. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die in der Regel von SQLAllocHandle zurückgegeben werden, und jede wird im Kontext dieser Funktion erläutert. Die Notation "(DM)" steht vor den Beschreibungen von SQLSTATEs, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

SQLAllocHandle wird verwendet, um Handles für Umgebungen, Verbindungen, Anweisungen und Deskriptoren zuzuweisen, wie in den folgenden Abschnitten beschrieben. Allgemeine Informationen zu Handles finden Sie unter Handles.

Mehrere Umgebungen, Verbindungs- oder Anweisungshandle können jeweils von einer Anwendung zugewiesen werden, wenn vom Treiber mehrere Zuordnungen unterstützt werden. In ODBC wird kein Grenzwert für die Anzahl der Umgebungs-, Verbindungs-, Anweisungs- oder Deskriptorhandles definiert, die jederzeit zugewiesen werden können. Treiber können die Anzahl eines bestimmten Handles einschränken, die jeweils zugewiesen werden können; weitere Informationen finden Sie in der Treiberdokumentation.

Wenn die Anwendung SQLAllocHandle mit *OutputHandlePtr auf eine Umgebung, Verbindung, Anweisung oder Beschreibungshandle aufruft, die bereits vorhanden ist, überschreibt der Treiber die dem Handle zugeordneten Informationen, es sei denn, die Anwendung verwendet Verbindungspooling (siehe "Allocating an Environment Attribute for Connection Pooling" weiter unten in diesem Abschnitt). Der Treiber-Manager überprüft nicht, ob der in *OutputHandlePtr eingegebene Handle bereits verwendet wird, oder ob der vorherige Inhalt eines Handles vor dem Überschreiben überprüft wird.

Auf Betriebssystemen, die mehrere Threads unterstützen, können Anwendungen dieselbe Umgebung, Verbindung, Anweisung oder Beschreibung für verschiedene Threads verwenden. Die Treiber müssen daher den sicheren, multithread-Zugriff auf diese Informationen unterstützen; Eine Möglichkeit, dies beispielsweise zu erreichen, ist die Verwendung eines kritischen Abschnitts oder eines Semaphors. Weitere Informationen zum Threading finden Sie unter Multithreading.

SQLAllocHandle legt das SQL_ATTR_ODBC_VERSION Umgebungsattribut nicht fest, wenn es aufgerufen wird, um ein Umgebungshandle zuzuweisen. Das Umgebungsattribut muss von der Anwendung festgelegt werden, oder SQLSTATE HY010 (Funktionssequenzfehler) wird zurückgegeben, wenn SQLAllocHandle aufgerufen wird, um ein Verbindungshandle zuzuweisen.

Für standardskonforme Anwendungen wird SQLAllocHandle zur Kompilierungszeit SQLAllocHandleStd zugeordnet. Der Unterschied zwischen diesen beiden Funktionen besteht darin, dass SQLAllocHandleStd das attribut der SQL_ATTR_ODBC_VERSION Umgebung auf SQL_OV_ODBC3 festlegt, wenn es mit dem HandleType-Argument aufgerufen wird, das auf SQL_HANDLE_ENV festgelegt ist. Dies geschieht, da standardkonforme Anwendungen immer ODBC 3 sind.x-Anwendungen . Darüber hinaus müssen die Standards nicht die Anwendungsversion registriert werden. Dies ist der einzige Unterschied zwischen diesen beiden Funktionen; andernfalls sind sie identisch. SQLAllocHandleStd wird SQLAllocHandle innerhalb des Treiber-Managers zugeordnet. Daher müssen Drittanbietertreiber SQLAllocHandleStd nicht implementieren.

ODBC 3.8-Anwendungen sollten Folgendes verwenden:

• SQLAllocHandle und nicht SQLAllocHandleStd , um ein Umgebungshandle zuzuweisen.

• SQLSetEnvAttr zum Festlegen des SQL_ATTR_ODBC_VERSION Umgebungsattributs auf SQL_OV_ODBC3_80.

Zuordnen eines Umgebungshandles

Ein Umgebungshandle bietet Zugriff auf globale Informationen wie gültige Verbindungsziehpunkte und aktive Verbindungsziehpunkte. Allgemeine Informationen zu Umgebungshandles finden Sie unter "Umgebungshandles".

Um ein Umgebungshandle anzufordern, ruft eine Anwendung SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV und einer InputHandle von SQL_NULL_HANDLE auf. Der Treiber weist Speicher für die Umgebungsinformationen zu und übergibt den Wert des zugeordneten Handles zurück im Argument *OutputHandlePtr . Die Anwendung übergibt den *OutputHandle-Wert in allen nachfolgenden Aufrufen, die ein Umgebungshandle-Argument erfordern. Weitere Informationen finden Sie unter "Allocating the Environment Handle".

Wenn bereits ein Umgebungshandle eines Treiber-Managers vorhanden ist, wird SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV nicht in diesem Treiber aufgerufen, wenn eine Verbindung hergestellt wird, nur SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC. Wenn ein Umgebungshandle eines Treibers nicht unter dem Umgebungshandle des Treiber-Managers vorhanden ist, werden sowohl SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV als auch SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC im Treiber aufgerufen, wenn das erste Verbindungshandle der Umgebung mit dem Treiber verbunden ist.

Wenn der Treiber-Manager die SQLAllocHandle-Funktion mit einem HandleType von SQL_HANDLE_ENV verarbeitet, überprüft er das Trace-Schlüsselwort im Abschnitt [ODBC] der Systeminformationen. Wenn sie auf 1 festgelegt ist, aktiviert der Treiber-Manager die Ablaufverfolgung für die aktuelle Anwendung. Wenn das Ablaufverfolgungskennzeichnung festgelegt ist, beginnt die Ablaufverfolgung, wenn das erste Umgebungshandle zugewiesen wird, und endet, wenn der letzte Umgebungshandle freigegeben wird. Weitere Informationen finden Sie unter Konfigurieren von Datenquellen.

Nach dem Zuweisen eines Umgebungshandles muss eine Anwendung SQLSetEnvAttr für das Umgebungshandle aufrufen, um das SQL_ATTR_ODBC_VERSION Umgebungsattribut festzulegen. Wenn dieses Attribut nicht festgelegt wird, bevor SQLAllocHandle aufgerufen wird, um ein Verbindungshandle für die Umgebung zuzuweisen, gibt der Aufruf zur Zuweisung der Verbindung SQLSTATE HY010 (Funktionssequenzfehler) zurück. Weitere Informationen finden Sie unter Deklarieren der ODBC-Version der Anwendung.

Zuweisung freigegebener Umgebungen für verbindungspooling

Umgebungen können von mehreren Komponenten in einem einzigen Prozess gemeinsam genutzt werden. Eine freigegebene Umgebung kann von mehreren Komponenten gleichzeitig verwendet werden. Wenn eine Komponente eine freigegebene Umgebung verwendet, kann sie poolierte Verbindungen verwenden, die es ermöglichen, eine vorhandene Verbindung zuzuweisen und zu verwenden, ohne diese Verbindung erneut zu erstellen.

Vor dem Zuweisen einer freigegebenen Umgebung, die für das Verbindungspooling verwendet werden kann, muss eine Anwendung SQLSetEnvAttr aufrufen, um das SQL_ATTR_CONNECTION_POOLING Umgebungsattribut auf SQL_CP_ONE_PER_DRIVER oder SQL_CP_ONE_PER_HENV festzulegen. SQLSetEnvAttr wird in diesem Fall mit EnvironmentHandle auf Null aufgerufen, wodurch das Attribut zu einem Attribut auf Prozessebene wird.

Nachdem verbindungspooling aktiviert wurde, ruft eine Anwendung SQLAllocHandle auf, wobei das HandleType-Argument auf SQL_HANDLE_ENV festgelegt ist. Die von diesem Aufruf zugewiesene Umgebung ist eine implizite freigegebene Umgebung, da verbindungspooling aktiviert wurde.

Wenn eine freigegebene Umgebung zugewiesen wird, wird die verwendete Umgebung erst bestimmt, wenn SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC aufgerufen wird. Zu diesem Zeitpunkt versucht der Treiber-Manager, eine vorhandene Umgebung zu finden, die den von der Anwendung angeforderten Umgebungsattributen entspricht. Wenn keine solche Umgebung vorhanden ist, wird eine als freigegebene Umgebung erstellt. Der Treiber-Manager verwaltet für jede freigegebene Umgebung eine Referenzanzahl; die Anzahl wird auf 1 festgelegt, wenn die Umgebung zum ersten Mal erstellt wird. Wenn eine übereinstimmende Umgebung gefunden wird, wird das Handle dieser Umgebung an die Anwendung zurückgegeben, und die Referenzanzahl wird erhöht. Ein auf diese Weise zugewiesenes Umgebungshandle kann in jeder ODBC-Funktion verwendet werden, die ein Umgebungshandle als Eingabeargument akzeptiert.

Zuordnen eines Verbindungshandles

Ein Verbindungshandle bietet Zugriff auf Informationen wie die gültige Anweisung und die Beschreibungshandles für die Verbindung und ob eine Transaktion derzeit geöffnet ist. Allgemeine Informationen zu Verbindungshandles finden Sie unter "Verbindungshandles".

Um ein Verbindungshandle anzufordern, ruft eine Anwendung SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC auf. Das InputHandle-Argument wird auf das Umgebungshandle festgelegt, das vom Aufruf von SQLAllocHandle zurückgegeben wurde, der dieses Handle zugewiesen hat. Der Treiber weist Speicher für die Verbindungsinformationen zu und übergibt den Wert des zugeordneten Handles zurück in *OutputHandlePtr. Die Anwendung übergibt den Wert *OutputHandlePtr in allen nachfolgenden Aufrufen, die ein Verbindungshandle erfordern. Weitere Informationen finden Sie unter "Zuweisung eines Verbindungshandles".

Der Treiber-Manager verarbeitet die SQLAllocHandle-Funktion und ruft die SQLAllocHandle-Funktion des Treibers auf, wenn die Anwendung SQLConnect, SQLBrowseConnect oder SQLDriverConnect aufruft. (Weitere Informationen finden Sie unter SQLConnect-Funktion.)

Wenn das SQL_ATTR_ODBC_VERSION Umgebungsattribut nicht festgelegt ist, bevor SQLAllocHandle aufgerufen wird, um ein Verbindungshandle für die Umgebung zuzuweisen, gibt der Aufruf zur Zuweisung der Verbindung SQLSTATE HY010 (Funktionssequenzfehler) zurück.

Wenn eine Anwendung SQLAllocHandle aufruft, wobei das InputHandle-Argument auf SQL_HANDLE_DBC festgelegt ist und auch auf ein freigegebenes Umgebungshandle festgelegt ist, versucht der Treiber-Manager, eine vorhandene freigegebene Umgebung zu finden, die den von der Anwendung festgelegten Umgebungsattributen entspricht. Wenn keine solche Umgebung vorhanden ist, wird eine erstellt, mit einer Referenzanzahl (verwaltet vom Treiber-Manager) von 1. Wenn eine übereinstimmende freigegebene Umgebung gefunden wird, wird dieses Handle an die Anwendung zurückgegeben, und die Referenzanzahl wird erhöht.

Die tatsächliche Verbindung, die verwendet wird, wird vom Treiber-Manager erst bestimmt, wenn SQLConnect oder SQLDriverConnect aufgerufen wird. Der Treiber-Manager verwendet die Verbindungsoptionen im Aufruf von SQLConnect (oder die Verbindungsstichwörter im Aufruf von SQLDriverConnect) und die Verbindungsattribute, die nach der Verbindungszuweisung festgelegt wurden, um zu bestimmen, welche Verbindung im Pool verwendet werden soll. Weitere Informationen finden Sie unter SQLConnect-Funktion.

Zuordnen eines Anweisungshandles

Ein Anweisungshandle bietet Zugriff auf Anweisungsinformationen, z. B. Fehlermeldungen, Cursorname und Statusinformationen für die SQL-Anweisungsverarbeitung. Allgemeine Informationen zu Anweisungshandles finden Sie unter "Anweisungshandles".

Um ein Anweisungshandle anzufordern, stellt eine Anwendung eine Verbindung mit einer Datenquelle und dann SQLAllocHandle auf, bevor sql-Anweisungen übermittelt werden. In diesem Aufruf sollte HandleType auf SQL_HANDLE_STMT festgelegt werden, und InputHandle sollte auf das Verbindungshandle festgelegt werden, das vom Aufruf von SQLAllocHandle zurückgegeben wurde, der dieses Handle zugewiesen hat. Der Treiber weist Speicher für die Anweisungsinformationen zu, ordnet das Anweisungshandle der angegebenen Verbindung zu und übergibt den Wert des zugeordneten Handles zurück in *OutputHandlePtr. Die Anwendung übergibt den *OutputHandlePtr-Wert in allen nachfolgenden Aufrufen, die ein Anweisungshandle erfordern. Weitere Informationen finden Sie unter "Zuordnen eines Anweisungshandles".

Wenn der Anweisungshandle zugewiesen wird, weist der Treiber automatisch eine Reihe von vier Deskriptoren zu und weist die Handles für diese Deskriptoren den Attributen SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC und SQL_ATTR_IMP_PARAM_DESC Anweisung zu. Diese werden als implizit zugewiesene Deskriptoren bezeichnet. Informationen zum expliziten Zuweisen eines Anwendungsdeskriptors finden Sie im folgenden Abschnitt " Allocating a Descriptor Handle".

Zuordnen eines Deskriptorhandle

Wenn eine Anwendung SQLAllocHandle mit einem HandleType von SQL_HANDLE_DESC aufruft, weist der Treiber einen Anwendungsdeskriptor zu. Diese werden als explizit zugewiesene Deskriptoren bezeichnet. Die Anwendung leitet einen Treiber an, einen explizit zugewiesenen Anwendungsdeskriptor anstelle eines automatisch zugewiesenen Anwendungsdeskriptors für ein bestimmtes Anweisungshandle zu verwenden, indem die SQLSetStmtAttr-Funktion mit dem attribut SQL_ATTR_APP_ROW_DESC oder SQL_ATTR_APP_PARAM_DESC aufgerufen wird. Ein Implementierungsdeskriptor kann nicht explizit zugewiesen werden, oder ein Implementierungsdeskriptor kann in einem SQLSetStmtAttr-Funktionsaufruf angegeben werden.

Explizit zugewiesene Deskriptoren werden einem Verbindungshandle anstelle eines Anweisungshandle zugeordnet (wie automatisch zugewiesene Deskriptoren sind). Deskriptoren bleiben nur zugewiesen, wenn eine Anwendung tatsächlich mit der Datenbank verbunden ist. Da explizit zugewiesene Deskriptoren einem Verbindungshandle zugeordnet sind, kann eine Anwendung einen explizit zugewiesenen Deskriptor mehreren Anweisungen innerhalb einer Verbindung zuordnen. Ein implizit zugewiesener Anwendungsdeskriptor kann dagegen nicht mehreren Anweisungshandle zugeordnet werden. (Es kann keinem anderen Anweisungshandle als dem zugeordneten Zugeordneten zugeordnet werden.) Explizit zugewiesene Deskriptorhandles können explizit von der Anwendung oder durch Aufrufen von SQLFreeHandle mit einem HandleType von SQL_HANDLE_DESC oder implizit beim Schließen der Verbindung freigegeben werden.

Wenn der explizit zugewiesene Deskriptor freigegeben wird, wird der implizit zugewiesene Deskriptor erneut der Anweisung zugeordnet. (Das attribut SQL_ATTR_APP_ROW_DESC oder SQL_ATTR_APP_PARAM_DESC für diese Anweisung wird erneut auf das implizit zugewiesene Deskriptorhandle festgelegt.) Dies gilt für alle Anweisungen, die dem explizit zugewiesenen Deskriptor für die Verbindung zugeordnet wurden.

Weitere Informationen zu Deskriptoren finden Sie unter Deskriptoren.

Codebeispiel

Siehe Beispiel-ODBC-Programm, SQLBrowseConnect-Funktion, SQLConnect-Funktion und SQLSetCursorName-Funktion.

Verwandte Funktionen

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien