SQLConnect-Funktion

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

Zusammenfassung
SQLConnect stellt Verbindungen zu einem Treiber und einer Datenquelle her. Der Verbindungs-Handle bezieht sich auf die Speicherung aller Informationen über die Verbindung zur Datenquelle, einschließlich Status, Transaktionsstatus und Fehlerinformationen.

Syntax

  
SQLRETURN SQLConnect(  
     SQLHDBC        ConnectionHandle,  
     SQLCHAR *      ServerName,  
     SQLSMALLINT    NameLength1,  
     SQLCHAR *      UserName,  
     SQLSMALLINT    NameLength2,  
     SQLCHAR *      Authentication,  
     SQLSMALLINT    NameLength3);  

Arguments

ConnectionHandle
[Eingabe] Verbindungshandle.

ServerName
[Eingabe] Name der Datenquelle. Die Daten können sich auf demselben Computer befinden wie das Programm oder auf einem anderen Computer irgendwo in einem Netzwerk. Informationen darüber, wie eine Anwendung eine Datenquelle auswählt, finden Sie unter Wahl einer Datenquelle oder eines Treibers.

NameLength1
[Eingabe] Länge von *ServerName in Zeichen.

UserName
[Eingabe] Benutzerkennung.

NameLength2
[Eingabe] Länge von *BenutzerName in Zeichen.

Authentifizierung
[Eingabe] Authentifizierungsstring (typischerweise das Passwort).

NameLength3
[Eingabe] Länge der *Authentifizierung in Zeichen.

Rückkehr

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_STILL_EXECUTING.

Diagnostics

Wenn SQLConnect SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugehöriger SQLSTATE-Wert erhalten werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_DBC und einem Handle von ConnectionHandle aufgerufen wird. Die folgende Tabelle listet die typischerweise von SQLConnect zurückgegebenen SQLSTATE-Werte auf und erklärt jeden einzelnen im Kontext dieser Funktion; die Notation "(DM)" geht den vom Treibermanager zurückgegebenen SQLSTATE-Beschreibungen voraus. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

Für Informationen darüber, warum eine Anwendung SQLConnec verwendet, siehe Connecting with SQLConnect.

Der Driver Manager verbindet sich erst mit einem Treiber, wenn die Anwendung eine Funktion (SQLConnect, SQLDriverConnect oder SQLBrowseConnect) aufruft, um sich mit dem Treiber zu verbinden. Bis zu diesem Zeitpunkt arbeitet der Driver Manager mit eigenen Handles und verwaltet die Verbindungsinformationen. Wenn die Anwendung eine Verbindungsfunktion aufruft, prüft der Driver Manager, ob derzeit ein Treiber für das angegebene ConnectionHandle verbunden ist:

• Wenn ein Treiber nicht verbunden ist, verbindet sich der Treibermanager mit dem Treiber und ruft SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV, SQLAllocHandle mit einem HandleType SQL_HANDLE_DBC, SQLSetConnectAttr (falls die Anwendung Verbindungsattribute angegeben hat) und die Verbindungsfunktion im Treiber auf. Der Treibermanager gibt SQLSTATE IM006 zurück (Treibers SQLSetConnectOption fehlgeschlagen) und SQL_SUCCESS_WITH_INFO für die Verbindungsfunktion, wenn der Treiber einen Fehler für SQLSetConnectAttr zurückgab. Weitere Informationen finden Sie unter Verbindung zu einer Datenquelle oder einem Treiber.

• Wenn der angegebene Treiber bereits auf dem ConnectionHandle verbunden ist, ruft der Treibermanager nur die Verbindungsfunktion im Treiber auf. In diesem Fall muss der Treiber sicherstellen, dass alle Verbindungsattribute für den ConnectionHandle ihre aktuellen Einstellungen beibehalten.

• Wenn ein anderer Treiber verbunden ist, ruft der Treibermanager SQLFreeHandle mit einem HandleType von SQL_HANDLE_DBC auf, und wenn in dieser Umgebung kein anderer Treiber verbunden ist, ruft er SQLFreeHandle mit einem HandleType von SQL_HANDLE_ENV im verbundenen Treiber auf und trennt diesen Treiber. Anschließend führt er die gleichen Operationen aus wie wenn ein Treiber nicht angeschlossen ist.

Der Treiber weist dann Handles zu und initialisiert sich selbst.

Wenn die Anwendung SQLDisconnect aufruft, ruft der Treiber-Manager SQLDisconnect im Treiber auf. Allerdings trennt er den Treiber nicht. Dies hält den Treiber im Speicher für Anwendungen, die wiederholt eine Datenquelle verbinden und von ihr trennen. Wenn die Anwendung SQLFreeHandle mit einem HandleType SQL_HANDLE_DBC aufruft, ruft der Treibermanager SQLFreeHandle mit einem HandleType SQL_HANDLE_DBC und dann SQLFreeHandle mit einem HandleType SQL_HANDLE_ENV im Treiber und trennt dann den Treiber.

Eine ODBC-Anwendung kann mehr als eine Verbindung herstellen.

Richtlinien für Fahrermanager

Der Inhalt von *ServerName beeinflusst, wie der Driver Manager und ein Treiber zusammenarbeiten, um eine Verbindung zu einer Datenquelle herzustellen.

• Wenn *ServerName einen gültigen Datenquellennamen enthält, findet der Treibermanager die entsprechende Datenquellenspezifikation in den Systeminformationen und verbindet sich mit dem zugehörigen Treiber. Der Driver Manager übergibt jedes SQLConnect-Argument an den Treiber.

• Wenn der Name der Datenquelle nicht gefunden wird oder ServerName ein Nullzeiger ist, findet der Driver Manager die Standard-Datenquellenspezifikation und verbindet sich mit dem zugehörigen Treiber. Der Driver Manager übergibt dem Treiber die UserName- und Authentifizierungsargumente unverändert sowie "DEFAULT" für das ServerName-Argument .

• Wenn das ServerName-Argument "DEFAULT" ist, sucht der Driver Manager die Standard-Datenquellenspezifikation und verbindet sich mit dem zugehörigen Treiber. Der Driver Manager übergibt jedes SQLConnect-Argument an den Treiber.

• Wenn der Name der Datenquelle nicht gefunden wird oder ServerName ein Nullzeiger ist und die Standard-Datenquellenspezifikation nicht existiert, gibt der Treibermanager SQL_ERROR mit SQLSTATE IM002 zurück (Datenquellenname nicht gefunden und kein Standardtreiber angegeben).

Nachdem sie vom Driver Manager verbunden wurde, kann ein Treiber seine entsprechende Datenquellenspezifikation in den Systeminformationen finden und treiberspezifische Informationen aus der Spezifikation verwenden, um die erforderlichen Verbindungsinformationen zu vervollständigen.

Wenn in den Systeminformationen der Datenquelle eine Standard-Übersetzungsbibliothek angegeben ist, verbindet sich der Treiber damit. Eine andere Übersetzungsbibliothek kann durch Aufruf von SQLSetConnectAttr mit dem Attribut SQL_ATTR_TRANSLATE_LIB verbunden werden. Eine Übersetzungsoption kann durch Aufruf von SQLSetConnectAttr mit dem Attribut SQL_ATTR_TRANSLATE_OPTION angegeben werden.

Wenn ein Treiber SQLConnect unterstützt, muss der Abschnitt für das Schlüsselwort des Treibers in den Systeminformationen des Treibers das ConnectFunctions-Schlüsselwort mit dem ersten Zeichensatz "Y" enthalten.

Verbindungspooling

Connection Pooling ermöglicht es einer Anwendung, eine bereits erstellte Verbindung wiederzuverwenden. Wenn Connection Pooling aktiviert und SQLConnect aufgerufen wird, versucht der Driver Manager, die Verbindung über eine Verbindung herzustellen, die Teil eines Pool von Verbindungen in einer für Connection Pooling vorgesehenen Umgebung ist. Diese Umgebung ist eine gemeinsame Umgebung, die von allen Anwendungen genutzt wird, die die Verbindungen im Pool nutzen.

Connection Pooling wird vor der Zuweisung der Umgebung aktiviert, indem SQLSetEnvAttr aufgerufen wird, um SQL_ATTR_CONNECTION_POOLING auf SQL_CP_ONE_PER_DRIVER zu setzen (was maximal einen Pool pro Treiber angibt) oder SQL_CP_ONE_PER_HENV (der maximal einen Pool pro Umgebung vorgibt). SQLSetEnvAttr wird in diesem Fall mit EnvironmentHandle auf null gesetzt, was das Attribut zu einem Prozess-Attribut macht. Wenn SQL_ATTR_CONNECTION_POOLING auf SQL_CP_OFF gesetzt ist, wird das Connection Pooling deaktiviert.

