Condividi tramite

Funzione SQLInstallTranslatorEx

  • Articolo

Conformità
Versione introdotta: ODBC 3.0

Riepilogo
SQLInstallTranslatorEx aggiunge informazioni su un traduttore alla sezione Odbcinst.ini delle informazioni di sistema (HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST. Chiave del Registro di sistema INI\ODBC Translators).

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

Sintassi

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

Argomenti

lpszTranslator
[Input] Deve contenere un elenco con terminazione null doubly di coppie chiave-valore che descrivono il traduttore. Per altre informazioni sulla sintassi delle coppie di parole chiave-valore, vedere Translator Specification Subkeys(Sottochiavi di specifiche translator).

Le parole chiave Translator e Setup devono essere incluse nella stringa lpszTranslator . La DLL di traduzione è elencata con la parola chiave Translator e la DLL di installazione del traduttore è elencata con la parola chiave Setup . 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 lpszTranslator è il seguente:

\0Translator=translator-DLL-filename\0[Setup=setup-DLL-filename\0]\0

lpszPathIn
[Input] Percorso completo del percorso in cui deve essere installato il traduttore o un puntatore Null. Se lpszPath è un puntatore Null, i traduttori verranno installati nella directory di sistema.

lpszPathOut
[Output] Percorso della directory di destinazione in cui deve essere installato il traduttore. Se il traduttore non è mai stato installato, lpszPathOut corrisponde a lpszPathIn. Se esiste un'installazione precedente del traduttore, lpszPathOut è il percorso dell'installazione precedente.

cbPathOutMax
[Input] Lunghezza di lpszPathOut.

pcbPathOut
[Output] Numero totale di byte disponibili 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 pcbPathOutMax meno il carattere di terminazione null. L'argomento pcbPathOut può essere un puntatore Null.

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

ODBC_INSTALL_INQUIRY: chiedere dove è possibile installare un traduttore.

ODBC_INSTALL_COMPLETE: completare la richiesta di installazione.

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

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

Resi

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

Diagnostica

Quando SQLInstallTranslatorEx 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_BUFF_LEN Lunghezza del buffer non valida L'argomento lpszPathOut non è sufficientemente grande da contenere il percorso di output. Il buffer contiene il percorso troncato.

L'argomento cbPathOutMax era 0 e l'argomento fRequest era ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE Tipo di richiesta non valido L'argomento fRequest non è uno dei seguenti:

ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE Coppie chiave-valore non valide L'argomento lpszTranslator contiene un errore di sintassi.
ODBC_ERROR_INVALID_PATH Percorso di installazione non valido L'argomento lpszPathIn contiene un percorso non valido.
ODBC_ERROR_INVALID_PARAM_SEQUENCE Sequenza di parametri non valida L'argomento lpszTranslator non contiene un elenco di coppie chiave-valore.
ODBC_ERROR_USAGE_UPDATE_FAILED Impossibile incrementare o decrementare il numero di utilizzo dei componenti del Registro di sistema Il programma di installazione non è riuscito ad incrementare il numero di utilizzo del traduttore.

Commenti

SQLInstallTranslatorEx fornisce un meccanismo per installare solo il traduttore. Questa funzione non copia effettivamente alcun file. Il programma chiamante è responsabile della copia dei file di traduzione.

SQLInstallTranslatorEx incrementa il numero di utilizzo dei componenti per il traduttore installato di 1. Se esiste già una versione del traduttore, ma il numero di utilizzo dei componenti per il traduttore 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 traduttore e della gestione del numero di utilizzo dei file. Se il file traduttore non è stato installato in precedenza, il programma di installazione dell'applicazione deve copiare il file o i file e creare il numero di utilizzo dei file o dei file. Se il file è stato installato in precedenza, il programma di installazione incrementa semplicemente il numero di utilizzo dei file.

Se una versione precedente del traduttore è stata installata in precedenza dall'applicazione, il traduttore deve essere disinstallato e quindi reinstallato, in modo che il conteggio dell'utilizzo del componente traduttore sia valido. SQLRemoveTranslator deve essere chiamato per decrementare il numero di utilizzo dei componenti e quindi è necessario chiamare SQLInstallTranslatorEx per incrementare il numero di utilizzo dei componenti. Il programma di installazione dell'applicazione deve sostituire il file o i file precedenti con il nuovo file. Il numero di utilizzo dei file rimarrà invariato e altre applicazioni che usavano il file di versione precedente useranno ora la versione più recente.

La lunghezza del percorso in lpszPathOut in SQLInstallTranslatorEx consente un processo di installazione in due fasi, in modo che un'applicazione possa determinare quale cbPathOutMax deve essere chiamando SQLInstallTranslatorEx con un fRequest della modalità ODBC_INSTALL_INQUIRY. Verrà restituito il numero totale di byte disponibili nel buffer pcbPathOut . SQLInstallTranslatorEx 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 SQLInstallTranslatorEx, è 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, SQLInstallTranslatorEx 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.

Per informazioni su Vedere
Restituzione di un'opzione di traduzione predefinita ConfigTranslator
Selezione di traduttori SQLGetTranslator
Rimozione dei traduttori SQLRemoveTranslator