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.

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.

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.

Fonctions connexes

Voir aussi

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