SQLConnect-Funktion

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

Zusammenfassung
SQLConnect stellt Verbindungen mit einem Treiber und einer Datenquelle her. Das Verbindungshandle verweist auf den Speicher aller Informationen zur Verbindung mit der Datenquelle, einschließlich Status, Transaktionsstatus und Fehlerinformationen.

Syntax

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

Argumente

ConnectionHandle
[Eingabe] Verbindungshandle.

ServerName
[Eingabe] Datenquellenname. Die Daten befinden sich möglicherweise auf demselben Computer wie das Programm oder auf einem anderen Computer in einem Netzwerk. Informationen dazu, wie eine Anwendung eine Datenquelle auswählt, finden Sie unter Auswählen einer Datenquelle oder eines Treibers.

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

UserName
[Eingabe] Benutzerbezeichner.

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

Authentifizierung
[Eingabe] Authentifizierungszeichenfolge (in der Regel das Kennwort).

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

Gibt zurück

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE oder SQL_STILL_EXECUTING.

Diagnose

Wenn SQLConnect SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_DBC und einem Handle of ConnectionHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die normalerweise von SQLConnect 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.

Kommentare

Informationen dazu, warum eine Anwendung SQLConnect verwendet, finden Sie unter Herstellen einer Verbindung mit SQLConnect.

Der Treiber-Manager stellt erst dann eine Verbindung mit einem Treiber her, wenn die Anwendung eine Funktion (SQLConnect, SQLDriverConnect oder SQLBrowseConnect) aufruft, um eine Verbindung mit dem Treiber herzustellen. Bis zu diesem Punkt arbeitet der Treiber-Manager mit seinen eigenen Handles und verwaltet Verbindungsinformationen. Wenn die Anwendung eine Verbindungsfunktion aufruft, überprüft der Treiber-Manager, ob für den angegebenen ConnectionHandle derzeit eine Verbindung mit einem Treiber besteht:

• Wenn ein Treiber nicht mit verbunden ist, stellt der Treiber-Manager eine Verbindung mit dem Treiber her und ruft SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV, SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC, SQLSetConnectAttr (wenn die Anwendung Verbindungsattribute angegeben hat) und die Verbindungsfunktion im Treiber auf. Der Treiber-Manager gibt SQLSTATE IM006 (Fehler beim SqlSetConnectOption-Treiber ) und SQL_SUCCESS_WITH_INFO für die Verbindungsfunktion zurück, wenn der Treiber einen Fehler für SQLSetConnectAttr zurückgegeben hat. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit einer Datenquelle oder einem Treiber.

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

• Wenn ein anderer Treiber mit einem anderen Treiber verbunden ist, ruft der Treiber-Manager SQLFreeHandle mit einem HandleType von SQL_HANDLE_DBC auf, und wenn kein anderer Treiber in dieser Umgebung verbunden ist, ruft er SQLFreeHandle mit einem HandleType von SQL_HANDLE_ENV im verbundenen Treiber auf und trennt diesen Treiber dann. Anschließend werden die gleichen Vorgänge ausgeführt, mit denen ein Treiber nicht verbunden ist.

Der Treiber ordnet dann Handles zu und initialisiert sich selbst.

Wenn die Anwendung SQLDisconnect aufruft, ruft der Treiber-Manager SQLDisconnect im Treiber auf. Der Treiber wird jedoch nicht getrennt. Dadurch bleibt der Treiber im Arbeitsspeicher für Anwendungen, die wiederholt eine Verbindung mit einer Datenquelle herstellen und diese trennen. Wenn die Anwendung SQLFreeHandle mit einem HandleType von SQL_HANDLE_DBC aufruft, ruft der Treiber-Manager SQLFreeHandle mit einem HandleType von SQL_HANDLE_DBC und dann SQLFreeHandle mit einem HandleType von SQL_HANDLE_ENV im Treiber auf und trennt dann den Treiber.

Eine ODBC-Anwendung kann mehrere Verbindungen herstellen.

Treiber-Manager-Richtlinien

Der Inhalt von *ServerName wirkt sich darauf aus, wie der Treiber-Manager und ein Treiber zusammenarbeiten, um eine Verbindung mit einer Datenquelle herzustellen.

• Wenn *ServerName einen gültigen Datenquellennamen enthält, sucht der Treiber-Manager die entsprechende Datenquellenspezifikation in den Systeminformationen und stellt eine Verbindung mit dem zugeordneten Treiber her. Der Treiber-Manager übergibt jedes SQLConnect-Argument an den Treiber.

• Wenn der Datenquellenname nicht gefunden werden kann oder ServerName ein NULL-Zeiger ist, sucht der Treiber-Manager die Standarddatenquellenspezifikation und stellt eine Verbindung mit dem zugeordneten Treiber her. Der Treiber-Manager übergibt an den Treiber die Argumente UserName und Authentication unverändert und "DEFAULT" für das Argument ServerName .

• Wenn das ServerName-Argument "DEFAULT" lautet, sucht der Treiber-Manager die Standarddatenquellenspezifikation und stellt eine Verbindung mit dem zugeordneten Treiber her. Der Treiber-Manager übergibt jedes SQLConnect-Argument an den Treiber.

• Wenn der Datenquellenname nicht gefunden werden kann oder ServerName ein NULL-Zeiger ist und die Standarddatenquellenspezifikation nicht vorhanden ist, gibt der Treiber-Manager SQL_ERROR mit SQLSTATE IM002 zurück (Datenquellenname nicht gefunden und kein Standardtreiber angegeben).

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

Wenn in den Systeminformationen für die Datenquelle eine Standardübersetzungsbibliothek angegeben ist, stellt der Treiber eine Verbindung mit dieser her. Eine andere Übersetzungsbibliothek kann durch Aufrufen von SQLSetConnectAttr mit dem attribut SQL_ATTR_TRANSLATE_LIB verbunden werden. Eine Übersetzungsoption kann durch Aufrufen von SQLSetConnectAttr mit dem attribut SQL_ATTR_TRANSLATE_OPTION angegeben werden.

Wenn ein Treiber SQLConnect unterstützt, muss der Treiberschlüsselwortabschnitt der Systeminformationen für den Treiber das Schlüsselwort ConnectFunctions enthalten, wobei das erste Zeichen auf "Y" festgelegt ist.

Verbindungspooling

Verbindungspooling ermöglicht es einer Anwendung, eine bereits erstellte Verbindung wiederzuverwenden. Wenn verbindungspooling aktiviert und SQLConnect aufgerufen wird, versucht der Treiber-Manager, die Verbindung mithilfe einer Verbindung herzustellen, die Teil eines Verbindungspools in einer Umgebung ist, die für verbindungspooling festgelegt wurde. Diese Umgebung ist eine freigegebene Umgebung, die von allen Anwendungen verwendet wird, die die Verbindungen im Pool verwenden.

Verbindungspooling wird aktiviert, bevor die Umgebung zugeordnet wird, indem SQLSetEnvAttr aufgerufen wird, um SQL_ATTR_CONNECTION_POOLING auf SQL_CP_ONE_PER_DRIVER (die maximal einen Pool pro Treiber angibt) oder SQL_CP_ONE_PER_HENV (der maximal einen Pool pro Umgebung angibt) festzulegen. SQLSetEnvAttr wird in diesem Fall aufgerufen, wobei EnvironmentHandle auf NULL festgelegt ist, wodurch das Attribut zu einem Attribut auf Prozessebene wird. Wenn SQL_ATTR_CONNECTION_POOLING auf SQL_CP_OFF festgelegt ist, ist das Verbindungspooling deaktiviert.

Nachdem das Verbindungspooling aktiviert wurde, wird SQLAllocHandle mit einem HandleType von SQL_HANDLE_ENV aufgerufen, um eine Umgebung zuzuordnen. Die durch diesen Aufruf zugeordnete Umgebung ist eine freigegebene Umgebung, da Verbindungspooling aktiviert wurde. Die verwendete 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 zuzuordnen. Der Treiber-Manager versucht, eine vorhandene freigegebene Umgebung zu finden, die den von der Anwendung festgelegten Umgebungsattributen entspricht. Wenn keine solche Umgebung vorhanden ist, wird eine als implizite freigegebene Umgebung erstellt. Wenn eine übereinstimmende freigegebene Umgebung gefunden wird, wird das Umgebungshandle an die Anwendung zurückgegeben, und die Verweisanzahl wird erhöht.

Die verwendete Verbindung wird jedoch erst bestimmt, wenn SQLConnect aufgerufen wird. An diesem Punkt versucht der Treiber-Manager, eine vorhandene Verbindung im Verbindungspool zu finden, die den von der Anwendung angeforderten Kriterien entspricht. Zu diesen Kriterien gehören die beim Aufruf von SQLConnect angeforderten Verbindungsoptionen (die Werte der Schlüsselwörter ServerName, UserName und Authentication ) sowie alle Verbindungsattribute, die seit SQLAllocHandle mit einem HandleType von SQL_HANDLE_DBC aufgerufen wurden. Der Treiber-Manager überprüft diese Kriterien mit den entsprechenden Verbindungsstichwörtern und Attributen in Verbindungen im Pool. Wenn eine Übereinstimmung gefunden wird, wird die Verbindung im Pool verwendet. Wenn keine Übereinstimmung gefunden wird, wird eine neue Verbindung erstellt.

Wenn das SQL_ATTR_CP_MATCH-Umgebungsattribut auf SQL_CP_STRICT_MATCH festgelegt ist, muss die Übereinstimmung genau sein, damit eine Verbindung im Pool verwendet werden kann. Wenn das SQL_ATTR_CP_MATCH-Umgebungsattribut auf SQL_CP_RELAXED_MATCH festgelegt ist, müssen die Verbindungsoptionen im Aufruf von SQLConnect übereinstimmen, aber nicht alle Verbindungsattribute müssen übereinstimmen.

Die folgenden Regeln werden angewendet, wenn ein Verbindungsattribute, wie es von der Anwendung vor dem Aufruf von SQLConnect festgelegt wurde, nicht mit dem Verbindungssattribut der Verbindung im Pool übereinstimmt:

• Wenn das Verbindungssattribut festgelegt werden muss, bevor die Verbindung hergestellt wird:

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

  Der Wert von SQL_ATTR_LOGIN_VALUE wirkt sich nicht auf die Übereinstimmung aus.

• Wenn das Verbindungsattribute entweder vor oder nach dem Herstellen der Verbindung festgelegt werden kann:

  Wenn das Verbindungssattribut nicht von der Anwendung festgelegt wurde, sondern für die Verbindung im Pool festgelegt wurde und eine Standardeinstellung vorhanden ist, wird das Verbindungsattribute in der gepoolten Verbindung auf den Standardwert zurückgesetzt, und eine Übereinstimmung wird deklariert. Wenn kein Standardwert vorhanden ist, wird die gepoolte Verbindung nicht als Übereinstimmung betrachtet.

  Wenn das Verbindungsattribute von der Anwendung festgelegt wurde, aber nicht für die Verbindung im Pool festgelegt wurde, wird das Verbindungsattribute im Pool in das von der Anwendung festgelegte Attribut geändert, und es wird eine Übereinstimmung deklariert.

  Wenn das Verbindungsattribute von der Anwendung festgelegt wurde und auch für die Verbindung im Pool festgelegt wurde, die Werte jedoch unterschiedlich sind, wird der Wert des Verbindungsattributes der Anwendung verwendet und eine Übereinstimmung deklariert.

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

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

Optimieren der Leistung von Verbindungspools

Wenn verteilte Transaktionen beteiligt sind, ist es möglich, die Leistung des Verbindungspools mithilfe von SQL_DTC_TRANSITION_COST zu optimieren, bei der es sich um eine SQLUINTEGER-Bitmaske handelt. Die übergänge, auf die verwiesen wird, sind die Übergänge des Verbindungsattributes SQL_ATTR_ENLIST_IN_DTC von Wert 0 zu ungleich null und umgekehrt. Dies ist eine Verbindung, die von nicht in einer verteilten Transaktion eingetragen ist, bis hin zur Registrierung in einer verteilten Transaktion und umgekehrt. Je nachdem, wie der Treiber die Registrierung implementiert hat (Festlegen des Verbindungsattributes SQL_ATTR_ENLIST_IN_DTC), können diese Übergänge teuer sein und sollten daher für eine optimale Leistung vermieden werden.

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

• SQL_DTC_ENLIST_EXPENSIVE impliziert, dass der Übergang von Null zu Null ungleich Null erheblich teurer ist als ein Übergang von ungleich null zu einem anderen Wert ungleich null (die Aufnahme einer zuvor eingetragenen Verbindung in der nächsten Transaktion).

• SQL_DTC_UNENLIST_EXPENSIVE bedeutet, dass der Übergang ungleich null zu null erheblich teurer ist als die Verwendung einer Verbindung, deren SQL_ATTR_ENLIST_IN_DTC Attribut bereits auf Null festgelegt ist.

Es gibt einen Kompromiss zwischen Leistung und Verbindungsnutzung. Wenn ein Treiber angibt, dass einer oder mehrere dieser Übergänge teuer sind, reagiert der Verbindungspooler des Treiber-Managers darauf, indem er mehr Verbindungen im Pool behält. Einige Der Verbindungen im Pool werden für die nicht transaktionale Verwendung bevorzugt, und einige werden für die transaktionale Verwendung bevorzugt. Wenn der Treiber jedoch angibt, dass diese Übergänge nicht teuer sind, können weniger Verbindungen verwendet werden, was möglicherweise zwischen nicht-transaktionaler und transaktionaler Verwendung wechselt.

Treiber, die keine SQL_ATTR_ENLIST_IN_DTC unterstützen, müssen SQL_DTC_TRANSITION_COST nicht unterstützen. Für Treiber, die SQL_ATTR_ENLIST_IN_DTC, aber keine SQL_DTC_TRANSITION_COST unterstützen, wird davon ausgegangen, dass die Übergänge nicht teuer sind, als ob der Treiber 0 (keine Bits festgelegt) für diesen Wert zurückgegeben hätte.

Obwohl SQL_DTC_TRANSITION_COST in ODBC 3.5 eingeführt wurde, ist odbc 2. Der x-Treiber kann dies auch unterstützen, da der Treiber-Manager diese Informationen unabhängig von der Treiberversion abfragt.

Codebeispiel

Im folgenden Beispiel ordnet eine Anwendung Umgebung und Verbindungshandles zu. Anschließend stellt er eine Verbindung mit der Datenquelle SalesOrders mit der Benutzer-ID JohnS und dem Kennwort Sesame her und verarbeitet Daten. Wenn die Verarbeitung der Daten abgeschlossen ist, wird die Verbindung mit der Datenquelle getrennt und die Handles freigegeben.

// 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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien