SQLConnect-függvény

Megfelelőség
Bevezetett verzió: ODBC 1.0 szabványmegfelelőség: ISO 92

Összefoglalás
Az SQLConnect kapcsolatot teremt egy illesztőgéphez és egy adatforráshoz. A kapcsolat kezelő minden adatforráshoz kapcsolódó információ tárolására utal, beleértve az állapotot, tranzakciós állapotot és hibainformációkat.

Syntax

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

Arguments

ConnectionHandle
[Bemenet] Kapcsolati leíró.

Kiszolgálónév
[Bemenet] Adatforrás név. Előfordulhat, hogy az adatok ugyanazon a számítógépen találhatók, mint a program, vagy egy másik számítógépen, valahol egy hálózaton. Arról, hogyan választja ki egy alkalmazás az adatforrást, lásd: Adatforrás vagy driver kiválasztása.

NameLength1
[Bemenet] A *ServerName hossza karakterekben.

UserName
[Bemenet] Felhasználói azonosító.

NameLength2
[Bemenet] A *UserName hossza karakterekben.

Authentication
[Bemenet] Hitelesítési string (általában a jelszó).

NameLength3
[Bemenet] *Hitelesítés karakterben történő hitelesítés hossza.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE vagy SQL_STILL_EXECUTING.

Diagnostics

Amikor az SQLConnect SQL_ERROR vagy SQL_SUCCESS_WITH_INFO értéket ad vissza, egy hozzárendelt SQLSTATE érték elérhető SQLGetDiagRec hívásával, amely egy SQL_HANDLE_DBC HandleType és egy ConnectionHandleHandle nevű HandleType segítségével szól. Az alábbi táblázat felsorolja az SQLConnect által általában visszaadott SQLSTATE értékeket, és mindegyiket ennek a függvénynek a kontextusában magyarázza; a "(DM)" jelölés megelőzi a Driver Manager által visszaadott SQLSTATE-leírásokat. Az egyes SQLSTATE-értékekhez társított visszatérési kód SQL_ERROR, kivéve, ha másként van feltüntetve.

Comments

Arról, miért használja egy alkalmazás SQLConnect-et, lásd: Kapcsolat SQLConnect-vel.

A Driver Manager nem csatlakozik egy driverhez, amíg az alkalmazás nem hív egy függvényt (SQLConnect, SQLDriverConnect vagy SQLBrowseConnect) az illesztőprogramhoz. Addig a Driver Manager saját kezelőfelületekkel dolgozik és kezeli a kapcsolati információkat. Amikor az alkalmazás kapcsolati függvényt hív, az Driver Manager ellenőrzi, hogy jelenleg csatlakozik-e egy illezőgéphez a megadott ConnectionHandle esetében:

• Ha egy illesztőprogramhoz nincs csatlakoztatva, a Driver Manager csatlakozik hozzá, és az SQLAllocHandle-t hívja SQL_HANDLE_ENV HandleType-vel , SQLAllocHandle-t SQL_HANDLE_DBC HandleType-vel , SQLSetConnectAttr-t (ha az alkalmazás bármilyen kapcsolati attribútumot megad), valamint az illesztőprogramban lévő kapcsolati funkcióval. A Driver Manager visszaadja az SQLSTATE IM006-ot (az illezser SQLSetConnectOption hibásodott), és SQL_SUCCESS_WITH_INFO a csatlakozási függvényre, ha az illesztőprogram SQLSetConnectAttr hibát mutat be. További információért lásd: Adatforráshoz vagy meghajtóhoz való csatlakozás.

• Ha a megadott illezőgép már csatlakozik a ConnectionHandle-en, a Driver Manager csak a csatlakozási funkciót hívja az illesztőprogramban. Ebben az esetben a meghajtónak biztosítania kell, hogy a ConnectionHandle összes kapcsolati attribútumja megőrizze aktuális beállításait.

• Ha egy másik illesztőprogramhoz csatlakozik, a Driver Manager a SQLFreeHandle-t hívja SQL_HANDLE_DBC HandleType-val , majd ha nincs más illesztőprogramhoz csatlakoztatva abban a környezetben, akkor a SQLFreeHandle-t hívja SQL_HANDLE_ENV HandleType-jével a csatlakoztatott driverben, majd leválasztja azt az illesztőprogramot. Ezután ugyanazokat a műveleteket végzi, mint amikor egy meghajtóhoz nincs csatlakoztatva.

