Fonction SQLSetConnectAttr
Conformité
Version introduite : Conformité aux normes ODBC 3.0 : ISO 92
Résumé
SQLSetConnectAttr définit des attributs qui régissent les aspects des connexions.
Remarque
Pour plus d’informations sur ce que le Gestionnaire de pilotes mappe cette fonction quand 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 SQLSetConnectAttr(
SQLHDBC ConnectionHandle,
SQLINTEGER Attribute,
SQLPOINTER ValuePtr,
SQLINTEGER StringLength);
Arguments
ConnectionHandle
[Entrée] Handle de connexion.
Attribut
[Entrée] Attribut à définir, répertorié dans « Commentaires ».
ValuePtr
[Entrée] Pointeur vers la valeur à associer à l’attribut. Selon la valeur de l’attribut, ValuePtr est une valeur entière non signée ou pointe vers une chaîne de caractères terminée par null. Notez que le type intégral de l’argument Attribut peut ne pas être de longueur fixe, consultez la section Commentaires pour plus de détails.
StringLength
[Entrée] Si l’attribut 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. Pour les données de chaîne de caractères, cet argument doit contenir le nombre d’octets dans la chaîne.
Si l’attribut est un attribut défini par ODBC et ValuePtr est un entier, StringLength est ignoré.
Si l’attribut est un attribut défini par le pilote, l’application indique la nature de l’attribut dans le Gestionnaire de pilotes en définissant l’argument StringLength . StringLength peut avoir les valeurs suivantes :
Si ValuePtr est un pointeur vers une chaîne de caractères, StringLength est la longueur de la chaîne ou SQL_NTS.
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 StringLength. Cela place une valeur négative dans StringLength.
Si ValuePtr est un pointeur vers une valeur autre qu’une chaîne de caractères ou une chaîne binaire, StringLength doit avoir la valeur SQL_IS_POINTER.
Si ValuePtr contient une valeur de longueur fixe, StringLength est SQL_IS_INTEGER ou SQL_IS_UINTEGER, le cas échéant.
Retours
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_STILL_EXECUTING.
Diagnostics
Lorsque SQLSetConnectAttr 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_DBC et un handle de ConnectionHandle. Le tableau suivant répertorie les valeurs SQLSTATE couramment retournées par SQLSetConnectAttr 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.
Le pilote peut retourner SQL_SUCCESS_WITH_INFO pour fournir des informations sur le résultat de la définition d’une option.
| SQLSTATE | Erreur | Description |
|---|---|---|
| 01000 | Avertissement général | Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Valeur d’option modifiée | Le pilote ne prenait pas en charge la valeur spécifiée dans ValuePtr et substituait une valeur similaire. (La fonction retourne SQL_SUCCESS_WITH_INFO.) |
| 08002 | Nom de connexion en cours d’utilisation | L’argument Attribut était SQL_ATTR_ODBC_CURSORS et le pilote était déjà connecté à la source de données. |
| 08003 | Connexion non ouverte | (DM) Une valeur d’attribut a été spécifiée qui nécessitait une connexion ouverte, mais la ConnectionHandle n’était pas dans un état connecté. |
| 08S01 | Échec du lien de communication | Le lien de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant l’achèvement du traitement de la fonction. |
| 24000 | État de curseur non valide | L’argument Attribut était SQL_ATTR_CURRENT_CATALOG et un jeu de résultats était en attente. |
| 25000 | Opération illégale lors d’une transaction locale | Une connexion se trouvait dans une transaction locale lors de la tentative d’inscription dans une connexion de transaction distribuée (DTC) en définissant l’attribut de connexion SQL_ATTR_ENLIST_IN_DTC. Une connexion est déjà inscrite dans un DTC. Une connexion a été inscrite dans une connexion de transaction distribuée et une transaction locale a été démarrée en définissant SQL_ATTR_AUTOCOMMIT sur SQL_AUTOCOMMIT_OFF. |
| 3D000 | Nom du catalogue non valide | L’argument Attribut était SQL_CURRENT_CATALOG et le nom de catalogue spécifié n’était pas valide. |
| HY000 | Erreur générale | Une erreur s’est produite pour laquelle il n’y avait aucun SQLSTATE spécifique et pour lequel 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 de mémoire nécessaire pour prendre en charge l’exécution ou l’achèvement de la fonction. |
| HY008 | Opération annulée | Le traitement asynchrone a été activé pour ConnectionHandle. La fonction SQLSetConnectAttr a été appelée et avant l’exécution terminée, la fonction SQLCancelHandle a été appelée sur ConnectionHandle, puis la fonction SQLSetConnectAttr a été appelée à nouveau sur ConnectionHandle. Ou bien, la fonction SQLSetConnectAttr a été appelée et, avant qu’elle ait terminé l’exécution, SQLCancelHandle a été appelée sur connectionHandle à partir d’un autre thread dans une application multithread. |
| HY009 | Utilisation non valide du pointeur Null | L’argument Attribute a identifié un attribut de connexion qui nécessitait une valeur de chaîne, et l’argument ValuePtr était un pointeur Null. |
| HY010 | Erreur de séquence de fonction | (DM) Une fonction en cours d’exécution asynchrone a été appelée pour un StatementHandle associé à ConnectionHandle et était toujours en cours d’exécution lorsque SQLSetConnectAttr a été appelé. (DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour connectionHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’un des handles d’instruction associés à ConnectionHandle et 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. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour un StatementHandle associé à ConnectionHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à l’exécution. (DM) SQLBrowseConnect a été appelé pour connectionHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée avant que SQLBrowseConnect ne retourne SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS. |
| HY011 | Impossible de définir l’attribut maintenant | L’argument Attribut a été SQL_ATTR_TXN_ISOLATION et une transaction a été ouverte. |
| 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, éventuellement en raison de conditions de mémoire insuffisantes. |
| HY024 | Valeur d’attribut non valide | Étant donné la valeur d’attribut spécifiée, une valeur non valide a été spécifiée dans ValuePtr. (Le Gestionnaire de pilotes retourne ce SQLSTATE uniquement pour les attributs de connexion et d’instruction qui acceptent un ensemble discret de valeurs, tels que SQL_ATTR_ACCESS_MODE ou SQL_ATTR_ASYNC_ENABLE. Pour tous les autres attributs de connexion et d’instruction, le pilote doit vérifier la valeur spécifiée dans ValuePtr.) L’argument Attribute était SQL_ATTR_TRACEFILE ou SQL_ATTR_TRANSLATE_LIB, et ValuePtr était une chaîne vide. |
| HY090 | Longueur de la chaîne ou de la mémoire tampon non valide | (DM) *ValuePtr est une chaîne de caractères et 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’attribut d’argument n’était pas valide pour la version d’ODBC prise en charge par le pilote. (DM) La valeur spécifiée pour l’attribut argument était un attribut en lecture seule. |
| HY114 | Le pilote ne prend pas en charge l’exécution de fonction asynchrone au niveau de la connexion | (DM) Une application a tenté d’activer l’exécution de fonction asynchrone 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 la fonction SQLEndTran. |
| HY121 | La bibliothèque de curseurs et le regroupement prenant en charge le pilote ne peuvent pas être activés en même temps | Pour plus d’informations, consultez Regroupement de connexions prenant en charge les pilotes. |
| HYC00 | Fonctionnalité facultative non implémentée | La valeur spécifiée pour l’attribut argument était un attribut de connexion ou d’instruction 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é | La période d’expiration de la connexion a expiré avant que la source de données ne réponde à la demande. La période d’expiration de connexion est définie via SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Le pilote ne prend pas en charge cette fonction | (DM) Le pilote associé à ConnectionHandle ne prend pas en charge la fonction. |
| IM009 | Impossible de charger la DLL de traduction | Le pilote n’a pas pu charger la DLL de traduction spécifiée pour la connexion. Cette erreur ne peut être retournée que lorsque l’attribut est SQL_ATTR_TRANSLATE_LIB. |
| IM017 | L’interrogation est désactivée en mode de notification asynchrone | Chaque fois que le modèle de notification est utilisé, l’interrogation est désactivée. |
| IM018 | SQLCompleteAsync n’a pas été appelé pour terminer l’opération asynchrone précédente sur ce handle. | Si l’appel de fonction précédent sur le handle retourne SQL_STILL_EXECUTING et si le mode de notification est activé, SQLCompleteAsync doit être appelé sur le handle pour effectuer un post-traitement et terminer l’opération. |
| S1118 | Le pilote ne prend pas en charge la notification asynchrone | SQL_ATTR_ASYNC_DBC_EVENT a été défini (une fois la connexion établie), mais la notification asynchrone n’est pas prise en charge par le pilote. |
Quand Attribute est un attribut d’instruction, SQLSetConnectAttr peut retourner n’importe quel SQLSTATEs retourné par SQLSetStmtAttr.
Commentaires
Pour obtenir des informations générales sur les attributs de connexion, consultez Attributs de connexion.
Les attributs actuellement définis et la version d’ODBC dans laquelle ils ont été introduits sont présentés dans le tableau plus loin dans cette section ; on s’attend à ce que d’autres attributs soient définis pour tirer parti de différentes sources de données. Une plage d’attributs est réservée par ODBC ; les développeurs de pilotes doivent réserver des valeurs pour leur propre utilisation spécifique au pilote à partir d’Open Group.
Remarque
La possibilité de définir des attributs d’instruction au niveau de la connexion en appelant SQLSetConnectAttr a été déconseillée dans ODBC 3*.x*. Les applications ODBC 3*.x* ne doivent jamais définir des attributs d’instruction au niveau de la connexion. Les attributs d’instruction ODBC 3*.x* ne peuvent pas être définis au niveau de la connexion, à l’exception des attributs SQL_ATTR_METADATA_ID et SQL_ATTR_ASYNC_ENABLE, qui sont à la fois des attributs de connexion et des attributs d’instruction et peuvent être définis au niveau de la connexion ou au niveau de l’instruction.
Les pilotes ODBC 3*.x* n’ont besoin que de prendre en charge cette fonctionnalité s’ils doivent utiliser des applications ODBC 2*.x* qui définissent les options d’instruction ODBC 2*.x* au niveau de la connexion. Pour plus d’informations, consultez Mappage SQLSetConnectOption dans l’annexe G : Instructions relatives à la compatibilité descendante.
Une application peut appeler SQLSetConnectAttr à tout moment entre le moment où la connexion est allouée et libérée. Tous les attributs de connexion et d’instruction correctement définis par l’application pour la connexion persistent jusqu’à ce que SQLFreeHandle soit appelé sur la connexion. Par exemple, si une application appelle SQLSetConnectAttr avant de se connecter à une source de données, l’attribut persiste même si SQLSetConnectAttr échoue dans le pilote lorsque l’application se connecte à la source de données ; si une application définit un attribut spécifique au pilote, l’attribut persiste même si l’application se connecte à un autre pilote sur la connexion.
Certains attributs de connexion peuvent être définis uniquement avant qu’une connexion ait été établie ; d’autres peuvent être définis uniquement une fois qu’une connexion a été établie. Le tableau suivant indique les attributs de connexion qui doivent être définis avant ou après la création d’une connexion. Indique que l’attribut peut être défini avant ou après la connexion.
| Attribut | Définir avant ou après la connexion ? |
|---|---|
| SQL_ATTR_ACCESS_MODE | Soit[1] |
| SQL_ATTR_ASYNC_DBC_EVENT | Vous pouvez soit utiliser |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE | Soit[4] |
| SQL_ATTR_ASYNC_DBC_PCALLBACK | Vous pouvez soit utiliser |
| SQL_ATTR_ASYNC_DBC_PCONTEXT | Vous pouvez soit utiliser |
| SQL_ATTR_ASYNC_ENABLE | Soit[2] |
| SQL_ATTR_AUTO_IPD | Vous pouvez soit utiliser |
| SQL_ATTR_AUTOCOMMIT | Soit[5] |
| SQL_ATTR_CONNECTION_DEAD | Après |
| SQL_ATTR_CONNECTION_TIMEOUT | Vous pouvez soit utiliser |
| SQL_ATTR_CURRENT_CATALOG | Soit[1] |
| SQL_ATTR_DBC_INFO_TOKEN | Après |
| SQL_ATTR_ENLIST_IN_DTC | Après |
| SQL_ATTR_LOGIN_TIMEOUT | Avant |
| SQL_ATTR_METADATA_ID | Vous pouvez soit utiliser |
| SQL_ATTR_ODBC_CURSORS | Avant |
| SQL_ATTR_PACKET_SIZE | Avant |
| SQL_ATTR_QUIET_MODE | Vous pouvez soit utiliser |
| SQL_ATTR_TRACE | Vous pouvez soit utiliser |
| SQL_ATTR_TRACEFILE | Vous pouvez soit utiliser |
| SQL_ATTR_TRANSLATE_LIB | Après |
| SQL_ATTR_TRANSLATE_OPTION | Après |
| SQL_ATTR_TXN_ISOLATION | Soit[3] |
[1] SQL_ATTR_ACCESS_MODE et SQL_ATTR_CURRENT_CATALOG peuvent être définis avant ou après la connexion, en fonction du pilote. Toutefois, les applications interopérables les définissent avant de se connecter, car certains pilotes ne prennent pas en charge la modification de celles-ci après la connexion.
[2] SQL_ATTR_ASYNC_ENABLE devez être défini avant qu’il y ait une instruction active.
[3] SQL_ATTR_TXN_ISOLATION ne peut être défini que s’il n’existe aucune transaction ouverte sur la connexion. Certains attributs de connexion prennent en charge la substitution d’une valeur similaire si la source de données ne prend pas en charge la valeur spécifiée dans *ValuePtr. Dans ce cas, le pilote retourne SQL_SUCCESS_WITH_INFO et SQLSTATE 01S02 (valeur d’option modifiée). Par exemple, si l’attribut est SQL_ATTR_PACKET_SIZE et *ValuePtr dépasse la taille maximale du paquet, le pilote remplace la taille maximale. Pour déterminer la valeur substituée, une application appelle SQLGetConnectAttr.
[4] Si SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE est défini avant l’ouverture d’une connexion, le Gestionnaire de pilotes définit l’attribut du pilote lorsque le pilote est chargé pendant un appel à SQLBrowseConnect, SQLConnect ou SQLDriverConnect. Avant un appel à SQLBrowseConnect, SQLConnect ou SQLDriverConnect, le Gestionnaire de pilotes ne sait pas quel pilote se connecter et ne sait pas si le pilote prend en charge les opérations de connexion asynchrones. Par conséquent, le Gestionnaire de pilotes retourne toujours SQL_SUCCESS. Toutefois, si le pilote ne prend pas en charge les opérations de connexion asynchrones, l’appel à SQLBrowseConnect, SQLConnect ou SQLDriverConnect échoue.
[5] Lorsque SQL_ATTR_AUTOCOMMIT a la valeur FALSE, les applications doivent appeler SQLEndTran(SQL_ROLLBACK) si une API retourne SQL_ERROR pour garantir la cohérence transactionnelle.
Le format des informations définies dans la mémoire tampon *ValuePtr dépend de l’attribut spécifié. SQLSetConnectAttr accepte les informations d’attribut dans l’un des deux formats différents : une chaîne de caractères terminée par null ou une valeur entière. Le format de chacun est noté dans la description de l’attribut. Les chaînes de caractères pointées par l’argument ValuePtr de SQLSetConnectAttr ont une longueur d’octets StringLength.
L’argument StringLength est ignoré si la longueur est définie par l’attribut, comme c’est le cas pour tous les attributs introduits dans ODBC 2*.x* ou une version antérieure.
| Attribut | Contenu valuePtr |
|---|---|
| SQL_ATTR_ACCESS_MODE (ODBC 1.0) | Valeur SQLUINTEGER. SQL_MODE_READ_ONLY est utilisé par le pilote ou la source de données comme indicateur que la connexion n’est pas nécessaire pour prendre en charge les instructions SQL qui provoquent la mise à jour. Ce mode peut être utilisé pour optimiser les stratégies de verrouillage, la gestion des transactions ou d’autres zones selon les besoins du pilote ou de la source de données. Le pilote n’est pas nécessaire pour empêcher l’envoi de ces instructions à la source de données. Le comportement du pilote et de la source de données lorsqu’il est demandé de traiter des instructions SQL qui ne sont pas en lecture seule pendant une connexion en lecture seule est défini par l’implémentation. SQL_MODE_READ_WRITE est la valeur par défaut. |
| SQL_ATTR_ASYNC_DBC_EVENT (ODBC 3.8) | Valeur SQLPOINTER qui est un handle d’événement. La notification de l’achèvement des fonctions asynchrones est activée en appelant SQLSetConnectAttr avec l’attribut SQL_ATTR_ASYNC_STMT_EVENT et en spécifiant le handle d’événement. Remarque : La méthode de notification n’est pas prise en charge avec la bibliothèque de curseurs. Une application reçoit un message d’erreur s’il tente d’activer la bibliothèque de curseurs via SQLSetConnectAttr, lorsque la méthode de notification est activée. |
| SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE (ODBC 3.8) | Valeur SQLUINTEGER qui active ou désactive l’exécution asynchrone de fonctions sélectionnées sur le handle de connexion. Pour plus d’informations, consultez Exécution asynchrone (méthode d’interrogation). SQL_ASYNC_DBC_ENABLE_ON = Activer l’opération asynchrone pour les fonctions liées à la connexion spécifiées. SQL_ASYNC_DBC_ENABLE_OFF = (valeur par défaut) Désactiver l’opération asynchrone pour les fonctions associées à la connexion spécifiées. Définir SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE est toujours synchrone (autrement dit, il ne retourne jamais SQL_STILL_EXECUTING). L’exécution asynchrone des opérations d’instruction est activée avec SQL_ATTR_ASYNC_ENABLE. |
| SQL_ATTR_ASYNC_DBC_PCALLBACK (ODBC 3.8) | Valeur SQLPOINTER qui pointe vers la structure de contexte. Seul le Gestionnaire de pilotes peut appeler la fonction SQLSetStmtAttr d’un pilote avec cet attribut. |
| SQL_ATTR_ASYNC_DBC_PCONTEXT (ODBC 3.8) | Valeur SQLPOINTER qui pointe vers la structure de contexte. Seul le Gestionnaire de pilotes peut appeler la fonction SQLSetStmtAttr d’un pilote avec cet attribut. |
| SQL_ATTR_ASYNC_ENABLE (ODBC 3.0) | Valeur SQLULEN qui spécifie si une fonction appelée avec une instruction sur la connexion spécifiée est exécutée de manière asynchrone : SQL_ASYNC_ENABLE_OFF = Désactiver la prise en charge de l’exécution asynchrone au niveau de la connexion pour les opérations d’instruction (valeur par défaut). SQL_ASYNC_ENABLE_ON = Activer la prise en charge de l’exécution asynchrone au niveau de la connexion pour les opérations d’instruction. Cet attribut peut être défini si SQLGetInfo avec le type d’informations SQL_ASYNC_MODE retourne SQL_AM_CONNECTION ou SQL_AM_STATEMENT. |
| SQL_ATTR_AUTO_IPD (ODBC 3.0) | Valeur SQLUINTEGER en lecture seule qui spécifie si la population automatique de l’IPD après un appel à SQLPrepare est prise en charge : SQL_TRUE = Remplissage automatique de l’IPD après un appel à SQLPrepare est pris en charge par le pilote. SQL_FALSE = Remplissage automatique de l’IPD après un appel à SQLPrepare n’est pas pris en charge par le pilote. Les serveurs qui ne prennent pas en charge les instructions préparées ne pourront pas remplir automatiquement l’IPD. Si SQL_TRUE est retournée pour l’attribut de connexion SQL_ATTR_AUTO_IPD, l’attribut d’instruction SQL_ATTR_ENABLE_AUTO_IPD peut être défini pour activer ou désactiver la population automatique de l’IPD. Si SQL_ATTR_AUTO_IPD est SQL_FALSE, SQL_ATTR_ENABLE_AUTO_IPD ne peut pas être défini sur SQL_TRUE. La valeur par défaut de SQL_ATTR_ENABLE_AUTO_IPD est égale à la valeur de SQL_ATTR_AUTO_IPD. Cet attribut de connexion peut être retourné par SQLGetConnectAttr , mais ne peut pas être défini par SQLSetConnectAttr. |
| SQL_ATTR_AUTOCOMMIT (ODBC 1.0) | Valeur SQLUINTEGER qui spécifie s’il faut utiliser le mode de validation automatique ou manuelle : SQL_AUTOCOMMIT_OFF = Le pilote utilise le mode de validation manuelle et l’application doit valider ou restaurer explicitement des transactions avec SQLEndTran. SQL_AUTOCOMMIT_ON = Le pilote utilise le mode de validation automatique. Chaque instruction est validée immédiatement après son exécution. Il s’agit de la valeur par défaut. Toutes les transactions ouvertes sur la connexion sont validées lorsque SQL_ATTR_AUTOCOMMIT est défini sur SQL_AUTOCOMMIT_ON pour passer du mode de validation manuelle au mode de validation automatique. Pour plus d’informations, consultez Le mode validation. Important : certaines sources de données suppriment les plans d’accès et ferment les curseurs pour toutes les instructions d’une connexion chaque fois qu’une instruction est validée ; le mode de validation automatique peut entraîner ce problème après l’exécution de chaque instruction non requête ou lorsque le curseur est fermé pour une requête. Pour plus d’informations, consultez les types d’informations SQL_CURSOR_COMMIT_BEHAVIOR et SQL_CURSOR_ROLLBACK_BEHAVIOR dans SQLGetInfo et l’effet des transactions sur les curseurs et les instructions préparées. Lorsqu’un lot est exécuté en mode de validation automatique, deux choses sont possibles. L’ensemble du lot peut être traité comme une unité autocommitable, ou chaque instruction d’un lot est traitée comme une unité autocommitable. Certaines sources de données peuvent prendre en charge ces comportements et peuvent fournir un moyen de choisir l’un ou l’autre. Il est défini par le pilote si un lot est traité comme une unité autocommitable ou si chaque instruction individuelle dans le lot est autocommitable. |
| SQL_ATTR_CONNECTION_DEAD (ODBC 3.5) |
Valeur SQLUINTEGER en lecture seule qui indique l’état de la connexion. Si SQL_CD_TRUE, la connexion a été perdue. Si SQL_CD_FALSE, la connexion est toujours active. |
| SQL_ATTR_CONNECTION_TIMEOUT (ODBC 3.0) | Valeur SQLUINTEGER correspondant au nombre de secondes à attendre la fin d’une requête sur la connexion avant de revenir à l’application. Le pilote doit retourner SQLSTATE HYT00 (expiration du délai d’expiration) chaque fois qu’il est possible d’expirer dans une situation qui n’est pas associée à l’exécution de la requête ou à la connexion. Si ValuePtr est égal à 0 (valeur par défaut), il n’y a pas de délai d’expiration. |
| SQL_ATTR_CURRENT_CATALOG (ODBC 2.0) | Chaîne de caractères contenant le nom du catalogue à utiliser par la source de données. Par exemple, dans SQL Server, le catalogue est une base de données. Par conséquent, le pilote envoie une instruction use database à la source de données, où la base de données est la base de données spécifiée dans *ValuePtr. Pour un pilote à niveau unique, le catalogue peut être un répertoire, de sorte que le pilote modifie son répertoire actuel par le répertoire spécifié dans *ValuePtr. |
| SQL_ATTR_DBC_INFO_TOKEN (ODBC 3.8) | Valeur SQLPOINTER utilisée pour définir le jeton d’informations de connexion dans le handle DBC lorsque le paramètre (*pRating) de SQLRateConnection n’est pas égal à 100. SQL_ATTR_DBC_INFO_TOKEN est défini uniquement. Il n’est pas possible d’utiliser SQLGetConnectAttr ou SQLGetConnectOption pour récupérer cette valeur. SQLSetConnectAttr du Gestionnaire de pilotes n’accepte pas SQL_ATTR_DBC_INFO_TOKEN, car une application ne doit pas définir cet attribut. Si un pilote retourne SQL_ERROR après avoir défini SQL_ATTR_DBC_INFO_TOKEN, la connexion obtenue à partir du pool est libérée. Le Gestionnaire de pilotes tente ensuite d’obtenir une autre connexion à partir du pool. Pour plus d’informations, consultez Développement de la sensibilisation au pool de connexions dans un pilote ODBC. |
| SQL_ATTR_ENLIST_IN_DTC (ODBC 3.0) | Valeur SQLPOINTER qui spécifie s’il faut utiliser le pilote ODBC dans les transactions distribuées coordonnées par microsoft Component Services. Transmettez un objet de transaction OLE DTC qui spécifie la transaction à exporter vers SQL Server, ou SQL_DTC_DONE pour mettre fin à l’association DTC de la connexion. Le client appelle la méthode OLE ITransactionDispenser ::BeginTransaction de Microsoft Distributed Transaction Coordinator (MS DTC) pour commencer une transaction MS DTC et créer un objet de transaction MS DTC qui représente la transaction. L’application appelle ensuite SQLSetConnectAttr avec l’option SQL_ATTR_ENLIST_IN_DTC pour associer l’objet transactionnel à la connexion ODBC. Toute l'activité de base de données connexe sera effectuée sous la protection de la transaction MS DTC. L’application appelle SQLSetConnectAttr avec SQL_DTC_DONE pour mettre fin à l’association DTC de la connexion. Pour plus d'informations, consultez la documentation MS DTC. |
| SQL_ATTR_LOGIN_TIMEOUT (ODBC 1.0) | Valeur SQLUINTEGER correspondant au nombre de secondes à attendre la fin d’une demande de connexion avant de revenir à l’application. La valeur par défaut dépend du pilote. Si ValuePtr est 0, le délai d’expiration est désactivé et une tentative de connexion attend indéfiniment. Si le délai d’expiration spécifié dépasse le délai maximal de connexion dans la source de données, le pilote remplace cette valeur et retourne SQLSTATE 01S02 (valeur d’option modifiée). |
| SQL_ATTR_METADATA_ID (ODBC 3.0) | Valeur SQLUINTEGER qui détermine la façon dont les arguments de chaîne des fonctions de catalogue sont traités. Si SQL_TRUE, l’argument de chaîne des fonctions de catalogue est traité comme des identificateurs. Le cas n’est pas significatif. Pour les chaînes non délimitées, le pilote supprime tous les espaces de fin et la chaîne est pliée en majuscules. Pour les chaînes délimitées, le pilote supprime les espaces de début ou de fin et prend littéralement tout ce qui se trouve entre les délimiteurs. Si l’un de ces arguments est défini sur un pointeur Null, la fonction retourne SQL_ERROR et SQLSTATE HY009 (utilisation non valide du pointeur Null). Si SQL_FALSE, les arguments de chaîne des fonctions de catalogue ne sont pas traités comme des identificateurs. L’affaire est importante. Ils peuvent contenir un modèle de recherche de chaîne ou non, en fonction de l’argument. La valeur par défaut est SQL_FALSE. L’argument TableType de SQLTables, qui prend une liste de valeurs, n’est pas affecté par cet attribut. SQL_ATTR_METADATA_ID pouvez également être défini au niveau de l’instruction. (Il s’agit du seul attribut de connexion qui est également un attribut d’instruction.) Pour plus d’informations, consultez Arguments dans les fonctions de catalogue. |
| SQL_ATTR_ODBC_CURSORS (ODBC 2.0) | Valeur SQLULEN spécifiant la façon dont le Gestionnaire de pilotes utilise la bibliothèque de curseurs ODBC : SQL_CUR_USE_IF_NEEDED = Le Gestionnaire de pilotes utilise la bibliothèque de curseurs ODBC uniquement si nécessaire. Si le pilote prend en charge l’option SQL_FETCH_PRIOR dans SQLFetchScroll, le Gestionnaire de pilotes utilise les fonctionnalités de défilement du pilote. Sinon, il utilise la bibliothèque de curseurs ODBC. SQL_CUR_USE_ODBC = Le Gestionnaire de pilotes utilise la bibliothèque de curseurs ODBC. SQL_CUR_USE_DRIVER = Le Gestionnaire de pilotes utilise les fonctionnalités de défilement du pilote. Il s’agit du paramètre par défaut. Pour plus d’informations sur la bibliothèque de curseurs ODBC, consultez l’annexe F : Bibliothèque de curseurs ODBC. Avertissement : la bibliothèque de curseurs sera supprimée dans une prochaine version de Windows. Évitez d’utiliser cette fonctionnalité dans le nouveau travail de développement et prévoyez de modifier les applications qui utilisent actuellement cette fonctionnalité. Microsoft recommande d’utiliser la fonctionnalité de curseur du pilote. |
| SQL_ATTR_PACKET_SIZE (ODBC 2.0) | Valeur SQLUINTEGER spécifiant la taille du paquet réseau en octets. Remarque : De nombreuses sources de données ne prennent pas en charge cette option ou peuvent uniquement retourner, mais pas définir la taille du paquet réseau. Si la taille spécifiée dépasse la taille maximale du paquet ou est inférieure à la taille minimale du paquet, le pilote remplace cette valeur et retourne SQLSTATE 01S02 (valeur d’option modifiée). Si l’application définit la taille des paquets une fois qu’une connexion a déjà été établie, le pilote retourne SQLSTATE HY011 (L’attribut ne peut pas être défini maintenant). |
| SQL_ATTR_QUIET_MODE (ODBC 2.0) | Handle de fenêtre (HWND). Si le handle de fenêtre est un pointeur Null, le pilote n’affiche aucune boîte de dialogue. Si le handle de fenêtre n’est pas un pointeur Null, il doit s’agir du handle de fenêtre parent de l’application. Il s’agit de la valeur par défaut. Le pilote utilise cette poignée pour afficher les boîtes de dialogue. Remarque : l’attribut de connexion SQL_ATTR_QUIET_MODE ne s’applique pas aux boîtes de dialogue affichées par SQLDriverConnect. |
| SQL_ATTR_TRACE (ODBC 1.0) | Valeur SQLUINTEGER indiquant au Gestionnaire de pilotes s’il faut effectuer le suivi : SQL_OPT_TRACE_OFF = Traçage désactivé (valeur par défaut) SQL_OPT_TRACE_ON = Suivi sur Lorsque le suivi est activé, le Gestionnaire de pilotes écrit chaque appel de fonction ODBC dans le fichier de trace. Remarque : lorsque le suivi est activé, le Gestionnaire de pilotes peut renvoyer SQLSTATE IM013 (erreur de fichier de trace) à partir de n’importe quelle fonction. Une application spécifie un fichier de trace avec l’option SQL_ATTR_TRACEFILE. Si le fichier existe déjà, le Gestionnaire de pilotes s’ajoute au fichier. Sinon, il crée le fichier. Si le suivi est activé et qu’aucun fichier de trace n’a été spécifié, le Gestionnaire de pilotes écrit dans le fichier SQL. JOURNAL dans le répertoire racine. Une application peut définir la variable ODBCSharedTraceFlag pour activer le suivi dynamiquement. Le suivi est ensuite activé pour toutes les applications ODBC en cours d’exécution. Si une application désactive le suivi, elle est désactivée uniquement pour cette application. Si le mot clé Trace dans les informations système est défini sur 1 lorsqu’une application appelle SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV, le suivi est activé pour tous les handles. Elle est activée uniquement pour l’application appelée SQLAllocHandle. L’appel de SQLSetConnectAttr avec un attribut de SQL_ATTR_TRACE ne nécessite pas que l’argument ConnectionHandle soit valide et ne retourne pas SQL_ERROR si ConnectionHandle a la valeur NULL. Cet attribut s’applique à toutes les connexions. |
| SQL_ATTR_TRACEFILE (ODBC 1.0) | Chaîne de caractères terminée par null contenant le nom du fichier de trace. La valeur par défaut de l’attribut SQL_ATTR_TRACEFILE est spécifiée avec le mot clé TraceFile dans les informations système. Pour plus d’informations, consultez la sous-clé ODBC. L’appel de SQLSetConnectAttr avec un attribut de SQL_ATTR_TRACEFILE ne nécessite pas que l’argument ConnectionHandle soit valide et ne retourne pas SQL_ERROR si ConnectionHandle n’est pas valide. Cet attribut s’applique à toutes les connexions. |
| SQL_ATTR_TRANSLATE_LIB (ODBC 1.0) | Chaîne de caractères terminée par null contenant le nom d’une bibliothèque contenant les fonctions SQLDriverToDataSource et SQLDataSourceToDriver auxquelles le pilote accède pour effectuer des tâches telles que la traduction de jeux de caractères. Cette option peut être spécifiée uniquement si le pilote s’est connecté à la source de données. Le paramètre de cet attribut persiste entre les connexions. Pour plus d’informations sur la traduction de données, consultez La documentation de référence sur les DLL de traduction et la fonction DLL de traduction. |
| SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) | Valeur d’indicateur 32 bits transmise à la DLL de traduction. Cet attribut ne peut être spécifié que si le pilote s’est connecté à la source de données. Pour plus d’informations sur la traduction de données, consultez les DLL de traduction. |
| SQL_ATTR_TXN_ISOLATION (ODBC 1.0) | Masque de bits 32 bits qui définit le niveau d’isolation des transactions pour la connexion actuelle. Une application doit appeler SQLEndTran pour valider ou restaurer toutes les transactions ouvertes sur une connexion, avant d’appeler SQLSetConnectAttr avec cette option. Les valeurs valides pour ValuePtr peuvent être déterminées en appelant SQLGetInfo avec InfoType égal à SQL_TXN_ISOLATION_OPTIONS. Pour obtenir une description des niveaux d’isolation des transactions, consultez la description du type d’informations SQL_DEFAULT_TXN_ISOLATION dans SQLGetInfo et les niveaux d’isolation des transactions. |
[1] Ces fonctions peuvent être appelées de manière asynchrone uniquement si le descripteur est un descripteur d’implémentation, et non un descripteur d’application.
Exemple de code
Consultez SQLConnect.
Fonctions connexes
| Pour plus d’informations sur | Consultez |
|---|---|
| Allocation d’un handle | SQLAllocHandle, fonction |
| Renvoi du paramètre d’un attribut de connexion | SQLGetConnectAttr, fonction |
Voir aussi
Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC