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.

Notes

Pour plus d’informations sur ce à quoi le Gestionnaire de pilotes mappe cette fonction lorsqu’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 à Attribute. Selon la valeur de Attribute, ValuePtr est une valeur entière non signée ou pointe vers une chaîne de caractères null. Notez que le type intégral de l’argument Attribute peut ne pas être de longueur fixe. Pour plus d’informations, consultez la section Commentaires.

StringLength
[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. Pour les données de chaîne de caractères, cet argument doit contenir le nombre d’octets dans la chaîne.

Si Attribute est un attribut défini par ODBC et Que 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 au 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 de la 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 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.)
08002 Nom de connexion utilisé L’argument Attribute a été 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 le ConnectionHandle n’était pas dans un état connecté.
08S01 Échec de la liaison de communication La liaison de communication entre le pilote et la source de données à laquelle le pilote a été connecté a échoué avant que la fonction n’ait terminé le traitement.
24 000 État de curseur non valide L’argument Attribute a été SQL_ATTR_CURRENT_CATALOG et un jeu de résultats était en attente.
25000 Opération non valide dans 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 de catalogue non valide L’argument Attribute é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 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.
HY008 Opération annulée Le traitement asynchrone a été activé pour ConnectionHandle. La fonction SQLSetConnectAttr a été appelée et, avant sa fin d’exécution, la fonction SQLCancelHandle a été appelée sur le ConnectionHandle, puis la fonction SQLSetConnectAttr a été appelée à nouveau sur le ConnectionHandle.

Ou bien, la fonction SQLSetConnectAttr a été appelée et, avant sa fin d’exécution, SQLCancelHandle a été appelé sur le ConnectionHandle à partir d’un thread différent dans une application multithread.
HY009 Utilisation non valide du pointeur null L’argument Attribute a identifié un attribut de connexion qui exigeait une valeur de chaîne, et l’argument ValuePtr était un pointeur null.
HY010 Erreur de séquence de fonction (DM) Une fonction d’exécution asynchrone a été appelée pour un StatementHandle associé à ConnectionHandle et s’exécutait toujours 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 s’exécutait toujours lorsque cette fonction a été appelée.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’un des handles d’instruction associés au ConnectionHandle et a renvoyé 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.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour un StatementHandle associé au ConnectionHandle et a renvoyé SQL_NEED_DATA. Cette fonction a été appelée avant l’envoi des données pour toutes les colonnes ou paramètres de données au moment de l’exécution.

(DM) SQLBrowseConnect a été appelé pour connectionHandle et a 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 Attribute 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 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. (Le Gestionnaire de pilotes retourne cette valeur SQLSTATE uniquement pour les attributs de connexion et d’instruction qui acceptent un ensemble discret de valeurs, comme 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 Chaîne ou longueur de 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’argument Attribute n’était pas valide pour la version d’ODBC prise en charge par le pilote.

(DM) La valeur spécifiée pour l’argument Attribute é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 asynchrone de fonction 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 FONCTION SQLEndTran.
HY121 La bibliothèque de curseurs et le regroupement de Driver-Aware 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’argument Attribute était une connexion ODBC valide ou un attribut d’instruction 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é Le délai d’expiration de la connexion a expiré avant que la source de données réponde à la demande. La période de délai d’expiration de la 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 effectuer 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.

Lorsque l’attribut est un attribut d’instruction, SQLSetConnectAttr peut retourner tous les SQLSTATEs retournés 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.

Notes

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 d’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 de l’instruction.

Les pilotes ODBC 3*.x* doivent uniquement prendre en charge cette fonctionnalité s’ils doivent fonctionner avec 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 de pilote pour 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 ne peuvent être définis qu’avant qu’une connexion n’ait été établie ; d’autres ne peuvent être définis qu’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 l’exécution d’une connexion. Indique que l’attribut peut être défini avant ou après la connexion.

Attribut Défini 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] les SQL_ATTR_ACCESS_MODE et les 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 la connexion, car certains pilotes ne prennent pas en charge leur modification après la connexion.

[2] SQL_ATTR_ASYNC_ENABLE doit être défini avant qu’il n’y ait une instruction active.

[3] SQL_ATTR_TXN_ISOLATION ne peut être défini que s’il n’y a pas de transactions ouvertes 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 Attribute est SQL_ATTR_PACKET_SIZE et que *ValuePtr dépasse la taille de paquet maximale, 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é lors d’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 est défini sur 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 null ou une valeur entière. Le format de chaque 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 de 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 des mises à jour. Ce mode peut être utilisé pour optimiser les stratégies de verrouillage, la gestion des transactions ou d’autres zones en fonction du pilote ou de la source de données. Le pilote n’est pas nécessaire pour empêcher l’envoi de telles instructions à la source de données. Le comportement du pilote et de la source de données lorsque vous êtes invité à traiter des instructions SQL qui ne sont pas en lecture seule lors d’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. Note: 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 si elle 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 de connexion spécifiées.

SQL_ASYNC_DBC_ENABLE_OFF = (Par défaut) Désactiver l’opération asynchrone pour les fonctions liées à la connexion spécifiées.

La définition de SQL_ATTR_ASYNC_DBC_FUNCTIONS_ENABLE est toujours synchrone (autrement dit, elle ne retournera 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 = La population automatique de l’IPD après un appel à SQLPrepare est prise en charge par le pilote.

SQL_FALSE = La population automatique de l’IPD après un appel à SQLPrepare n’est pas prise 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é 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 de validation manuelle :

SQL_AUTOCOMMIT_OFF = Le pilote utilise le mode de validation manuelle, et l’application doit valider ou restaurer explicitement les 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 Mode de 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 autocommit peut provoquer cette opération 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 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 deux comportements et peuvent fournir un moyen de choisir l’un ou l’autre. Le pilote définit si un lot est traité comme une unité autocommitable ou si chaque instruction individuelle du 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 avant de revenir à l’application. Le pilote doit retourner SQLSTATE HYT00 (Délai d’expiration) à chaque fois qu’il est possible d’expirer dans une situation non associée à l’exécution ou à la connexion de la requête.

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 étant une base de données, le pilote envoie une instruction de base de donnéesUSE à 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 à un niveau unique, le catalogue peut être un répertoire, de sorte que le pilote remplace 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 alors d’obtenir une autre connexion à partir du pool. Pour plus d’informations, consultez Développement d'Connection-Pool de sensibilisation 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 MICROSOFT Distributed Transaction Coordinator (MS DTC) OLE ITransactionDispenser::BeginTransaction 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 transaction à 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 un terme à l'association de DTC avec 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 d’attente d’une demande de connexion avant de revenir à l’application. La valeur par défaut dépend du pilote. Si ValuePtr a la valeur 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 d’expiration 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 comment 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 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. Elles peuvent contenir un modèle de recherche de chaîne ou non, selon 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 peut é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 comment 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 Annexe F : Bibliothèque de curseurs ODBC. Avertissement: La bibliothèque de curseurs sera supprimée dans une version ultérieure 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. Note: De nombreuses sources de données ne prennent pas en charge cette option ou peuvent uniquement retourner, mais pas définir la taille des paquets réseau.

Si la taille spécifiée dépasse la taille maximale du paquet ou est inférieure à la taille de paquet minimale, le pilote remplace cette valeur et retourne SQLSTATE 01S02 (Valeur d’option modifiée).

Si l’application définit la taille du paquet après 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) Un 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 ce handle pour afficher les boîtes de dialogue. Note: 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 = Traçage sur

Lorsque le traçage est activé, le Gestionnaire de pilotes écrit chaque appel de fonction ODBC dans le fichier de trace. Note: Lorsque le suivi est activé, le Gestionnaire de pilotes peut retourner 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 l’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. LOG 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 qui a appelé 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 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 jeu 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 est conservé entre les connexions. Pour plus d’informations sur la traduction de données, consultez DLL de traduction et Référence des fonctions DLL de traduction.
SQL_ATTR_TRANSLATE_OPTION (ODBC 1.0) Valeur d’indicateur 32 bits qui est passée à 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 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 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.

Pour obtenir des informations sur Consultez
Allocation d’un handle SQLAllocHandle, fonction
Retour du paramètre d’un attribut de connexion Fonction SQLGetConnectAttr

Voir aussi

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