SQLInstallDriverEx, fonction

Conformité
Version introduite : ODBC 3.0

Résumé
SQLInstallDriverEx ajoute des informations sur le pilote à l’entrée Odbcinst.ini dans les informations système et incrémente l’usageCount du pilote de 1. Toutefois, si une version du pilote existe déjà, mais que la valeur UsageCount du pilote n’existe pas, la nouvelle valeur UsageCount est définie sur 2.

Cette fonction ne copie pas réellement de fichiers. Il incombe au programme appelant de copier correctement les fichiers du pilote dans le répertoire cible.

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

Syntaxe

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

Arguments

lpszDriver
[Entrée] Description du pilote (généralement le nom du SGBD associé) présentée aux utilisateurs au lieu du nom du pilote physique. L’argument lpszDriver doit contenir une liste doublement null de paires mot clé-valeur décrivant le pilote. Pour plus d’informations sur les paires mot clé-valeur, consultez Les sous-clés de spécification du pilote. Pour plus d’informations sur la chaîne doublement terminée par null, consultez La fonction ConfigDSN.

lpszPathIn
[Entrée] Chemin complet du répertoire cible de l’installation ou d’un pointeur Null. Si lpszPathIn est un pointeur Null, les pilotes sont installés dans le répertoire système.

lpszPathOut
[Sortie] Chemin du répertoire cible où le pilote doit être installé. Si le pilote n’a pas été installé précédemment, lpszPathOut doit être identique à l’emplacement lpszPathIn. Si le pilote a été installé précédemment, lpszPathOut est le chemin de l’installation précédente.

cbPathOutMax
[Entrée] Longueur de lpszPathOut.

ccpPathOut
[Sortie] Nombre total d’octets (à l’exclusion du caractère de terminaison Null) disponibles pour retourner dans lpszPathOut. Si le nombre d’octets disponibles pour retourner est supérieur ou égal à cbPathOutMax, le chemin de sortie dans lpszPathOut est tronqué en cbPathOutMax moins le caractère de terminaison Null. L’argument ccpPathOut peut être un pointeur Null.

fRequest
[Entrée] Type de requête. L’argument fRequest doit contenir l’une des valeurs suivantes :

ODBC_INSTALL_INQUIRY : Renseignez-vous sur l’emplacement d’installation d’un pilote.

ODBC_INSTALL_COMPLETE : effectuez la demande d’installation.

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

Les applications ne doivent pas définir le nombre d'utilisations. ODBC conservera ce nombre.

Retours

La fonction retourne TRUE si elle réussit, FALSE si elle échoue.

Diagnostics

Lorsque SQLInstallDriverEx 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	Erreur	Description
ODBC_ERROR_GENERAL_ERR	Erreur générale du programme d’installation	Une erreur s’est produite pour laquelle aucune erreur de programme d’installation spécifique n’a été générée.
ODBC_ERROR_INVALID_BUFF_LEN	Longueur de mémoire tampon non valide	L’argument lpszPathOut n’était pas suffisamment grand pour contenir le chemin de sortie. La mémoire tampon contient le chemin tronqué. L’argument cbPathOutMax était 0 et 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 lpszDriver 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_LOAD_LIBRARY_FAILED	Impossible de charger le pilote ou la bibliothèque de configuration translator	Impossible de charger la bibliothèque de configuration du pilote.
ODBC_ERROR_INVALID_PARAM_SEQUENCE	Séquence de paramètres non valide	L’argument lpszDriver 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’utilisations du composant	Le programme d’installation n’a pas pu incrémenter le nombre d’utilisations du pilote.

Commentaires

L’argument lpszDriver est une liste d’attributs sous la forme de paires mot clé-valeur. Chaque paire est terminée avec 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 cette liste est le suivant :

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

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

où \0 est un octet null et driver-attr-keywordn est n’importe quel mot clé d’attribut de pilote. Les mots clés doivent apparaître dans l’ordre spécifié. Par exemple, supposons qu’un pilote pour les fichiers texte mis en forme possède des DLL distinctes et configure des DLL et peut utiliser des fichiers avec les extensions .txt et .csv. L’argument lpszDriver pour ce pilote peut être le suivant :

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

Supposons qu’un pilote pour SQL Server n’a pas de DLL d’installation distincte et n’a pas de mots clés d’attribut de pilote. L’argument lpszDriver pour ce pilote peut être le suivant :

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

Une fois que SQLInstallDriverEx récupère des informations sur le pilote à partir de l’argument lpszDriver , il ajoute la description du pilote à la section [Pilotes ODBC] de l’entrée Odbcinst.ini dans les informations système. Il crée ensuite une section intitulée avec la description du pilote et ajoute les chemins complets de la DLL du pilote et de la DLL d’installation. Enfin, il retourne le chemin d’accès du répertoire cible de l’installation, mais ne copie pas les fichiers du pilote vers celui-ci. Le programme appelant doit en fait copier les fichiers du pilote dans le répertoire cible.

SQLInstallDriverEx incrémente le nombre d’utilisations des composants pour le pilote installé par 1. Si une version du pilote existe déjà, mais que le nombre d’utilisations du composant pour le pilote n’existe pas, la nouvelle valeur du nombre d’utilisations du composant est définie sur 2.

Le programme d’installation de l’application est chargé de copier physiquement le fichier de pilote et de maintenir le nombre d’utilisations de fichiers. Si le fichier de pilote n’a pas été installé précédemment, le programme d’installation de l’application doit copier le fichier dans le chemin lpszPathIn et créer le nombre d’utilisations du fichier. Si le fichier a été installé précédemment, le programme d’installation incrémente simplement le nombre d’utilisations du fichier et retourne le chemin d’accès de l’installation précédente dans l’argument lpszPathOut .

Remarque

Pour plus d’informations sur le nombre d’utilisations des composants et les nombres d’utilisations de fichiers, consultez Comptage d’utilisation.

Si une version antérieure du fichier de pilote a été précédemment installée par l’application, le pilote doit être désinstallé, puis réinstallé, afin que le nombre d’utilisations du composant du pilote soit valide. SQLConfigDriver (avec une requête fRequest de ODBC_REMOVE_DRIVER) doit d’abord être appelé, puis SQLRemoveDriver doit être appelé pour décrémenter le nombre d’utilisations des composants. SQLInstallDriverEx doit ensuite être appelé pour réinstaller le pilote, en incrémentant le nombre d’utilisations des composants. Le programme d’installation de l’application doit remplacer l’ancien fichier par le nouveau fichier. Le nombre d’utilisations de fichiers reste le même, et toute autre application qui a utilisé l’ancien fichier de version utilisera désormais la version la plus récente.

Remarque

Si le pilote a été précédemment installé et QUE SQLInstallDriverEx est appelé pour installer le pilote dans un autre répertoire, la fonction retourne TRUE, mais lpszPathOut inclut le répertoire où le pilote a déjà été installé. Il n’inclut pas le répertoire entré dans l’argument lpszDriver .

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

Si vous choisissez de ne pas utiliser le modèle à deux phases pour SQLInstallDriverEx, 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, SQLInstallDriverEx 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, avec le résultat que la troncation se produit.

Une fois QUE SQLInstallDriverEx a été appelé et que le programme d’installation de l’application a copié le fichier de pilote (si nécessaire), la DLL d’installation du pilote doit appeler SQLConfigDriver pour définir la configuration du pilote.

Fonctions connexes

Pour plus d’informations sur	Consultez
Installation du Gestionnaire de pilotes	SQLInstallDriverManager