Funzione SQLInstallDriverEx

Conformità
Versione introdotta: ODBC 3.0

Riepilogo
SQLInstallDriverEx aggiunge informazioni sul driver alla voce Odbcinst.ini nelle informazioni di sistema e incrementa il valore UsageCount del driver di 1. Tuttavia, se esiste già una versione del driver, ma il valore UsageCount per il driver non esiste, il nuovo valore UsageCount è impostato su 2.

Questa funzione non copia effettivamente alcun file. È responsabilità del programma chiamante copiare correttamente i file del driver nella directory di destinazione.

È anche possibile accedere alle funzionalità di SQLInstallDriverEx con ODBCCONF.EXE.

Sintassi

  
BOOL SQLInstallDriverEx(  
     LPCSTR    lpszDriver,  
     LPCSTR    lpszPathIn,  
     LPSTR     lpszPathOut,  
     WORD      cbPathOutMax,  
     WORD *    pcbPathOut,  
     WORD      fRequest,  
     LPDWORD   lpdwUsageCount);  

Argomenti

lpszDriver
[Input] Descrizione del driver (in genere il nome del DBMS associato) presentato agli utenti invece del nome del driver fisico. L'argomento lpszDriver deve contenere un elenco doubly con terminazione Null di coppie chiave-valore che descrivono il driver. Per altre informazioni sulle coppie chiave-valore, vedere Sottochiavi specifiche del driver. Per altre informazioni sulla stringa con terminazione null doubly, vedere Funzione ConfigDSN.

lpszPathIn
[Input] Percorso completo della directory di destinazione dell'installazione o puntatore Null. Se lpszPathIn è un puntatore Null, i driver verranno installati nella directory di sistema.

lpszPathOut
[Output] Percorso della directory di destinazione in cui deve essere installato il driver. Se il driver non è stato installato in precedenza, lpszPathOut deve essere uguale a lpszPathIn. Se il driver è stato installato in precedenza, lpszPathOut è il percorso dell'installazione precedente.

cbPathOutMax
[Input] Lunghezza di lpszPathOut.

pcbPathOut
[Output] Numero totale di byte (escluso il carattere di terminazione Null) disponibile per la restituzione in lpszPathOut. Se il numero di byte disponibili per la restituzione è maggiore o uguale a cbPathOutMax, il percorso di output in lpszPathOutOut viene troncato a cbPathOutMax meno il carattere di terminazione null. L'argomento pcbPathOut può essere un puntatore Null.

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

ODBC_INSTALL_INQUIRY: chiedere dove è possibile installare un driver.

ODBC_INSTALL_COMPLETE: completare la richiesta di installazione.

lpdwUsageCount
[Output] Numero di utilizzo del driver dopo la chiamata di questa funzione.

Le applicazioni non dovrebbero impostare il conteggio di utilizzo. ODBC manterrà questo conteggio.

Valori restituiti

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

Diagnostica

Quando SQLInstallDriverEx 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.

Commenti

L'argomento lpszDriver è un 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. Il formato di questo elenco è il seguente:

driver-desc\ 0Driver=driver-DLL-filename\0[Setup=setup-DLL-filename\0]

[driver-attr-keyword1 value1\=0][driver-attr-keyword2 value2=\0]...\0

dove \0 è un byte Null e driver-attr-keywordn è qualsiasi parola chiave dell'attributo driver. Le parole chiave devono essere visualizzate nell'ordine specificato. Si supponga, ad esempio, che un driver per i file di testo formattati disponga di DLL di driver e di installazione separate e possa usare file con le estensioni .txt e .csv. L'argomento lpszDriver per questo driver potrebbe essere il seguente:

Text\0Driver=TEXT.DLL\0Setup=TXTSETUP.DLL\0FileUsage=1\0  
FileExtns=*.txt,*.csv\0\0  

Si supponga che un driver per SQL Server non disponga di una DLL di installazione separata e che non disponga di parole chiave per gli attributi del driver. L'argomento lpszDriver per questo driver potrebbe essere il seguente:

SQL Server\0Driver=SQLSRVR.DLL\0\0  

Dopo che SQLInstallDriverEx recupera informazioni sul driver dall'argomento lpszDriver , aggiunge la descrizione del driver alla sezione [Driver ODBC] della voce Odbcinst.ini nelle informazioni di sistema. Crea quindi una sezione intitolata con la descrizione del driver e aggiunge i percorsi completi della DLL del driver e della DLL di installazione. Infine, restituisce il percorso della directory di destinazione dell'installazione, ma non copia i file del driver. Il programma chiamante deve effettivamente copiare i file del driver nella directory di destinazione.

SQLInstallDriverEx incrementa il numero di utilizzo dei componenti per il driver installato di 1. Se esiste già una versione del driver, ma il numero di utilizzo dei componenti per il driver non esiste, il nuovo valore del conteggio di utilizzo dei componenti è impostato su 2.

Il programma di installazione dell'applicazione è responsabile della copia fisica del file del driver e della gestione del numero di utilizzo dei file. Se il file del driver non è stato installato in precedenza, il programma di installazione dell'applicazione deve copiare il file nel percorso lpszPathIn e creare il numero di utilizzo dei file. Se il file è stato installato in precedenza, il programma di installazione incrementa semplicemente il numero di utilizzo dei file e restituisce il percorso dell'installazione precedente nell'argomento lpszPathOut .

Se una versione precedente del file del driver è stata installata in precedenza dall'applicazione, il driver deve essere disinstallato e quindi reinstallato, in modo che il numero di utilizzo dei componenti driver sia valido. SQLConfigDriver (con fRequest di ODBC_REMOVE_DRIVER) deve prima essere chiamato e quindi SQLRemoveDriver deve essere chiamato per decrementare il numero di utilizzo dei componenti. SQLInstallDriverEx deve quindi essere chiamato per reinstallare il driver, incrementando il numero di utilizzo dei componenti. Il programma di installazione dell'applicazione deve sostituire il file precedente con il nuovo file. Il numero di utilizzo dei file rimarrà invariato e qualsiasi altra applicazione che usa il file di versione precedente userà ora la versione più recente.

La lunghezza del percorso in lpszPathOut in SQLInstallDriverEx consente un processo di installazione in due fasi, in modo che un'applicazione possa determinare quale cbPathOutMax deve essere chiamando SQLInstallDriverEx con un fRequest della modalità ODBC_INSTALL_INQUIRY. Verrà restituito il numero totale di byte disponibili nel buffer pcbPathOut . SQLInstallDriverEx può quindi essere chiamato con un fRequest di ODBC_INSTALL_COMPLETE e l'argomento cbPathOutMax impostato sul valore nel buffer pcbPathOut , più il carattere di terminazione null.

Se si sceglie di non usare il modello a due fasi per SQLInstallDriverEx, è necessario impostare cbPathOutMax, che definisce le dimensioni dell'archiviazione per il percorso della directory di destinazione, sul valore _MAX_PATH, come definito in Stdlib.h, per evitare il troncamento.

Quando fRequest è ODBC_INSTALL_COMPLETE, SQLInstallDriverEx non consente a lpszPathOut di essere NULL (o cbPathOutMax su 0). Se fRequest è ODBC_INSTALL_COMPLETE, false viene restituito quando il numero di byte disponibili per la restituzione è maggiore o uguale a cbPathOutMax, con il risultato che si verifica il troncamento.

Dopo che SQLInstallDriverEx è stato chiamato e il programma di installazione dell'applicazione ha copiato il file del driver (se necessario), la DLL di installazione del driver deve chiamare SQLConfigDriver per impostare la configurazione per il driver.

Funzioni correlate