SQLAllocHandle, fonction

  • Article

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

Résumé
SQLAllocHandle alloue un environnement, une connexion, une instruction ou un handle descripteur.

Notes

Cette fonction est une fonction générique pour l’allocation de handles qui remplace les fonctions ODBC 2.0 SQLAllocConnect, SQLAllocEnv et SQLAllocStmt. Pour autoriser les applications appelant SQLAllocHandle à fonctionner avec ODBC 2. x pilotes, un appel à SQLAllocHandle est mappé dans le Gestionnaire de pilotes à SQLAllocConnect, SQLAllocEnv ou SQLAllocStmt, le cas échéant. Pour plus d’informations, consultez « Commentaires ». Pour plus d’informations sur ce à quoi le Gestionnaire de pilotes mappe cette fonction lorsqu’un odbc 3. L’application x fonctionne avec odbc 2. x pilote, consultez Mappage des fonctions de remplacement pour la compatibilité descendante des applications.

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 de la sensibilisation Connection-Pool dans un pilote ODBC.

InputHandle
[Entrée] Handle d’entrée dans le contexte duquel le nouveau handle doit être alloué. Si HandleType est SQL_HANDLE_ENV, c’est 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 renvoyer 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, en fonction de 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 .

Erreurs d’allocation de gestion de l’environnement

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 lorsque SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV est appelé, ou si 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 de l’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, SQLBrowseConnect ou SQLDriverConnect au niveau du Gestionnaire de pilotes 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 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 le 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 de SQLSTATEs retournées par le Gestionnaire de pilotes. Le code de retour associé à chaque valeur SQLSTATE est SQL_ERROR, sauf indication contraire.

SQLSTATE Error Description
01000 Avertissement général Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
08003 Connexion non ouverte (DM) L’argument HandleType était SQL_HANDLE_STMT ou SQL_HANDLE_DESC, mais la connexion spécifiée par l’argument InputHandle n’était pas ouverte. Le processus de connexion doit être terminé correctement (et la connexion doit être ouverte) pour que le pilote puisse allouer un handle d’instruction ou de descripteur.
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 (DM) Le Gestionnaire de pilotes n’a pas pu allouer de mémoire pour le handle spécifié.

Le pilote n’a pas pu allouer de mémoire pour le handle spécifié.
HY009 Utilisation non valide du pointeur null (DM) L’argument OutputHandlePtr était un pointeur null.
HY010 Erreur de séquence de fonction (DM) L’argument HandleType a été SQL_HANDLE_DBC et SQLSetEnvAttr n’a pas été appelé pour définir l’attribut d’environnement SQL_ODBC_VERSION.

(DM) Une fonction d’exécution asynchrone a été appelée pour l’InputHandle et était toujours en cours d’exécution lorsque la fonction SQLAllocHandle a été appelée avec HandleType défini sur SQL_HANDLE_STMT ou SQL_HANDLE_DESC.
HY013 Erreur de gestion de la mémoire L’argument HandleType était SQL_HANDLE_DBC, SQL_HANDLE_STMT ou SQL_HANDLE_DESC ; et 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.
HY014 Limite du nombre de handles dépassé La limite définie par le pilote pour le nombre de handles qui peuvent être alloués pour le type de handle indiqué par l’argument HandleType a été atteinte.
HY092 Identificateur d’attribut/d’option non valide (DM) L’argument HandleType n’était pas : SQL_HANDLE_ENV, SQL_HANDLE_DBC, SQL_HANDLE_STMT ou SQL_HANDLE_DESC.
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 L’argument HandleType a été SQL_HANDLE_DESC et le pilote était odbc 2. x 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) L’argument HandleType était SQL_HANDLE_STMT et le pilote n’était pas un pilote ODBC valide.

(DM) L’argument HandleType a été SQL_HANDLE_DESC et le pilote ne prend pas en charge l’allocation d’un handle de descripteur.

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 pouvant être alloués à tout moment. Les conducteurs 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 de 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 le contenu précédent d’un handle avant de les remplacer.

Notes

La programmation d’application ODBC est incorrecte pour appeler SQLAllocHandle deux fois avec la même variable d’application définie pour *OutputHandlePtr sans appeler SQLFreeHandle pour libérer le handle avant de le réallouer. Le remplacement des handles ODBC d’une telle manière peut entraîner un comportement incohérent ou des erreurs de la part des pilotes ODBC.

Sur les systèmes d’exploitation qui prennent en charge plusieurs threads, les applications peuvent utiliser le même environnement, la même connexion, le même handle d’instruction ou de descripteur sur différents threads. Les pilotes doivent donc prendre en charge l’accès sécurisé et multithread à ces informations ; Une façon d’y parvenir, 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, sinon 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. Cela est fait parce que les applications conformes aux normes sont toujours ODBC 3. x applications. En outre, les normes ne nécessitent pas l’enregistrement 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 dans le 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 permet d’accéder à des informations globales telles que des handles de connexion valides et des 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à un handle d’environnement de pilote, SQLAllocHandle avec un HandleType de SQL_HANDLE_ENV n’est pas appelé dans ce pilote lorsqu’une connexion est établie, uniquement 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 l’appel de SQLAllocHandle pour allouer un handle de connexion sur l’environnement, l’appel pour allouer la connexion renvoie 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. DANS ce cas, SQLSetEnvAttr est appelé avec EnvironmentHandle défini sur null, ce qui fait de l’attribut un 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 sera 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 n’est pas 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, un environnement 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 lors de la création de l’environnement. 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 manière peut être utilisé dans toute fonction ODBC qui accepte un handle d’environnement comme argument d’entrée.

Allocation d'un handle de connexion

Un handle de connexion permet d’accéder à des informations telles que les handles d’instruction et de descripteur valides 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 qui a été 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 l’appel de SQLAllocHandle pour allouer un handle de connexion sur l’environnement, l’appel pour allouer la connexion renvoie 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 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é. 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 quelle connexion dans le pool doit être utilisée. Pour plus d’informations, consultez Fonction SQLConnect.

Allocation d'un descripteur d'instruction

Un handle d’instruction permet d’accéder 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’instruction, consultez Descripteurs 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 de 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 un descripteur d’application explicitement, consultez la section suivante, « Allocation d’un handle 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 indique à un pilote d’utiliser un descripteur d’application explicitement alloué au lieu d’un descripteur 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 être spécifié dans un appel de fonction SQLSetStmtAttr .

Les descripteurs alloués explicitement sont associés à un handle de connexion au lieu d’un handle d’instruction (comme le sont les descripteurs alloués automatiquement). Les descripteurs restent alloués uniquement lorsqu’une application est réellement connectée à la base de données. Étant donné que les descripteurs explicitement alloués sont associés à un handle de connexion, une application peut associer un descripteur explicitement alloué à plusieurs instructions au sein d’une connexion. En revanche, un descripteur d’application alloué implicitement 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 descripteurs explicitement alloués peuvent être libérés explicitement par l’application ou en appelant 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 de nouveau défini sur le handle de descripteur alloué implicitement.) 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 Exemple de programme ODBC, fonction SQLBrowseConnect, fonction SQLConnect et fonction SQLSetCursorName.

Pour obtenir des informations sur Consultez
Exécution d’une instruction SQL SQLExecDirect, fonction
Exécution d’une instruction SQL préparée SQLExecute, fonction
Libération d’un environnement, d’une connexion, d’une instruction ou d’un handle de descripteur Fonction SQLFreeHandle
Préparation d’une instruction pour l’exécution Fonction SQLPrepare
Définition d’un attribut de connexion Fonction SQLSetConnectAttr
Définition d’un champ de descripteur SQLSetDescField, fonction
Définition d’un attribut d’environnement Fonction SQLSetEnvAttr
Définition d’un attribut d’instruction Fonction SQLSetStmtAttr

Voir aussi

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