Funzione ConfigDSN

Conformità
Versione introdotta: ODBC 1.0

Summary
ConfigDSN aggiunge, modifica o elimina origini dati dalle informazioni di sistema. Potrebbe richiedere informazioni di connessione all'utente. Può essere 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 visualizza alcuna finestra 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 anziché il nome del driver fisico.

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

Restituisce

La funzione restituisce TRUE se ha esito positivo, FALSE 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 vengono illustrati 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 parola chiave-valore non valide L'argomento lpszAttributes conteneva un errore di sintassi.
ODBC_ERROR_INVALID_NAME Nome del driver o del convertitore non valido L'argomento lpszDriver non è valido. Impossibile trovare l'oggetto 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 del 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 parola 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 creare nuovamente l'origine dati usando la funzionalità di installazione AUTO del programma di installazione. Quando gli utilizzi dei valori ConfigDSN e 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 [] {} (),;? * I caratteri =!@ e il valore della parola chiave DSN non possono essere costituiti solo da spazi vuoti. A causa della grammatica del Registro di sistema, le parole chiave e i nomi delle origini dati non possono contenere la barra rovesciata ( \ ).

ConfigDSN deve chiamare SQLValidDSN per controllare la lunghezza del nome dell'origine dati e per verificare che non siano inclusi caratteri non validi nel nome. Se il nome dell'origine dati è più lungo 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 parola 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 richiede 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 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 al Registro di sistema). 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 registro).

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 in lpszAttributes, usa le informazioni provenienti dalle informazioni di sistema. L'utente può modificare le informazioni prima che ConfigDSN le archivi nelle informazioni di sistema.

Se il nome dell'origine dati è stato modificato, ConfigDSN chiama innanzitutto SQLRemoveDSNFromIni nella DLL del programma di installazione per rimuovere la specifica dell'origine dati esistente dal file Odbc.ini (o registro). Segue quindi la procedura descritta nella 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 registro). 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 chiamare 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 del nome di un'origine dati Odbc.ini (o registro) SQLRemoveDSNFromIni
Aggiunta di un nome di origine dati Odbc.ini (o registro) SQLWriteDSNToIni
Scrittura di un valore nel file Odbc.ini o nel Registro di sistema SQLWritePrivateProfileString