Funzione SQLConnect

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92

Sommario
SQLConnect stabilisce connessioni con un driver e una sorgente dati. Il handle di connessione fa riferimento all'archiviazione di tutte le informazioni sulla connessione alla fonte dati, inclusi stato, stato della transazione e informazioni sugli errori.

Syntax

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

Arguments

ConnectionHandle
[Input] Handle di connessione.

Nome del Server
[Input] Nome della fonte dati. I dati potrebbero trovarsi nello stesso computer del programma o in un altro computer in una rete. Per informazioni su come un'applicazione sceglie una fonte dati, vedi Scelta di una fonte o di un driver dati.

NameLength1
[Input] Lunghezza di *ServerName in caratteri.

UserName
[Input] Identificatore utente.

NameLength2
[Input] Lunghezza di *UserName in caratteri.

Autenticazione
[Input] Stringa di autenticazione (tipicamente la password).

NameLength3
[Input] Lunghezza di *Autenticazione nei caratteri.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.

Diagnostics

Quando SQLConnect restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, un valore SQLSTATE associato può essere ottenuto chiamando SQLGetDiagRec con un HandleType di SQL_HANDLE_DBC e un Handle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE tipicamente restituiti da SQLConnect e spiega ciascuno nel contesto di questa funzione; la notazione "(DM)" precede le descrizioni degli stati SQL restituite dal Driver Manager. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Comments

Per informazioni sul motivo per cui un'applicazione utilizza SQLConnect, vedi Connessione con SQLConnect.

Il Driver Manager non si connette a un driver finché l'applicazione non chiama una funzione (SQLConnect, SQLDriverConnect o SQLBrowseConnect) per collegarsi al driver. Fino a quel momento, il Driver Manager lavora con i propri handle e gestisce le informazioni di connessione. Quando l'applicazione chiama una funzione di connessione, il Driver Manager verifica se un driver è attualmente connesso per il ConnectionHandle specificato:

• Se un driver non è connesso, il Driver Manager si collega al driver e chiama SQLAllocHandle con un HandleType di SQL_HANDLE_ENV, SQLAllocHandle con un HandleType di SQL_HANDLE_DBC, SQLSetConnectAttr (se l'applicazione ha specificato qualche attributo di connessione) e la funzione di connessione nel driver. Il Driver Manager restituisce SQLSTATE IM006 ( SQLSetConnectOption del driver fallito) e SQL_SUCCESS_WITH_INFO per la funzione di connessione se il driver restituisce un errore per SQLSetConnectAttr. Per maggiori informazioni, vedi Connessione a una sorgente dati o a un driver.

• Se il driver specificato è già collegato sulla ConnectionHandle, il Driver Manager chiama solo la funzione di connessione nel driver. In questo caso, il driver deve assicurarsi che tutti gli attributi di connessione per il ConnectionHandle mantengano le impostazioni attuali.

• Se è collegato a un driver diverso, il Driver Manager chiama SQLFreeHandle con un HandleType di SQL_HANDLE_DBC e poi, se nessun altro driver è collegato in quell'ambiente, chiama SQLFreeHandle con un HandleType di SQL_HANDLE_ENV nel driver connesso e poi disconnette quel driver. Successivamente esegue le stesse operazioni quando un driver non è collegato.

Il driver quindi assegna le manette e si inizializza.

Quando l'applicazione chiama SQLDisconnect, Gestione driver chiama SQLDisconnect nel driver. Tuttavia, non scollega il driver. Questo mantiene il driver in memoria per applicazioni che si connettono e si disconnettono ripetutamente da una sorgente dati. Quando l'applicazione chiama SQLFreeHandle con un HandleType di SQL_HANDLE_DBC, il Driver Manager chiama SQLFreeHandle con un HandleType di SQL_HANDLE_DBC e poi SQLFreeHandle con un HandleType di SQL_HANDLE_ENV nel driver, e poi disconnette il driver.

Un'applicazione ODBC può stabilire più di una connessione.

Linee guida per il Driver Manager

I contenuti di *ServerName influenzano il modo in cui il Driver Manager e un driver collaborano per stabilire una connessione con una fonte di dati.

• Se *ServerName contiene un nome valido di sorgente dati, il Driver Manager localizza la specifica corrispondente della sorgente dati nelle informazioni di sistema e si collega al driver associato. Il Driver Manager passa ogni argomento SQLConnect al driver.

• Se il nome della sorgente dati non può essere trovato o ServerName è un puntatore nullo, il Driver Manager localizza la specifica predefinita della fonte dati e si collega al driver associato. Il Driver Manager passa al driver gli argomenti UserName e Authentication non modificati, e "DEFAULT" per l'argomento Servername .

• Se l'argomento ServerName è "DEFAULT", il Driver Manager localizza la specifica predefinita della sorgente dati e si collega al driver associato. Il Driver Manager passa ogni argomento SQLConnect al driver.

• Se il nome della sorgente dati non può essere trovato o ServerName è un puntatore nullo, e la specifica predefinita della sorgente dati non esiste, il Driver Manager restituisce SQL_ERROR con SQLSTATE IM002 (nome della sorgente dati non trovato e nessun driver predefinito specificato).

Dopo che è stato collegato dal Driver Manager, un driver può localizzare la specifica della sua fonte di dati corrispondente nelle informazioni di sistema e utilizzare le informazioni specifiche della specifica per completare il set di informazioni di connessione richieste.

Se una libreria di traduzione predefinita è specificata nelle informazioni di sistema per la sorgente dati, il driver si collega ad essa. Una libreria di traduzione diversa può essere collegata chiamando SQLSetConnectAttr con l'attributo SQL_ATTR_TRANSLATE_LIB. Un'opzione di traduzione può essere specificata chiamando SQLSetConnectAttr con l'attributo SQL_ATTR_TRANSLATE_OPTION.

Se un driver supporta SQLConnect, la sezione delle informazioni di sistema del driver deve contenere la parola chiave ConnectFunctions con il primo set di caratteri su "Y".

Gestione del pool di connessioni

Il pool di connessione permette a un'applicazione di riutilizzare una connessione già creata. Quando il pool di connessioni è abilitato e SQLConnect viene chiamato, il Driver Manager cerca di effettuare la connessione utilizzando una connessione che fa parte di un pool di connessioni in un ambiente designato per il pool di connessioni. Questo ambiente è condiviso utilizzato da tutte le applicazioni che utilizzano le connessioni nel pool.

Il pool di connessione viene abilitato prima che l'ambiente venga allocato, chiamando SQLSetEnvAttr per impostare SQL_ATTR_CONNECTION_POOLING su SQL_CP_ONE_PER_DRIVER (che specifica un massimo di un pool per driver) o SQL_CP_ONE_PER_HENV (che specifica un massimo di un pool per ambiente). SQLSetEnvAttr in questo caso viene chiamato con EnvironmentHandle impostato su null, il che rende l'attributo un attributo a livello di processo. Se SQL_ATTR_CONNECTION_POOLING è impostato su SQL_CP_OFF, il pool di connessione viene disabilitato.

Dopo che il pool di connessione è stato abilitato, viene chiamato SQLAllocHandle con un HandleType di SQL_HANDLE_ENV per allocare un ambiente. L'ambiente allocato da questa chiamata è un ambiente condiviso perché il pool di connessione è stato abilitato. Tuttavia, l'ambiente che verrà utilizzato non viene determinato fino a quando SQLAllocHandle con un HandleType di SQL_HANDLE_DBC viene chiamato.

Viene chiamato SQLAllocHandle con un HandleType di SQL_HANDLE_DBC per allocare una connessione. Il Driver Manager cerca di trovare un ambiente condiviso esistente che corrisponda agli attributi dell'ambiente impostati dall'applicazione. Se tale ambiente non esiste, uno viene creato come un ambiente condiviso implicito. Se si trova un ambiente condiviso corrispondente, il handle dell'ambiente viene restituito all'applicazione e il suo conteggio di riferimenti viene incrementato.

Tuttavia, la connessione che verrà utilizzata non viene determinata fino a quando non viene chiamato SQLConnect . A quel punto, il Driver Manager cerca di trovare una connessione esistente nel pool di connessione che corrisponda ai criteri richiesti dall'applicazione. Questi criteri includono le opzioni di connessione richieste nella chiamata a SQLConnect (i valori delle parole chiave NomeServer, Nome Utente e Autenticazione ) e qualsiasi attributo di connessione impostato da quando SQLAllocHandle con un HandleType di SQL_HANDLE_DBC è stato chiamato. Il Driver Manager verifica questi criteri rispetto alle corrispondenti parole chiave e attributi delle connessioni nel pool. Se viene trovata una corrispondenza, viene utilizzata la connessione nel pool. Se non si trova alcuna corrispondenza, viene creata una nuova connessione.

Se l'attributo SQL_ATTR_CP_MATCH environment è impostato su SQL_CP_STRICT_MATCH, la corrispondenza deve essere esatta affinché una connessione nel pool venga utilizzata. Se l'attributo dell'ambiente SQL_ATTR_CP_MATCH è impostato su SQL_CP_RELAXED_MATCH, le opzioni di connessione nella chiamata a SQLConnect devono corrispondere, ma non tutti gli attributi di connessione devono corrispondere.

Le seguenti regole vengono applicate quando un attributo di connessione, come stabilito dall'applicazione prima che SQLConnect venga chiamato, non corrisponde all'attributo di connessione della connessione nel pool:

• Se l'attributo connessione deve essere impostato prima che la connessione venga effettuata:

  Se SQL_ATTR_CP_MATCH è SQL_CP_STRICT_MATCH, SQL_ATTR_PACKET_SIZE nella connessione aggregata deve essere identica all'attributo imposto dall'applicazione. Se SQL_CP_RELAXED_MATCH, i valori di SQL_ATTR_PACKET_SIZE possono essere diversi.

  Il valore di SQL_ATTR_LOGIN_VALUE non influisce sulla corrispondenza.

• Se l'attributo connessione può essere impostato prima o dopo che la connessione è stata effettuata:

  Se l'attributo connessione non è stato impostato dall'applicazione ma è stato impostato sulla connessione nel pool, e c'è un valore predefinito, l'attributo connessione nella connessione poolata viene riportato al valore predefinito e viene dichiarata una corrispondenza. Se non c'è un default, la connessione aggregata non è considerata corrispondenza.

  Se l'attributo connessione è stato impostato dall'applicazione ma non è stato impostato sulla connessione nel pool, l'attributo connection sul pool viene cambiato in quello impostato dall'applicazione e viene dichiarata una corrispondenza.

  Se l'attributo connessione è stato impostato dall'applicazione, e anche sulla connessione nel pool ma i valori sono diversi, viene utilizzato il valore dell'attributo connessione dell'applicazione e viene dichiarata una corrispondenza.

• Se i valori degli attributi di connessione specifici del driver non sono identici e SQL_ATTR_CP_MATCH è impostato su SQL_CP_STRICT_MATCH, la connessione nel pool non viene utilizzata.

Quando l'applicazione chiama SQLDisconnect per disconnettersi, la connessione viene restituita al pool di connessioni ed è disponibile per il riutilizzo.

Ottimizzazione delle prestazioni del pool di connessione

Quando sono coinvolte transazioni distribuite, è possibile ottimizzare le prestazioni del pool di connessione utilizzando SQL_DTC_TRANSITION_COST, che è una bitmask SQLUINTE. Le transizioni a cui si fa riferimento sono le transizioni dell'attributo di connessione SQL_ATTR_ENLIST_IN_DTC vanno da 0 a non zero, e viceversa. Questa è una connessione che va da non arruolato in una transazione distribuita a inserito in una transazione distribuita, e viceversa. A seconda di come il driver ha implementato l'arruolamento (impostando l'attributo di connessione SQL_ATTR_ENLIST_IN_DTC), queste transizioni possono essere costose e dovrebbero quindi essere evitate per ottenere le migliori prestazioni.

Il valore restituito dal driver contiene una qualsiasi combinazione dei seguenti bit:

• SQL_DTC_ENLIST_EXPENSIVE, quando impostato, implica che la transizione da zero a non nulla è significativamente più costosa di una transizione da un valore non nullo a un altro valore non nullo (coinvolgendo una connessione precedentemente arruolata nella sua prossima transazione).

• SQL_DTC_UNENLIST_EXPENSIVE, quando impostato, implica che la transizione non da zero a zero è significativamente più costosa rispetto all'uso di una connessione il cui attributo SQL_ATTR_ENLIST_IN_DTC è già impostato a zero.

C'è un compromesso tra prestazioni e utilizzo della connessione. Se un driver indica che una o più di queste transizioni sono costose, il pool di connessione del driver manager risponde mantenendo più connessioni nel pool. Alcune delle connessioni nel pool sono preferite per l'uso non transazionale, altre per l'uso transazionale. Tuttavia, se il driver indica che queste transizioni non sono costose, si possono utilizzare meno connessioni, alternando tra usi non transazionali e transazionali.

I driver che non supportano SQL_ATTR_ENLIST_IN_DTC non devono supportare SQL_DTC_TRANSITION_COST. Per i driver che supportano SQL_ATTR_ENLIST_IN_DTC ma non SQL_DTC_TRANSITION_COST, si assume che le transizioni non siano costose, come se il driver restituisse 0 (nessun bit impostato) per questo valore.

Sebbene SQL_DTC_TRANSITION_COST sia stato introdotto in ODBC 3.5, un ODBC 2. Il driver X può anche supportarlo perché il driver manager interrogherà queste informazioni indipendentemente dalla versione del driver.

Esempio di codice

Nel seguente esempio, un'applicazione alloca l'ambiente e le handle di connessione. Successivamente si collega alla sorgente dati SalesOrders con l'ID utente JohnS e la password Sesame e elabora i dati. Quando ha terminato di elaborare i dati, si disconnette dalla fonte dati e libera le handle.

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

Funzioni correlate

Vedere anche

Riferimento API ODBC
File di intestazione ODBC