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 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.

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.

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.

Fonctions connexes

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