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.
| SQLSTATE | Errore | Descrizione |
|---|---|---|
| 01000 | Avviso generale | Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01004 | Dati stringa, troncati a destra | Il buffer *OutConnectionString non era sufficientemente grande da restituire l'intera stringa di connessione, quindi la stringa di connessione è stata troncata. La lunghezza della stringa di connessione non troncata viene restituita in *StringLength2Ptr. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S00 | Attributo della stringa di connessione non valido | Nella stringa di connessione (InConnectionString) è stata specificata una parola chiave di attributo non valida, ma il driver è riuscito comunque a connettersi all'origine dati. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S02 | Valore dell'opzione modificato | Il driver non supporta il valore specificato a cui punta l'argomento ValuePtr in SQLSetConnectAttr e ha sostituito un valore simile. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S08 | Errore durante il salvataggio del DSN del file | La stringa in *InConnectionString contiene una parola chiave FILEDSN , ma il file con estensione dsn non è stato salvato. (La funzione restituisce SQL_SUCCESS_WITH_INFO. |
| 01S09 | Parola chiave non valida | (DM) La stringa in *InConnectionString contiene una parola chiave SAVEFILE ma non una parola chiave DRIVER o FILEDSN . (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. |
| 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 SQLDriverConnect . |
| 28000 | Specifica di autorizzazione non valida | L'identificatore utente o la stringa di autorizzazione o entrambi, come specificato nella stringa di connessione (InConnectionString), hanno violato le 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 *szMessageText descrive l'errore e la relativa causa. |
| HY000 | Errore generale: Dsn file non valido | (DM) La stringa in *InConnectionString contiene una parola chiave FILEDSN, ma il nome del file dsn non è stato trovato. |
| HY000 | Errore generale: Impossibile creare il buffer di file | (DM) La stringa in *InConnectionString conteneva una parola chiave FILEDSN, ma il file con estensione dsn era illeggibile. |
| HY001 | Errore di allocazione della memoria | Gestione driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione SQLDriverConnect . Il 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 è stata chiamata e, prima di completare l'esecuzione, la funzione SQLCancelHandle è stata chiamata in ConnectionHandle e quindi la funzione SQLDriverConnect è stata chiamata nuovamente in ConnectionHandle. In alternativa, è stata chiamata la funzione SQLDriverConnect e, prima di completare l'esecuzione, SQLCancelHandle è stato chiamato in ConnectionHandle da un thread diverso in un'applicazione multithread. |
| HY010 | Errore della sequenza di funzioni | (DM) È stata chiamata un'altra funzione in esecuzione asincrona (non SQLDriverConnect) per ConnectionHandle ed era ancora in esecuzione quando è stata chiamata la funzione SQLDriverConnect . |
| HY013 | Errore di gestione della memoria | Impossibile elaborare la chiamata di funzione SQLDriverConnect 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 StringLength1 è minore di 0 e non è uguale a SQL_NTS. (DM) Il valore specificato per l'argomento BufferLength è minore di 0. |
| HY092 | Identificatore di attributo/opzione non valido | (DM) L'argomento DriverCompletion è stato SQL_DRIVER_PROMPT e l'argomento WindowHandle era un puntatore Null. |
| HY110 | Completamento driver non valido | (DM) Il valore specificato per l'argomento DriverCompletion non è uguale a SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED o SQL_DRIVER_NOPROMPT. (DM) Il pool di connessioni è stato abilitato e il valore specificato per l'argomento DriverCompletion non è uguale a SQL_DRIVER_NOPROMPT. |
| HYC00 | Funzionalità facoltativa non implementata | Il driver non supporta la versione del comportamento ODBC richiesto dall'applicazione. |
| HYT00 | Timeout scaduto | Periodo di timeout di accesso scaduto prima del completamento della connessione all'origine dati. Il periodo di timeout viene impostato tramite SQLSetConnectAttr, SQL_ATTR_LOGIN_TIMEOUT. |
| 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 corrispondente al nome dell'origine dati specificato non supporta la funzione. |
| IM002 | Origine dati non trovata e nessun driver predefinito specificato | (DM) Il nome dell'origine dati specificato nella stringa di connessione (InConnectionString) non è stato trovato nelle informazioni di sistema e non esiste alcuna specifica del driver predefinita. (DM) Impossibile trovare informazioni sull'origine dati ODBC e sul driver predefinito nelle informazioni di sistema. |
| IM003 | Impossibile caricare il driver specificato | (DM) Il driver elencato nella specifica dell'origine dati nelle informazioni di sistema o specificato dalla parola chiave DRIVER non è stato trovato o non è stato possibile caricare per qualche altro motivo. |
| IM004 | SQLAllocHandle del driver in SQL_HANDLE_ENV non riuscito | (DM) Durante SQLDriverConnect, Gestione driver ha chiamato la funzione SQLAllocHandle del driver con un fHandleType di SQL_HANDLE_ENV e il driver ha restituito un errore. |
| IM005 | SQLAllocHandle del driver in SQL_HANDLE_DBC non riuscito. | (DM) Durante SQLDriverConnect, Gestione driver ha chiamato la funzione SQLAllocHandle del driver con un fHandleType di SQL_HANDLE_DBC e il driver ha restituito un errore. |
| IM006 | SqlSetConnectAttr del driver non riuscito | (DM) Durante SQLDriverConnect, Gestione driver ha chiamato la funzione SQLSetConnectAttr del driver e il driver ha restituito un errore. |
| IM007 | Nessuna origine dati o driver specificato; dialogo non consentito | Nella stringa di connessione non è stato specificato alcun nome o driver dell'origine dati e DriverCompletion è stato SQL_DRIVER_NOPROMPT. |
| IM008 | Finestra di dialogo non riuscita | Il driver ha tentato di visualizzare la finestra di dialogo di accesso e non è riuscito. WindowHandle è un puntatore Null e DriverCompletion non è stato SQL_DRIVER_NO_PROMPT. |
| IM009 | Impossibile caricare la DLL di traduzione | Il driver non è riuscito a caricare la DLL di conversione specificata per l'origine dati o per la connessione. |
| IM010 | Nome origine dati troppo lungo | (DM) Il valore dell'attributo per la parola chiave DSN è maggiore di SQL_MAX_DSN_LENGTH caratteri. |
| IM011 | Nome driver troppo lungo | (DM) Il valore dell'attributo per la parola chiave DRIVER è maggiore di 255 caratteri. |
| IM012 | Errore di sintassi delle parole chiave DRIVER | (DM) La coppia di parole chiave-valore per la parola chiave DRIVER contiene un errore di sintassi. (DM) La stringa in *InConnectionString contiene una parola chiave FILEDSN , ma il file con estensione dsn non contiene una parola chiave DRIVER o una parola chiave DSN . |
| 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 | SqlDriverConnect 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
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.
| Parola chiave | Descrizione del valore dell'attributo |
|---|---|
| DSN | Nome di un'origine dati restituita da SQLDataSources o dalla finestra di dialogo origini dati di SQLDriverConnect. |
| FILEDSN | Nome di un file con estensione dsn da cui verrà compilata una stringa di connessione per l'origine dati. Queste origini dati sono denominate origini dati di file. |
| AUTISTA | Descrizione del driver restituito dalla funzione SQLDrivers . Ad esempio, Rdb o SQL Server. |
| UID | ID utente. |
| PWD | Password corrispondente all'ID utente o stringa vuota se non è presente alcuna password per l'ID utente (PWD=;). |
| SAVEFILE | Nome file di un file con estensione dsn in cui devono essere salvati i valori di attributo delle parole chiave usate per rendere presente la connessione. |
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".
Nota
Un file con estensione dsn può essere modificato direttamente chiamando le funzioni SQLReadFileDSN e SQLWriteFileDSN nella DLL del programma di installazione.
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:
Se la stringa di connessione contiene la parola chiave DSN , Gestione driver recupera il driver associato all'origine dati dalle informazioni di sistema.
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".
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.
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:
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).
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.
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.
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.
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:
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.
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.
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.
Se il driver restituisce SQL_SUCCESS, restituisce l'argomento OutConnectionString contenente la stringa di connessione all'applicazione.
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:
Se la stringa di connessione contiene la parola chiave DSN , il driver recupera le informazioni per l'origine dati specificata.
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
| 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 |
| Connessione a un'origine dati | Funzione SQLConnect |
| Disconnessione da un'origine dati | Funzione SQLDisconnect |
| Restituzione di descrizioni e attributi del driver | Funzione SQLDrivers |
| Liberare un handle | Funzione SQLFreeHandle |
| Impostazione di un attributo di connessione | Funzione SQLSetConnectAttr |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per