Funzione ConfigDSN

  • Articolo

Conformità
Versione introdotta: ODBC 1.0

Riepilogo
ConfigDSN aggiunge, modifica o elimina le origini dati dalle informazioni di sistema. Potrebbe richiedere all'utente le informazioni di connessione. Può trovarsi nella DLL del driver o in una DLL di installazione separata.

Sintassi

  
BOOL ConfigDSN(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszAttributes);

Argomenti

hwndParent
[Input] Handle della finestra padre. La funzione non visualizzerà finestre di dialogo se l'handle è Null.

fRequest
[Input] Tipo di richiesta. L'argomento fRequest deve contenere uno dei valori seguenti:

ODBC_ADD_DSN: aggiungere una nuova origine dati.

ODBC_CONFIG_DSN: configurare (modificare) un'origine dati esistente.

ODBC_REMOVE_DSN: rimuovere un'origine dati esistente.

lpszDriver
[Input] Descrizione del driver (in genere il nome del DBMS associato) presentato agli utenti invece del nome del driver fisico.

lpszAttributes
[Input] Elenco di attributi con terminazione Null doubly sotto forma di coppie chiave-valore. Per altre informazioni, vedere "Commenti".

Resi

Se ha esito positivo, la funzione restituisce TRUE se ha esito negativo.

Diagnostica

Quando ConfigDSN restituisce FALSE, un valore *pfErrorCode associato viene inserito nel buffer degli errori del programma di installazione tramite una chiamata a SQLPostInstallerError e può essere ottenuto chiamando SQLInstallerError. Nella tabella seguente sono elencati i valori *pfErrorCode che possono essere restituiti da SQLInstallerError e spiega ognuno nel contesto di questa funzione.

*pfErrorCode Errore Descrizione
ODBC_ERROR_INVALID_HWND Handle di finestra non valido L'argomento hwndParent non è valido.
ODBC_ERROR_INVALID_KEYWORD_VALUE Coppie chiave-valore non valide L'argomento lpszAttributes contiene un errore di sintassi.
ODBC_ERROR_INVALID_NAME Driver o nome traduttore non valido L'argomento lpszDriver non è valido. Non è stato trovato nel Registro di sistema.
ODBC_ERROR_INVALID_REQUEST_TYPE Tipo di richiesta non valido L'argomento fRequest non è uno dei seguenti:

ODBC_ADD_DSN ODBC_CONFIG_DSN ODBC_REMOVE_DSN
ODBC_ERROR_REQUEST_FAILED Richiesta non riuscita Impossibile eseguire l'operazione richiesta dall'argomento fRequest .
ODBC_ERROR_DRIVER_SPECIFIC Errore specifico del driver o del traduttore Errore specifico del driver per il quale non è presente alcun errore di programma di installazione ODBC definito. L'argomento SzError in una chiamata alla funzione SQLPostInstallerError deve contenere il messaggio di errore specifico del driver.

Commenti

ConfigDSN riceve le informazioni di connessione dalla DLL del programma di installazione come elenco di attributi sotto forma di coppie chiave-valore. Ogni coppia viene terminata con un byte Null e l'intero elenco viene terminato con un byte Null. Ovvero, due byte Null contrassegnano la fine dell'elenco. Gli spazi non sono consentiti intorno al segno di uguale nella coppia parola chiave-valore. ConfigDSN può accettare parole chiave non valide per SQLBrowseConnect e SQLDriverConnect. ConfigDSN non supporta necessariamente tutte le parole chiave valide per SQLBrowseConnect e SQLDriverConnect. ConfigDSN non accetta la parola chiave DRIVER. Le parole chiave usate dalla funzione ConfigDSN devono supportare tutte le opzioni necessarie per ricreare l'origine dati usando la funzionalità di installazione AUTOMATICA del programma di installazione. Quando vengono usati i valori ConfigDSN e i valori della stringa di connessione sono gli stessi, è necessario usare le stesse parole chiave.

Come in SQLBrowseConnect e SQLDriverConnect, le parole chiave e i relativi valori non devono contenere [ ]{}(),;? *=!@ caratteri e il valore della parola chiave DSN non può essere costituito solo da spazi vuoti. A causa della grammatica del Registro di sistema, le parole chiave e i nomi delle origini dati non possono contenere il carattere barra rovesciata (\).

ConfigDSN deve chiamare SQLValidDSN per controllare la lunghezza del nome dell'origine dati e verificare che nel nome non siano inclusi caratteri non validi. Se il nome dell'origine dati è più lungo di SQL_MAX_DSN_LENGTH o include caratteri non validi, SQLValidDSN restituisce un errore e ConfigDSN restituisce un errore. La lunghezza del nome dell'origine dati viene controllata anche da SQLWriteDSNToIni.

Ad esempio, per configurare un'origine dati che richiede un ID utente, una password e un nome di database, un'applicazione di installazione potrebbe passare le coppie chiave-valore seguenti:

