Fonction SQLSetEnvAttr

  • Article

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

Résumé
SQLSetEnvAttr définit des attributs qui régissent les aspects des environnements.

Syntaxe

  
SQLRETURN SQLSetEnvAttr(  
     SQLHENV      EnvironmentHandle,  
     SQLINTEGER   Attribute,  
     SQLPOINTER   ValuePtr,  
     SQLINTEGER   StringLength);

Arguments

EnvironnementHandle
[Entrée] Handle d’environnement.

Attribut
[Entrée] Attribut à définir, répertorié dans « Commentaires ».

ValuePtr
[Entrée] Pointeur vers la valeur à associer à Attribute. Selon la valeur d’Attribute, ValuePtr est une valeur entière 32 bits ou pointe vers une chaîne de caractères null.

StringLength
[Entrée] Si ValuePtr pointe vers une chaîne de caractères ou une mémoire tampon binaire, cet argument doit être la longueur de *ValuePtr. Pour les données de chaîne de caractères, cet argument doit contenir le nombre d’octets dans la chaîne.

Si ValuePtr est un entier, StringLength est ignoré.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLSetEnvAttr 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 généralement retournées par SQLSetEnvAttr 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. Si un pilote ne prend pas en charge un attribut d’environnement, l’erreur peut être retournée uniquement pendant le temps de connexion.

SQLSTATE Error Description
01000 Avertissement général Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
01S02 Valeur de l’option modifiée Le pilote n’a pas pris en charge la valeur spécifiée dans ValuePtr et a remplacé une valeur similaire. (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.
HY009 Utilisation non valide du pointeur null L’argument Attribute a identifié un attribut d’environnement qui exigeait une valeur de chaîne, et l’argument ValuePtr était un pointeur null.
HY010 Erreur de séquence de fonction (DM) Un handle de connexion a été alloué sur EnvironmentHandle.

(DM) SQL_ATTR_ODBC_VERSION n’a pas été défini avec SQLSetEnvAttr et Attribute n’est pas égal à SQL_ATTR_ODBC_VERSION. 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 consultés, peut-être en raison de conditions de mémoire insuffisantes.
HY024 Valeur d’attribut non valide Compte tenu de la valeur Attribute spécifiée, une valeur non valide a été spécifiée dans ValuePtr.
HY090 Chaîne ou longueur de mémoire tampon non valide L’argument StringLength était inférieur à 0, mais n’était pas SQL_NTS.
HY092 Identificateur d’attribut/d’option non valide (DM) 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.

(DM) L’argument Attribute a été SQL_ATTR_OUTPUT_NTS et ValuePtr a été SQL_FALSE.

Commentaires

Une application peut appeler SQLSetEnvAttr uniquement si aucun handle de connexion n’est alloué sur l’environnement. Tous les attributs d’environnement correctement définis par l’application pour l’environnement persistent jusqu’à ce que SQLFreeHandle soit appelé sur l’environnement. Plusieurs handles d’environnement peuvent être alloués simultanément dans ODBC 3.x.

Le format des informations définies via ValuePtr dépend de l’attribut spécifié. SQLSetEnvAttr accepte les informations d’attribut dans l’un des deux formats différents : une chaîne de caractères null ou une valeur entière 32 bits. Le format de chaque est noté dans la description de l’attribut.

Il n’existe aucun attribut d’environnement spécifique au pilote.

Les attributs de connexion ne peuvent pas être définis par un appel à SQLSetEnvAttr. Si vous essayez d’effectuer cette opération, vous retournez SQLSTATE HY092 (identificateur d’attribut/d’option non valide).

Attribut Contenu de ValuePtr
SQL_ATTR_CONNECTION_POOLING (ODBC 3.8) Valeur SQLUINTEGER 32 bits qui active ou désactive le regroupement de connexions au niveau de l’environnement. Les valeurs suivantes sont utilisées :

SQL_CP_OFF = Le regroupement de connexions est désactivé. Il s’agit de la valeur par défaut.

SQL_CP_ONE_PER_DRIVER = Un pool de connexions unique est pris en charge pour chaque pilote. Chaque connexion dans un pool est associée à un seul pilote.

SQL_CP_ONE_PER_HENV = Un pool de connexions unique est pris en charge pour chaque environnement. Chaque connexion d’un pool est associée à un environnement.

SQL_CP_DRIVER_AWARE = Utilisez la fonctionnalité de sensibilisation du pool de connexions du pilote, si elle est disponible. Si le pilote ne prend pas en charge la sensibilisation du pool de connexions, SQL_CP_DRIVER_AWARE est ignoré et SQL_CP_ONE_PER_HENV est utilisé. Pour plus d’informations, consultez Regroupement de connexions prenant en charge les pilotes. Dans un environnement où certains pilotes prennent en charge et où certains pilotes ne prennent pas en charge la reconnaissance du pool de connexions, SQL_CP_DRIVER_AWARE peut activer la fonctionnalité de sensibilisation du pool de connexions sur les pilotes de prise en charge, mais cela équivaut à définir sur SQL_CP_ONE_PER_HENV sur les pilotes qui ne prennent pas en charge la fonctionnalité de sensibilisation du pool de connexions.

Le regroupement de connexions est activé en appelant SQLSetEnvAttr pour définir l’attribut SQL_ATTR_CONNECTION_POOLING sur SQL_CP_ONE_PER_DRIVER ou SQL_CP_ONE_PER_HENV. Cet appel doit être effectué avant que l’application alloue l’environnement partagé pour lequel le regroupement de connexions doit être activé. Le handle d’environnement dans l’appel à SQLSetEnvAttr est défini sur null, ce qui fait SQL_ATTR_CONNECTION_POOLING un attribut au niveau du processus. Une fois le regroupement de connexions activé, l’application alloue un environnement partagé implicite en appelant SQLAllocHandle avec l’argument InputHandle défini sur SQL_HANDLE_ENV.

Une fois que le regroupement de connexions a été activé et qu’un environnement partagé a été sélectionné pour une application, SQL_ATTR_CONNECTION_POOLING ne peut pas être réinitialisé pour cet environnement, car SQLSetEnvAttr est appelé avec un handle d’environnement null lors de la définition de cet attribut. Si cet attribut est défini alors que le regroupement de connexions est déjà activé sur un environnement partagé, l’attribut affecte uniquement les environnements partagés qui sont alloués par la suite.

Il est également possible d’activer le regroupement de connexions sur un environnement. Notez les points suivants concernant le regroupement de connexions d’environnement :

- L’activation du regroupement de connexions sur un handle NULL est un attribut au niveau du processus. Les environnements alloués ultérieurement seront un environnement partagé et hériteront du paramètre de regroupement de connexions au niveau du processus.
- Une fois qu’un environnement est alloué, une application peut toujours modifier son paramètre de pool de connexions.
- Si le regroupement de connexions d’environnement est activé et que le pilote de la connexion utilise le regroupement de pilotes, le regroupement d’environnements prend la préférence.

SQL_ATTR_CONNECTION_POOLING est implémenté à l’intérieur du Gestionnaire de pilotes. Un pilote n’a pas besoin d’implémenter SQL_ATTR_CONNECTION_POOLING. Les applications ODBC 2.0 et 3.0 peuvent définir cet attribut d’environnement.

Pour plus d’informations, consultez ODBC Connection Pooling.
SQL_ATTR_CP_MATCH (ODBC 3.0) Valeur SQLUINTEGER 32 bits qui détermine la façon dont une connexion est choisie dans un pool de connexions. Quand SQLConnect ou SQLDriverConnect est appelé, le Gestionnaire de pilotes détermine quelle connexion est réutilisée à partir du pool. Le Gestionnaire de pilotes tente de faire correspondre les options de connexion dans l’appel et les attributs de connexion définis par l’application aux mots clés et aux attributs de connexion des connexions dans le pool. La valeur de cet attribut détermine le niveau de précision des critères de correspondance.

Les valeurs suivantes sont utilisées pour définir la valeur de cet attribut :

SQL_CP_STRICT_MATCH = Seules les connexions qui correspondent exactement aux options de connexion de l’appel et aux attributs de connexion définis par l’application sont réutilisées. Il s’agit de la valeur par défaut.

SQL_CP_RELAXED_MATCH = Les connexions avec des mots clés de chaîne de connexion correspondants peuvent être utilisées. Les mots clés doivent correspondre, mais tous les attributs de connexion ne doivent pas correspondre.

Pour plus d’informations sur la façon dont le Gestionnaire de pilotes effectue la correspondance lors de la connexion à une connexion mise en pool, consultez SQLConnect. Pour plus d’informations sur le regroupement de connexions, consultez Regroupement de connexions ODBC.
SQL_ATTR_ODBC_VERSION (ODBC 3.0) Entier 32 bits qui détermine si certaines fonctionnalités présentent le comportement ODBC 2.x ou ODBC 3.x . Les valeurs suivantes sont utilisées pour définir la valeur de cet attribut :

SQL_OV_ODBC3_80 = Le gestionnaire de pilotes et le pilote présentent le comportement ODBC 3.8 suivant :

- Le pilote retourne et attend des codes ODBC 3.x pour la date, l’heure et l’horodatage.
- Le pilote retourne des codes ODBC 3.x SQLSTATE lorsque SQLError, SQLGetDiagField ou SQLGetDiagRec est appelé.
- L’argument CatalogName dans un appel à SQLTables accepte un modèle de recherche.
- Le Gestionnaire de pilotes prend en charge l’extensibilité du type de données C. Pour plus d’informations sur l’extensibilité du type de données C, consultez Types de données C dans ODBC.

Pour plus d’informations, consultez Nouveautés d’ODBC 3.8.

SQL_OV_ODBC3 = Le gestionnaire de pilotes et le pilote présentent le comportement ODBC 3.x suivant :

- Le pilote retourne et attend des codes ODBC 3.x pour la date, l’heure et l’horodatage.
- Le pilote retourne des codes ODBC 3.x SQLSTATE lorsque SQLError, SQLGetDiagField ou SQLGetDiagRec est appelé.
- L’argument CatalogName dans un appel à SQLTables accepte un modèle de recherche.
- Le Gestionnaire de pilotes ne prend pas en charge l’extensibilité du type de données C.

SQL_OV_ODBC2 = Le gestionnaire de pilotes et le pilote présentent le comportement ODBC 2.x suivant. Cela est particulièrement utile pour une application ODBC 2.x qui fonctionne avec un pilote ODBC 3.x .

- Le pilote retourne et attend des codes ODBC 2.x pour la date, l’heure et l’horodatage.
- Le pilote retourne des codes ODBC 2.x SQLSTATE lorsque SQLError, SQLGetDiagField ou SQLGetDiagRec est appelé.
- L’argument CatalogName dans un appel à SQLTables n’accepte pas de modèle de recherche.
- Le Gestionnaire de pilotes ne prend pas en charge l’extensibilité du type de données C.

Une application doit définir cet attribut d’environnement avant d’appeler une fonction qui a un argument SQLHENV, sinon l’appel retourne SQLSTATE HY010 (erreur de séquence de fonction). Il est spécifique au pilote si un comportement supplémentaire existe pour ces indicateurs environnementaux.

- Pour plus d’informations, consultez Déclaration de la version ODBC de l’application et modifications de comportement.
SQL_ATTR_OUTPUT_NTS (ODBC 3.0) Entier 32 bits qui détermine la façon dont le pilote retourne les données de chaîne. Si SQL_TRUE, le pilote retourne les données de chaîne terminées par null. Si SQL_FALSE, le pilote ne retourne pas les données de chaîne terminées par null.

Cet attribut est par défaut SQL_TRUE. Un appel à SQLSetEnvAttr pour le définir sur SQL_TRUE retourne SQL_SUCCESS. Un appel à SQLSetEnvAttr pour le définir sur SQL_FALSE retourne SQL_ERROR et SQLSTATE HYC00 (fonctionnalité facultative non implémentée).
Pour obtenir des informations sur Consultez
Allocation d’un handle SQLAllocHandle, fonction
Retour du paramètre d’un attribut d’environnement SQLGetEnvAttr, fonction

Voir aussi

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