SQLDriverConnect Function

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

Riepilogo
SQLDriverConnect è un'alternativa a SQLConnect. Supporta origini dati che richiedono più informazioni di connessione rispetto ai tre argomenti in SQLConnect, finestre di dialogo per richiedere all'utente tutte le informazioni di connessione e origini dati non definite nelle informazioni di sistema. Per altre informazioni, vedere Connessione con SQLDriverConnect.

Sintassi

  
SQLRETURN SQLDriverConnect(  
     SQLHDBC         ConnectionHandle,  
     SQLHWND         WindowHandle,  
     SQLCHAR *       InConnectionString,  
     SQLSMALLINT     StringLength1,  
     SQLCHAR *       OutConnectionString,  
     SQLSMALLINT     BufferLength,  
     SQLSMALLINT *   StringLength2Ptr,  
     SQLUSMALLINT    DriverCompletion);  

Argomenti

ConnectionHandle
[Input] Handle di connessione.

WindowHandle
[Input] Handle di finestra. L'applicazione può passare l'handle della finestra padre, se applicabile o un puntatore Null se l'handle di finestra non è applicabile o SQLDriverConnect non presenterà alcuna finestra di dialogo.

InConnectionString
[Input] Stringa di connessione completa (vedere la sintassi in "Comments"), una stringa di connessione parziale o una stringa vuota.

StringLength1
[Input] Lunghezza di *InConnectionString, in caratteri se la stringa è Unicode o byte se la stringa è ANSI o DBCS.

OutConnectionString
[Output] Puntatore a un buffer per la stringa di connessione completata. Al termine della connessione all'origine dati di destinazione, questo buffer contiene la stringa di connessione completata. Le applicazioni devono allocare almeno 1.024 caratteri per questo buffer.

Se OutConnectionString è NULL, StringLength2Ptr restituirà comunque il numero totale di caratteri (escluso il carattere di terminazione Null per i dati di tipo carattere) da restituire nel buffer a cui punta OutConnectionString.

BufferLength
[Input] Lunghezza del buffer *OutConnectionString , in caratteri.

StringLength2Ptr
[Output] Puntatore a un buffer in cui restituire il numero totale di caratteri (escluso il carattere di terminazione Null) disponibile per restituire in *OutConnectionString. Se il numero di caratteri disponibili per la restituzione è maggiore o uguale a BufferLength, la stringa di connessione completata in *OutConnectionString viene troncata a BufferLength meno la lunghezza di un carattere di terminazione Null.

DriverCompletion
[Input] Flag che indica se Gestione driver o driver deve richiedere altre informazioni di connessione:

SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED o SQL_DRIVER_NOPROMPT.

Per altre informazioni, vedere "Comments.")

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR, SQL_INVALID_HANDLE o SQL_STILL_EXECUTING.

Diagnostica

Quando SQLDriverConnect restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con fHandleType di SQL_HANDLE_DBC e hHandle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLDriverConnect e spiega ognuno di essi 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

Una stringa di connessione ha la sintassi seguente:

connection-string ::= empty-string[;] | attribute[;] | attributo; stringa di connessione

empty-string ::=attribute ::= attribute-keyword=attribute-value | DRIVER=[{]attribute-value[}]

attribute-keyword ::= DSN | UID | PWD | driver-defined-attribute-keyword

attribute-value ::= character-string

identificatore driver-defined-attribute-keyword ::=

dove la stringa di caratteri ha zero o più caratteri; l'identificatore ha uno o più caratteri; attribute-keyword non fa distinzione tra maiuscole e minuscole; attribute-value può fare distinzione tra maiuscole e minuscole e il valore della parola chiave DSN non è costituito esclusivamente da spazi vuoti.

A causa della grammatica dei file di inizializzazione e della stringa di connessione, parole chiave e valori di attributo che contengono i caratteri []{}(),;? *=!@ non racchiuso tra parentesi graffe deve essere evitato. Il valore della parola chiave DSN non può essere costituito solo da spazi vuoti e non deve contenere spazi vuoti iniziali. A causa della grammatica delle informazioni di sistema, le parole chiave e i nomi delle origini dati non possono contenere il carattere barra rovesciata (\).

Le applicazioni non devono aggiungere parentesi graffe intorno al valore dell'attributo dopo la parola chiave DRIVER , a meno che l'attributo non contenga un punto e virgola (;), nel qual caso sono necessarie le parentesi graffe. Se il valore dell'attributo ricevuto dal driver include parentesi graffe, il driver non deve rimuoverlo, ma deve far parte della stringa di connessione restituita.

