SQLConnect-functie

Conformiteit
Versie geïntroduceerd: NALEVING van ODBC 1.0-standaarden: ISO 92

Samenvatting
SQLConnect legt verbindingen met een driver en een databron. De verbindingshandtak verwijst naar opslag van alle informatie over de verbinding naar de databron, inclusief status, transactiestatus en foutinformatie.

Syntax

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

Arguments

ConnectionHandle
[Invoer] Verbindingsgreep.

Servernaam
[Invoer] Naam van de gegevensbron. De gegevens bevinden zich mogelijk op dezelfde computer als het programma of op een andere computer ergens in een netwerk. Voor informatie over hoe een applicatie een databron kiest, zie Kies van een gegevensbron of driver.

NameLength1
[Invoer] Lengte van *ServerName in tekens.

UserName
[Invoer] Gebruikersidentificatie.

NameLength2
[Invoer] Lengte van *Gebruikersnaam in tekens.

Authentication
[Invoer] Authenticatiestring (meestal het wachtwoord).

NameLength3
[Invoer] Lengte van *Authenticatie in tekens.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE of SQL_STILL_EXECUTING.

Diagnostics

Wanneer SQLConnect SQL_ERROR of SQL_SUCCESS_WITH_INFO teruggeeft, kan een bijbehorende SQLSTATE-waarde worden verkregen door SQLGetDiagRec aan te roepen met een HandleType van SQL_HANDLE_DBC en een Handle van ConnectionHandle. De volgende tabel geeft een overzicht van de SQLSTATE-waarden die doorgaans door SQLConnect worden teruggegeven en legt elk uit in de context van deze functie; de notatie "(DM)" gaat vooraf aan de beschrijvingen van SQLSTATES die door de Driver Manager worden teruggegeven. De retourcode die is gekoppeld aan elke SQLSTATE-waarde is SQL_ERROR, tenzij anders vermeld.

Comments

Voor informatie over waarom een applicatie SQLConnect gebruikt, zie Connecting with SQLConnect.

De Driver Manager maakt pas verbinding met een driver als de applicatie een functie aanroept (SQLConnect, SQLDriverConnect of SQLBrowseConnect) om verbinding te maken met de driver. Tot dat moment werkt de Driver Manager met zijn eigen handles en beheert hij verbindingsinformatie. Wanneer de applicatie een verbindingsfunctie aanroept, controleert de Driver Manager of er momenteel een driver is verbonden voor de opgegeven ConnectionHandle:

• Als een driver niet is verbonden, verbindt de Driver Manager met de driver en roept SQLAllocHandle aan met een HandleType van SQL_HANDLE_ENV, SQLAllocHandle met een HandleType van SQL_HANDLE_DBC, SQLSetConnectAttr (als de applicatie verbindingsattributen heeft gespecificeerd), en de verbindingsfunctie in de driver. De Driver Manager geeft SQLSTATE IM006 terug (de SQLSetConnectOption van de driver faalde) en SQL_SUCCESS_WITH_INFO voor de verbindingsfunctie als de driver een foutmelding gaf voor SQLSetConnectAttr. Voor meer informatie, zie Verbinden met een databron of driver.

• Als de gespecificeerde driver al is verbonden op de ConnectionHandle, roept de Driver Manager alleen de verbindingsfunctie in de driver aan. In dit geval moet de driver ervoor zorgen dat alle verbindingsattributen voor de ConnectionHandle hun huidige instellingen behouden.

• Als een andere driver is aangesloten, roept de Driver Manager SQLFreeHandle aan met een HandleType van SQL_HANDLE_DBC, en als er in die omgeving geen andere driver is aangesloten, roept hij SQLFreeHandle aan met een HandleType van SQL_HANDLE_ENV in de verbonden driver en verbreekt die driver. Vervolgens voert het dezelfde bewerkingen uit als wanneer een driver niet is aangesloten.

De driver wijst vervolgens handles toe en initialiseert zichzelf.

