SQLConfigDriver, fonction

Conformité
Version introduite : ODBC 2.5

Résumé
SQLConfigDriver charge la DLL d’installation de pilote appropriée et appelle la fonction ConfigDriver .

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

Syntaxe

  
BOOL SQLConfigDriver(  
     HWND     hwndParent,  
     WORD     fRequest,  
     LPCSTR   lpszDriver,  
     LPCSTR   lpszArgs,  
     LPSTR    lpszMsg,  
     WORD     cbMsgMax,  
     WORD *   pcbMsgOut);  

Arguments

hwndParent
[Entrée] Poignée de fenêtre parente. La fonction n’affiche aucune boîte de dialogue si le handle est null.

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

ODBC_CONFIG_DRIVER : modifie le délai d’expiration du regroupement de connexions utilisé par le pilote.

ODBC_INSTALL_DRIVER : installe un nouveau pilote.

ODBC_REMOVE_DRIVER : supprime un pilote existant.

Cette option peut également être spécifique au pilote, auquel cas la requête fRequest pour la première option doit commencer à partir de ODBC_CONFIG_DRIVER_MAX+1. La requête fRequest pour toute option supplémentaire doit également commencer à partir d’une valeur supérieure à ODBC_CONFIG_DRIVER_MAX+1.

lpszDriver
[Entrée] Nom du pilote tel qu’inscrit dans les informations système.

lpszArgs
[Entrée] Chaîne terminée par null qui contient des arguments pour une demande fRequest spécifique au pilote.

lpszMsg
[Sortie] Chaîne terminée par null qui contient un message de sortie de l’installation du pilote.

cbMsgMax
[Entrée] Longueur de lpszMsg.

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

Retours

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

Diagnostics

Lorsque SQLConfigDriver 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 lpszMsg n’était pas valide.
ODBC_ERROR_INVALID_HWND	Handle de fenêtre non valide	L’argument hwndParent n’est pas valide.
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_DRIVER ODBC_REMOVE_DRIVER L’argument fRequest était une option spécifique au pilote qui était inférieure ou égale à ODBC_CONFIG_DRIVER_MAX.
ODBC_ERROR_INVALID_NAME	Nom du pilote ou du traducteur non valide	L’argument lpszDriver n’était pas valide. Il est introuvable dans le Registre.
ODBC_ERROR_INVALID_KEYWORD_VALUE	Paires mot clé-valeur non valides	L’argument lpszArgs contenait une erreur de syntaxe.
ODBC_ERROR_REQUEST_FAILED	Échec de la demande	Le programme d’installation n’a pas pu effectuer l’opération demandée par l’argument fRequest . L’appel à ConfigDriver a échoué.
ODBC_ERROR_LOAD_LIBRARY_FAILED	Impossible de charger le pilote ou la bibliothèque de configuration du traducteur	Impossible de charger la bibliothèque d’installation du pilote.
ODBC_ERROR_OUT_OF_MEM	Mémoire insuffisante	Le programme d’installation n’a pas pu effectuer la fonction en raison d’un manque de mémoire.

Commentaires

SQLConfigDriver permet à une application d’appeler la routine ConfigDriver d’un pilote sans avoir à connaître le nom et à charger la DLL d’installation spécifique au pilote. Un programme d’installation appelle cette fonction une fois la DLL d’installation du pilote installée. Le programme appelant doit être conscient que cette fonction n’est peut-être pas disponible pour tous les pilotes. Dans ce cas, le programme appelant doit continuer sans erreur.

options Driver-Specific

Une application peut demander des fonctionnalités spécifiques au pilote exposées par le pilote à l’aide de l’argument fRequest . La requête fRequest pour la première option sera ODBC_CONFIG_DRIVER_MAX+1, et les options supplémentaires seront incrémentées de 1 à partir de cette valeur. Tous les arguments requis par le pilote pour cette fonction doivent être fournis dans une chaîne terminée par null passée dans l’argument lpszArgs . Les pilotes fournissant ces fonctionnalités doivent conserver une table des options spécifiques aux pilotes. Les options doivent être entièrement documentées dans la documentation du pilote. Les rédacteurs d’applications qui utilisent des options spécifiques au pilote doivent savoir que cette utilisation rendra l’application moins interopérable.

Définition du délai d’expiration du regroupement de connexions

Les propriétés du délai d’expiration du regroupement de connexions peuvent être définies lorsque vous définissez la configuration du pilote. SQLConfigDriver est appelé avec une requête fRequest de ODBC_CONFIG_DRIVER et lpszArgs définie sur CPTimeout. CPTimeout détermine la période pendant laquelle une connexion peut rester dans le pool de connexions sans être utilisée. Lorsque le délai d’expiration expire, la connexion est fermée et supprimée du pool. Le délai d’expiration par défaut est de 60 secondes.

Lorsque SQLConfigDriver est appelé avec fRequest défini sur ODBC_INSTALL_DRIVER ou ODBC_REMOVE_DRIVER, le Gestionnaire de pilotes charge la DLL d’installation de pilote appropriée et appelle la fonction ConfigDriver . Lorsque SQLConfigDriver est appelé avec une requête fRequest de ODBC_CONFIG_DRIVER, tout le traitement est effectué dans le programme d’installation ODBC, de sorte que la DLL d’installation du pilote n’a pas besoin d’être chargée.

Messages

Une routine de configuration de pilote peut envoyer un sms à une application sous forme de chaînes terminées par null dans la mémoire tampon lpszMsg . Le message sera tronqué en cbMsgMax moins le caractère d’arrêt Null par la fonction ConfigDriver s’il est supérieur ou égal à des caractères cbMsgMax .

Fonctions connexes

Pour obtenir des informations sur	Consultez
Ajout, modification ou suppression d’un pilote	ConfigDriver(dans la DLL d’installation)
Suppression de la source de données par défaut	SQLRemoveDefaultDataSource