Funzione SQLConnect

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

Riepilogo
SQLConnect stabilisce connessioni a un driver e a un'origine dati. L'handle di connessione fa riferimento all'archiviazione di tutte le informazioni sulla connessione all'origine dati, inclusi lo stato, lo stato della transazione e le informazioni sull'errore.

Sintassi

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

Argomenti

ConnectionHandle
[Input] Handle di connessione.

ServerName
[Input] Nome origine 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 un'origine dati, vedere Scelta di un'origine dati o driver.

NameLength1
[Input] Lunghezza di *NomeServer in caratteri.

UserName
[Input] Identificatore utente.

NameLength2
[Input] Lunghezza di *UserName in caratteri.

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

NameLength3
[Input] Lunghezza di *Autenticazione in caratteri.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.

Diagnostica

Quando SQLConnect restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_DBC e handle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE restituiti in genere da SQLConnect e ne spiega ognuno nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Commenti

Per informazioni sul motivo per cui un'applicazione usa SQLConnect, vedere Connessione con SQLConnect.

Gestione driver non si connette a un driver finché l'applicazione non chiama una funzione (SQLConnect, SQLDriverConnect o SQLBrowseConnect) per connettersi al driver. Fino a quel punto, Gestione driver funziona con i propri handle e gestisce le informazioni di connessione. Quando l'applicazione chiama una funzione di connessione, Gestione driver controlla se un driver è attualmente connesso a per connectionHandle specificato:

• Se un driver non è connesso a , Gestione driver si connette al driver e chiama SQLAllocHandle con handleType di SQL_HANDLE_ENV, SQLAllocHandle con handleTypedi SQL_HANDLE_DBC, SQLSetConnectAttr (se l'applicazione ha specificato attributi di connessione) e la funzione di connessione nel driver. Gestione driver restituisce SQLSTATE IM006 (SQLSetConnectOption del driver non riuscito) e SQL_SUCCESS_WITH_INFO per la funzione di connessione se il driver ha restituito un errore per SQLSetConnectAttr. Per altre informazioni, vedere Connessione a un'origine dati o a un driver.

• Se il driver specificato è già connesso a in ConnectionHandle, Gestione driver chiama solo la funzione di connessione nel driver. In questo caso, il driver deve assicurarsi che tutti gli attributi di connessione per ConnectionHandle mantengano le impostazioni correnti.

• Se un driver diverso è connesso a , Gestione driver chiama SQLFreeHandle con handleType di SQL_HANDLE_DBC e quindi, se nessun altro driver è connesso a in tale ambiente, chiama SQLFreeHandle con handleType di SQL_HANDLE_ENV nel driver connesso e quindi disconnette tale driver. Esegue quindi le stesse operazioni di quando un driver non è connesso.

Il driver alloca quindi handle e inizializza se stesso.

Quando l'applicazione chiama SQLDisconnect, Gestione driver chiama SQLDisconnect nel driver. Tuttavia, non disconnette il driver. In questo modo il driver viene mantenuto in memoria per le applicazioni che si connettono ripetutamente a e si disconnettono da un'origine dati. Quando l'applicazione chiama SQLFreeHandle con handleTypedi SQL_HANDLE_DBC, Gestione driver chiama SQLFreeHandle con handleTypedi SQL_HANDLE_DBC e quindi SQLFreeHandle con handleType di SQL_HANDLE_ENV nel driver e quindi disconnette il driver.

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

Linee guida di Gestione driver

Il contenuto di *ServerName influisce sul modo in cui Gestione driver e un driver interagiscono per stabilire una connessione a un'origine dati.

• Se *ServerName contiene un nome di origine dati valido, Gestione driver individua la specifica dell'origine dati corrispondente nelle informazioni di sistema e si connette al driver associato. Gestione driver passa ogni argomento SQLConnect al driver.

• Se non è possibile trovare il nome dell'origine dati o ServerName è un puntatore Null, Gestione driver individua la specifica dell'origine dati predefinita e si connette al driver associato. Gestione driver passa al driver gli argomenti UserName e Authentication non modificato e "DEFAULT" per l'argomento ServerName .

• Se l'argomento ServerName è "DEFAULT", Gestione driver individua la specifica dell'origine dati predefinita e si connette al driver associato. Gestione driver passa ogni argomento SQLConnect al driver.

• Se non è possibile trovare il nome dell'origine dati o ServerName è un puntatore Null e la specifica dell'origine dati predefinita non esiste, Gestione driver restituisce SQL_ERROR con SQLSTATE IM002 (nome origine dati non trovato e nessun driver predefinito specificato).

Dopo la connessione da gestione driver, un driver può individuare la specifica dell'origine dati corrispondente nelle informazioni di sistema e usare le informazioni specifiche del driver dalla specifica per completare il set di informazioni di connessione necessarie.

Se viene specificata una libreria di traduzione predefinita nelle informazioni di sistema per l'origine dati, il driver si connette. Una libreria di traduzione diversa può essere connessa chiamando SQLSetConnectAttr con l'attributo SQL_ATTR_TRANSLATE_LIB. È possibile specificare un'opzione di conversione chiamando SQLSetConnectAttr con l'attributo SQL_ATTR_TRANSLATE_OPTION.

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

Pool di connessioni

Il pool di connessioni consente a un'applicazione di riutilizzare una connessione già creata. Quando il pool di connessioni è abilitato e viene chiamato SQLConnect , Gestione driver tenta di stabilire la connessione usando una connessione che fa parte di un pool di connessioni in un ambiente designato per il pool di connessioni. Questo ambiente è un ambiente condiviso usato da tutte le applicazioni che usano le connessioni nel pool.

Il pool di connessioni 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 ogni ambiente). SQLSetEnvAttr in questo caso viene chiamato con EnvironmentHandle impostato su null, che rende l'attributo un attributo a livello di processo. Se SQL_ATTR_CONNECTION_POOLING è impostato su SQL_CP_OFF, il pool di connessioni è disabilitato.

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