Wanneer de toepassing SQLDisconnect aanroept, roept Driver Manager SQLDisconnect aan in het stuurprogramma. Het koppelt echter de driver niet los. Dit houdt de driver in het geheugen voor applicaties die herhaaldelijk verbinding maken met en loskoppelen van een databron. Wanneer de applicatie SQLFreeHandle aanroept met een HandleType van SQL_HANDLE_DBC, roept de Driver Manager SQLFreeHandle aan met een HandleType van SQL_HANDLE_DBC en vervolgens SQLFreeHandle met een HandleType van SQL_HANDLE_ENV in de driver, waarna de driver wordt losgekoppeld.

Een ODBC-applicatie kan meer dan één verbinding tot stand brengen.

Richtlijnen voor de bestuurdersmanager

De inhoud van *ServerName beïnvloedt hoe de Driver Manager en een driver samenwerken om een verbinding met een databron tot stand te brengen.

• Als *ServerName een geldige gegevensbronnaam bevat, zoekt de Driver Manager de bijbehorende gegevensbronspecificatie in de systeeminformatie en maakt verbinding met de bijbehorende driver. De Driver Manager geeft elk SQLConnect-argument door aan de driver.

• Als de naam van de databron niet wordt gevonden of ServerName een nullpointer is, zoekt de Driver Manager de standaard databronspecificatie op en maakt verbinding met de bijbehorende driver. De Driver Manager geeft de UserName- en Authenticatieargumenten ongewijzigd door aan de driver, en "DEFAULT" voor het ServerName-argument .

• Als het ServerName-argument "DEFAULT" is, zoekt de Driver Manager de standaard gegevensbronspecificatie en maakt verbinding met de bijbehorende driver. De Driver Manager geeft elk SQLConnect-argument door aan de driver.

• Als de naam van de gegevensbron niet kan worden gevonden of ServerName een nullpointer is en de standaard gegevensbronspecificatie niet bestaat, stuurt de Driver Manager SQL_ERROR terug met SQLSTATE IM002 (Gegevensbronnaam niet gevonden en geen standaard driver gespecificeerd).

Nadat deze is verbonden door de Driver Manager, kan een driver zijn overeenkomstige databronspecificatie in de systeeminformatie vinden en driver-specifieke informatie uit die specificatie gebruiken om de benodigde verbindingsinformatie compleet te maken.

Als een standaard vertaalbibliotheek is gespecificeerd in de systeeminformatie voor de databron, maakt de driver verbinding met deze databron. Een andere vertaalbibliotheek kan worden aangesloten door SQLSetConnectAttr aan te roepen met het attribuut SQL_ATTR_TRANSLATE_LIB. Een vertaaloptie kan worden gespecificeerd door SQLSetConnectAttr aan te roepen met het attribuut SQL_ATTR_TRANSLATE_OPTION.

Als een driver SQLConnec ondersteunt, moet het driversleutelwoordgedeelte van de systeeminformatie voor de driver het ConnectFunctions-sleutelwoord bevatten met het eerste teken als eerste teken op "Y."

Verbindingspoolbeheer

Connection pooling stelt een applicatie in staat om een verbinding die al is aangemaakt opnieuw te gebruiken. Wanneer connection pooling is ingeschakeld en SQLConnect wordt aangeroepen, probeert de Driver Manager de verbinding te maken met een verbinding die deel uitmaakt van een pool van verbindingen in een omgeving die is aangewezen voor connection pooling. Deze omgeving is een gedeelde omgeving die wordt gebruikt door alle applicaties die de verbindingen in de pool gebruiken.

Connection pooling wordt ingeschakeld voordat de omgeving wordt toegewezen door SQLSetEnvAttr aan te roepen om SQL_ATTR_CONNECTION_POOLING in te stellen op SQL_CP_ONE_PER_DRIVER (wat een maximum van één pool per driver specificeert) of SQL_CP_ONE_PER_HENV (dat een maximum van één pool per omgeving specificeert). SQLSetEnvAttr wordt in dit geval aangeroepen met EnvironmentHandle op null gezet, waardoor het attribuut een procesniveauattribuut wordt. Als SQL_ATTR_CONNECTION_POOLING op SQL_CP_OFF staat, wordt connection pooling uitgeschakeld.

