SQLParamData, fonction

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

Résumé
SQLParamData est utilisé avec SQLPutData pour fournir des données de paramètre au moment de l’exécution de l’instruction, et avec SQLGetData pour récupérer les données de paramètre de sortie diffusées en continu.

Syntaxe

  
SQLRETURN SQLParamData(  
     SQLHSTMT       StatementHandle,  
     SQLPOINTER *   ValuePtrPtr);  

Arguments

StatementHandle
[Entrée] Handle d’instruction.

ValuePtrPtr
[Sortie] Pointeur vers une mémoire tampon dans laquelle retourner l’adresse de la mémoire tampon ParameterValuePtr spécifiée dans SQLBindParameter (pour les données de paramètre) ou l’adresse de la mémoire tampon TargetValuePtr spécifiée dans SQLBindCol (pour les données de colonne), comme contenu dans le champ d’enregistrement de descripteur SQL_DESC_DATA_PTR.

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, SQL_INVALID_HANDLE ou SQL_PARAM_DATA_AVAILABLE.

Diagnostics

Lorsque SQLParamData 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_STMT et un Handle of StatementHandle. Le tableau suivant répertorie les valeurs SQLSTATE généralement retournées par SQLParamData 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.

SQLSTATE	Erreur	Description
01000	Avertissement général	Message d’information spécifique au pilote. (La fonction retourne SQL_SUCCESS_WITH_INFO.)
07006	Violation d’attribut de type de données restreint	La valeur de données identifiée par l’argument ValueType dans SQLBindParameter pour le paramètre lié n’a pas pu être convertie en type de données identifié par l’argument ParameterType dans SQLBindParameter. La valeur de données retournée pour un paramètre lié comme SQL_PARAM_INPUT_OUTPUT ou SQL_PARAM_OUTPUT n’a pas pu être convertie en type de données identifié par l’argument ValueType dans SQLBindParameter. (Si les valeurs de données d’une ou plusieurs lignes n’ont pas pu être converties, mais qu’une ou plusieurs lignes ont été retournées avec succès, cette fonction retourne SQL_SUCCESS_WITH_INFO.)
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.
22026	Chaîne de données ou longueur non correspondante	Le type d’informations SQL_NEED_LONG_DATA_LEN dans SQLGetInfo était « Y », et moins de données ont été envoyées pour un paramètre long (le type de données était SQL_LONGVARCHAR, SQL_LONGVARBINARY ou un type de données spécifique à une source de données longue) que celui spécifié avec l’argument StrLen_or_IndPtr dans SQLBindParameter. Le type d’informations SQL_NEED_LONG_DATA_LEN dans SQLGetInfo était « Y », et moins de données ont été envoyées pour une longue colonne (le type de données était SQL_LONGVARCHAR, SQL_LONGVARBINARY ou un type de données spécifique à une source de données longue) que celui spécifié dans la mémoire tampon de longueur correspondant à une colonne d’une ligne de données ajoutées ou mises à jour avec SQLBulkOperations ou mis à jour avec SQLSetPos.
40001	Échec de sérialisation	La transaction a été restaurée en raison d’un interblocage de ressources avec une autre transaction.
40003	Saisie semi-automatique de l’instruction inconnue	La connexion associée a échoué pendant l’exécution de cette fonction et l’état de la transaction ne peut pas être déterminé.
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 StatementHandle. La fonction a été appelée et avant qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle ; la fonction a ensuite été appelée à nouveau sur StatementHandle. La fonction a été appelée et avant qu’elle ait terminé l’exécution, SQLCancel ou SQLCancelHandle a été appelée sur l’InstructionHandle à partir d’un autre thread dans une application multithread.
HY010	Erreur de séquence de fonction	(DM) L’appel de fonction précédent n’était pas un appel à SQLExecDirect, SQLExecute, SQLBulkOperations ou SQLSetPos où le code de retour était SQL_NEED_DATA, ou l’appel de fonction précédent était un appel à SQLPutData. L’appel de fonction précédent était un appel à SQLParamData. (DM) Une fonction en cours d’exécution asynchrone a été appelée pour le handle de connexion associé à StatementHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLParamData a été appelée. (DM) Une fonction en cours d’exécution asynchrone (et non celle-ci) a été appelée pour l’instruction StatementHandle et était toujours en cours d’exécution lorsque cette fonction a été appelée. SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et retourné SQL_NEED_DATA. SQLCancel a été appelé avant que les données ne soient envoyées pour tous les paramètres ou colonnes de données à l’exécution.
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.
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.
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 qui correspond à StatementHandle ne prend pas en charge la fonction.
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.

Si SQLParamData est appelé lors de l’envoi de données pour un paramètre dans une instruction SQL, il peut retourner n’importe quel SQLSTATE qui peut être retourné par la fonction appelée pour exécuter l’instruction (SQLExecute ou SQLExecDirect). Si elle est appelée lors de l’envoi de données pour une colonne mise à jour ou ajoutée avec SQLBulkOperations ou mise à jour avec SQLSetPos, elle peut retourner n’importe quel SQLSTATE qui peut être retourné par SQLBulkOperations ou SQLSetPos.

