SQLParamData, fonction

  • Article

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 des paramètres de sortie 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 renvoyer 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 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.)
07006 Violation d’attribut de type de données restreinte 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é en tant que 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 de plusieurs lignes n’ont pas pu être converties, mais qu’une ou plusieurs lignes ont été correctement retournées, cette fonction retourne SQL_SUCCESS_WITH_INFO.)
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.
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 celles spécifiées 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 colonne longue (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 celles spécifiées dans la mémoire tampon de longueur correspondant à une colonne d’une ligne de données qui a été ajoutée ou mise à jour avec SQLBulkOperations ou mise à jour avec SQLSetPos.
40001 Échec de sérialisation La transaction a été annulée en raison d’un blocage des ressources avec une autre transaction.
40003 Saisie semi-automatique d’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 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 l’instruction StatementHandle. La fonction a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé sur l’InstructionHandle ; la fonction a ensuite été appelée à nouveau sur l’InstructionHandle.

La fonction a été appelée et, avant de terminer l’exécution, SQLCancel ou SQLCancelHandle a été appelé 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 d’exécution asynchrone a été appelée pour le handle de connexion associé à l’InstructionHandle. Cette fonction asynchrone était toujours en cours d’exécution lorsque la fonction SQLParamData a été appelée.

(DM) Une fonction d’exécution asynchrone (et non celle-ci) a été appelée pour l’InstructionHandle et s’exécutait toujours lorsque cette fonction a été appelée.

SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’InstructionHandle et renvoyé SQL_NEED_DATA. SQLCancel a été appelé avant l’envoi des données pour toutes les colonnes ou paramètres 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 consultés, peut-être 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 FONCTION SQLEndTran.
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 qui correspond à l’InstructionHandle 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 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.

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). S’il est appelé lors de l’envoi de données pour une colonne en cours de mise à jour ou d’ajout avec SQLBulkOperations ou mise à jour avec SQLSetPos, il peut retourner n’importe quel SQLSTATE qui peut être retourné par SQLBulkOperations ou SQLSetPos.

Commentaires

SQLParamData peut être appelé pour fournir des données à 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 mise à jour par un appel à SQLSetPos. Au moment de l’exécution, SQLParamData renvoie à l’application un indicateur des données requises par le pilote.

Lorsqu’une application appelle SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos, le pilote retourne SQL_NEED_DATA s’il a besoin de données à l’exécution. Une application appelle ensuite SQLParamData pour déterminer les données à envoyer. Si le pilote nécessite 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 a besoin de données de colonne, le pilote retourne dans la mémoire tampon *ValuePtrPtr l’adresse à laquelle la colonne était liée à l’origine, comme suit :

Adresse + liée Décalage de liaison + ((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 d’une seule ligne, qui sont la valeur 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.

Il retourne également SQL_NEED_DATA, qui indique à 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 toutes les données 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 au moment de l’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 au niveau de 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 de données à l’exécution sont transmises au moment de l’exécution de l’instruction, 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 de données à l’exécution sont mises à jour ou ajoutées, consultez la section « Utilisation de SQLSetPos » dans SQLSetPos, « Exécution d’un Mises à jour à l’aide de signets » dans SQLBulkOperations et Données longues et SQLSetPos et SQLBulkOperations.

SQLParamData peut être appelé pour récupérer les paramètres de sortie 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 SQL_PARAM_DATA_AVAILABLE et les paramètres de sortie diffusés, consultez Récupération des paramètres de sortie à l’aide de SQLGetData.

Exemple de code

Consultez SQLPutData.

Pour obtenir des informations sur Consultez
Liaison d’une mémoire tampon à un paramètre Fonction SQLBindParameter
Annulation du traitement des instructions SQLCancel, fonction
Retour d’informations sur un paramètre dans une instruction Fonction SQLDescribeParam
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 Fonction SQLPutData

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