Funzione SQLDriverConnect

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

Sommario
SQLDriverConnect è un'alternativa a SQLConnect. Supporta sorgenti di dati che richiedono più informazioni di connessione rispetto ai tre argomenti di SQLConnect, finestre di dialogo per indicare all'utente tutte le informazioni di connessione e fonti di dati non definite nelle informazioni di sistema. Per maggiori informazioni, vedi Connessione con SQLDriverConnect.

Syntax

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

Arguments

ConnectionHandle
[Input] Handle di connessione.

WindowHandle
[Input] Maniglia della finestra. L'applicazione può passare il handle della finestra genitore, se applicabile, oppure un null pointer se il handle della finestra non è applicabile o SQLDriverConnect non presenta alcuna finestra di dialogo.

InConnectionString
[Input] Una stringa di connessione completa (vedi la sintassi in "Commenti"), una stringa di connessione parziale o una stringa vuota.

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

OutConnectionString
[Output] Puntatore a un buffer per la stringa di connessione completata. Al momento della connessione con successo alla sorgente dati di destinazione, questo buffer contiene la stringa di connessione completata. Le applicazioni dovrebbero allocare almeno 1.024 caratteri per questo buffer.

Se OutConnectionString è NULL, StringLength2Ptr restituirà comunque il numero totale di caratteri (escluso il carattere di null-termination per i dati caratteristi) disponibili da restituire nel buffer indicato da 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 null-termination) disponibili in *OutConnectionString. Se il numero di caratteri disponibili da restituire è maggiore o uguale a BufferLength, la stringa di connessione completata in *OutConnectionString' viene troncata a BufferLength meno la lunghezza di un carattere null-termination.

DriverCompletion
[Input] Segnalazione che indica se il Driver Manager o il driver devono richiedere ulteriori informazioni sulla connessione:

SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED o SQL_DRIVER_NOPROMPT.

(Per ulteriori informazioni, vedi "Commenti.")

Returns

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

Diagnostics

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

SQLSTATE Error 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 abbastanza grande da restituire l'intera stringa di connessione, quindi la stringa di connessione fu troncata. La lunghezza della stringa di connessione non runcata viene restituita in *StringLength2Ptr. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
01S00 Attributo di stringa di connessione invalido Una parola chiave di attributo non valida era specificata nella stringa di connessione (InConnectionString), ma il driver riusciva comunque a connettersi alla sorgente dati. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
01S02 Valore dell'opzione modificato Il driver non supportava il valore specificato indicato dall'argomento ValuePtr in SQLSetConnectAttr e ne ha sostituito un valore simile. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
01S08 File di salvataggio di errore DSN La stringa in *InConnectionString conteneva una parola chiave FILEDSN , ma il file .dsn non veniva salvato. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
01S09 Parola chiave non valida (DM) La stringa in *InConnectionString conteneva una parola chiave SAVEFILE ma non una parola chiave DRIVER o FILEDSN . (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08001 Il cliente non riesce a stabilire la connessione Il driver non è riuscito a stabilire una connessione con la fonte dei dati.
08002 Nome della connessione in uso (DM) Il ConnectionHandle specificato era già stato usato per stabilire una connessione con una fonte di dati, e la connessione era ancora aperta.
08004 Il server ha rifiutato la connessione La sorgente dati ha rifiutato l'instaurazione della connessione per motivi definiti dall'implementazione.
08S01 Errore del collegamento di comunicazione Il collegamento di comunicazione tra il driver e la sorgente dati a cui il driver stava tentando di collegarsi fallì prima che la funzione SQLDriverConnect completasse l'elaborazione.
28000 Specifica di autorizzazione non valida O l'identificatore utente o la stringa di autorizzazione, o entrambi, come specificato nella stringa di connessione (InConnectionString), violavano le restrizioni definite dalla fonte 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 sua causa.
HY000 Errore generale: file dsn non valido (DM) La stringa in *InConnectionString conteneva una parola chiave FILEDSN, ma il nome del file .dsn non è stato trovato.
HY000 Errore generale: Impossibile creare file buffer (DM) La stringa in *InConnectionString conteneva una parola chiave FILEDSN, ma il file .dsn era illeggibile.
HY001 Errore di allocazione della memoria Il Driver Manager non poteva allocare la 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 era abilitata per il ConnectionHandle. La funzione veniva chiamata e, prima che completasse l'esecuzione, la funzione SQLCancelHandle veniva chiamata sul ConnectionHandle, e poi la funzione SQLDriverConnect veniva chiamata di nuovo sul ConnectionHandle.

Oppure, veniva chiamata la funzione SQLDriverConnect e, prima che completasse l'esecuzione, SQLCancelHandle veniva chiamato sul ConnectionHandle da un thread diverso in un'applicazione multithread.
HY010 Errore della sequenza di funzioni (DM) Un'altra funzione in esecuzione asincrona (non SQLDriverConnect) veniva chiamata per il ConnectionHandle e continuava a essere in esecuzione quando veniva chiamata la funzione SQLDriverConnect .
HY013 Errore di gestione della memoria La chiamata alla funzione SQLDriverConnect non poteva essere elaborata perché gli oggetti di memoria sottostanti non potevano essere accessibili, probabilmente a causa di condizioni di memoria basse.
HY090 Lunghezza della stringa o del buffer non valida (DM) Il valore specificato per l'argomento StringLength1 era inferiore a 0 e non era uguale a SQL_NTS.

(DM) Il valore specificato per l'argomento BufferLength è minore di 0.
HY092 Identificatore di attributo/opzione invalido (DM) L'argomento DriverCompletion era SQL_DRIVER_PROMPT, e l'argomento WindowHandle era un puntatore nullo.
HY110 Completamento del driver non valido (DM) Il valore specificato per l'argomento DriverCompletion non era uguale a SQL_DRIVER_PROMPT, SQL_DRIVER_COMPLETE, SQL_DRIVER_COMPLETE_REQUIRED o SQL_DRIVER_NOPROMPT.

(DM) Il pooling di connessione era abilitato e il valore specificato per l'argomento DriverCompletion non era uguale a SQL_DRIVER_NOPROMPT.
HYC00 Funzionalità facoltativa non implementata Il driver non supporta la versione del comportamento ODBC richiesta dall'applicazione.
HYT00 Timeout scaduto Il periodo di timeout per il login è scaduto prima che la connessione alla fonte dati fosse completata. Il periodo di timeout è 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 della sorgente dati specificato non supporta la funzione.
IM002 Fonte dati non trovata e nessun driver predefinito specificato (DM) Il nome della sorgente dati specificato nella stringa di connessione (InConnectionString) non era presente nelle informazioni di sistema e non c'era una specifica predefinita del driver.

(DM) Le informazioni sulla sorgente dei dati ODBC e sui driver predefiniti non sono state trovate nelle informazioni di sistema.
IM003 Il driver specificato non poteva essere caricato (DM) Il driver elencato nella specifica della sorgente dati nelle informazioni di sistema o specificato dalla parola chiave DRIVER non è stato trovato o non poteva essere caricato per qualche altro motivo.
IM004 SQLAllocHandle del driver su SQL_HANDLE_ENV fallito (DM) Durante SQLDriverConnect, il Driver Manager chiamava la funzione SQLAllocHandle del driver con un fHandleType di SQL_HANDLE_ENV e il driver restituiva un errore.
IM005 SQLAllocHandle del driver su SQL_HANDLE_DBC è fallito. (DM) Durante SQLDriverConnect, il Driver Manager chiamava la funzione SQLAllocHandle del driver con un fHandleType di SQL_HANDLE_DBC e il driver restituiva un errore.
IM006 Il SQLSetConnectAttr del driver è fallito (DM) Durante SQLDriverConnect, il Driver Manager chiamava la funzione SQLSetConnectAttr del driver e il driver restituiva un errore.
IM007 Nessuna fonte di dati o driver specificato; dialogo vietato Nessun nome di sorgente dati o driver era specificato nel stringa di connessione, e DriverCompletion era SQL_DRIVER_NOPROMPT.
IM008 Dialogo fallito Il driver ha tentato di visualizzare la finestra di dialogo per l'accesso e ha fallito.

WindowHandle era un puntatore nullo, e DriverCompletion non era SQL_DRIVER_NO_PROMPT.
IM009 Impossibile caricare la DLL di traduzione Il driver non poteva caricare la DLL di traduzione specificata per la sorgente dati o per la connessione.
IM010 Nome della sorgente dati troppo lungo (DM) Il valore dell'attributo per la parola chiave DSN era più lungo di SQL_MAX_DSN_LENGTH caratteri.
IM011 Nome del pilota troppo lungo (DM) Il valore dell'attributo per la parola chiave DRIVER era più lungo di 255 caratteri.
IM012 Errore di sintassi della parola chiave DRIVER (DM) La coppia parola-valore per la parola chiave DRIVER conteneva un errore di sintassi.

(DM) La stringa in *InConnectionString conteneva una parola chiave FILEDSN , ma il file .dsn non conteneva una parola chiave DRIVER o una parola chiave DSN .
IM014 La DSN specificata contiene una discrepanza architetturale tra il Driver e l'Applicazione (DM) L'applicazione a 32 bit utilizza un DSN collegato a un driver a 64 bit; O viceversa.
IM015 SQLDriverConnect del driver su SQL_HANDLE_DBC_INFO_HANDLE guasto Se un driver restituisce SQL_ERROR, il Driver Manager restituirà SQL_ERROR all'applicazione e la connessione fallirà.

Per maggiori informazioni su SQL_HANDLE_DBC_INFO_TOKEN, vedi Sviluppare la consapevolezza Connection-Pool 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 notifiche asincrone Quando il driver non supporta la notifica asincrona, non puoi impostare SQL_ATTR_ASYNC_DBC_EVENT o SQL_ATTR_ASYNC_DBC_RETCODE_PTR.

Comments

Una stringa di connessione ha la seguente sintassi:

stringa-connessione ::= stringa-vuota[;] | attributo[;] | attributo; stringa di connessione

sequenza vuota ::=attributo ::= parola chiave=attributo-valore | DRIVER=[{]attribute-value[}]

parola chiave attribute ::= DSN | UID | PWD | parola chiave chiave auto-definito-attributo-

attribute-value ::= stringa-carattere

Parola chiave di attributo definita dal driver ::= identificatore

dove la stringa di caratteri ha zero o più caratteri; l'identificatore ha uno o più caratteri; attribute-keyword non è distinto dalla maiuscola e minuscolo; il valore attributo può essere distinto dalla maiuscola e minuscola; e il valore della parola chiave DSN non consiste solo in spazi vuoti.

A causa della grammatica del file di stringa di connessione e di inizializzazione, delle parole chiave e dei valori degli attributi che contengono i caratteri []{}(),;? *=!@ non chiuso con le apparecchie da evitare da evitare. 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 le parentesi attorno 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. 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.

Un valore DSN o stringa di connessione racchiuso con bracket ({}) contenente uno qualsiasi dei caratteri []{}(),;? *=!@ viene passato intatto al pilota. Tuttavia, quando si usano questi caratteri in una parola chiave, il Driver Manager restituisce un errore lavorando con file DSN ma passa la stringa di connessione al driver per le stringhe di connessione normali. 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 utilizza informazioni provenienti dalle informazioni di sistema, il driver deve definire abbastanza parole chiave affinché possa connettersi a una sorgente dati usando solo le informazioni contenute nella stringa di connessione. (Per maggiori informazioni, vedi "Linee guida per il conducente", più avanti in questa sezione.) Il driver definisce quali parole chiave sono necessarie per connettersi alla fonte dati.

La tabella seguente descrive i valori degli attributi delle parole chiave DSN,FILEDSN, DRIVER,UID,PWD e SAVEFILE .

Keyword Descrizione del valore dell'attributo
DSN Nome di una sorgente dati come restituito da SQLDataSources o dalla finestra di dialogo sorgenti dati di SQLDriverConnect.
ARCHIVIATO. Nome di un file .dsn da cui verrà costruita una stringa di connessione per la sorgente dati. Queste fonti di dati sono chiamate sorgenti di file data.
PILOTA Descrizione del driver come restituita dalla funzione SQLDrivers . Ad esempio, Rdb o SQL Server.
UID ID utente.
PWD La password corrispondente all'ID utente, oppure una stringa vuota se non esiste una password per l'ID utente (PWD=;).
ARCHIVIO DI SALVATAGGIO Il nome del file di un file .dsn in cui dovrebbero essere salvati i valori degli attributi delle parole chiave usate per creare la connessione attuale e di successo.

Per informazioni su come un'applicazione sceglie una sorgente di dati o un driver, vedi Scelta di una fonte di dati o di un driver.

Se vengono ripetute parole chiave nella stringa di connessione, il driver utilizza il valore associato alla prima occorrenza della parola chiave. Se le parole chiave DSN e DRIVER sono incluse nella stessa stringa di connessione, il Driver Manager e il driver usano la parola chiave che appare per prima.

Le parole chiave FILEDSN e DSN sono mutuamente esclusive: viene usata quella che appare per prima e quella che appare seconda viene ignorata. Le parole chiave FILEDSN e DRIVER , invece, non sono mutuamente esclusive. Se una parola chiave appare in una stringa di connessione con FILEDSN, allora viene utilizzato il valore dell'attributo della parola chiave nella stringa di connessione invece del valore dell'attributo della stessa parola chiave nel file .dsn.

Se viene utilizzata la parola chiave FILEDSN, le parole chiave specificate in un file .dsn vengono usate per creare una stringa di connessione. (Per ulteriori informazioni, vedi "File Data Sources", più avanti in questa sezione.) La parola chiave UID è opzionale; un file .dsn può essere creato solo con la parola chiave DRIVER . La parola chiave PWD non è memorizzata in un file .dsn. La directory predefinita per salvare e caricare un file .dsn sarà una combinazione del percorso specificato da CommonFileDir in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\ Windows\CurrentVersion e "ODBC\DataSources". (Se CommonFileDir fosse "C:\Program Files\Common Files", la directory predefinita sarebbe "C:\Program Files\Common Files\ODBC\Data Sources".)

Note

Un file .dsn può essere manipolato direttamente chiamando le funzioni SQLReadFileDSN e SQLWriteFileDSN nella DLL dell'installatore.

Se viene utilizzata la parola chiave SAVEFILE , i valori degli attributi delle parole chiave usate per creare la connessione attuale e riuscita verranno salvati come file .dsn con il nome del valore dell'attributo della parola chiave SAVEFILE . La parola chiave SAVEFILE deve essere usata insieme alla parola chiave DRIVER , alla parola chiave FILEDSN o a entrambe, oppure la funzione restituisce SQL_SUCCESS_WITH_INFO con SQLSTATE 01S09 (parola chiave non valida). La parola chiave SAVEFILE deve apparire prima della parola chiave DRIVER nella stringa di connessione, altrimenti i risultati non saranno definiti.

Linee guida per il Driver Manager

Il Driver Manager costruisce una stringa di connessione da passare al driver nell'argomento InConnectionString della funzione SQLDriverConnect del driver. Il Driver Manager non modifica l'argomento InConnectionString che gli viene passato dall'applicazione.

L'azione del Driver Manager si basa sul valore dell'argomento DriverCompleting :

  • SQL_DRIVER_PROMPT: Se il stringa di connessione non contiene né la parola chiave DRIVER, né DSN, né FILEDSN, il Driver Manager mostra la finestra di dialogo Sorgenti dati. Costruisce una stringa di connessione dal nome della sorgente dati restituito dalla finestra di dialogo e da qualsiasi altra parola chiave passata dall'applicazione. Se il nome della sorgente dati restituito dalla finestra di dialogo è vuoto, il Driver Manager specifica la coppia parola-valore chiave DSN=Default. (Questa finestra di dialogo non mostrerà una sorgente dati con il nome "Default".)

  • SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED: Se il stringa di connessione specificato dall'applicazione include la parola chiave DSN, il Driver Manager copia il stringa di connessione specificato dall'applicazione. Altrimenti, compie le stesse azioni che fa quando DriverCompletion è SQL_DRIVER_PROMPT.

  • SQL_DRIVER_NOPROMPT: Il Driver Manager copia le stringa di connessione specificate dall'applicazione.

Se la stringa di connessione specificata dall'applicazione contiene la parola chiave DRIVER, il Driver Manager copia la stringa di connessione specificata dall'applicazione.

Utilizzando la stringa di connessione che ha costruito, il Driver Manager determina quale driver usare, si collega a quel driver e passa la stringa di connessione che ha costruito al driver; per maggiori informazioni sull'interazione tra il Driver Manager e il driver, consulta la sezione "Commenti" in SQLConnect Function. Se la stringa di connessione non contiene la parola chiave DRIVER, il Driver Manager determina quale driver utilizzare come segue:

  1. Se la stringa di connessione contiene la parola chiave DSN, il Driver Manager recupera il driver associato alla sorgente dati dalle informazioni di sistema.

  2. Se la stringa di connessione non contiene la parola chiave DSN o la sorgente dati non viene trovata, il Driver Manager recupera il driver associato alla sorgente dati predefinita dalle informazioni di sistema. (Per ulteriori informazioni, vedi Sottochiave predefinita.) Il Driver Manager cambia 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", il Driver Manager recupera il driver associato alla sorgente dati predefinita dalle informazioni di sistema.

  4. Se la sorgente dati non viene trovata e la sorgente dati predefinita non viene trovata, il Driver Manager restituisce SQL_ERROR con SQLSTATE IM002 (Sorgente dati non trovata e nessun driver predefinito specificato).

Origini dei dati del 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 né dalla parola chiave DSNda quella DRIVER, allora il Driver Manager crea una stringa di connessione usando le informazioni nel file .dsn e l'argomento InConnectionString. Il Driver Manager procede come segue:

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

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

    Se la sorgente dati del file non è condividebile, il Driver Manager legge il valore della parola chiave DSN e si collega se necessario alla fonte dati utente o di sistema indicata dalla sorgente dati del file non condividebile. I passaggi da 3 a 5 non vengono eseguiti.

  3. Costruisce una stringa di connessione per il driver. La driver stringa di connessione è l'unione delle parole chiave specificate nel file .dsn e di quelle specificate nella stringa di connessione originale dell'applicazione. Le regole per la costruzione della driver stringa di connessione dove 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 gli stessi nel file .dsn e nella stringa di connessione dell'applicazione, allora le informazioni sul driver nel file .dsn vengono ignorate e vengono utilizzate le informazioni del driver nella stringa di connessione dell'applicazione. Se i driver specificati dalla parola chiave DRIVER sono gli stessi nel file .dsn e nella stringa di connessione dell'applicazione, allora dove tutte le parole chiave si sovrappongono, quelle specificate nella stringa di connessione dell'applicazione hanno precedenza su quelle specificate nel file .dsn.

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

  4. Carica il driver cercando nella voce del registro HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\<Driver Nome>\Driver dove <Nome> Driver è specificato dalla parola chiave DRIVER .

  5. Passa al driver la nuova stringa di connessioni.

Per esempi di file .dsn, vedi Connessione tramite File Data Sources.

Parola chiave SAVEFILE

Se la stringa di connessione specificata dall'applicazione contiene la parola chiave SAVEFILE, allora il Driver Manager salva la stringa di connessione in un file .dsn. Il Driver Manager procede come segue:

  1. Controlla se il nome del file .dsn incluso come valore attributo della parola chiave SAVEFILE sia valido. In caso contrario, restituisce SQL_ERROR con SQLSTATE IM014 (nome non valido del file DSN). La validità del nome del file è determinata dalle regole standard di denominazione del sistema. Se il nome del file è una stringa vuota ("") e l'argomento DriverCompletion non è SQL_DRIVER_NOPROMPT, allora il nome del file è valido. Se il nome del file esiste già, allora 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 invita l'utente a specificare se il file debba essere sovrascritto. Se viene inserito No, appare la finestra di dialogo File-Salva .

  2. Se il driver restituisce SQL_SUCCESS e il nome del file non era una stringa vuota, allora il Driver Manager scrive le informazioni di connessione restituite nell'argomento OutConnectionString nel file specificato con il formato specificato nella sezione "Connection Strings" precedentemente in questa sezione.

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

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

  5. Se il driver restituisce SQL_SUCCESS_WITH_INFO o SQL_ERROR, allora il Driver Manager restituisce lo stato SQLa all'applicazione.

Linee guida per i piloti

Il driver verifica se la stringa di connessione passata dal Driver Manager contiene la parola chiave DSN o DRIVER. Se la stringa di connessione contiene la parola chiave DRIVER, il driver non può recuperare informazioni sulla sorgente dati dalle informazioni di sistema. Se la stringa di connessione contiene la parola chiave DSN o non contiene né la parola chiave DSNquella DRIVER, il driver può recuperare informazioni sulla sorgente dati dalle informazioni di sistema come segue:

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

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

Il driver utilizza qualsiasi informazione recuperata dalle informazioni di sistema per integrare le informazioni trasmesse nella stringa di connessione. Se le informazioni contenute nelle informazioni di sistema duplicano quelle nella stringa di connessione, il driver utilizza le informazioni nella stringa di connessione.

In base al valore di DriverCompletion, il driver richiede all'utente informazioni di connessione, come l'ID utente e la password, e si collega alla fonte dati:

  • SQL_DRIVER_PROMPT: Il pilota mostra una finestra di dialogo, utilizzando i valori del stringa di connessione e le informazioni di sistema (se presenti) come valori iniziali. Quando l'utente esce dalla finestra di dialogo, il driver si collega alla sorgente dati. Costruisce inoltre una stringa di connessione dal valore della parola chiave DSN o DRIVER in *InConnectionString e dalle informazioni restituite dalla finestra di dialogo. Inserisce questa stringa di connessione nel buffer *OutConnectionString.

  • SQL_DRIVER_COMPLETE o SQL_DRIVER_COMPLETE_REQUIRED: Se il stringa di connessione contiene abbastanza informazioni e queste sono corrette, il driver si collega alla sorgente dati e copia *InConnectionString in *OutConnectionString. Se manca o è errata qualche informazione, il driver compie le stesse azioni che fa quando DriverCompletion è SQL_DRIVER_PROMPT, tranne che se DriverCompletion è SQL_DRIVER_COMPLETE_REQUIRED, il driver disabilita i controlli per qualsiasi informazione non necessaria per connettersi alla fonte dati.

  • SQL_DRIVER_NOPROMPT: Se il stringa di connessione contiene abbastanza informazioni, il driver si collega alla sorgente dati e copia *InConnectionString in *OutConnectionString. Altrimenti, il driver restituisce SQL_ERROR per SQLDriverConnect.

Al momento della connessione riuscita alla sorgente dati, il driver imposta anche *StringLength2Ptr alla lunghezza della stringa di connessione di uscita disponibile per il ritorno in *OutConnectionString.

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

Per informazioni su come il Driver Manager e il driver interagiscono durante il processo di connessione, vedi SQLConnect Function.

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

Connettersi quando il pool di connessione è abilitato

Il pool di connessione permette a un'applicazione di riutilizzare una connessione già creata. Quando viene chiamato SQLDriverConnect , il Driver Manager tenta di effettuare la connessione utilizzando una connessione che fa parte di un pool di connessioni in un ambiente designato per il pool di connessioni. Per ulteriori informazioni sul pool di connessioni, consulta la Funzione SQLConnect.

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

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

  • Non viene effettuata alcuna elaborazione del connection pooling quando la parola chiave SAVEFILE viene specificata nella stringa di connessione.

  • Se il pool di connessione è 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 (Invalid driver completion).

Attributi di connessione

L'attributo SQL_ATTR_LOGIN_TIMEOUT connessione, impostato tramite SQLSetConnectAttr, definisce il numero di secondi per attendere che una richiesta di accesso si completi con una connessione riuscita da parte del driver prima di tornare all'applicazione. Se all'utente viene chiesto di completare la stringa di connessione, inizia un periodo di attesa per ogni richiesta di login quando il driver avvia il processo di connessione.

Il driver apre la connessione in modalità accesso SQL_MODE_READ_WRITE di default. 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 una libreria di traduzione predefinita è specificata nelle informazioni di sistema per la sorgente dati, il driver la carica. Una libreria di traduzione diversa può essere caricata chiamando SQLSetConnectAttr con l'attributo SQL_ATTR_TRANSLATE_LIB. Un'opzione di traduzione può essere specificata chiamando SQLSetConnectAttr con l'opzione SQL_ATTR_TRANSLATE_OPTION.

Per maggiori informazioni, vedi 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);  
   }  
}  

Vedi anche Esempio di Programma ODBC.

Per informazioni su Vedi
Allocazione di un manico Funzione SQLAllocHandle
Scoprire e enumerare i valori necessari per connettersi a una sorgente di dati Funzione SQLBrowseConnect
Connessione a un'origine dati Funzione SQLConnect
Disconnessione da una fonte di dati Funzione SQLDisconnect
Descrizioni e attributi dei piloti che ritornano Funzione SQLDrivers
Liberare una maniglia Funzione SQLFreeHandle
Impostazione di un attributo di connessione Funzione SQLSetConnectAttr

Vedere anche

Riferimento API ODBC
File di intestazione ODBC