SQLGetEnvAttr, fonction

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

Résumé
SQLGetEnvAttr retourne le paramètre actuel d’un attribut d’environnement.

Syntaxe

  
SQLRETURN SQLGetEnvAttr(  
     SQLHENV        EnvironmentHandle,  
     SQLINTEGER     Attribute,  
     SQLPOINTER     ValuePtr,  
     SQLINTEGER     BufferLength,  
     SQLINTEGER *   StringLengthPtr);  

Arguments

EnvironmentHandle
[Entrée] Handle d’environnement.

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

ValuePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner la valeur actuelle de l’attribut spécifié par Attribute.

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 ValuePtr pointe vers une chaîne de caractères, cet argument doit être la longueur de *ValuePtr. Si *ValuePtr est un entier, BufferLength est ignoré. Si *ValuePtr est une chaîne Unicode (lors de l’appel de SQLGetEnvAttrW), l’argument BufferLength doit être un nombre pair. Si la valeur de l’attribut n’est pas une chaîne de caractères, BufferLength n’est pas utilisé.

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 de l’attribut est une chaîne de caractères et que le nombre d’octets disponibles à retourner est supérieur ou égal à BufferLength, les données de *ValuePtr sont tronquées en BufferLength moins la longueur d’un caractère d’arrêt Null et sont terminées par la valeur Null par le pilote.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NO_DATA, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLGetEnvAttr retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec un HandleType de SQL_HANDLE_ENV et un Handle de EnvironmentHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLGetEnvAttr 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 la liste des attributs, consultez SQLSetEnvAttr. Il n’existe aucun attribut d’environnement spécifique au pilote. Si Attribute spécifie un attribut qui renvoie une chaîne, ValuePtr doit être un pointeur vers une mémoire tampon dans laquelle retourner la chaîne. La longueur maximale de la chaîne, y compris l’octet de terminaison Null, sera octets BufferLength .

SQLGetEnvAttr peut être appelé à tout moment entre l’allocation et la libération d’un handle d’environnement. Tous les attributs d’environnement correctement définis par l’application pour l’environnement sont conservés jusqu’à ce que SQLFreeHandle soit appelé sur environmentHandle avec un HandleType de SQL_HANDLE_ENV. Plusieurs handles d’environnement peuvent être alloués simultanément dans ODBC 3*.x*. Un attribut d’environnement sur un environnement n’est pas affecté quand un autre environnement a été alloué.

Fonctions connexes

Voir aussi

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