Ezután a meghajtó kiosztja a fogantyúkat és inicializálja magát.

Amikor az alkalmazás meghívja az SQLDisconnectet, az Illesztőprogram-kezelő meghívja az SQLDisconnectet az illesztőprogramban. Azonban nem kapcsolja le a meghajtót. Ez megtartja az illesztőprogramot a memóriában azoknál az alkalmazásoknál, amelyek ismételten csatlakoznak és leválasztják az adatforrást. Amikor az alkalmazás SQL_HANDLE_DBC HandleType-valhívja az SQLFreeHandle-t, a Driver Manager a SQLFreeHandle-t SQL_HANDLE_DBC HandleType-jével, majd SQLFreeHandle-t SQL_HANDLE_ENV HandleType-jével a driverben, majd lecsatlakoztatja a drivert.

Egy ODBC alkalmazás több kapcsolatot is létrehozhat.

Versenyzővezetői irányelvek

A *ServerName tartalma befolyásolja, hogyan működik együtt a Driver Manager és egy driver az adatforráshoz való kapcsolat létrehozásában.

• Ha a *ServerName érvényes adatforrás nevet tartalmaz, a Driver Manager megtalálja a megfelelő adatforrás specifikációt a rendszerinformációk között, és csatlakozik a hozzá tartozó illesztőprogramhoz. A Driver Manager minden SQLConnect argumentumot továbbít az illesztővezetőnek.

• Ha az adatforrás neve nem található, vagy a ServerName null mutató, a Driver Manager megtalálja az alapértelmezett adatforrás specifikációt, és csatlakozik a hozzá tartozó illesztőprogramhoz. A Driver Manager módosítatlanul továbbítja a UserName és Authentication argumentumokat, valamint a "DEFAULT" jelet a ServerName argumentumhoz.

• Ha a ServerName érve "DEFAULT", akkor a Driver Manager megtalálja az alapértelmezett adatforrás specifikációt, és csatlakozik a hozzá tartozó illesztőprogramhoz. A Driver Manager minden SQLConnect argumentumot továbbít az illesztővezetőnek.

• Ha az adatforrás neve nem található meg, vagy a ServerName null mutató, és az alapértelmezett adatforrás specifikáció nem létezik, akkor a Driver Manager SQL_ERROR SQLSTATE IM002-vel (adatforrás név nem található meg és alapértelmezett illesztőprogram nincs megadva).

Miután a Driver Manager csatlakozott hozzá, az illesztőprogram megtalálhatja a megfelelő adatforrás specifikációját a rendszerinformációkban, és a specifikációból származó illesztő-specifikus információkat felhasználva kiegészítheti a szükséges kapcsolati információkat.

Ha az adatforrás rendszerinformációiban egy alapértelmezett fordítókönyvtár van megadva, az illesztőprogram csatlakozik hozzá. Egy másik fordító könyvtárhoz csatlakoztatható az SQLSetConnectAttr hívásával a SQL_ATTR_TRANSLATE_LIB attribútummal. Fordítási opció megadható úgy, hogy az SQLSetConnectAttr hívása a SQL_ATTR_TRANSLATE_OPTION attribútummal szól.

Ha egy illesztőprogram támogatja az SQLConnect-et, akkor a meghajtó rendszerinformációinak kulcsszószekciójában tartalmaznia kell a ConnectFunctions kulcsszót, amelynek első karaktere "Y" lesz.

Kapcsolatkészlet-kezelés

A kapcsolat pooling lehetővé teszi, hogy az alkalmazás újrahasznosítsa a már létrehozott kapcsolatot. Amikor a kapcsolat pooling engedélyezett és az SQLConnect hívása történik, a Driver Manager megpróbálja létrehozni a kapcsolatot egy olyan kapcsolat segítségével, amely egy olyan környezetben található kapcsolati készlet része, amelyet a kapcsolat poolingra kijelöltek. Ez a környezet egy megosztott környezet, amelyet minden alkalmazás használ, amely használja a pool kapcsolatait.

A kapcsolat pooling engedélyezése a környezet kiosztása előtt az SQLSetEnvAttr hívásával történik, hogy SQL_ATTR_CONNECTION_POOLING SQL_CP_ONE_PER_DRIVER-re állítsuk be (ami egy meghajtónként maximum egy poolot jelöl meg) vagy SQL_CP_ONE_PER_HENV (amely környezetenként maximum egy poolot jelöl meg). Az SQLSetEnvAttr ebben az esetben a EnvironmentHandle null-ra állítva hívják, ami az attribútumot folyamatszintű attribútummá teszi. Ha SQL_ATTR_CONNECTION_POOLING SQL_CP_OFF-re van állítva, a kapcsolat poolingolása letiltott.

A kapcsolat pooling engedélyezése után az SQLAllocHandle egy SQL_HANDLE_ENV HandleType segítségével meghívják a környezet kijelölésére. A hívás által kijelölt környezet megosztott környezet, mivel a kapcsolat pooling engedélyezve van. Azonban a használt környezetet csak akkor határozzák meg, ha az SQLAllocHandle egy SQL_HANDLE_DBC HandleType segítségével meghívjuk.

Az SQLAllocHandle egy SQL_HANDLE_DBC HandleType segítségével hívják meg a kapcsolat kijelölésére. A Driver Manager megpróbál találni egy meglévő megosztott környezetet, amely megfelel az alkalmazás által beállított környezeti attribútumoknak. Ha ilyen környezet nem létezik, akkor az implicit megosztott környezetként jön létre. Ha találunk egy megfelelő megosztott környezetet, a környezeti handle visszakerül az alkalmazáshoz, és annak hivatkozási száma növekedik.

Azonban a használt kapcsolatot csak akkor határozzák meg, ha az SQLConnect meghívása történik. Ekkor a Driver Manager megpróbál találni egy meglévő kapcsolatot a kapcsolati poolban, amely megfelel az alkalmazás által kért kritériumoknak. Ezek a kritériumok közé tartoznak az SQLConnect hívásban kért kapcsolati opciók (a ServerName, UserName és Authentication kulcsszavak értékei), valamint az SQLAllocHandle SQL_HANDLE_DBC HandleType meghívása óta beállított kapcsolat attribútumok. A Driver Manager ezeket a kritériumokat ellenőrzi a megfelelő kapcsolati kulcsszavakkal és attribútumokkal a poolban lévő kapcsolatokban. Ha találnak egyezést, a medencében lévő kapcsolatot használják. Ha nem talál egyezést, új kapcsolat jön létre.

Ha a SQL_ATTR_CP_MATCH környezeti attribútumot SQL_CP_STRICT_MATCH-re állították, akkor a párosításnak pontosnak kell lennie ahhoz, hogy a poolban lévő kapcsolatot használhassanak. Ha a SQL_ATTR_CP_MATCH környezet attribútuma SQL_CP_RELAXED_MATCH-re van beállítva, akkor az SQLConnect hívásában lévő kapcsolati opcióknak egyezniük kell, de nem minden kapcsolati attribútumnak kell egyeznie.

Az alábbi szabályokat alkalmazzák, ha egy kapcsolat attribútum, amelyet az alkalmazás az SQLConnect meghívása előtt állított be, nem egyezik meg a poolban lévő kapcsolat kapcsolat attribútumával:

• Ha a kapcsolat attribútumát be kell állítani a kapcsolat létrehozása előtt:

  Ha SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH, akkor a SQL_ATTR_PACKET_SIZE a pooled kapcsolatban azonosnak kell lennie az alkalmazás által adott attribútumhalmazsal. Ha SQL_CP_RELAXED_MATCH, akkor SQL_ATTR_PACKET_SIZE értékei eltérhetnek.

  A SQL_ATTR_LOGIN_VALUE értéke nem befolyásolja a párosítást.

• Ha a kapcsolat attribútuma beállítható a kapcsolat előtt vagy után:

  Ha az alkalmazás nem állította be a kapcsolat attribútumát, hanem a poolban lévő kapcsolaton állította be, és van alapértelmezett tulajdonság, akkor a csatlakozó attribútumot visszaállítják az alapértelmezettre, és egyezést hirdetnek. Ha nincs alapértelmezett opció, a közös kapcsolatot nem tekintik egyezésnek.

  Ha az alkalmazás beállította a kapcsolat attribútumot, de a poolban lévő kapcsolaton nem állították be, akkor a poolban lévő kapcsolat attribútumát az alkalmazás által állított attribútumra változtatják, és egyezést hirdetnek.

  Ha az alkalmazás beállította a kapcsolat attribútumot, és a poolban lévő kapcsolaton is beállították, de az értékek eltérnek, akkor az alkalmazás kapcsolat attribútumának értékét használják, és egyezést hirdetnek.

