SQLAllocHandle-Funktion

  • Artikel

Konformität
Version eingeführt: ODBC 3.0-Normenkonformität: ISO 92

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

Hinweis

Diese Funktion ist eine generische Funktion zum Zuweisen von Handles, die die ODBC 2.0-Funktionen SQLAllocConnect, SQLAllocEnv und SQLAllocStmt ersetzt. Damit Anwendungen, die SQLAllocHandle aufrufen, mit ODBC 2 arbeiten können x-Treiber : Ein Aufruf von SQLAllocHandle wird im Treiber-Manager sqlAllocConnect, SQLAllocEnv oder SQLAllocStmt zugeordnet. Weitere Informationen finden Sie unter Kommentare. Weitere Informationen dazu, was der Treiber-Manager diese Funktion bei ODBC 3 ordnet. Die x-Anwendung arbeitet mit ODBC 2. x-Treiber , siehe Zuordnen von Ersatzfunktionen für die Abwärtskompatibilität von Anwendungen.

Syntax

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

Argumente

HandleType
[Eingabe] Der Typ des handle, 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 Handle-Typ nicht verwenden. Weitere Informationen zu SQL_HANDLE_DBC_INFO_TOKEN finden Sie unter Entwickeln Connection-Pool Awareness in einem ODBC-Treiber.

InputHandle
[Eingabe] Das Eingabehandle, in dessen Kontext das neue Handle zugeordnet 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 handelt.

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

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE oder SQL_ERROR.

Wenn SQLAllocHandle beim Zuweisen eines anderen Handles als ein Umgebungshandle SQL_ERROR zurückgibt, legt es OutputHandlePtr je nach Wert von HandleType auf SQL_NULL_HDBC, SQL_NULL_HSTMT oder SQL_NULL_HDESC fest, es sei denn, das Ausgabeargument ist ein NULL-Zeiger. Die Anwendung kann dann zusätzliche Informationen aus der Diagnosedatenstruktur abrufen, die dem Handle im Argument InputHandle zugeordnet ist.

Zuordnungsfehler bei Der Umgebungshandle

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 arbeitsspeicher für *OutputHandlePtr nicht zuordnen kann, wenn SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV aufgerufen wird oder die Anwendung einen NULL-Zeiger 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 NULL-Zeiger bereitgestellt, der SQL_ERROR zurückgibt). Es gibt keinen Handle, dem zusätzliche Diagnoseinformationen zugeordnet werden sollen.

Der Treiber-Manager ruft die Zuordnungsfunktion der Umgebung 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-, SQLBrowseConnect- oder SQLDriverConnect-Funktion auf Treiber-Manager-Ebene SQL_ERROR zurück. Die Diagnosedatenstruktur enthält SQLSTATE IM004 (Fehler beim SqlAllocHandle-Treiber ). 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-Funktion.

Diagnose

Wenn SQLAllocHandle SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec aufgerufen wird, wobei der entsprechende HandleType und Handle auf den Wert von InputHandle festgelegt sind. 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 normalerweise von SQLAllocHandle zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

SQLSTATE Fehler BESCHREIBUNG
01000 Allgemeine Warnung Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.)
08003 Verbindung nicht geöffnet (DM) Das HandleType-Argument wurde SQL_HANDLE_STMT oder SQL_HANDLE_DESC, aber die durch das InputHandle-Argument angegebene Verbindung war nicht geöffnet. Der Verbindungsvorgang muss erfolgreich abgeschlossen werden (und die Verbindung muss geöffnet sein), damit der Treiber eine Anweisung oder ein Deskriptorhandle zuweisen kann.
HY000 Allgemeiner Fehler Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache.
HY001 Fehler bei der Speicherbelegung (DM) Der Treiber-Manager konnte dem angegebenen Handle keinen Arbeitsspeicher zuweisen.

Der Treiber konnte dem angegebenen Handle keinen Arbeitsspeicher zuweisen.
HY009 Ungültige Verwendung von NULL-Zeiger (DM) Das OutputHandlePtr-Argument war ein NULL-Zeiger.
HY010 Funktionssequenzfehler (DM) Das HandleType-Argument wurde SQL_HANDLE_DBC, und SQLSetEnvAttr wurde nicht aufgerufen, um das SQL_ODBC_VERSION-Umgebungsattribut festzulegen.

(DM) Eine asynchron ausgeführte Funktion wurde für InputHandle aufgerufen und wurde weiterhin ausgeführt, als die SQLAllocHandle-Funktion aufgerufen wurde, wobei HandleType auf SQL_HANDLE_STMT oder SQL_HANDLE_DESC festgelegt wurde.
HY013 Fehler bei der Speicherverwaltung Das HandleType-Argument wurde SQL_HANDLE_DBC, SQL_HANDLE_STMT oder SQL_HANDLE_DESC; und der Funktionsaufruf konnte nicht verarbeitet werden, weil auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen.
HY014 Grenzwert für die Anzahl überschrittener Handles Der vom Treiber definierte Grenzwert für die Anzahl der Handles, die für den Typ des Handles zugeordnet werden können, der durch das HandleType-Argument angegeben wird, wurde erreicht.
HY092 Ungültiger Attribut-/Optionsbezeichner (DM) Das HandleType-Argument lautete nicht: SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT oder SQL_HANDLE_DESC.
HY117 Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen und schreibgeschützte Funktionen sind zulässig. (DM) Weitere Informationen zum Angehaltenen Zustand finden Sie unter SQLEndTran-Funktion.
HYC00 Optionale Funktion nicht implementiert Das HandleType-Argument wurde SQL_HANDLE_DESC, und der Treiber war ein ODBC 2.The HandleType argument is is SQL_HANDLE_DESC and the driver is an ODBC 2. x-Treiber .
HYT01 Verbindungstimeout abgelaufen Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitraum für das Verbindungstimeout wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT.
IM001 Der Treiber unterstützt diese Funktion nicht. (DM) Das HandleType-Argument wurde SQL_HANDLE_STMT, und der Treiber war kein gültiger ODBC-Treiber.

(DM) Das HandleType-Argument wurde SQL_HANDLE_DESC, und der Treiber unterstützt die Zuordnung eines Deskriptorhandles nicht.

Kommentare

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

Mehrere Umgebungs-, Verbindungs- oder Anweisungshandles können von einer Anwendung gleichzeitig zugewiesen werden, wenn mehrere Zuordnungen vom Treiber unterstützt werden. In ODBC ist kein Grenzwert für die Anzahl von Umgebungs-, Verbindungs-, Anweisungs- oder Deskriptorhandles definiert, die gleichzeitig zugeordnet werden können. Treiber können eine Begrenzung für die Anzahl eines bestimmten Typs von Griffen festlegen, die jeweils zugeordnet werden können; Weitere Informationen finden Sie in der Treiberdokumentation.

Wenn die Anwendung SQLAllocHandle aufruft und *OutputHandlePtr auf ein bereits vorhandenes Umgebungs-, Verbindungs-, Anweisungs- oder Deskriptorhandle festgelegt ist, überschreibt der Treiber die dem Handle zugeordneten Informationen, es sei denn, die Anwendung verwendet Verbindungspooling (siehe "Zuweisung eines Umgebungsattributs für Verbindungspooling" weiter unten in diesem Abschnitt). Der Treiber-Manager überprüft weder, ob das in *OutputHandlePtreingegebene Handle bereits verwendet wird, noch überprüft er den vorherigen Inhalt eines Handles, bevor er sie überschreibt.

Hinweis

Es ist eine falsche ODBC-Anwendungsprogrammierung, SQLAllocHandle zweimal mit derselben Anwendungsvariable aufzurufen, die für *OutputHandlePtr definiert ist, ohne SQLFreeHandle aufzurufen, um das Handle vor der Neuzuweisung freizugeben. Das Überschreiben von ODBC-Handles auf diese Weise kann zu inkonsistentem Verhalten oder Fehlern von ODBC-Treibern führen.

Unter Betriebssystemen, die mehrere Threads unterstützen, können Anwendungen die gleiche Umgebung, Verbindung, Anweisung oder Deskriptorhandle für verschiedene Threads verwenden. Treiber müssen daher einen sicheren Multithreadzugriff auf diese Informationen unterstützen. Eine Möglichkeit, dies zu erreichen, ist beispielsweise 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 standardkonforme Anwendungen wird SQLAllocHandle zur Kompilierzeit SQLAllocHandleStd zugeordnet. Der Unterschied zwischen diesen beiden Funktionen besteht darin, dass SQLAllocHandleStd das SQL_ATTR_ODBC_VERSION environment-Attribut auf SQL_OV_ODBC3 festlegt, wenn es aufgerufen wird, wobei das HandleType-Argument auf SQL_HANDLE_ENV festgelegt ist. Dies geschieht, da standardkonforme Anwendungen immer ODBC 3 sind. x-Anwendungen . Darüber hinaus erfordern die Standards keine Registrierung der Anwendungsversion. 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 , um das SQL_ATTR_ODBC_VERSION-Umgebungsattribut auf SQL_OV_ODBC3_80 festzulegen.

