Fonction SQLGetConnectAttr

Conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92

Résumé
SQLGetConnectAttr retourne le paramètre actuel d’un attribut de connexion.

Notes

Pour plus d’informations sur ce à quoi le Gestionnaire de pilotes mappe cette fonction lorsqu’une application ODBC 3*.x* fonctionne avec un pilote ODBC 2*.x*, consultez Mappage des fonctions de remplacement pour la compatibilité descendante des applications.

Syntaxe

  
SQLRETURN SQLGetConnectAttr(  
     SQLHDBC        ConnectionHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);  

Arguments

ConnectionHandle
[Entrée] Handle de connexion.

Attribut
[Entrée] Attribut à récupérer.

ValuePtr
[Sortie] Pointeur vers la mémoire dans laquelle retourner la valeur actuelle de l’attribut spécifié par Attribute. Pour les attributs de type entier, certains pilotes peuvent écrire uniquement les 32 bits inférieurs ou 16 bits d’une mémoire tampon et laisser le bit d’ordre supérieur inchangé. Par conséquent, les applications doivent utiliser une mémoire tampon de SQLULEN et initialiser la valeur sur 0 avant d’appeler cette fonction.

Si ValuePtr a la valeur NULL, StringLengthPtr retourne toujours le nombre total d’octets (à l’exclusion du caractère d’arrêt Null pour les données de caractères) pouvant être retournés dans la mémoire tampon vers laquelle valuePtr pointe.

BufferLength
[Entrée] Si Attribute est un attribut défini par ODBC et que ValuePtr pointe vers une chaîne de caractères ou une mémoire tampon binaire, cet argument doit être la longueur de *ValuePtr. Si Attribute est un attribut défini par ODBC et *ValuePtr est un entier, BufferLength est ignoré. Si la valeur dans *ValuePtr est une chaîne Unicode (lors de l’appel de SQLGetConnectAttrW), l’argument BufferLength doit être un nombre pair.

Si Attribut est un attribut défini par le pilote, l’application indique la nature de l’attribut au Gestionnaire de pilotes en définissant l’argument BufferLength . BufferLength peut avoir les valeurs suivantes :

• Si *ValuePtr est un pointeur vers une chaîne de caractères, BufferLength est la longueur de la chaîne.

• Si *ValuePtr est un pointeur vers une mémoire tampon binaire, l’application place le résultat de la macro SQL_LEN_BINARY_ATTR(length) dans BufferLength. Cela place une valeur négative dans BufferLength.

• Si *ValuePtr est un pointeur vers une valeur autre qu’une chaîne de caractères ou une chaîne binaire, BufferLength doit avoir la valeur SQL_IS_POINTER.

• Si *ValuePtr contient un type de données de longueur fixe, BufferLength est SQL_IS_INTEGER ou SQL_IS_UINTEGER, selon le cas.

StringLengthPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le nombre total d’octets (à l’exclusion du caractère de terminaison Null) disponibles à retourner dans *ValuePtr. Si la valeur d’attribut est une chaîne de caractères et que le nombre d’octets disponibles à retourner est supérieur à BufferLength moins la longueur du caractère d’arrêt null, les données de *ValuePtr sont tronquées en BufferLength moins la longueur du caractère d’arrêt Null et sont terminées par null par le pilote.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLGetConnectAttr retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue à partir de la structure de données de diagnostic en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_DBC et un Handlede ConnectionHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLGetConnectAttr et explique chacune d’elles dans le contexte de cette fonction ; La notation « (DM) » précède les descriptions de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

SQLSTATE	Error	Description
01000	Avertissement général	Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
01004	Données de chaîne, tronquées à droite	Les données retournées dans *ValuePtr ont été tronquées pour être BufferLength moins la longueur d’un caractère d’arrêt Null. La longueur de la valeur de chaîne non chiffrée est retournée dans *StringLengthPtr. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
08003	Connexion non ouverte	(DM) Une valeur d’attribut qui nécessitait une connexion ouverte a été spécifiée.
08S01	Échec de la liaison de communication	Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant la fin du traitement de la fonction.
HY000	Erreur générale	Une erreur s’est produite pour laquelle il n’y avait pas de SQLSTATE spécifique et pour laquelle aucun SQLSTATE spécifique à l’implémentation n’a été défini. Le message d’erreur retourné par la structure des données de diagnostic par l’argument MessageText dans SQLGetDiagField décrit l’erreur et sa cause.
HY001	Erreur d’allocation de mémoire	Le pilote n’a pas pu allouer la mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction.
HY010	Erreur de séquence de fonction	(DM) SQLBrowseConnect a été appelé pour connectionHandle et a retourné SQL_NEED_DATA. Cette fonction a été appelée avant que SQLBrowseConnect ne retourne SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour connectionHandle et a retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés en continu.
HY013	Erreur de gestion de la mémoire	L’appel de fonction n’a pas pu être traité, car les objets de mémoire sous-jacents n’ont pas pu être accessibles, peut-être en raison de conditions de mémoire insuffisantes.
HY090	Chaîne ou longueur de mémoire tampon non valide	(DM) *ValuePtr est une chaîne de caractères, et BufferLength était inférieur à zéro, mais pas égal à SQL_NTS.
HY092	Identificateur d’attribut/d’option non valide	La valeur spécifiée pour l’argument Attribute n’était pas valide pour la version d’ODBC prise en charge par le pilote.
HY114	Le pilote ne prend pas en charge l’exécution de fonctions asynchrones au niveau de la connexion	(DM) Une application a tenté d’activer l’exécution asynchrone de fonction avec SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE pour un pilote qui ne prend pas en charge les opérations de connexion asynchrones.
HY117	La connexion est suspendue en raison d’un état de transaction inconnu. Seules les fonctions de déconnexion et de lecture seule sont autorisées.	(DM) Pour plus d’informations sur l’état suspendu, consultez Fonction SQLEndTran.
HYC00	Fonctionnalité facultative non implémentée	La valeur spécifiée pour l’argument Attribut était un attribut de connexion ODBC valide pour la version d’ODBC prise en charge par le pilote, mais n’était pas prise en charge par le pilote.
HYT01	Délai d’attente de la connexion expiré	Le délai d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. Le délai d’expiration de connexion est défini via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.
IM001	Le pilote ne prend pas en charge cette fonction	(DM) Le pilote qui correspond à ConnectionHandle ne prend pas en charge la fonction .

Commentaires

Pour obtenir des informations générales sur les attributs de connexion, consultez Attributs de connexion.

Pour obtenir la liste des attributs qui peuvent être définis, consultez SQLSetConnectAttr. Notez que si Attribute spécifie un attribut qui retourne une chaîne, ValuePtr doit être un pointeur vers une mémoire tampon pour la chaîne. La longueur maximale de la chaîne retournée, y compris le caractère d’arrêt null, sera d’octets BufferLength .

Selon l’attribut, une application n’a pas besoin d’établir une connexion avant d’appeler SQLGetConnectAttr. Toutefois, si SQLGetConnectAttr est appelé et que l’attribut spécifié n’a pas de valeur par défaut et n’a pas été défini par un appel antérieur à SQLSetConnectAttr, SQLGetConnectAttr retourne SQL_NO_DATA.

Si Attribute est SQL_ATTR_ TRACE ou SQL_ATTR_ TRACEFILE, ConnectionHandle n’a pas besoin d’être valide et SQLGetConnectAttr ne retourne pas SQL_ERROR ou SQL_INVALID_HANDLE si ConnectionHandle n’est pas valide. Ces attributs s’appliquent à toutes les connexions. SQLGetConnectAttr retourne SQL_ERROR ou SQL_INVALID_HANDLE si un autre argument n’est pas valide.

Bien qu’une application puisse définir des attributs d’instruction à l’aide de SQLSetConnectAttr, une application ne peut pas utiliser SQLGetConnectAttr pour récupérer des valeurs d’attribut d’instruction ; il doit appeler SQLGetStmtAttr pour récupérer le paramètre des attributs d’instruction.

Les attributs de connexion SQL_ATTR_AUTO_IPD et SQL_ATTR_CONNECTION_DEAD peuvent être retournés par un appel à SQLGetConnectAttr , mais ils ne peuvent pas être définis par un appel à SQLSetConnectAttr.

Notes

Il n’existe aucune prise en charge asynchrone de SQLGetConnectAttr. Lors de l’implémentation de SQLGetConnectAttr, un pilote peut améliorer les performances en réduisant le nombre de fois où des informations sont envoyées ou demandées à partir du serveur.

Fonctions connexes

Pour obtenir des informations sur	Consultez
Retour du paramètre d’un attribut d’instruction	Fonction SQLGetStmtAttr
Définition d’un attribut de connexion	Fonction SQLSetConnectAttr
Définition d’un attribut d’environnement	Fonction SQLSetEnvAttr
Définition d’un attribut d’instruction	Fonction SQLSetStmtAttr

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC