SQLGetEnvAttr, fonction

  • Article

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.

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 le 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.)
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 SQLGetDiagRec dans la mémoire tampon *MessageText 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) SQL_ATTR_ODBC_VERSION n’a pas encore été défini via SQLSetEnvAttr. Vous n’avez pas besoin de définir SQL_ATTR_ODBC_VERSION explicitement si vous utilisez SQLAllocHandleStd.
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.
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.
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 Attribute était un attribut d’environnement ODBC valide pour la version d’ODBC prise en charge par le pilote, mais n’était pas prise en charge par le pilote.
IM001 Le pilote ne prend pas en charge cette fonction (DM) Le pilote correspondant à EnvironmentHandle ne prend pas en charge la fonction .

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é.

Notes

L’attribut d’environnement SQL_ATTR_OUTPUT_NTS est pris en charge par les applications conformes aux normes. Lorsque SQLGetEnvAttr est appelé, le Gestionnaire de pilotes ODBC 3*.x* retourne toujours SQL_TRUE pour cet attribut. SQL_ATTR_OUTPUT_NTS peut être défini sur SQL_TRUE uniquement par un appel à SQLSetEnvAttr.

Pour obtenir des informations sur Consultez
Retour du paramètre d’un attribut de connexion Fonction SQLGetConnectAttr
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