• Ha az illesztőprogram-specifikus kapcsolati attribútumok értékei nem azonosak, és SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH-re van állítva, akkor a poolban lévő kapcsolatot nem használják.

Amikor az alkalmazás az SQLDisconnectet hívja a megszakításra, a kapcsolat visszakerül a kapcsolati poolba, és újrahasználható.

A kapcsolat pooling teljesítményének optimalizálása

Elosztott tranzakciók esetén a kapcsolat pooling teljesítményének optimalizálása lehetséges SQL_DTC_TRANSITION_COST használatával, amely SQLUINTEGER bitmaszk. Az említett átmenetek a kapcsolati attribútum SQL_ATTR_ENLIST_IN_DTC 0-ról nulláról nem nullára való átmenetei, illetve fordítva. Ez egy olyan kapcsolat, amely elosztott tranzakcióban nem szerepel egy elosztott tranzakcióban való bejegyzett állapotból egy elosztott tranzakcióba való belépésre, és fordítva. Attól függően, hogyan valósította meg a sofőr a besorolást (a kapcsolati attribútum beállítása SQL_ATTR_ENLIST_IN_DTC), ezek az átmenetek drágák lehetnek, ezért a legjobb teljesítmény érdekében kerülni kell őket.

A meghajtó által visszaadott érték az alábbi bitek bármely kombinációját tartalmazza:

• SQL_DTC_ENLIST_EXPENSIVE, ha beállítva állítva, azt feltételezi, hogy a nulláról nulláról nem nullára való átmenet jelentősen drágább, mint a nulláról egy másik nulla értékre való átmenet (egy korábban regisztrált kapcsolat bevonása a következő tranzakcióba).

• SQL_DTC_UNENLIST_EXPENSIVE, ha beállítva állíta, azt jelenti, hogy a nulláról nullára való átmenet jelentősen drágább, mint egy olyan kapcsolat használata, amelynek SQL_ATTR_ENLIST_IN_DTC attribútuma már nullára van állítva.

Van egy teljesítmény és kapcsolathasználat közötti kompromisszum. Ha egy driver jelezi, hogy ezek közül egy vagy több átmenet költséges, a driver manager connection pooler erre reagál azzal, hogy több kapcsolatot tart a poolban. A pool néhány kapcsolata nem tranzakciós használatra preferált, míg néhány tranzakciós használatra. Ha azonban a meghajtó jelezi, hogy ezek az átmenetek nem drágák, kevesebb kapcsolat használható, esetleg váltakozva a nem tranzakciós és tranzakciós használat között.

Azok a driverek, amelyek nem támogatják SQL_ATTR_ENLIST_IN_DTC, nem kell támogatniuk SQL_DTC_TRANSITION_COST. Azoknál a drivereknél, amelyek SQL_ATTR_ENLIST_IN_DTC-t támogatnak, de nem SQL_DTC_TRANSITION_COST, feltételezik, hogy az átmenetek nem drágák, mintha az illesztőprogram 0-t (bit nélkül) adna vissza ehhez az értékhez.

Bár SQL_DTC_TRANSITION_COST az ODBC 3.5-ben jelent meg, egy ODBC 2. Az X driver is támogathatja, mert a driver manager függetlenül lekérdezi ezeket az információkat, függetlenül a meghajtó verziótól.

Kódpélda

A következő példában egy alkalmazás a környezetet és a kapcsolati handle-eket osztja ki. Ezután csatlakozik a SalesOrders adatforráshoz a JohnS felhasználóazonosítóval és a Sesame jelszóval, és feldolgozza az adatokat. Amikor befejezi az adatfeldolgozást, elválik az adatforrástól, és felszabadítja a fogantyúkat.

// 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);  
   }  
}  

Kapcsolódó funkciók

Lásd még

ODBC API-referencia
ODBC-fejlécfájlok