Nadat connection pooling is ingeschakeld, wordt SQLAllocHandle met een HandleType van SQL_HANDLE_ENV aangeroepen om een omgeving toe te wijzen. De omgeving die door deze oproep wordt toegewezen, is een gedeelde omgeving omdat verbindingspooling is ingeschakeld. De omgeving die gebruikt zal worden, wordt echter pas bepaald wanneer SQLAllocHandle met een HandleType van SQL_HANDLE_DBC wordt aangeroepen.

SQLAllocHandle met een HandleType van SQL_HANDLE_DBC wordt aangeroepen om een verbinding toe te wijzen. De Driver Manager probeert een bestaande gedeelde omgeving te vinden die overeenkomt met de omgevingsattributen die door de applicatie zijn ingesteld. Als zo'n omgeving niet bestaat, wordt er een gecreëerd als een impliciete gedeelde omgeving. Als een overeenkomstige gedeelde omgeving wordt gevonden, wordt de omgevingshandle teruggegeven aan de applicatie en wordt het aantal referenties verhoogd.

De verbinding die gebruikt zal worden, wordt echter pas bepaald nadat SQLConnect wordt aangeroepen. Op dat moment probeert de Driver Manager een bestaande verbinding in de verbindingspool te vinden die voldoet aan de door de applicatie gevraagde criteria. Deze criteria omvatten de verbindingsopties die worden gevraagd in de aanroep naar SQLConnect (de waarden van de ServerName,UserName- en Authenticatiesleutelwoorden ) en eventuele verbindingsattributen die zijn ingesteld sinds SQLAllocHandle met een HandleType van SQL_HANDLE_DBC is aangeroepen. De Driver Manager controleert deze criteria aan de hand van de bijbehorende verbindingssleutelwoorden en attributen in verbindingen in de pool. Als er een match wordt gevonden, wordt de verbinding in de pool gebruikt. Als er geen match wordt gevonden, wordt er een nieuwe verbinding aangemaakt.

Als het attribuut SQL_ATTR_CP_MATCH environment is ingesteld op SQL_CP_STRICT_MATCH, moet de match exact zijn voor een verbinding in de pool die gebruikt kan worden. Als het SQL_ATTR_CP_MATCH omgevingsattribuut is ingesteld op SQL_CP_RELAXED_MATCH, moeten de verbindingsopties in de aanroep naar SQLConnect overeenkomen, maar niet alle verbindingsattributen hoeven overeen te komen.

De volgende regels worden toegepast wanneer een verbindingsattribuut, zoals door de applicatie ingesteld voordat SQLConnect wordt aangeroepen, niet overeenkomt met het verbindingsattribuut van de verbinding in de pool:

• Als het verbindingsattribuut moet worden ingesteld voordat de verbinding wordt gemaakt:

  Als SQL_ATTR_CP_MATCH SQL_CP_STRICT_MATCH is, moet SQL_ATTR_PACKET_SIZE in de gepoolde verbinding identiek zijn aan het attribuut dat door de applicatie is ingesteld. Als SQL_CP_RELAXED_MATCH, kunnen de waarden van SQL_ATTR_PACKET_SIZE verschillen.

  De waarde van SQL_ATTR_LOGIN_VALUE beïnvloedt de match niet.

• Als het verbindingsattribuut kan worden ingesteld vóór of nadat de verbinding is gemaakt:

  Als het verbindingsattribuut niet door de applicatie is ingesteld maar wel op de verbinding in de pool, en er is een standaard, wordt het verbindingsattribuut in de gepoolde verbinding teruggezet naar de standaard en wordt er een match gedeclareerd. Als er geen default is, wordt de gepoolde verbinding niet als match beschouwd.

  Als het verbindingsattribuut door de applicatie is ingesteld maar niet op de verbinding in de pool, wordt het verbindingsattribuut op de pool veranderd in het door de applicatie ingestelde attribuut en wordt een match gedeclareerd.

  Als het connection-attribuut door de applicatie is ingesteld, en ook op de connection in de pool maar de waarden verschillen, wordt de waarde van het connection-attribuut van de applicatie gebruikt en wordt een match gedeclareerd.