DSN=Personnel Data\0UID=Smith\0PWD=Sesame\0DATABASE=Personnel\0\0

Per altre informazioni su queste parole chiave, vedere SQLDriverConnect e la documentazione di ogni driver.

Per visualizzare una finestra di dialogo, hwndParent non deve essere null.

Aggiunta di un'origine dati

Se un nome di origine dati viene passato a ConfigDSN in lpszAttributes, ConfigDSN verifica che il nome sia valido. Se il nome dell'origine dati corrisponde a un nome di origine dati esistente e hwndParent è null, ConfigDSN sovrascrive il nome esistente. Se corrisponde a un nome esistente e hwndParent non è null, ConfigDSN chiede all'utente di sovrascrivere il nome esistente.

Se lpszAttributes contiene informazioni sufficienti per connettersi a un'origine dati, ConfigDSN può aggiungere l'origine dati o visualizzare una finestra di dialogo con cui l'utente può modificare le informazioni di connessione. Se lpszAttributes non contiene informazioni sufficienti per connettersi a un'origine dati, ConfigDSN deve determinare le informazioni necessarie. Se hwndParent non è Null, viene visualizzata una finestra di dialogo per recuperare le informazioni dall'utente.

Se ConfigDSN visualizza una finestra di dialogo, deve visualizzare tutte le informazioni di connessione passate in lpszAttributes. In particolare, se è stato passato un nome di origine dati, ConfigDSN visualizza tale nome ma non consente all'utente di modificarlo. ConfigDSN può fornire valori predefiniti per le informazioni di connessione non passate in lpszAttributes.

Se ConfigDSN non riesce a ottenere informazioni di connessione complete per un'origine dati, restituisce FALSE.

Se ConfigDSN può ottenere informazioni di connessione complete per un'origine dati, chiama SQLWriteDSNToIni nella DLL del programma di installazione per aggiungere la nuova specifica dell'origine dati al file Odbc.ini (o registro). SQLWriteDSNToIni aggiunge il nome dell'origine dati alla sezione [Origini dati ODBC], crea la sezione specifica dell'origine dati e aggiunge la parola chiave DRIVER con la descrizione del driver come valore. ConfigDSN chiama SQLWritePrivateProfileString nella DLL del programma di installazione per aggiungere eventuali parole chiave e valori aggiuntivi usati dal driver.

Modifica di un'origine dati

Per modificare un'origine dati, è necessario passare un nome di origine dati a ConfigDSN in lpszAttributes. ConfigDSN verifica che il nome dell'origine dati si trova nel file Odbc.ini (o nel Registro di sistema).

Se hwndParent è null, ConfigDSN usa le informazioni in lpszAttributes per modificare le informazioni nel file Odbc.ini (o registro). Se hwndParent non è null, ConfigDSN visualizza una finestra di dialogo usando le informazioni in lpszAttributes. Per informazioni non contenute in lpszAttributes, vengono utilizzate informazioni dalle informazioni di sistema. L'utente può modificare le informazioni prima che ConfigDSN lo archivii nelle informazioni di sistema.

Se il nome dell'origine dati è stato modificato, ConfigDSN chiama prima SQLRemoveDSNFromIni nella DLL del programma di installazione per rimuovere la specifica dell'origine dati esistente dal file Odbc.ini (o registro di sistema). Segue quindi i passaggi della sezione precedente per aggiungere la nuova specifica dell'origine dati. Se il nome dell'origine dati non è stato modificato, ConfigDSN chiama SQLWritePrivateProfileString nella DLL del programma di installazione per apportare altre modifiche. ConfigDSN non può eliminare o modificare il valore della parola chiave driver .

Eliminazione di un'origine dati

Per eliminare un'origine dati, è necessario passare un nome di origine dati a ConfigDSN in lpszAttributes. ConfigDSN verifica che il nome dell'origine dati si trova nel file Odbc.ini (o nel Registro di sistema). Chiama quindi SQLRemoveDSNFromIni nella DLL del programma di installazione per rimuovere l'origine dati.

Nota

Se si scrive una versione Unicode di questa routine, è necessario chiamarla ConfigDSNW, con argomenti LPCWSTR anziché LPCSTR.

Per informazioni su Vedere
Aggiunta, modifica o rimozione di un'origine dati SQLConfigDataSource
Recupero di un valore dal file Odbc.ini o dal Registro di sistema SQLGetPrivateProfileString
Rimozione dell'origine dati predefinita SQLRemoveDefaultDataSource
Rimozione di un nome di origine dati da Odbc.ini (o registro) SQLRemoveDSNFromIni
Aggiunta di un nome di origine dati a Odbc.ini (o registro) SQLWriteDSNToIni
Scrittura di un valore nel file Odbc.ini o nel Registro di sistema SQLWritePrivateProfileString