Commentaires

SQLParamData peut être appelé pour fournir des données au niveau de l’exécution pour deux utilisations : les données de paramètre qui seront utilisées dans un appel à SQLExecute ou SQLExecDirect, ou les données de colonne qui seront utilisées lorsqu’une ligne est mise à jour ou ajoutée par un appel à SQLBulkOperations ou mis à jour par un appel à SQLSetPos. Au moment de l’exécution, SQLParamData retourne à l’application un indicateur dont le pilote a besoin.

Lorsqu’une application appelle SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos, le pilote retourne SQL_NEED_DATA s’il a besoin de données au niveau de l’exécution. Une application appelle ensuite SQLParamData pour déterminer les données à envoyer. Si le pilote requiert des données de paramètre, le pilote retourne dans la mémoire tampon de sortie *ValuePtrPtr la valeur que l’application a placée dans la mémoire tampon de l’ensemble de lignes. L’application peut utiliser cette valeur pour déterminer les données de paramètre demandées par le pilote. Si le pilote requiert des données de colonne, le pilote retourne dans la mémoire tampon *ValuePtrPtr l’adresse à laquelle la colonne était initialement liée, comme suit :

Décalage de liaison d’adresse + liée + ((Numéro de ligne - 1) x Taille d’élément)

où les variables sont définies comme indiqué dans le tableau suivant.

Variable	Description
Adresse liée	Adresse spécifiée avec l’argument TargetValuePtr dans SQLBindCol.
Décalage de liaison	Valeur stockée à l’adresse spécifiée avec l’attribut d’instruction SQL_ATTR_ROW_BIND_OFFSET_PTR.
Row Number	Numéro de base 1 de la ligne dans l’ensemble de lignes. Pour les extractions à une seule ligne, qui sont les valeurs par défaut, il s’agit de 1.
Taille de l’élément	Valeur de l’attribut d’instruction SQL_ATTR_ROW_BIND_TYPE pour les mémoires tampons de données et de longueur/indicateur.

Elle retourne également SQL_NEED_DATA, qui est un indicateur à l’application qu’elle doit appeler SQLPutData pour envoyer les données.

L’application appelle SQLPutData autant de fois que nécessaire pour envoyer les données au moment de l’exécution pour la colonne ou le paramètre. Une fois que toutes les données ont été envoyées pour la colonne ou le paramètre, l’application appelle à nouveau SQLParamData . Si SQLParamData retourne à nouveau SQL_NEED_DATA, les données doivent être envoyées pour un autre paramètre ou colonne. Par conséquent, l’application appelle à nouveau SQLPutData. Si toutes les données en cours d’exécution ont été envoyées pour tous les paramètres ou colonnes, SQLParamData retourne SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, la valeur dans *ValuePtrPtr n’est pas définie et l’instruction SQL peut être exécutée ou l’appel SQLBulkOperations ou SQLSetPos peut être traité.

Si SQLParamData fournit des données de paramètre pour une instruction de mise à jour ou de suppression recherchée qui n’affecte aucune ligne à la source de données, l’appel à SQLParamData retourne SQL_NO_DATA.

Pour plus d’informations sur la façon dont les données des paramètres d’exécution de données au moment de l’exécution de l’instruction sont passées, consultez « Passage de valeurs de paramètre » dans SQLBindParameter et envoi de données longues. Pour plus d’informations sur la façon dont les données de colonne d’exécution sont mises à jour ou ajoutées, consultez la section « Utilisation de SQLSetPos » dans SQLSetPos, « Exécution de mises à jour en bloc à l’aide de signets » dans SQLBulkOperations et SqlSetPos et SQLBulkOperations.

SQLParamData peut être appelé pour récupérer les paramètres de sortie diffusés en continu. Lorsque SQLMoreResults, SQLExecute, SQLGetData ou SQLExecDirect retourne SQL_PARAM_DATA_AVAILABLE, appelez SQLParamData pour déterminer quel paramètre a une valeur disponible. Pour plus d’informations sur les paramètres de sortie SQL_PARAM_DATA_AVAILABLE et diffusés en continu, consultez Récupération des paramètres de sortie à l’aide de SQLGetData.

Exemple de code

Consultez SQLPutData.

Fonctions connexes

Pour plus d’informations sur	Consultez
Liaison d’une mémoire tampon à un paramètre	SQLBindParameter, fonction
Annulation du traitement des instructions	SQLCancel, fonction
Retour d’informations sur un paramètre dans une instruction	SQLDescribeParam, fonction
Exécution d’une instruction SQL	SQLExecDirect, fonction
Exécution d’une instruction SQL préparée	SQLExecute, fonction
Envoi de données de paramètre au moment de l’exécution	SQLPutData, fonction

Voir aussi

Informations de référence sur l’API ODBC
Fichiers d’en-tête ODBC
Récupération des paramètres de sortie à l’aide de SQLGetData