Condividi tramite

Funzione SQLCreateDataSource

  • Articolo

Conformità
Versione introdotta: ODBC 2.0

Riepilogo
SQLCreateDataSource visualizza una finestra di dialogo con cui l'utente può aggiungere un'origine dati.

Sintassi

  
BOOL SQLCreateDataSource(  
     HWND    hwnd,  
     LPSTR   lpszDS);

Argomenti

hwnd
[Input] Handle della finestra padre.

lpszDS
[Input] Nome origine dati. lpszDS può essere un puntatore Null o una stringa vuota.

Resi

SQLCreateDataSource restituisce TRUE se viene creata l'origine dati. In caso contrario, restituisce FALSE.

Diagnostica

Quando SQLCreateDataSource restituisce FALSE, è possibile ottenere un valore *pfErrorCode associato 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_GENERAL_ERR Errore generale del programma di installazione Si è verificato un errore per il quale non si è verificato un errore specifico del programma di installazione.
ODBC_ERROR_INVALID_HWND Handle di finestra non valido L'argomento hwnd non è valido o NULL.
ODBC_ERROR_INVALID_DSN DSN non valido L'argomento lpszDS contiene una stringa non valida per un DSN.
ODBC_ERROR_REQUEST_FAILED Richiesta non riuscita Chiamata a ConfigDSN con l'opzione ODBC_ADD_DSN non riuscita.
ODBC_ERROR_LOAD_LIBRARY_FAILED Impossibile caricare il driver o la libreria di installazione del traduttore Impossibile caricare la libreria di installazione del driver.
ODBC_ERROR_USER_CANCELED Operazione annullata dall'utente L'utente ha annullato la creazione di una nuova origine dati.
ODBC_ERROR_CREATE_DSN_FAILED Impossibile creare il DSN richiesto Impossibile connettersi al database. La chiamata a SQLDriverConnect per un DSN file non ha restituito una connessione riuscita.

Impossibile scrivere nel file.
ODBC_ERROR_OUT_OF_MEM Memoria insufficiente Il programma di installazione non è riuscito a eseguire la funzione a causa di una mancanza di memoria.

Commenti

Se hwnd è null, SQLCreateDataSource restituisce FALSE. In caso contrario, viene visualizzata la finestra di dialogo Crea nuova origine dati con una pagina della procedura guidata per la scelta del tipo di origine dati da configurare, come illustrato nella figura seguente.

Create New Data Source dialog box: select type

L'opzione predefinita è Origine dati file. Quando si sceglie un'origine dati e si fa clic su Avanti , viene visualizzata la pagina della procedura guidata seguente che contiene un elenco di driver installati.

Create New Data Source dialog box: select driver

Se si fa clic su Annulla , la finestra di dialogo scompare e SQLCreateDataSource restituisce FALSE con il codice di errore di ODBC_ERROR_USER_CANCELED. Se è stata selezionata l'opzione Origine dati utente o Origine dati di sistema, il pulsante Avanzate non è disponibile.

Quando si fa clic sul pulsante Avanti , si verificherà una delle operazioni seguenti, a seconda del tipo di origine dati selezionato:

  • Se è stata selezionata l'opzione Origine dati file, viene visualizzata una pagina della procedura guidata che consente all'utente di immettere un nome file.

  • Se è stata selezionata l'origine dati utente o l'origine dati di sistema, viene visualizzata una pagina della procedura guidata che visualizza il tipo di origine dati e il driver per la revisione e quando si fa clic su Fine viene impostata l'origine dati.

Se si fa clic su Avanzate nella pagina Creazione guidata nuova origine dati, viene visualizzata una pagina della procedura guidata per l'immissione delle informazioni specifiche del driver. Nella casella di testo di questa finestra di dialogo digitare il driver e le parole chiave separate da restituisce, come illustrato nella figura seguente.

Advance File DSN Creation Settings dialog box

Altre parole chiave specifiche del driver sono disponibili nella descrizione di SQLDriverConnect. Sono consentiti tutti tranne il DSN .

Il valore predefinito per l'opzione Verifica connessione è TRUE. Questa impostazione predefinita si applica se la pagina della procedura guidata è attivata o meno. Se si fa clic su OK , la stringa specificata nella casella di testo e il valore dell'opzione Verifica connessione vengono memorizzati nella cache. (Se il Viene fatto clic sul pulsante Chiudi o Annulla , tutte le informazioni specifiche del driver appena immesse vengono perse perché la stringa specificata nella casella di testo e il valore dell'opzione Verifica connessione non vengono memorizzati nella cache.

Se l'origine dati file è stata selezionata nella prima pagina della procedura guidata, dopo aver selezionato un driver e aver immesso i valori delle parole chiave nella pagina Avanzate della procedura guidata, all'utente verrà richiesto di immettere un nome file. Fare clic su Sfoglia per cercare un nome di file, nel qual caso la directory predefinita nella casella Sfoglia viene specificata da una combinazione del percorso specificato da CommonFileDir in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion e "ODBC\DataSources". Se CommonFileDir era "C:\Programmi\File comuni", la directory predefinita sarà "C:\Programmi\File comuni\ODBC\Origini dati".

Quando è stato immesso un nome di file e si fa clic su Avanti , il nome file immesso viene controllato per la validità rispetto alle regole di denominazione dei file standard del sistema operativo. Se il nome del file non è valido, una finestra di messaggio di errore notifica all'utente che è stato immesso un nome file non valido. Dopo che l'utente riconosce la finestra di messaggio, lo stato attivo viene restituito alla pagina della procedura guidata in cui viene immesso il nome del file. Se il nome file è valido, viene visualizzata una pagina della procedura guidata che mostra le coppie di parole chiave-valore selezionate per la revisione, come illustrato nella figura seguente.

Create New Data Source dialog box: review

Se si fa clic su Fine e l'origine dati file è stata selezionata come tipo di origine dati e se l'opzione Verifica questa connessione è TRUE, SQLDriverConnect viene chiamato con le parole chiave SAVEFILE e DRIVER . L'argomento DriverCompletion è impostato su SQL_DRIVER_COMPLETE. Il nome del file per la parola chiave SAVEFILE è il nome immesso o scelto e il nome del driver per la parola chiave DRIVER è il nome scelto. Se nella pagina Avanzate della procedura guidata è stata specificata una stringa di connessione specifica del driver, tale stringa viene aggiunta dopo la parola chiave DRIVER .

Se SQLDriverConnect restituisce SQL_SUCCESS, Gestione driver ha creato il DSN file. SQLCreateDataSource restituisce TRUE. Se SQLDriverConnect non restituisce SQL_SUCCESS, una finestra di messaggio di avviso indica che non è stato possibile stabilire una connessione all'origine dati. È comunque possibile creare un DSN con informazioni di connessione minime. Questa finestra di messaggio consente all'utente di annullare o continuare con la creazione del DSN file.

Se l'utente sceglie di continuare a creare il DSN, questo processo continua come se l'opzione Verifica questa connessione fosse impostata su FALSE. Se l'utente sceglie di annullare, viene restituito FALSE per SQLCreateDataSource con un codice di errore di ODBC_ERROR_CREATE_DSN_FAILED.

Se l'origine dati file è stata selezionata come tipo di origine dati e l'opzione Verifica questa connessione è FALSE, viene creato un DSN file con la parola chiave DRIVER e la stringa di connessione specificata dall'utente (se presente) dalla pagina Avanzate della procedura guidata. Se la creazione del file ha avuto esito positivo, viene restituito TRUE per SQLCreateDataSource. Se la creazione del file non è riuscita, viene visualizzata una finestra di messaggio di errore che informa l'utente con qualsiasi errore restituito dal sistema operativo. FALSE viene restituito per SQLCreateDataSource con un codice di errore di ODBC_ERROR_CREATE_DSN_FAILED. Per altre informazioni sulle origini dati dei file, vedere Connessione tramite origini dati file o vedere SQLDriverConnect.

Se l'opzione User o System Data Source è stata selezionata come tipo di origine dati, ConfigDSN nella libreria di installazione driver viene chiamata con il ODBC_ADD_DSN fRequest. Per altre informazioni, vedere ConfigDSN.

Per informazioni su Vedere
Gestione delle origini dati SQLManageDataSources