SQLAllocHandle, fonction

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

Résumé
SQLAllocHandle alloue un handle d’environnement, de connexion, d’instruction ou de descripteur.

Syntaxe

  
SQLRETURN SQLAllocHandle(  
      SQLSMALLINT   HandleType,  
      SQLHANDLE     InputHandle,  
      SQLHANDLE *   OutputHandlePtr);  

Arguments

HandleType
[Entrée] Type de handle à allouer par SQLAllocHandle. Il doit s’agir de l’une des valeurs suivantes :

• SQL_HANDLE_DBC

• SQL_HANDLE_DBC_INFO_TOKEN

• SQL_HANDLE_DESC

• SQL_HANDLE_ENV

• SQL_HANDLE_STMT

SQL_HANDLE_DBC_INFO_TOKEN handle est utilisé uniquement par le Gestionnaire de pilotes et le pilote. Les applications ne doivent pas utiliser ce type de handle. Pour plus d’informations sur SQL_HANDLE_DBC_INFO_TOKEN, consultez Développement d’une sensibilisation au pool de connexions dans un pilote ODBC.

InputHandle
[Entrée] Handle d’entrée dans lequel le nouveau handle doit être alloué dans le contexte. Si HandleType est SQL_HANDLE_ENV, il s’agit de SQL_NULL_HANDLE. Si HandleType est SQL_HANDLE_DBC, il doit s’agir d’un handle d’environnement, et s’il est SQL_HANDLE_STMT ou SQL_HANDLE_DESC, il doit s’agir d’un handle de connexion.

OutputHandlePtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner le handle à la structure de données nouvellement allouée.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_INVALID_HANDLE ou SQL_ERROR.

Lors de l’allocation d’un handle autre qu’un handle d’environnement, si SQLAllocHandle retourne SQL_ERROR, il définit OutputHandlePtr sur SQL_NULL_HDBC, SQL_NULL_HSTMT ou SQL_NULL_HDESC, selon la valeur de HandleType, sauf si l’argument de sortie est un pointeur Null. L’application peut ensuite obtenir des informations supplémentaires à partir de la structure de données de diagnostic associée au handle dans l’argument InputHandle .

Gestion de l’environnement des erreurs d’allocation

L’allocation d’environnement se produit à la fois dans le Gestionnaire de pilotes et dans chaque pilote. L’erreur retournée par SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV dépend du niveau dans lequel l’erreur s’est produite.

Si le Gestionnaire de pilotes ne peut pas allouer de mémoire pour *OutputHandlePtr quand SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV est appelé, ou que l’application fournit un pointeur Null pour OutputHandlePtr, SQLAllocHandle retourne SQL_ERROR. Le Gestionnaire de pilotes définit *OutputHandlePtr sur SQL_NULL_HENV (sauf si l’application a fourni un pointeur Null, qui retourne SQL_ERROR). Il n’existe aucun handle auquel associer des informations de diagnostic supplémentaires.

Le Gestionnaire de pilotes n’appelle pas la fonction d’allocation du handle d’environnement au niveau du pilote tant que l’application n’appelle pas SQLConnect, SQLBrowseConnect ou SQLDriverConnect. Si une erreur se produit dans la fonction SQLAllocHandle au niveau du pilote, la fonction SQLConnect au niveau du Gestionnaire de pilotes, SQLBrowseConnect ou SQLDriverConnect retourne SQL_ERROR. La structure des données de diagnostic contient SQLSTATE IM004 (échec de SQLAllocHandle du pilote). L’erreur est retournée sur un handle de connexion.

Pour plus d’informations sur le flux d’appels de fonction entre le Gestionnaire de pilotes et un pilote, consultez la fonction SQLConnect.

Diagnostics

Lorsque SQLAllocHandle retourne SQL_ERROR ou SQL_SUCCESS_WITH_INFO, une valeur SQLSTATE associée peut être obtenue en appelant SQLGetDiagRec avec le HandleType et handle appropriés définis sur la valeur inputHandle. SQL_SUCCESS_WITH_INFO (mais pas SQL_ERROR) peut être retourné pour l’argument OutputHandle . Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLAllocHandle et explique chacune d’elles dans le contexte de cette fonction ; la notation « (DM) » précède les descriptions des SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

Commentaires

SQLAllocHandle est utilisé pour allouer des handles pour les environnements, les connexions, les instructions et les descripteurs, comme décrit dans les sections suivantes. Pour obtenir des informations générales sur les handles, consultez Handles.

Plusieurs handles d’environnement, de connexion ou d’instruction peuvent être alloués par une application à la fois si plusieurs allocations sont prises en charge par le pilote. Dans ODBC, aucune limite n’est définie sur le nombre de handles d’environnement, de connexion, d’instruction ou de descripteur qui peuvent être alloués à tout moment. Les pilotes peuvent imposer une limite au nombre d’un certain type de handle qui peut être alloué à la fois ; pour plus d’informations, consultez la documentation du pilote.

Si l’application appelle SQLAllocHandle avec *OutputHandlePtr défini sur un handle d’environnement, de connexion, d’instruction ou descripteur qui existe déjà, le pilote remplace les informations associées au handle, sauf si l’application utilise le regroupement de connexions (voir « Allocation d’un attribut d’environnement pour le regroupement de connexions » plus loin dans cette section). Le Gestionnaire de pilotes ne vérifie pas si le handle entré dans *OutputHandlePtr est déjà utilisé, ni vérifie-t-il le contenu précédent d’un handle avant de les remplacer.

Sur les systèmes d’exploitation qui prennent en charge plusieurs threads, les applications peuvent utiliser le même environnement, connexion, instruction ou descripteur sur différents threads. Les pilotes doivent donc prendre en charge l’accès sécurisé et multithread à ces informations ; pour ce faire, par exemple, consiste à utiliser une section critique ou un sémaphore. Pour plus d’informations sur le threading, consultez Multithreading.

SQLAllocHandle ne définit pas l’attribut d’environnement SQL_ATTR_ODBC_VERSION lorsqu’il est appelé pour allouer un handle d’environnement ; l’attribut d’environnement doit être défini par l’application, ou SQLSTATE HY010 (erreur de séquence de fonction) est retourné lorsque SQLAllocHandle est appelé pour allouer un handle de connexion.

Pour les applications conformes aux normes, SQLAllocHandle est mappé à SQLAllocHandleStd au moment de la compilation. La différence entre ces deux fonctions est que SQLAllocHandleStd définit l’attribut d’environnement SQL_ATTR_ODBC_VERSION sur SQL_OV_ODBC3 lorsqu’il est appelé avec l’argument HandleType défini sur SQL_HANDLE_ENV. Pour ce faire, les applications conformes aux normes sont toujours ODBC 3.applications x . De plus, les normes ne nécessitent pas l’inscription de la version de l’application. Il s’agit de la seule différence entre ces deux fonctions ; sinon, ils sont identiques. SQLAllocHandleStd est mappé à SQLAllocHandle à l’intérieur du gestionnaire de pilotes. Par conséquent, les pilotes tiers n’ont pas besoin d’implémenter SQLAllocHandleStd.

Les applications ODBC 3.8 doivent utiliser :

• SQLAllocHandle et non SQLAllocHandleStd pour allouer un handle d’environnement.

• SQLSetEnvAttr pour définir l’attribut d’environnement SQL_ATTR_ODBC_VERSION sur SQL_OV_ODBC3_80.

Allocation d'un handle d'environnement

Un handle d’environnement fournit l’accès aux informations globales, telles que les handles de connexion valides et les handles de connexion actifs. Pour obtenir des informations générales sur les handles d’environnement, consultez Handles d’environnement.

Pour demander un handle d’environnement, une application appelle SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV et un InputHandle de SQL_NULL_HANDLE. Le pilote alloue de la mémoire pour les informations d’environnement et transmet la valeur du handle associé dans l’argument *OutputHandlePtr . L’application transmet la valeur *OutputHandle dans tous les appels suivants qui nécessitent un argument de handle d’environnement. Pour plus d’informations, consultez Allocation du handle d’environnement.

Sous le handle d’environnement d’un gestionnaire de pilotes, s’il existe déjà le handle d’environnement d’un pilote, SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV n’est pas appelé dans ce pilote lorsqu’une connexion est établie, seul SQLAllocHandle avec un HandleType de SQL_HANDLE_DBC. Si le handle d’environnement d’un pilote n’existe pas sous le handle d’environnement du Gestionnaire de pilotes, SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV et SQLAllocHandle avec un HandleType de SQL_HANDLE_DBC sont appelés dans le pilote lorsque le premier handle de connexion de l’environnement est connecté au pilote.

Lorsque le Gestionnaire de pilotes traite la fonction SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV, il vérifie le mot clé Trace dans la section [ODBC] des informations système. S’il est défini sur 1, le Gestionnaire de pilotes active le suivi pour l’application actuelle. Si l’indicateur de trace est défini, le suivi démarre lorsque le premier handle d’environnement est alloué et se termine lorsque le dernier handle d’environnement est libéré. Pour plus d’informations, consultez Configuration des sources de données.

Après avoir alloué un handle d’environnement, une application doit appeler SQLSetEnvAttr sur le handle d’environnement pour définir l’attribut d’environnement SQL_ATTR_ODBC_VERSION. Si cet attribut n’est pas défini avant que SQLAllocHandle soit appelé pour allouer un handle de connexion sur l’environnement, l’appel à allouer la connexion retourne SQLSTATE HY010 (erreur de séquence de fonction). Pour plus d’informations, consultez Déclaration de la version ODBC de l’application.

Allocation d’environnements partagés pour le regroupement de connexions

Les environnements peuvent être partagés entre plusieurs composants sur un seul processus. Un environnement partagé peut être utilisé par plusieurs composants en même temps. Lorsqu’un composant utilise un environnement partagé, il peut utiliser des connexions mises en pool, ce qui lui permet d’allouer et d’utiliser une connexion existante sans recréer cette connexion.

Avant d’allouer un environnement partagé qui peut être utilisé pour le regroupement de connexions, une application doit appeler SQLSetEnvAttr pour définir l’attribut d’environnement SQL_ATTR_CONNECTION_POOLING sur SQL_CP_ONE_PER_DRIVER ou SQL_CP_ONE_PER_HENV. SQLSetEnvAttr dans ce cas est appelé avec EnvironmentHandle défini sur Null, ce qui rend l’attribut au niveau du processus.

Une fois le regroupement de connexions activé, une application appelle SQLAllocHandle avec l’argument HandleType défini sur SQL_HANDLE_ENV. L’environnement alloué par cet appel est un environnement partagé implicite, car le regroupement de connexions a été activé.

Lorsqu’un environnement partagé est alloué, l’environnement qui sera utilisé n’est pas déterminé tant que SQLAllocHandle avec un HandleType de SQL_HANDLE_DBC est appelé. À ce stade, le Gestionnaire de pilotes tente de trouver un environnement existant qui correspond aux attributs d’environnement demandés par l’application. S’il n’existe aucun environnement de ce type, il est créé en tant qu’environnement partagé. Le Gestionnaire de pilotes gère un nombre de références pour chaque environnement partagé ; le nombre est défini sur 1 lorsque l’environnement est créé pour la première fois. Si un environnement correspondant est trouvé, le handle de cet environnement est retourné à l’application et le nombre de références est incrémenté. Un handle d’environnement alloué de cette façon peut être utilisé dans n’importe quelle fonction ODBC qui accepte un handle d’environnement en tant qu’argument d’entrée.

Allocation d'un handle de connexion

Un handle de connexion fournit l’accès aux informations telles que l’instruction valide et les handles de descripteur sur la connexion et indique si une transaction est actuellement ouverte. Pour obtenir des informations générales sur les handles de connexion, consultez Handles de connexion.

Pour demander un handle de connexion, une application appelle SQLAllocHandle avec un HandleType de SQL_HANDLE_DBC. L’argument InputHandle est défini sur le handle d’environnement retourné par l’appel à SQLAllocHandle qui a alloué ce handle. Le pilote alloue de la mémoire pour les informations de connexion et transmet la valeur du handle associé dans *OutputHandlePtr. L’application transmet la valeur *OutputHandlePtr dans tous les appels suivants qui nécessitent un handle de connexion. Pour plus d’informations, consultez Allocation d’un handle de connexion.

Le Gestionnaire de pilotes traite la fonction SQLAllocHandle et appelle la fonction SQLAllocHandle du pilote lorsque l’application appelle SQLConnect, SQLBrowseConnect ou SQLDriverConnect. (Pour plus d’informations, consultez FONCTION SQLConnect.)

Si l’attribut d’environnement SQL_ATTR_ODBC_VERSION n’est pas défini avant que SQLAllocHandle soit appelé pour allouer un handle de connexion sur l’environnement, l’appel à allouer la connexion retourne SQLSTATE HY010 (erreur de séquence de fonction).

Lorsqu’une application appelle SQLAllocHandle avec l’argument InputHandle défini sur SQL_HANDLE_DBC et également définie sur un handle d’environnement partagé, le Gestionnaire de pilotes tente de trouver un environnement partagé existant qui correspond aux attributs d’environnement définis par l’application. S’il n’existe aucun environnement de ce type, un environnement est créé, avec un nombre de références (géré par le Gestionnaire de pilotes) de 1. Si un environnement partagé correspondant est trouvé, ce handle est retourné à l’application et son nombre de références est incrémenté.

La connexion réelle qui sera utilisée n’est pas déterminée par le Gestionnaire de pilotes tant que SQLConnect ou SQLDriverConnect n’est pas appelée. Le Gestionnaire de pilotes utilise les options de connexion dans l’appel à SQLConnect (ou les mots clés de connexion dans l’appel à SQLDriverConnect) et les attributs de connexion définis après l’allocation de connexion pour déterminer la connexion dans le pool à utiliser. Pour plus d’informations, consultez la fonction SQLConnect.

Allocation d'un descripteur d'instruction

Un handle d’instruction fournit l’accès aux informations d’instruction, telles que les messages d’erreur, le nom du curseur et les informations d’état pour le traitement des instructions SQL. Pour obtenir des informations générales sur les handles d’instructions, consultez Handles d’instruction.

Pour demander un handle d’instruction, une application se connecte à une source de données, puis appelle SQLAllocHandle avant d’envoyer des instructions SQL. Dans cet appel, HandleType doit être défini sur SQL_HANDLE_STMT et InputHandle doit être défini sur le handle de connexion retourné par l’appel à SQLAllocHandle qui a alloué ce handle. Le pilote alloue de la mémoire pour les informations d’instruction, associe le handle d’instruction à la connexion spécifiée et transmet la valeur du handle associé dans *OutputHandlePtr. L’application transmet la valeur *OutputHandlePtr dans tous les appels suivants qui nécessitent un handle d’instruction. Pour plus d’informations, consultez Allocation d’un handle d’instruction.

Lorsque le handle d’instruction est alloué, le pilote alloue automatiquement un ensemble de quatre descripteurs et affecte les handles pour ces descripteurs aux attributs d’instruction SQL_ATTR_APP_ROW_DESC, SQL_ATTR_APP_PARAM_DESC, SQL_ATTR_IMP_ROW_DESC et SQL_ATTR_IMP_PARAM_DESC. Ces descripteurs sont appelés descripteurs implicitement alloués. Pour allouer explicitement un descripteur d’application, consultez la section suivante : « Allocation d’un descripteur de descripteur ».

Allocation d’un handle de descripteur

Lorsqu’une application appelle SQLAllocHandle avec un HandleType de SQL_HANDLE_DESC, le pilote alloue un descripteur d’application. Ces descripteurs sont appelés descripteurs explicitement alloués. L’application dirige un pilote pour utiliser un descripteur d’application explicitement alloué au lieu d’un descripteur d’application alloué automatiquement pour un handle d’instruction donné en appelant la fonction SQLSetStmtAttr avec l’attribut SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC. Un descripteur d’implémentation ne peut pas être alloué explicitement, ni un descripteur d’implémentation ne peut pas être spécifié dans un appel de fonction SQLSetStmtAttr .

Les descripteurs explicitement alloués sont associés à un handle de connexion au lieu d’un handle d’instruction (car les descripteurs alloués automatiquement sont). Les descripteurs restent alloués uniquement lorsqu’une application est réellement connectée à la base de données. Étant donné que les descripteurs alloués explicitement sont associés à un handle de connexion, une application peut associer un descripteur alloué explicitement à plusieurs instructions au sein d’une connexion. En revanche, un descripteur d’application implicitement alloué ne peut pas être associé à plusieurs handles d’instruction. (Il ne peut pas être associé à un handle d’instruction autre que celui pour lequel il a été alloué.) Les handles de descripteur explicitement alloués peuvent être libérés explicitement par l’application ou par l’appel de SQLFreeHandle avec un HandleType de SQL_HANDLE_DESC, ou implicitement lorsque la connexion est fermée.

Lorsque le descripteur explicitement alloué est libéré, le descripteur implicitement alloué est de nouveau associé à l’instruction. (L’attribut SQL_ATTR_APP_ROW_DESC ou SQL_ATTR_APP_PARAM_DESC pour cette instruction est à nouveau défini sur le descripteur implicitement alloué.) Cela est vrai pour toutes les instructions associées au descripteur explicitement alloué sur la connexion.

Pour plus d’informations sur les descripteurs, consultez Descripteurs.

Exemple de code

Consultez l’exemple de programme ODBC, de fonction SQLBrowseConnect, de fonction SQLConnect et de fonction SQLSetCursorName.

Fonctions connexes

Voir aussi

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