• Als de waarden van driver-specifieke verbindingsattributen niet identiek zijn en SQL_ATTR_CP_MATCH is ingesteld op SQL_CP_STRICT_MATCH, wordt de verbinding in de pool niet gebruikt.

Wanneer de applicatie SQLDisconnect oproept om de verbinding te verbreken, wordt de verbinding teruggegeven aan de verbindingspool en is deze beschikbaar voor hergebruik.

Optimalisatie van de prestaties van verbindingspooling

Wanneer gedistribueerde transacties betrokken zijn, is het mogelijk om de prestaties van connection pooling te optimaliseren door gebruik te maken van SQL_DTC_TRANSITION_COST, een SQLUINTEGER bitmask. De overgangen waar naar wordt verwezen zijn de overgangen van het verbindingsattribuut SQL_ATTR_ENLIST_IN_DTC van waarde 0 naar niet-nul, en omgekeerd. Dit is een verbinding die van niet geregistreerd in een gedistribueerde transactie naar 'geregistreerd' in een gedistribueerde transactie gaat, en omgekeerd. Afhankelijk van hoe de driver enlistment heeft geïmplementeerd (het instellen van verbindingsattribuut SQL_ATTR_ENLIST_IN_DTC), kunnen deze overgangen duur zijn en daarom vermeden worden voor de beste prestaties.

De waarde die door de driver wordt teruggegeven, bevat een willekeurige combinatie van de volgende bits:

• SQL_DTC_ENLIST_EXPENSIVE, wanneer ingesteld, impliceert dat de overgang van nul naar niet-nul aanzienlijk duurder is dan een overgang van niet-nul naar een andere niet-nul waarde (waarbij een eerder aangewezen verbinding wordt ingeschakeld in de volgende transactie).

• SQL_DTC_UNENLIST_EXPENSIVE, wanneer ingesteld, impliceert dat de overgang van niet-nul naar nul aanzienlijk duurder is dan het gebruik van een verbinding waarvan het SQL_ATTR_ENLIST_IN_DTC-attribuut al op nul is gezet.

Er is een afweging tussen prestaties en verbindingsgebruik. Als een driver aangeeft dat een of meer van deze overgangen duur zijn, reageert de connection pooler van de driver manager hierop door meer verbindingen in de pool te houden. Sommige verbindingen in de pool hebben de voorkeur voor niet-transactioneel gebruik, en sommige voor transactioneel gebruik. Als de drijfveer echter aangeeft dat deze overgangen niet duur zijn, kunnen er minder verbindingen worden gebruikt, mogelijk afwisselend tussen niet-transactioneel en transactioneel gebruik.

Drivers die SQL_ATTR_ENLIST_IN_DTC niet ondersteunen, hoeven SQL_DTC_TRANSITION_COST niet te ondersteunen. Voor drivers die SQL_ATTR_ENLIST_IN_DTC ondersteunen maar niet SQL_DTC_TRANSITION_COST, wordt aangenomen dat de overgangen niet duur zijn, alsof de driver 0 (geen bits ingesteld) voor deze waarde teruggeeft.

Hoewel SQL_DTC_TRANSITION_COST werd geïntroduceerd in ODBC 3.5, een ODBC 2. X-driver kan het ook ondersteunen omdat de drivermanager deze informatie zal opvragen, ongeacht de driverversie.

Codevoorbeeld

In het volgende voorbeeld wijst een applicatie omgevings- en verbindingshandles toe. Vervolgens maakt het verbinding met de SalesOrders-databron met het gebruikers-ID JohnS en het wachtwoord Sesame en verwerkt de gegevens. Wanneer de data is verwerkt, verbreekt hij de verbinding met de databron en maakt hij de handles vrij.

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

Gerelateerde functies

Zie ook

ODBC-API-verwijzing
ODBC-headerbestanden