Funkce SQLConnect

Soulad
Zavedená verze: Dodržování standardů ODBC 1.0: ISO 92

Shrnutí
SQLConnect navazuje spojení s ovladačem a datovým zdrojem. Handle spojení odkazuje na ukládání všech informací o připojení ke zdroji dat, včetně stavu, stavu transakce a chybových informací.

Syntax

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

Arguments

ConnectionHandle
[Vstup] Popisovač připojení.

název serveru
[Vstup] Název zdroje dat. Data můžou být umístěná ve stejném počítači jako program nebo v jiném počítači někde v síti. Pro informace o tom, jak aplikace vybírá zdroj dat, viz Volba zdroje dat nebo ovladače.

NameLength1
[Vstup] Délka *ServerName ve znacích.

UserName
[Vstup] Identifikátor uživatele.

NameLength2
[Vstup] Délka *UserName " v znacích.

Authentication
[Vstup] Autentizační řetězec (obvykle heslo).

NameLength3
[Vstup] Délka *Autentizace znaky.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE nebo SQL_STILL_EXECUTING.

Diagnostics

Když SQLConnect vrací SQL_ERROR nebo SQL_SUCCESS_WITH_INFO, lze získat přidruženou hodnotu SQLstate, kterou lze získat voláním SQLGetDiagRec s HandleType SQL_HANDLE_DBC a HandlemConnectionHandle. Následující tabulka uvádí hodnoty SQLSTATE, které SQLConnect obvykle vrací, a vysvětluje každou z nich v kontextu této funkce; notace "(DM)" předchází popisům SQLstavů vráceným Správcem ovladačů. Návratový kód přidružený ke každé hodnotě SQLSTATE je SQL_ERROR, pokud není uvedeno jinak.

Comments

Pro informace o tom, proč aplikace používá SQLConnect, viz Connecting with SQLConnect.

Správce ovladačů se k ovladači nepřipojí, dokud aplikace nezavolá funkci (SQLConnect, SQLDriverConnect nebo SQLBrowseConnect), která se k ovladači připojí. Do té doby Driver Manager pracuje se svými vlastními handlery a spravuje informace o připojení. Když aplikace volá funkci připojení, správce ovladačů kontroluje, zda je ovladač aktuálně připojen pro specifikovaný ConnectionHandle:

• Pokud ovladač není připojen, Driver Manager se k němu připojí a volá SQLAllocHandle pomocí HandleType of SQL_HANDLE_ENV, SQLAllocHandle s HandleType SQL_HANDLE_DBC, SQLSetConnectAttr (pokud aplikace specifikovala nějaké atributy připojení) a funkci spojení v ovladači. Správce ovladačů vrací SQLSTATE IM006 ( SQLSetConnectOption ovladače selhal) a SQL_SUCCESS_WITH_INFO pro funkci připojení, pokud ovladač vrátil chybu pro SQLSetConnectAttr. Pro více informací viz Připojení ke zdroji dat nebo ovladači.

• Pokud je specifikovaný ovladač již připojen na ConnectionHandle, Driver Manager volá pouze funkci připojení v ovladači. V takovém případě musí ovladač zajistit, aby všechny atributy spojení pro ConnectionHandle zůstaly aktuální nastavení.

• Pokud je připojen jiný ovladač, správce ovladačů volá SQLFreeHandle s HandleType SQL_HANDLE_DBC, a pokud není v daném prostředí připojen žádný jiný ovladač, zavolá SQLFreeHandle s HandleType SQL_HANDLE_ENV v připojeném ovladači a poté ovladač odpojí. Poté provádí stejné operace jako když ovladač není připojen.

Ovladač pak alokuje, rukojeti a inicializuje sám sebe.

Když aplikace volá SQLDisconnect, Správce ovladačů volá SQLDisconnect v ovladači. Ovladač se však neodpojí. Tím zůstává ovladač v paměti pro aplikace, které se opakovaně připojují a odpojují od datového zdroje. Když aplikace volá SQLFreeHandle s HandleType SQL_HANDLE_DBC, Driver Manager zavolá SQLFreeHandle s HandleType SQL_HANDLE_DBC a poté SQLFreeHandle s HandleType SQL_HANDLE_ENV v ovladači a poté ovladač odpojí.

Aplikace ODBC může navázat více než jedno spojení.

Pokyny pro řidiče

Obsah *ServerName ovlivňuje, jak Driver Manager a ovladač spolupracují při navázání spojení se zdrojem dat.

• Pokud *ServerName obsahuje platné jméno zdroje dat, správce ovladačů najde odpovídající specifikaci zdroje v systémových informacích a připojí se k příslušnému ovladači. Správce ovladačů předává každý argument SQLConnect ovladači.

• Pokud nelze najít název zdroje dat nebo je ServerName null, Driver Manager najde výchozí specifikaci zdroje dat a připojí se k příslušnému ovladači. Správce ovladačů předá ovladači nezměněné argumenty UserName a Authentication , a "DEFAULT" pro argument ServerName .

• Pokud je argument ServerName "DEFAULT", Driver Manager vyhledá výchozí specifikaci zdroje dat a připojí se k příslušnému ovladači. Správce ovladačů předává každý argument SQLConnect ovladači.

• Pokud nelze najít název zdroje dat nebo je ServerName nullovým ukazatelem a výchozí specifikace zdroje dat neexistuje, správce ovladačů SQL_ERROR vrátí s SQLSTATE IM002 (název zdroje dat nenalezen a výchozí ovladač není specifikován).

Po připojení Driver Managerem může ovladač najít odpovídající specifikaci zdroje dat v systémových informacích a použít specifické informace ze specifikace k dokončení požadované sady informací o připojení.

Pokud je v systémových informacích pro datový zdroj specifikována výchozí překladová knihovna, ovladač se k ní připojí. Jinou překladovou knihovnu lze připojit voláním SQLSetConnectAttr s atributem SQL_ATTR_TRANSLATE_LIB. Možnost překladu lze zvolit voláním SQLSetConnectAttr s atributem SQL_ATTR_TRANSLATE_OPTION.

Pokud ovladač podporuje SQLConnect, musí sekce klíčových slov v systémových informacích pro ovladač obsahovat klíčové slovo ConnectFunctions s prvním znakem nastaveným na "Y."

Sdružování připojení

Poolování spojení umožňuje aplikaci znovu použít již vytvořené spojení. Když je pooling spojení povolen a SQLConnect je volán, Driver Manager se snaží navázat spojení pomocí spojení, které je součástí poolu v prostředí určeném pro pooling spojení. Toto prostředí je sdílené prostředí, které používají všechny aplikace, jež využívají spojení v poolu.

Poolování spojení je povoleno před alokací prostředí voláním SQLSetEnvAttr , které nastaví SQL_ATTR_CONNECTION_POOLING na SQL_CP_ONE_PER_DRIVER (což specifikuje maximálně jeden pool na ovladač) nebo SQL_CP_ONE_PER_HENV (který určuje maximálně jeden pool na prostředí). SQLSetEnvAttr se v tomto případě volá s nastavením EnvironmentHandle na null, což z atributu činí atribut na úrovni procesu. Pokud je SQL_ATTR_CONNECTION_POOLING nastaveno na SQL_CP_OFF, pooling připojení je zakázán.

Po povolení poolingu spojení je SQLAllocHandle s HandleType SQL_HANDLE_ENV vyvolán pro alokaci prostředí. Prostředí přidělené tímto hovorem je sdílené prostředí, protože pooling spojení bylo povoleno. Prostředí, které bude použito, však není určeno, dokud není vyvolán SQLAllocHandle s HandleType SQL_HANDLE_DBC.

SQLAllocHandle s HandleType of SQL_HANDLE_DBC je volán k alokaci spojení. Správce ovladačů se snaží najít existující sdílené prostředí, které odpovídá atributům nastaveným aplikací. Pokud takové prostředí neexistuje, vytváří se jako implicitní sdílené prostředí. Pokud je nalezeno odpovídající sdílené prostředí, aplikaci se vrátí handle prostředí a jeho počet referencí se zvýší.

Připojení, které bude použito, však není určeno až do vyvolání SQLConnect . V tu chvíli se Driver Manager snaží najít existující spojení v poolu připojení, které splňuje kritéria požadovaná aplikací. Tato kritéria zahrnují možnosti připojení požadované při volání do SQLConnect (hodnoty klíčových slov ServerName, UserName a Authenticing ) a jakékoli atributy připojení nastavené od vyvolání SQLAllocHandle s HandleType SQL_HANDLE_DBC. Driver Manager kontroluje tato kritéria podle odpovídajících klíčových slov a atributů spojení v rámci poolu. Pokud se najde shoda, použije se spojení v poolu. Pokud se nenajde shoda, vytvoří se nové spojení.

Pokud je atribut SQL_ATTR_CP_MATCH prostředí nastaven na SQL_CP_STRICT_MATCH, musí být shoda přesná, aby bylo možné použít spojení v poolu. Pokud je atribut SQL_ATTR_CP_MATCH prostředí nastaven na SQL_CP_RELAXED_MATCH, musí se možnosti připojení ve volání SQLConnect shodovat, ale ne všechny atributy spojení.

Následující pravidla se aplikují, když atribut spojení, nastavený aplikací před voláním SQLConnect , neodpovídá atributu spojení spojení v poolu:

• Pokud musí být atribut spojení nastaven před navázáním spojení:

  Pokud je SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH, musí být SQL_ATTR_PACKET_SIZE ve spojení ve skupině totožné s atributovou sadou aplikace. Pokud SQL_CP_RELAXED_MATCH, hodnoty SQL_ATTR_PACKET_SIZE mohou být různé.

  Hodnota SQL_ATTR_LOGIN_VALUE neovlivňuje samotný zápas.

• Pokud lze atribut spojení nastavit buď před, nebo po navázání spojení:

  Pokud atribut spojení nebyl nastaven aplikací, ale byl nastaven na spojení ve skupině a existuje výchozí nastavení, atribut spojení ve skupině se vrátí na výchozí hodnotu a je deklarováno shodování. Pokud nedojde k defaultu, spojené spojení se nepovažuje za shodu.

  Pokud byl atribut spojení nastaven aplikací, ale nebyl nastaven na spojení v poolu, atribut connection v poolu se změní na atribut nastavený aplikací a je deklarováno shoda.

  Pokud byl atribut spojení nastaven aplikací a byl také nastaven na spojení v poolu, ale hodnoty jsou odlišné, použije se hodnota atributu spojení aplikace a je deklarováno shodování.

• Pokud hodnoty atributů spojení specifických pro ovladač nejsou totožné a SQL_ATTR_CP_MATCH je nastaveno na SQL_CP_STRICT_MATCH, spojení v poolu se nepoužívá.

Když aplikace zavolá SQLDisconnect k odpojení, spojení se vrátí do poolu a je k dispozici pro opětovné použití.

Optimalizace výkonu poolingu spojení

Pokud jsou zapojeny distribuované transakce, je možné optimalizovat výkon poolingu spojení pomocí SQL_DTC_TRANSITION_COST, což je SQLUINTEGER bitmask. Přechody, o kterých se mluví, jsou přechody atributu spojení SQL_ATTR_ENLIST_IN_DTC přechodu z hodnoty 0 do nenulové hodnoty a naopak. Jedná se o spojení přechodu z nezařazení do distribuované transakce na zařazení do distribuované transakce a naopak. V závislosti na tom, jak řidič implementoval zařazení (nastavení atributu spojení SQL_ATTR_ENLIST_IN_DTC), mohou být tyto přechody nákladné a proto by se jim mělo vyhnout pro nejlepší výkon.

Hodnota vrácená ovladačem obsahuje libovolnou kombinaci následujících bitů:

• SQL_DTC_ENLIST_EXPENSIVE, když je nastaven, znamená, že přechod z nuly na nenulu je výrazně dražší než přechod z nenulového na jinou nenulovou hodnotu (při začlenění dříve zapsaného spojení do další transakce).

• SQL_DTC_UNENLIST_EXPENSIVE, když je nastaveno, znamená, že přechod z nenuly na nulu je výrazně dražší než použití spojení, jehož atribut SQL_ATTR_ENLIST_IN_DTC je již nastaven na nulu.

Existuje kompromis mezi výkonem a využitím připojení. Pokud ovladač uvede, že jeden nebo více těchto přechodů je nákladné, správce ovladačů na to reaguje tím, že ponechá více spojení ve skupině. Některá spojení v poolu jsou preferována pro netransakční použití, jiná pro transakční použití. Pokud však ovladač uvádí, že tyto přechody nejsou nákladné, lze použít méně spojení, možná střídavě mezi netransakčním a transakčním použitím.

Ovladače, které nepodporují SQL_ATTR_ENLIST_IN_DTC, nemusí podporovat SQL_DTC_TRANSITION_COST. U ovladačů, které podporují SQL_ATTR_ENLIST_IN_DTC, ale ne SQL_DTC_TRANSITION_COST, se předpokládá, že přechody nejsou drahé, jako by ovladač vracel 0 (bez nastavených bitů) pro tuto hodnotu.

Ačkoliv byl SQL_DTC_TRANSITION_COST zaveden v ODBC 3.5, ODBC 2. Ovladač X jej také podporuje, protože správce ovladačů tyto informace dotazuje bez ohledu na verzi ovladače.

Příklad kódu

V následujícím příkladu aplikace přiděluje prostředí a kontaktní handle. Poté se připojí ke zdroji dat SalesOrders s uživatelským ID JohnS a heslem Sesame a zpracovává data. Po dokončení zpracování dat se odpojí od zdroje dat a uvolní rukojeti.

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

Související funkce

Viz také

Referenční rozhraní ODBC API
Soubory hlaviček ODBC