Nachdem das Connection Pooling aktiviert wurde, wird SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV aufgerufen, um eine Umgebung zuzuweisen. Die von diesem Aufruf zugewiesene Umgebung ist eine geteilte Umgebung, da Connection Pooling aktiviert wurde. Die zu verwendende Umgebung wird jedoch erst bestimmt, wenn SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC aufgerufen wird.

SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC wird aufgerufen, um eine Verbindung zuzuweisen. Der Driver Manager versucht, eine bestehende gemeinsame Umgebung zu finden, die mit den von der Anwendung festgelegten Umgebungsattributen übereinstimmt. Wenn keine solche Umgebung existiert, wird eine als implizite gemeinsame Umgebung geschaffen. Wenn eine passende gemeinsame Umgebung gefunden wird, wird der Umgebungshandle an die Anwendung zurückgegeben und die Referenzanzahl erhöht.

Die verwendete Verbindung wird jedoch erst bestimmt, wenn SQLConnect aufgerufen wird. An diesem Punkt versucht der Driver Manager, eine bestehende Verbindung im Verbindungspool zu finden, die den von der Anwendung geforderten Kriterien entspricht. Diese Kriterien umfassen die im Aufruf zu SQLConnect angeforderten Verbindungsoptionen (die Werte der ServerName-, Benutzernamen- und Authentifizierungsschlüsselwörter ) sowie alle seit dem Aufruf von SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC gesetzten Verbindungsattribute. Der Driver Manager prüft diese Kriterien mit den entsprechenden Verbindungsschlüsselwörtern und -attributen in Verbindungen im Pool. Wenn ein Match gefunden wird, wird die Verbindung im Pool verwendet. Wenn kein Match gefunden wird, wird eine neue Verbindung erstellt.

Wenn das Attribut SQL_ATTR_CP_MATCH environment auf SQL_CP_STRICT_MATCH gesetzt ist, muss das Match exakt sein, damit eine Verbindung im Pool verwendet werden kann. Wenn das Attribut SQL_ATTR_CP_MATCH Umgebung auf SQL_CP_RELAXED_MATCH gesetzt ist, müssen die Verbindungsoptionen im Aufruf zu SQLConnect übereinstimmen, aber nicht alle Verbindungsattribute müssen übereinstimmen.

Die folgenden Regeln gelten, wenn ein Verbindungsattribut, wie es von der Anwendung vor dem Aufruf von SQLConnect gesetzt wurde, nicht mit dem Verbindungsattribut der Verbindung im Pool übereinstimmt:

• Wenn das Verbindungsattribut gesetzt werden muss, bevor die Verbindung hergestellt wird:

  Wenn SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH ist, muss SQL_ATTR_PACKET_SIZE in der Pool-Verbindung identisch mit dem von der Anwendung gesetzten Attribut sein. Wenn SQL_CP_RELAXED_MATCH, können die Werte von SQL_ATTR_PACKET_SIZE unterschiedlich sein.

  Der Wert von SQL_ATTR_LOGIN_VALUE beeinflusst das Match nicht.

• Wenn das Verbindungsattribut entweder vor oder nach der Verbindung gesetzt werden kann:

  Wenn das Verbindungsattribut nicht von der Anwendung gesetzt wurde, sondern auf die Verbindung im Pool, und es gibt ein Standard-Attribut, wird das Verbindungsattribut in der gepoolten Verbindung wieder auf den Standard gesetzt und ein Match wird deklariert. Wenn es keinen Standard gibt, gilt die gepoolte Verbindung nicht als Match.

  Wenn das Verbindungsattribut von der Anwendung gesetzt wurde, aber nicht auf die Verbindung im Pool, wird das Verbindungsattribut im Pool auf das von der Anwendung gesetzte Attribut geändert und ein Match wird deklariert.

  Wenn das Verbindungsattribut von der Anwendung gesetzt wurde und auch auf die Verbindung im Pool gesetzt wurde, aber die Werte unterschiedlich sind, wird der Wert des Verbindungsattributs der Anwendung verwendet und ein Match deklariert.

• Wenn die Werte der treiberspezifischen Verbindungsattribute nicht identisch sind und SQL_ATTR_CP_MATCH auf SQL_CP_STRICT_MATCH gesetzt ist, wird die Verbindung im Pool nicht verwendet.

Wenn die Anwendung SQLDisconnect aufruft, um die Verbindung zu trennen, wird die Verbindung dem Verbindungspool zurückgegeben und steht zur Wiederverwendung zur Verfügung.

Optimierung der Connection Pooling-Leistung

Bei verteilten Transaktionen ist es möglich, die Connection Pooling-Leistung durch SQL_DTC_TRANSITION_COST zu optimieren, eine SQLUINTEGER-Bitmaske. Die genannten Übergänge sind die Übergänge des Verbindungsattributs, SQL_ATTR_ENLIST_IN_DTC von Wert 0 auf ungleich null geht, und umgekehrt. Dies ist eine Verbindung, die von "nicht in einer verteilten Transaktion" zu "aufgenommen" in einer verteilten Transaktion und umgekehrt geht. Je nachdem, wie der Treiber die Enlistment implementiert hat (Einstellung des Verbindungsattributs SQL_ATTR_ENLIST_IN_DTC), können diese Übergänge teuer sein und sollten daher für die beste Leistung vermieden werden.

Der vom Treiber zurückgegebene Wert enthält eine beliebige Kombination der folgenden Bits:

• SQL_DTC_ENLIST_EXPENSIVE, wenn gesetzt, impliziert, dass der Übergang von null zu null deutlich teurer ist als ein Übergang von nicht null zu einem anderen von null verschiedenen Wert (indem eine zuvor gelistete Verbindung in die nächste Transaktion eingebunden wird).

• SQL_DTC_UNENLIST_EXPENSIVE, wenn gesetzt, impliziert, dass der Übergang von Null zu Null deutlich teurer ist als die Verwendung einer Verbindung, deren SQL_ATTR_ENLIST_IN_DTC Attribut bereits auf Null gesetzt ist.

Es gibt einen Kompromiss zwischen Leistung und Verbindungsnutzung. Wenn ein Treiber angibt, dass einer oder mehrere dieser Übergänge teuer sind, reagiert der Connection Pooler des Treibermanagers darauf, indem er mehr Verbindungen im Pool behält. Einige der Verbindungen im Pool werden für nicht-transaktionale Zwecke bevorzugt, andere für transaktionale Zwecke. Wenn der Treiber jedoch angibt, dass diese Übergänge nicht teuer sind, können weniger Verbindungen genutzt werden, möglicherweise durch Wechsel zwischen nicht-transaktionaler und transaktionaler Nutzung.

Treiber, die SQL_ATTR_ENLIST_IN_DTC nicht unterstützen, müssen SQL_DTC_TRANSITION_COST nicht unterstützen. Für Treiber, die SQL_ATTR_ENLIST_IN_DTC, aber nicht SQL_DTC_TRANSITION_COST unterstützen, wird angenommen, dass die Übergänge nicht teuer sind, als ob der Treiber 0 (ohne gesetzte Bits) für diesen Wert zurückgeben würde.

Obwohl SQL_DTC_TRANSITION_COST in ODBC 3.5 eingeführt wurde, wurde ein ODBC 2. Der X-Treiber kann dies ebenfalls unterstützen, da der Treibermanager diese Informationen unabhängig von der Treiberversion abfragt.

Codebeispiel

Im folgenden Beispiel weist eine Anwendung Umgebungs- und Verbindungsgriffe zu. Anschließend verbindet er sich mit der Verkaufsorder-Datenquelle mit der Benutzer-ID JohnS und dem Passwort Sesame und verarbeitet die Daten. Wenn die Datenverarbeitung abgeschlossen ist, trennt er sich von der Datenquelle und befreit die Handles.

// SQLConnect_ref.cpp  
// compile with: odbc32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR * OutConnStr = (SQLCHAR * )malloc(255);  
   SQLSMALLINT * OutConnStrLen = (SQLSMALLINT *)malloc(255);  
  
   // Allocate environment handle  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
  
   // Set the ODBC version environment attribute  
   if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
      retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (void*)SQL_OV_ODBC3, 0);   
  
      // Allocate connection handle  
      if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
         retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
  
         // Set login timeout to 5 seconds  
         if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
            SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
            // Connect to data source  
            retcode = SQLConnect(hdbc, (SQLCHAR*) "NorthWind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
  
            // Allocate statement handle  
            if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
               retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);   
  
               // Process data  
               if (retcode == SQL_SUCCESS || retcode == SQL_SUCCESS_WITH_INFO) {  
                  SQLFreeHandle(SQL_HANDLE_STMT, hstmt);  
               }  
  
               SQLDisconnect(hdbc);  
            }  
  
            SQLFreeHandle(SQL_HANDLE_DBC, hdbc);  
         }  
      }  
      SQLFreeHandle(SQL_HANDLE_ENV, henv);  
   }  
}  

Verwandte Funktionen

Siehe auch

ODBC-API-Referenz
ODBC-Headerdateien