Zuordnen eines Umgebungshandles

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

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

Wenn unter dem Umgebungshandle eines Treiber-Managers bereits ein Umgebungshandle des Treibers vorhanden ist, wird SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV in diesem Treiber nicht aufgerufen, wenn eine Verbindung hergestellt wird, nur SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC. Wenn das Umgebungshandle eines Treibers unter dem Umgebungshandle des Treiber-Managers nicht 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 Ablaufverfolgungsflag festgelegt ist, beginnt die Ablaufverfolgung, wenn das erste Umgebungshandle zugewiesen wird, und endet, wenn das letzte Umgebungshandle freigegeben wird. Weitere Informationen finden Sie unter Konfigurieren von Datenquellen.

Nach der Zuordnung eines Umgebungshandles muss eine Anwendung SQLSetEnvAttr für das Umgebungshandle aufrufen, um das SQL_ATTR_ODBC_VERSION-Umgebungsattribut festzulegen. Wenn dieses Attribut nicht festgelegt ist, bevor SQLAllocHandle aufgerufen wird, um ein Verbindungshandle für die Umgebung zuzuweisen, gibt der Aufruf zum Zuweisen 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 für mehrere Komponenten in einem einzelnen Prozess gemeinsam genutzt werden. Eine freigegebene Umgebung kann von mehreren Komponenten gleichzeitig verwendet werden. Wenn eine Komponente eine freigegebene Umgebung verwendet, kann sie Poolverbindungen verwenden, sodass sie eine vorhandene Verbindung zuordnen und verwenden kann, ohne diese Verbindung erneut zu erstellen.

Vor der Zuordnung einer freigegebenen Umgebung, die für das Verbindungspooling verwendet werden kann, muss eine Anwendung SQLSetEnvAttr aufrufen, um das SQL_ATTR_CONNECTION_POOLING environment-Attribut auf SQL_CP_ONE_PER_DRIVER oder SQL_CP_ONE_PER_HENV festzulegen. SQLSetEnvAttr wird in diesem Fall aufgerufen, wobei EnvironmentHandle auf NULL festgelegt ist, wodurch das Attribut zu einem Attribut auf Prozessebene wird.

Nachdem das Verbindungspooling aktiviert wurde, ruft eine Anwendung SQLAllocHandle auf, wobei das HandleType-Argument auf SQL_HANDLE_ENV festgelegt ist. Die durch diesen Aufruf zugewiesene Umgebung ist eine implizite freigegebene Umgebung, da das 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. An diesem Punkt 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 eine Referenzanzahl für jede freigegebene Umgebung. die Anzahl wird beim ersten Erstellen der Umgebung auf 1 festgelegt. Wenn eine übereinstimmende Umgebung gefunden wird, wird das Handle dieser Umgebung an die Anwendung zurückgegeben, und die Verweisanzahl wird erhöht. Ein so zugeordnetes Umgebungshandle kann in jeder ODBC-Funktion verwendet werden, die ein Umgebungshandle als Eingabeargument akzeptiert.

Zuordnen eines Verbindungshandles

Ein Verbindungshandle ermöglicht den Zugriff auf Informationen wie die gültige Anweisung und die Deskriptorhandles für die Verbindung und darüber, 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 Argument InputHandle wird auf das Umgebungshandle festgelegt, das vom Aufruf von SQLAllocHandle zurückgegeben wurde, das diesem Handle zugeordnet ist. Der Treiber weist Arbeitsspeicher für die Verbindungsinformationen zu und übergibt den Wert des zugeordneten Handles in *OutputHandlePtr zurück. Die Anwendung übergibt den Wert *OutputHandlePtr in allen nachfolgenden Aufrufen, die ein Verbindungshandle erfordern. Weitere Informationen finden Sie unter Zuweisen eines Verbindungshandles.

Der Treiber-Manager verarbeitet die FUNKTION SQLAllocHandle 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 zum Zuweisen der Verbindung SQLSTATE HY010 (Funktionssequenzfehler) zurück.

Wenn eine Anwendung SQLAllocHandle aufruft, wobei das Argument InputHandle 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 mit einer Referenzanzahl (vom Treiber-Manager verwaltet) von 1 erstellt. Wenn eine übereinstimmende freigegebene Umgebung gefunden wird, wird dieses Handle an die Anwendung zurückgegeben, und die Verweisanzahl wird erhöht.

Die tatsächliche Verbindung, die verwendet wird, wird erst vom Treiber-Manager bestimmt, wenn SQLConnect oder SQLDriverConnect aufgerufen wird. Der Treiber-Manager verwendet die Verbindungsoptionen im Aufruf von SQLConnect (oder die Verbindungsschlüsselwörter im Aufruf von SQLDriverConnect) und die Nach der Verbindungszuordnung festgelegten Verbindungsattribute, 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 wie Fehlermeldungen, den Cursornamen 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 her und ruft dann SQLAllocHandle auf, bevor SQL-Anweisungen übermittelt werden. In diesem Aufruf sollte HandleType auf SQL_HANDLE_STMT und InputHandle auf das Verbindungshandle festgelegt werden, das durch den Aufruf von SQLAllocHandle zurückgegeben wurde, der diesem Handle zugeordnet ist. Der Treiber weist Arbeitsspeicher 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 Wert *OutputHandlePtr in allen nachfolgenden Aufrufen, die ein Anweisungshandle erfordern. Weitere Informationen finden Sie unter Zuweisen eines Anweisungshandles.

Wenn das Anweisungshandle zugewiesen wird, weist der Treiber automatisch einen Satz von vier Deskriptoren zu und weist die Handles für diese Deskriptoren den SQL_ATTR_APP_ROW_DESC-, SQL_ATTR_APP_PARAM_DESC-, SQL_ATTR_IMP_ROW_DESC- und SQL_ATTR_IMP_PARAM_DESC-Anweisungsattributen zu. Diese werden als implizit zugeordnete Deskriptoren bezeichnet. Informationen zum expliziten Zuweisen eines Anwendungsdeskriptors finden Sie im folgenden Abschnitt unter Zuweisen eines Deskriptorhandles.

Zuweisen eines Deskriptorhandles

Wenn eine Anwendung SQLAllocHandle mit einem HandleType von SQL_HANDLE_DESC aufruft, weist der Treiber einen Anwendungsdeskriptor zu. Diese werden als explizit zugeordnete Deskriptoren bezeichnet. Die Anwendung weist einen Treiber an, einen explizit zugeordneten 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 weder explizit zugeordnet werden, noch kann ein Implementierungsdeskriptor in einem SQLSetStmtAttr-Funktionsaufruf angegeben werden.

Explizit zugeordnete Deskriptoren sind einem Verbindungshandle anstelle eines Anweisungshandles zugeordnet (wie automatisch zugeordnete Deskriptoren). Deskriptoren bleiben nur dann zugeordnet, wenn eine Anwendung tatsächlich mit der Datenbank verbunden ist. Da explizit zugeordnete Deskriptoren einem Verbindungshandle zugeordnet sind, kann eine Anwendung einen explizit zugeordneten Deskriptor mehr als einer Anweisung innerhalb einer Verbindung zuordnen. Ein implizit zugeordneter Anwendungsdeskriptor kann dagegen nicht mehr als einem Anweisungshandle zugeordnet werden. (Es kann keinem anderen Anweisungshandle als dem 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 freigegeben werden, wenn die Verbindung geschlossen wird.

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

Weitere Informationen zu Deskriptoren finden Sie unter Deskriptoren.

Codebeispiel

Weitere Informationen finden Sie unter Beispiel-ODBC-Programm, SQLBrowseConnect-Funktion, SQLConnect-Funktion und SQLSetCursorName-Funktion.

Informationen über Finden Sie unter
Ausführen einer SQL-Anweisung SQLExecDirect-Funktion
Ausführen einer vorbereiteten SQL-Anweisung SQLExecute-Funktion
Freigeben eines Umgebungs-, Verbindungs-, Anweisungs- oder Deskriptorhandles SQLFreeHandle-Funktion
Vorbereiten einer Anweisung für die Ausführung SQLPrepare-Funktion
Festlegen eines Verbindungsattributes SQLSetConnectAttr-Funktion
Festlegen eines Deskriptorfelds SQLSetDescField-Funktion
Festlegen eines Umgebungsattributs SQLSetEnvAttr-Funktion
Festlegen eines Anweisungsattributs SQLSetStmtAttr-Funktion

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien