SQLInstallTranslatorEx, fonction

Conformité
Version introduite : ODBC 3.0

Résumé
SQLInstallTranslatorEx ajoute des informations sur un traducteur à la section Odbcinst.ini des informations système (HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\clé de Registre ODBC Translators).

Les fonctionnalités de SQLInstallTranslatorEx sont également accessibles avec ODBCCONF.EXE.

Syntaxe

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

Arguments

lpszTranslator
[Entrée] Celle-ci doit contenir une liste doublement terminée par un caractère Null de paires mot clé-valeur décrivant le traducteur. Pour plus d’informations sur la syntaxe des paires mot clé-valeur, consultez Sous-clés de spécification Translator.

Les mots clés Translator et Setup doivent être inclus dans la chaîne lpszTranslator . La DLL de traduction est répertoriée avec le mot clé Translator , et la DLL d’installation de translator est répertoriée avec le mot clé Setup . Chaque paire se termine par un octet NULL, et la liste entière est terminée par un octet NULL. (Autrement dit, deux octets NULL marquent la fin de la liste.) Le format de lpszTranslator est le suivant :

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

lpszPathIn
[Entrée] Chemin d’accès complet de l’emplacement où le traducteur doit être installé ou un pointeur Null. Si lpszPath est un pointeur null, les traducteurs sont installés dans le répertoire Système.

lpszPathOut
[Sortie] Chemin du répertoire cible dans lequel le traducteur doit être installé. Si le traducteur n’a jamais été installé, lpszPathOut est identique à lpszPathIn. S’il existe une installation antérieure du traducteur, lpszPathOut est le chemin de l’installation précédente.

cbPathOutMax
[Entrée] Longueur de lpszPathOut.

pcbPathOut
[Sortie] Nombre total d’octets disponibles à retourner dans lpszPathOut. Si le nombre d’octets disponibles à retourner est supérieur ou égal à cbPathOutMax, le chemin de sortie dans lpszPathOutOut est tronqué en pcbPathOutMax moins le caractère d’arrêt Null. L’argument pcbPathOut peut être un pointeur null.

fRequest
[Entrée] Type de demande. fRequest doit contenir l’une des valeurs suivantes :

ODBC_INSTALL_INQUIRY : Renseignez-vous sur l’emplacement où un traducteur peut être installé.

ODBC_INSTALL_COMPLETE : terminez la demande d’installation.

lpdwUsageCount
[Sortie] Nombre d’utilisations du traducteur après l’appel de cette fonction.

Les applications ne doivent pas définir le nombre d’utilisations. ODBC conserve ce nombre.

Retours

La fonction retourne TRUE si elle réussit, FALSE en cas d’échec.

Diagnostics

Lorsque SQLInstallTranslatorEx retourne FALSE, une valeur *pfErrorCode associée peut être obtenue en appelant SQLInstallerError. Le tableau suivant répertorie les valeurs *pfErrorCode qui peuvent être retournées par SQLInstallerError et explique chacune d’elles dans le contexte de cette fonction.

*pfErrorCode	Error	Description
ODBC_ERROR_GENERAL_ERR	Erreur générale du programme d’installation	Une erreur s’est produite pour laquelle il n’y avait pas d’erreur de programme d’installation spécifique.
ODBC_ERROR_INVALID_BUFF_LEN	Longueur de la mémoire tampon non valide	L’argument lpszPathOut n’était pas assez grand pour contenir le chemin de sortie. La mémoire tampon contient le chemin d’accès tronqué. L’argument cbPathOutMax était 0 et l’argument fRequest était ODBC_INSTALL_COMPLETE.
ODBC_ERROR_INVALID_REQUEST_TYPE	Type de requête non valide	L’argument fRequest n’était pas l’un des éléments suivants : ODBC_INSTALL_INQUIRY ODBC_INSTALL_COMPLETE
ODBC_ERROR_INVALID_KEYWORD_VALUE	Paires mot clé-valeur non valides	L’argument lpszTranslator contenait une erreur de syntaxe.
ODBC_ERROR_INVALID_PATH	Chemin d’installation non valide	L’argument lpszPathIn contenait un chemin d’accès non valide.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Séquence de paramètres non valide	L’argument lpszTranslator ne contenait pas de liste de paires mot clé-valeur.
ODBC_ERROR_USAGE_UPDATE_FAILED	Impossible d’incrémenter ou de décrémenter le nombre d’utilisation des composants du Registre	Le programme d’installation n’a pas pu incrémenter le nombre d’utilisations du traducteur.

Commentaires

SQLInstallTranslatorEx fournit un mécanisme pour installer uniquement le traducteur. Cette fonction ne copie pas réellement de fichiers. Le programme appelant est chargé de copier les fichiers du traducteur.

SQLInstallTranslatorEx incrémente le nombre d’utilisation des composants pour le traducteur installé de 1. Si une version du traducteur existe déjà, mais que le nombre d’utilisation des composants pour le traducteur n’existe pas, la valeur du nouveau nombre d’utilisation des composants est définie sur 2.

Le programme d’installation de l’application est chargé de copier physiquement le fichier translator et de maintenir le nombre d’utilisations de fichiers. Si le fichier translator n’a pas été installé précédemment, le programme d’installation de l’application doit copier le ou les fichiers et créer le nombre d’utilisations de fichiers. Si le fichier a été installé précédemment, le programme d’installation incrémente simplement le nombre d’utilisations de fichiers.

Si une version antérieure du traducteur a été précédemment installée par l’application, le traducteur doit être désinstallé, puis réinstallé, afin que le nombre d’utilisations du composant translator soit valide. SQLRemoveTranslator doit être appelé pour décrémenter le nombre d’utilisations des composants, puis SQLInstallTranslatorEx doit être appelé pour incrémenter le nombre d’utilisation des composants. Le programme d’installation de l’application doit remplacer le ou les anciens fichiers par le nouveau fichier. Le nombre d’utilisations de fichiers reste le même, et les autres applications qui utilisaient l’ancienne version utilisent désormais la version la plus récente.

La longueur du chemin d’accès dans lpszPathOut dans SQLInstallTranslatorEx permet un processus d’installation en deux phases, de sorte qu’une application peut déterminer ce que cbPathOutMax doit être en appelant SQLInstallTranslatorEx avec une requête fRequest en mode ODBC_INSTALL_INQUIRY. Cela retourne le nombre total d’octets disponibles dans la mémoire tampon pcbPathOut . SQLInstallTranslatorEx peut ensuite être appelé avec une requête fRequest de ODBC_INSTALL_COMPLETE et l’argument cbPathOutMax défini sur la valeur dans la mémoire tampon pcbPathOut , plus le caractère d’arrêt Null.

Si vous choisissez de ne pas utiliser le modèle en deux phases pour SQLInstallTranslatorEx, vous devez définir cbPathOutMax, qui définit la taille du stockage pour le chemin du répertoire cible, sur la valeur _MAX_PATH, comme défini dans Stdlib.h, pour empêcher la troncation.

Lorsque fRequest est ODBC_INSTALL_COMPLETE, SQLInstallTranslatorEx n’autorise pas lpszPathOut à avoir la valeur NULL (ou cbPathOutMax sur 0). Si fRequest est ODBC_INSTALL_COMPLETE, FALSE est retourné lorsque le nombre d’octets disponibles à retourner est supérieur ou égal à cbPathOutMax, ce qui entraîne la troncation.

Fonctions connexes

Pour obtenir des informations sur	Consultez
Retour d’une option de traduction par défaut	ConfigTranslator
Sélection des traducteurs	SQLGetTranslator
Suppression de traducteurs	SQLRemoveTranslator