Valore della stringa di connessione o DSN racchiuso tra parentesi graffe ({}) contenenti uno dei caratteri []{}(),;? *=!@ viene passato intatto al driver. Tuttavia, quando si usano questi caratteri in una parola chiave, Gestione driver restituisce un errore quando si utilizzano DSN file, ma passa la stringa di connessione al driver per le normali stringhe di connessione. Evitare di usare parentesi graffe incorporate in un valore di parola chiave.

La stringa di connessione può includere un numero qualsiasi di parole chiave definite dal driver. Poiché la parola chiave DRIVER non usa informazioni dalle informazioni di sistema, il driver deve definire parole chiave sufficienti in modo che un driver possa connettersi a un'origine dati usando solo le informazioni nella stringa di connessione. Per altre informazioni, vedere "Linee guida per i driver" più avanti in questa sezione. Il driver definisce le parole chiave necessarie per connettersi all'origine dati.

Nella tabella seguente vengono descritti i valori di attributo delle parole chiave DSN, FILEDSN, DRIVER, UID, PWD e SAVEFILE.

Per informazioni su come un'applicazione sceglie un'origine dati o un driver, vedere Scelta di un'origine dati o di un driver.

Se nella stringa di connessione vengono ripetute parole chiave, il driver usa il valore associato alla prima occorrenza della parola chiave. Se le parole chiave DSN e DRIVER sono incluse nella stessa stringa di connessione, Gestione driver e il driver usano la parola chiave che viene visualizzata per prima.

Le parole chiave FILEDSN e DSN si escludono a vicenda: ogni parola chiave visualizzata viene usata per prima e quella che appare seconda viene ignorata. Le parole chiave FILEDSN e DRIVER , d'altra parte, non si escludono a vicenda. Se una parola chiave viene visualizzata in una stringa di connessione con FILEDSN, viene usato il valore dell'attributo della parola chiave nella stringa di connessione anziché il valore dell'attributo della stessa parola chiave nel file con estensione dsn.

Se viene utilizzata la parola chiave FILEDSN , le parole chiave specificate in un file con estensione dsn vengono usate per creare una stringa di connessione. Per altre informazioni, vedere "Origini dati file" più avanti in questa sezione. La parola chiave UID è facoltativa. È possibile creare un file con estensione dsn solo con la parola chiave DRIVER . La parola chiave PWD non viene archiviata in un file con estensione dsn. La directory predefinita per il salvataggio e il caricamento di un file con estensione dsn sarà una combinazione del percorso specificato da CommonFileDir in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion e "ODBC\DataSources". Se CommonFileDir fosse "C:\Programmi\File comuni", la directory predefinita sarà "C:\Programmi\File comuni\ODBC\Origini dati".

Se viene utilizzata la parola chiave SAVEFILE , i valori dell'attributo delle parole chiave usate per rendere presente la connessione verranno salvati come file con estensione dsn con il nome del valore dell'attributo della parola chiave SAVEFILE . La parola chiave SAVEFILE deve essere usata in combinazione con la parola chiave DRIVER , la parola chiave FILEDSN o entrambi oppure la funzione restituisce SQL_SUCCESS_WITH_INFO con SQLSTATE 01S09 (parola chiave non valida). La parola chiave SAVEFILE deve essere visualizzata prima della parola chiave DRIVER nella stringa di connessione oppure i risultati non saranno definiti.

Linee guida di Gestione driver

Gestione driver costruisce una stringa di connessione da passare al driver nell'argomento InConnectionString della funzione SQLDriverConnect del driver. Gestione driver non modifica l'argomento InConnectionString passato dall'applicazione.

L'azione di Gestione driver si basa sul valore dell'argomento DriverCompletion :

• SQL_DRIVER_PROMPT: se la stringa di connessione non contiene la parola chiave DRIVER, DSN o FILEDSN , Gestione driver visualizza la finestra di dialogo Origini dati. Costruisce una stringa di connessione dal nome dell'origine dati restituita dalla finestra di dialogo e da qualsiasi altra parola chiave passata dall'applicazione. Se il nome dell'origine dati restituito dalla finestra di dialogo è vuoto, Gestione driver specifica la coppia chiave-valore DSN=Default. Questa finestra di dialogo non visualizzerà un'origine dati con il nome "Default".

• SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED: se la stringa di connessione specificata dall'applicazione include la parola chiave DSN , Gestione driver copia la stringa di connessione specificata dall'applicazione. In caso contrario, vengono eseguite le stesse azioni eseguite quando DriverCompletion è SQL_DRIVER_PROMPT.

• SQL_DRIVER_NOPROMPT: Gestione driver copia la stringa di connessione specificata dall'applicazione.

Se la stringa di connessione specificata dall'applicazione contiene la parola chiave DRIVER , Gestione driver copia la stringa di connessione specificata dall'applicazione.

Usando la stringa di connessione costruita, Gestione driver determina il driver da usare, si connette a tale driver e passa la stringa di connessione che ha costruito al driver; Per altre informazioni sull'interazione di Gestione driver e driver, vedere la sezione "Commenti" in FUNZIONE SQLConnect. Se la stringa di connessione non contiene la parola chiave DRIVER , Gestione driver determina il driver da usare come segue:

1. Se la stringa di connessione contiene la parola chiave DSN , Gestione driver recupera il driver associato all'origine dati dalle informazioni di sistema.

2. Se la stringa di connessione non contiene la parola chiave DSN o l'origine dati non viene trovata, Gestione driver recupera il driver associato all'origine dati predefinita dalle informazioni di sistema. Per altre informazioni, vedere Sottochiave predefinita. Gestione driver modifica il valore della parola chiave DSN nella stringa di connessione in "DEFAULT".

3. Se la parola chiave DSN nella stringa di connessione è impostata su "DEFAULT", Gestione driver recupera il driver associato all'origine dati predefinita dalle informazioni di sistema.

4. Se l'origine dati non viene trovata e l'origine dati predefinita non viene trovata, Gestione driver restituisce SQL_ERROR con SQLSTATE IM002 (origine dati non trovata e nessun driver predefinito specificato).

Origini dati di file

Se la stringa di connessione specificata dall'applicazione nella chiamata a SQLDriverConnect contiene la parola chiave FILEDSN e questa parola chiave non viene sostituita dalla parola chiave DSN o DRIVER , Gestione driver crea una stringa di connessione usando le informazioni nel file con estensione dsn e l'argomento InConnectionString . Gestione driver procede come segue:

1. Controlla se il nome file del file con estensione dsn è valido. In caso contrario, restituisce SQL_ERROR con SQLSTATE IM014 (nome DSN file non valido). Se il nome del file è una stringa vuota ("") e SQL_DRIVER_NOPROMPT non viene specificato, verrà visualizzata la finestra di dialogo Apri file. Se il nome file contiene un percorso valido, ma nessun nome file o un nome file non valido e SQL_DRIVER_NOPROMPT non viene specificato, la finestra di dialogo Apri file viene visualizzata con la directory corrente impostata su quella specificata nel nome del file. Se il nome del file è una stringa vuota ("") o il nome file contiene un percorso valido, ma non un nome file o un nome di file non valido e viene specificato SQL_DRIVER_NOPROMPT, SQL_ERROR viene restituito con SQLSTATE IM014 (nome non valido del DSN del file).

2. Legge tutte le parole chiave nella sezione [ODBC] del file con estensione dsn. Se la parola chiave DRIVER non è presente, restituisce SQL_ERROR con SQLSTATE IM012 (errore di sintassi delle parole chiave del driver), tranne dove il file con estensione dsn non è condivisibile e pertanto contiene solo la parola chiave DSN .

   Se l'origine dati del file non è condivisibile, Gestione driver legge il valore della parola chiave DSN e si connette in base alle esigenze all'origine dati utente o di sistema a cui punta l'origine dati file non condivisibile. I passaggi da 3 a 5 non vengono eseguiti.

3. Costruisce una stringa di connessione per il driver. La stringa di connessione del driver è l'unione delle parole chiave specificate nel file con estensione dsn e quelle specificate nella stringa di connessione dell'applicazione originale. Le regole per la costruzione della stringa di connessione del driver in cui le parole chiave si sovrappongono sono le seguenti:

   • Se la parola chiave DRIVER esiste nella stringa di connessione dell'applicazione e i driver specificati dalle parole chiave DRIVER non sono uguali nel file con estensione dsn e nella stringa di connessione dell'applicazione, le informazioni sul driver nel file con estensione dsn vengono ignorate e vengono usate le informazioni sul driver nella stringa di connessione dell'applicazione. Se i driver specificati dalla parola chiave DRIVER sono uguali nel file dsn e nella stringa di connessione dell'applicazione, dove tutte le parole chiave si sovrappongono, quelle specificate nella stringa di connessione dell'applicazione hanno la precedenza su quelle specificate nel file con estensione dsn.

   • Nella nuova stringa di connessione la parola chiave FILEDSN viene eliminata.

4. Carica il driver cercando nella voce del Registro di sistema HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST. INI\<Driver Name>\Driver where <Driver Name> is specified by the DRIVER keyword.

5. Passa il driver alla nuova stringa di connessioni.

Per esempi di file con estensione dsn, vedere Connessione tramite origini dati file.

Parola chiave SAVEFILE

Se la stringa di connessione specificata dall'applicazione contiene la parola chiave SAVEFILE , Gestione driver salva la stringa di connessione in un file con estensione dsn. Gestione driver procede come segue:

1. Verifica se il nome file del file con estensione dsn incluso come valore dell'attributo della parola chiave SAVEFILE è valido. In caso contrario, restituisce SQL_ERROR con SQLSTATE IM014 (nome DSN file non valido). La validità del nome file è determinata dalle regole di denominazione standard del sistema. Se il nome file è una stringa vuota ("") e l'argomento DriverCompletion non è SQL_DRIVER_NOPROMPT, il nome file è valido. Se il nome file esiste già, se DriverCompletion è SQL_DRIVER_NOPROMPT, il file viene sovrascritto. Se DriverCompletion è SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED, una finestra di dialogo richiede all'utente di specificare se il file deve essere sovrascritto. Se non viene immesso alcun valore, verrà visualizzata la finestra di dialogo Salva file.

2. Se il driver restituisce SQL_SUCCESS e il nome file non era una stringa vuota, Gestione driver scrive le informazioni di connessione restituite nell'argomento OutConnectionString nel file specificato con il formato specificato nella sezione "Stringhe di connessione" precedente in questa sezione.

3. Se il driver restituisce SQL_SUCCESS e il nome del file era una stringa vuota (""), Gestione driver chiama la finestra di dialogo comune File-Salva con l'oggetto hwnd specificato e scrive le informazioni di connessione restituite in OutConnectionString nel file specificato nella finestra di dialogo Common File-Save con il formato specificato nella sezione "Stringhe di connessione" precedente in questa sezione.

4. Se il driver restituisce SQL_SUCCESS, restituisce l'argomento OutConnectionString contenente la stringa di connessione all'applicazione.

5. Se il driver restituisce SQL_SUCCESS_WITH_INFO o SQL_ERROR, Gestione driver restituisce SQLSTATE all'applicazione.

Linee guida per i driver

Il driver controlla se la stringa di connessione passata da Gestione driver contiene la parola chiave DSN o DRIVER . Se la stringa di connessione contiene la parola chiave DRIVER , il driver non può recuperare informazioni sull'origine dati dalle informazioni di sistema. Se la stringa di connessione contiene la parola chiave DSN o non contiene il DSN o la parola chiave DRIVER , il driver può recuperare informazioni sull'origine dati dalle informazioni di sistema come indicato di seguito:

1. Se la stringa di connessione contiene la parola chiave DSN , il driver recupera le informazioni per l'origine dati specificata.

2. Se la stringa di connessione non contiene la parola chiave DSN , l'origine dati specificata non viene trovata o la parola chiave DSN è impostata su "DEFAULT", il driver recupera le informazioni per l'origine dati predefinita.

Il driver usa tutte le informazioni recuperate dalle informazioni di sistema per aumentare le informazioni passate nella stringa di connessione. Se le informazioni contenute nelle informazioni di sistema duplicano le informazioni nella stringa di connessione, il driver usa le informazioni nella stringa di connessione.

In base al valore di DriverCompletion, il driver richiede all'utente le informazioni di connessione, ad esempio l'ID utente e la password, e si connette all'origine dati:

• SQL_DRIVER_PROMPT: il driver visualizza una finestra di dialogo, usando i valori della stringa di connessione e le informazioni di sistema (se presenti) come valori iniziali. Quando l'utente esce dalla finestra di dialogo, il driver si connette all'origine dati. Costruisce anche una stringa di connessione dal valore della parola chiave DSN o DRIVER in *InConnectionString e le informazioni restituite dalla finestra di dialogo. Inserisce questa stringa di connessione nel buffer *OutConnectionString .

• SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED: se la stringa di connessione contiene informazioni sufficienti e tali informazioni sono corrette, il driver si connette all'origine dati e copia *InConnectionString in *OutConnectionString. Se mancano informazioni o non sono corrette, il driver esegue le stesse azioni eseguite quando DriverCompletion è SQL_DRIVER_PROMPT, ad eccezione del fatto che se DriverCompletion è SQL_DRIVER_COMPLETE_REQUIRED, il driver disabilita i controlli per eventuali informazioni non necessarie per connettersi all'origine dati.

• SQL_DRIVER_NOPROMPT: se la stringa di connessione contiene informazioni sufficienti, il driver si connette all'origine dati e copia *InConnectionString in *OutConnectionString. In caso contrario, il driver restituisce SQL_ERROR per SQLDriverConnect.

Al termine della connessione all'origine dati, il driver imposta anche *StringLength2Ptr sulla lunghezza della stringa di connessione di output disponibile per la restituzione in *OutConnectionString.

Se l'utente annulla una finestra di dialogo presentata da Gestione driver o dal driver, SQLDriverConnect restituisce SQL_NO_DATA.

Per informazioni sull'interazione tra Gestione driver e driver durante il processo di connessione, vedere Funzione SQLConnect.

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

Connessione quando il pool di connessioni è abilitato

Il pool di connessioni consente a un'applicazione di riutilizzare una connessione già creata. Quando viene chiamato SQLDriverConnect , 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. Per altre informazioni sul pool di connessioni, vedere Funzione SQLConnect.

Un'applicazione può impostare SQL_ATTR_RESET_CONNECTION prima di chiamare SQLDisconnect in una connessione in cui è abilitato il pooling. Per altre informazioni, vedere Funzione SQLSetConnectAttr.

Le restrizioni seguenti si applicano quando un'applicazione chiama SQLDriverConnect per connettersi a una connessione in pool:

• Non viene eseguita alcuna elaborazione del pool di connessioni quando la parola chiave SAVEFILE viene specificata nella stringa di connessione.

• Se il pool di connessioni è abilitato, SQLDriverConnect può essere chiamato solo con un argomento DriverCompletion di SQL_DRIVER_NOPROMPT. Se SQLDriverConnect viene chiamato con qualsiasi altro driverCompletion, verrà restituito SQLSTATE HY110 (completamento driver non valido).

Attributi di connessione

L'attributo di connessione SQL_ATTR_LOGIN_TIMEOUT, impostato usando SQLSetConnectAttr, definisce il numero di secondi di attesa per il completamento di una richiesta di accesso con esito positivo da parte del driver prima di tornare all'applicazione. Se all'utente viene richiesto di completare la stringa di connessione, inizia un periodo di attesa per ogni richiesta di accesso all'avvio del processo di connessione.

Il driver apre la connessione in SQL_MODE_READ_WRITE modalità di accesso per impostazione predefinita. Per impostare la modalità di accesso su SQL_MODE_READ_ONLY, l'applicazione deve chiamare SQLSetConnectAttr con l'attributo SQL_ATTR_ACCESS_MODE prima di chiamare SQLDriverConnect.

Se viene specificata una libreria di traduzione predefinita nelle informazioni di sistema per l'origine dati, il driver lo carica. È possibile caricare una libreria di traduzione diversa chiamando SQLSetConnectAttr con l'attributo SQL_ATTR_TRANSLATE_LIB. È possibile specificare un'opzione di conversione chiamando SQLSetConnectAttr con l'opzione SQL_ATTR_TRANSLATE_OPTION.

Per altre informazioni, vedere Connessione con SQLDriverConnect.

// SQLDriverConnect_ref.cpp  
// compile with: odbc32.lib user32.lib  
#include <windows.h>  
#include <sqlext.h>  
  
int main() {  
   SQLHENV henv;  
   SQLHDBC hdbc;  
   SQLHSTMT hstmt;  
   SQLRETURN retcode;  
  
   SQLCHAR OutConnStr[255];  
   SQLSMALLINT OutConnStrLen;  
  
   HWND desktopHandle = GetDesktopWindow();   // desktop's window handle  
  
   // 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, (SQLPOINTER*)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);  
  
            retcode = SQLDriverConnect( // SQL_NULL_HDBC  
               hdbc,   
               desktopHandle,   
               (SQLCHAR*)"driver=SQL Server",   
               _countof("driver=SQL Server"),  
               OutConnStr,  
               255,   
               &OutConnStrLen,  
               SQL_DRIVER_PROMPT );  
  
            // 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);  
   }  
}  

Vedere anche Programma ODBC di esempio.

Funzioni correlate

Vedi anche

Riferimento API ODBC
File di intestazione ODBC