SQLAllocHandle con handleType di SQL_HANDLE_DBC viene chiamato per allocare una connessione. Gestione driver tenta di trovare un ambiente condiviso esistente che corrisponda agli attributi dell'ambiente impostati dall'applicazione. Se non esiste un ambiente di questo tipo, ne viene creato uno come ambiente condiviso implicito. Se viene trovato un ambiente condiviso corrispondente, l'handle di ambiente viene restituito all'applicazione e il relativo conteggio dei riferimenti viene incrementato.

Tuttavia, la connessione che verrà usata non viene determinata fino a quando non viene chiamato SQLConnect . A questo punto, Gestione driver tenta di trovare una connessione esistente nel pool di connessioni che corrisponde ai criteri richiesti dall'applicazione. Questi criteri includono le opzioni di connessione richieste nella chiamata a SQLConnect (i valori delle parole chiave ServerName, UserName e Authentication) e gli attributi di connessione impostati dopo la chiamata a SQLAllocHandle con handleType di SQL_HANDLE_DBC è stato chiamato. Gestione driver controlla questi criteri in base alle parole chiave e agli attributi di connessione corrispondenti nelle connessioni nel pool. Se viene trovata una corrispondenza, viene usata la connessione nel pool. Se non viene trovata alcuna corrispondenza, viene creata una nuova connessione.

Se l'attributo dell'ambiente SQL_ATTR_CP_MATCH è impostato su SQL_CP_STRICT_MATCH, la corrispondenza deve essere esatta per l'uso di una connessione nel pool. Se l'attributo di 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 regole seguenti vengono applicate quando un attributo di connessione, impostato dall'applicazione prima della chiamata a SQLConnect , non corrisponde all'attributo di connessione della connessione nel pool:

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

  Se SQL_ATTR_CP_MATCH è SQL_CP_STRICT_MATCH, SQL_ATTR_PACKET_SIZE nella connessione in pool deve essere identico all'attributo impostato 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 di connessione può essere impostato prima o dopo la connessione:

  Se l'attributo di connessione non è stato impostato dall'applicazione ma è stato impostato sulla connessione nel pool ed è presente un valore predefinito, l'attributo di connessione nella connessione in pool viene impostato nuovamente sul valore predefinito e viene dichiarata una corrispondenza. Se non è presente alcun valore predefinito, la connessione in pool non viene considerata una corrispondenza.

  Se l'attributo di connessione è stato impostato dall'applicazione ma non è stato impostato sulla connessione nel pool, l'attributo di connessione nel pool viene modificato in tale set dall'applicazione e viene dichiarata una corrispondenza.

  Se l'attributo di connessione è stato impostato dall'applicazione ed è stato impostato anche sulla connessione nel pool, ma i valori sono diversi, viene usato il valore dell'attributo di 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 usata.

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 connessioni

Quando sono coinvolte transazioni distribuite, è possibile ottimizzare le prestazioni del pool di connessioni usando SQL_DTC_TRANSITION_COST, ovvero una maschera di bit SQLUINTEGER. Le transizioni a cui si fa riferimento sono le transizioni dell'attributo di connessione SQL_ATTR_ENLIST_IN_DTC passando dal valore 0 al diverso da zero e viceversa. Si tratta di una connessione che non viene inserita in una transazione distribuita per l'integrazione in una transazione distribuita e viceversa. A seconda del modo in cui il driver ha implementato l'integrazione (impostazione dell'attributo di connessione SQL_ATTR_ENLIST_IN_DTC), queste transizioni possono essere costose e pertanto devono essere evitate per ottenere prestazioni ottimali.

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

• SQL_DTC_ENLIST_EXPENSIVE, se impostato, implica che la transizione da zero a zero è significativamente più costosa rispetto a una transizione da diverso da zero a un altro valore diverso da zero (integrazione di una connessione precedentemente inclusa nella successiva transazione).

• SQL_DTC_UNENLIST_EXPENSIVE, se impostato, implica che la transizione diversa da zero è notevolmente più costosa rispetto all'uso di una connessione il cui attributo SQL_ATTR_ENLIST_IN_DTC è già impostato su zero.

Esiste un compromesso tra le prestazioni e l'utilizzo delle connessioni. Se un driver indica che una o più di queste transizioni sono costose, il pooler di connessioni di Gestione driver risponde a questo problema mantenendo più connessioni nel pool. Alcune delle connessioni nel pool sono preferite per l'uso non transazionale e alcune sono preferite per l'uso transazionale. Tuttavia, se il driver indica che queste transizioni non sono costose, è possibile usare meno connessioni, ad esempio alternando tra uso non transazionale e transazionale.

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 presuppone che le transizioni non siano costose, come se il driver restituisce 0 (senza bit impostati) per questo valore.

Sebbene SQL_DTC_TRANSITION_COST sia stato introdotto in ODBC 3.5, odbc 2.X driver può supportarlo anche perché gestione driver eseguirà query su queste informazioni indipendentemente dalla versione del driver.

Esempio di codice

Nell'esempio seguente un'applicazione alloca gli handle di ambiente e di connessione. Si connette quindi all'origine dati SalesOrders con l'ID utente JohnS e la password Sesame ed elabora i dati. Al termine dell'elaborazione dei dati, si disconnette dall'origine dati e libera gli 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

Vedi anche

Riferimento API ODBC
File di intestazione ODBC