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.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| 01000 | Avviso generale | Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S02 | Valore dell'opzione modificato | Il driver non supporta il valore specificato dell'argomento ValuePtr in SQLSetConnectAttr e ha sostituito un valore simile. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 08001 | Il client non è in grado di stabilire la connessione | Il driver non è riuscito a stabilire una connessione con l'origine dati. |
| 08002 | Nome connessione in uso | (DM) ConnectionHandle specificato era già stato usato per stabilire una connessione con un'origine dati e la connessione era ancora aperta o l'utente stava esplorando una connessione. |
| 08004 | Il server ha rifiutato la connessione | L'origine dati ha rifiutato la creazione della connessione per motivi definiti dall'implementazione. |
| 08S01 | Errore del collegamento di comunicazione | Collegamento di comunicazione tra il driver e l'origine dati a cui il driver stava tentando di connettersi non è riuscito prima del completamento dell'elaborazione della funzione. |
| 28000 | Specifica di autorizzazione non valida | Valore specificato per l'argomento UserName o il valore specificato per l'argomento Autenticazione violata restrizioni definite dall'origine dati. |
| HY000 | Errore generale: | Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa. |
| HY001 | Errore di allocazione della memoria | (DM) Gestione driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione. |
| HY008 | Operazione annullata | L'elaborazione asincrona è stata abilitata per ConnectionHandle. La funzione SQLConnect è stata chiamata e, prima del completamento dell'esecuzione, è stata chiamata la funzione SQLCancelHandle in ConnectionHandle e quindi la funzione SQLConnect è stata chiamata di nuovo in ConnectionHandle. In alternativa, è stata chiamata la funzione SQLConnect e, prima del completamento dell'esecuzione, SQLCancelHandle è stato chiamato in ConnectionHandle da un thread diverso in un'applicazione multithread. |
| HY010 | Errore della sequenza di funzioni | (DM) Una funzione in esecuzione asincrona (non questa) è stata chiamata per ConnectionHandle ed era ancora in esecuzione quando questa funzione è stata chiamata. |
| HY013 | Errore di gestione della memoria | Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente. |
| HY090 | Lunghezza della stringa o del buffer non valida | (DM) Il valore specificato per l'argomento NameLength1, NameLength2 o NameLength3 è minore di 0 ma non uguale a SQL_NTS. (DM) Il valore specificato per l'argomento NameLength1 ha superato la lunghezza massima per un nome di origine dati. |
| HYT00 | Timeout scaduto | Periodo di timeout della query scaduto prima del completamento della connessione all'origine dati. Il periodo di timeout viene impostato tramite SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT. |
| HY114 | Il driver non supporta l'esecuzione asincrona a livello di connessione | (DM) L'applicazione ha abilitato l'operazione asincrona sull'handle di connessione prima di stabilire la connessione. Tuttavia, il driver non supporta operazioni asincrone sull'handle di connessione. |
| HYT01 | Il timeout della connessione è scaduto | Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Il driver non supporta questa funzione | (DM) Il driver specificato dal nome dell'origine dati non supporta la funzione. |
| IM002 | Origine dati non trovata e nessun driver predefinito specificato | (DM) Il nome dell'origine dati specificato nell'argomento NomeServer non è stato trovato nelle informazioni di sistema, né esiste una specifica del driver predefinita. |
| IM003 | Impossibile connettere il driver specificato a | (DM) Il driver elencato nella specifica dell'origine dati nelle informazioni di sistema non è stato trovato o non è stato possibile connettersi a per qualche altro motivo. |
| IM004 | SQLAllocHandle del driver in SQL_HANDLE_ENV non riuscito | (DM) Durante SQLConnect, Gestione driver ha chiamato la funzione SQLAllocHandle del driver con handleType di SQL_HANDLE_ENV e il driver ha restituito un errore. |
| IM005 | SQLAllocHandle del driver in SQL_HANDLE_DBC non riuscito | (DM) Durante SQLConnect, Gestione driver ha chiamato la funzione SQLAllocHandle del driver con handleType di SQL_HANDLE_DBC e il driver ha restituito un errore. |
| IM006 | SqlSetConnectAttr del driver non riuscito | Durante SQLConnect, Gestione driver ha chiamato la funzione SQLSetConnectAttr del driver e il driver ha restituito un errore. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| IM009 | Impossibile connettersi alla DLL di conversione | Il driver non è riuscito a connettersi alla DLL di conversione specificata per l'origine dati. |
| IM010 | Nome origine dati troppo lungo | (DM) *ServerName era più lungo di SQL_MAX_DSN_LENGTH caratteri. |
| IM014 | Il DSN specificato contiene una mancata corrispondenza dell'architettura tra il driver e l'applicazione | (DM) un'applicazione a 32 bit usa un DSN che si connette a un driver a 64 bit; o viceversa. |
| IM015 | SqlConnect del driver in SQL_HANDLE_DBC_INFO_HANDLE non riuscito | Se un driver restituisce SQL_ERROR, Gestione driver restituirà SQL_ERROR all'applicazione e la connessione avrà esito negativo. Per altre informazioni sulle SQL_HANDLE_DBC_INFO_TOKEN, vedere Sviluppo di consapevolezza del pool di connessioni in un driver ODBC. |
| IM017 | Il polling è disabilitato in modalità di notifica asincrona | Ogni volta che viene usato il modello di notifica, il polling è disabilitato. |
| IM018 | SQLCompleteAsync non è stato chiamato per completare l'operazione asincrona precedente su questo handle. | Se la chiamata di funzione precedente sull'handle restituisce SQL_STILL_EXECUTING e se la modalità di notifica è abilitata, è necessario chiamare SQLCompleteAsync sull'handle per eseguire la post-elaborazione e completare l'operazione. |
| S1118 | Il driver non supporta la notifica asincrona | Quando il driver non supporta la notifica asincrona, non è possibile impostare SQL_ATTR_ASYNC_DBC_EVENT o SQL_ATTR_ASYNC_DBC_RETCODE_PTR. |
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
| Per informazioni su | Vedere |
|---|---|
| Allocazione di un handle | Funzione SQLAllocHandle |
| Individuazione ed enumerazione dei valori necessari per la connessione a un'origine dati | Funzione SQLBrowseConnect |
| Disconnessione da un'origine dati | Funzione SQLDisconnect |
| Connessione a un'origine dati tramite una stringa di connessione o una finestra di dialogo | Funzione SQLDriverConnect |
| Restituzione dell'impostazione di un attributo di connessione | Funzione SQLGetConnectAttr |
| Impostazione di un attributo di connessione | Funzione SQLSetConnectAttr |