Partage via

Fonction SQLBindParameter

  • Article

Conformité
Version introduite : Conformité aux normes ODBC 2.0 : ODBC

Résumé
SQLBindParameter lie une mémoire tampon à un marqueur de paramètre dans une instruction SQL. SQLBindParameter prend en charge la liaison à un type de données C Unicode, même si le pilote sous-jacent ne prend pas en charge les données Unicode.

Remarque

Cette fonction remplace la fonction ODBC 1.0 SQLSetParam. Pour plus d’informations, consultez « Commentaires ».

Syntaxe

  
SQLRETURN SQLBindParameter(  
      SQLHSTMT        StatementHandle,  
      SQLUSMALLINT    ParameterNumber,  
      SQLSMALLINT     InputOutputType,  
      SQLSMALLINT     ValueType,  
      SQLSMALLINT     ParameterType,  
      SQLULEN         ColumnSize,  
      SQLSMALLINT     DecimalDigits,  
      SQLPOINTER      ParameterValuePtr,  
      SQLLEN          BufferLength,  
      SQLLEN *        StrLen_or_IndPtr);

Arguments

StatementHandle
[Entrée] Handle d’instruction.

ParameterNumber
[Entrée] Numéro de paramètre, ordonné séquentiellement dans l’ordre croissant des paramètres, commençant à 1.

InputOutputType
[Entrée] Type du paramètre. Pour plus d’informations, consultez « InputOutputType Argument » dans « Comments ».

ValueType
[Entrée] Type de données C du paramètre. Pour plus d’informations, consultez « ValueType Argument » dans « Comments ».

ParameterType
[Entrée] Type de données SQL du paramètre. Pour plus d’informations, consultez « ParameterType Argument » dans « Comments ».

ColumnSize
[Entrée] Taille de la colonne ou de l’expression du marqueur de paramètre correspondant. Pour plus d’informations, consultez « Argument ColumnSize » dans « Commentaires ».

Si votre application s’exécute sur un système d’exploitation Windows 64 bits, consultez les informations ODBC 64 bits.

DecimalDigits
[Entrée] Chiffres décimaux de la colonne ou de l’expression du marqueur de paramètre correspondant. Pour plus d’informations sur la taille de colonne, consultez Taille de colonne, Chiffres décimaux, Longueur des octets de transfert et Taille d’affichage.

ParameterValuePtr
[Entrée différée] Pointeur vers une mémoire tampon pour les données du paramètre. Pour plus d’informations, consultez « Argument ParameterValuePtr » dans « Comments ».

BufferLength
[Entrée/sortie] Longueur de la mémoire tampon ParameterValuePtr en octets. Pour plus d’informations, consultez « Argument BufferLength » dans « Commentaires ».

Consultez les informations ODBC 64 bits si votre application s’exécute sur un système d’exploitation 64 bits.

StrLen_or_IndPtr
[Entrée différée] Pointeur vers une mémoire tampon pour la longueur du paramètre. Pour plus d’informations, consultez « StrLen_or_IndPtr argument » dans « Commentaires ».

Retours

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

Lorsque SQLBindParameter 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 SQLBindParameter 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 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 Le type de données identifié par l’argument ValueType ne peut pas être converti en type de données identifié par l’argument ParameterType . Notez que cette erreur peut être retournée par SQLExecDirect, SQLExecute ou SQLPutData au moment de l’exécution, au lieu de SQLBindParameter.
07009 Index de descripteur non valide (DM) La valeur spécifiée pour l’argument ParameterNumber était inférieure à 1.
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.
HY003 Type de mémoire tampon d’application non valide La valeur spécifiée par l’argument ValueType n’était pas un type de données C valide ou SQL_C_DEFAULT.
HY004 Type de données SQL non valide La valeur spécifiée pour l’argument ParameterType n’était ni un identificateur de type de données SQL ODBC valide ni un identificateur de type de données SQL spécifique au pilote pris en charge par le pilote.
HY009 Valeur d’argument non valide (DM) L’argument ParameterValuePtr était un pointeur Null, l’argument StrLen_or_IndPtr était un pointeur Null et l’argument InputOutputType n’était pas SQL_PARAM_OUTPUT.

(DM) SQL_PARAM_OUTPUT, où l’argument ParameterValuePtr était un pointeur Null, le type C était char ou binaire, et le BufferLength (cbValueMax) était supérieur à 0.
HY010 Erreur de séquence de fonction (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 SQLBindParameter a été appelé.

(DM) SQLExecute, SQLExecDirect ou SQLMoreResults a été appelé pour l’instruction StatementHandle et retourné SQL_PARAM_DATA_AVAILABLE. Cette fonction a été appelée avant la récupération des données pour tous les paramètres diffusés en continu.

(DM) Une fonction en cours d’exécution asynchrone a été appelée pour l’instruction StatementHandle et était toujours en cours d’exécution lors de l’appel de cette fonction.

(DM) SQLExecute, SQLExecDirect, SQLBulkOperations ou SQLSetPos a été appelé pour l’instructionHandle et retourné SQL_NEED_DATA. Cette fonction a été appelée 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.
HY021 Informations de descripteur incohérentes Les informations du descripteur vérifiées lors d’une vérification de cohérence n’ont pas été cohérentes. (Consultez la section « Vérifications de cohérence » dans SQLSetDescField.)

La valeur spécifiée pour l’argument DecimalDigits était en dehors de la plage de valeurs prises en charge par la source de données pour une colonne du type de données SQL spécifié par l’argument ParameterType .
HY090 Longueur de la chaîne ou de la mémoire tampon non valide (DM) La valeur dans BufferLength était inférieure à 0. (Voir la description du champ SQL_DESC_DATA_PTR dans SQLSetDescField.)
HY104 Valeur de précision ou d’échelle non valide La valeur spécifiée pour l’argument ColumnSize ou DecimalDigits était en dehors de la plage de valeurs prises en charge par la source de données pour une colonne du type de données SQL spécifié par l’argument ParameterType .
HY105 Type de paramètre non valide (DM) La valeur spécifiée pour l’argument InputOutputType n’était pas valide. (Voir « Commentaires »).
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.
HYC00 Fonctionnalité facultative non implémentée Le pilote ou la source de données ne prend pas en charge la conversion spécifiée par la combinaison de la valeur spécifiée pour l’argument ValueType et la valeur spécifique au pilote spécifiée pour l’argument ParameterType.

La valeur spécifiée pour l’argument ParameterType était un identificateur de type de données ODBC SQL valide pour la version d’ODBC prise en charge par le pilote, mais elle n’était pas prise en charge par le pilote ou la source de données.

Le pilote prend uniquement en charge ODBC 2.x et l’argument ValueType était l’un des éléments suivants :

SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT

et tous les types de données C d’intervalle répertoriés dans les types de données C dans l’annexe D : Types de données.

Le pilote prend uniquement en charge les versions ODBC antérieures à la version 3.50 et l’argument ValueType a été SQL_C_GUID.
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 associé à StatementHandle ne prend pas en charge la fonction.

Commentaires

Une application appelle SQLBindParameter pour lier chaque marqueur de paramètre dans une instruction SQL. Les liaisons restent en vigueur jusqu’à ce que l’application appelle à nouveau SQLBindParameter , appelle SQLFreeStmt avec l’option SQL_RESET_PARAMS, ou appelle SQLSetDescField pour définir le champ d’en-tête SQL_DESC_COUNT de l’APD sur 0.

Pour plus d’informations sur les paramètres, consultez Paramètres de l’instruction. Pour plus d’informations sur les types de données de paramètre et les marqueurs de paramètres, consultez Types de données de paramètre et marqueurs de paramètres dans l’annexe C : Grammaire SQL.

ParameterNumber, argument

Si ParameterNumber dans l’appel à SQLBindParameter est supérieur à la valeur de SQL_DESC_COUNT, SQLSetDescField est appelé pour augmenter la valeur de SQL_DESC_COUNT à ParameterNumber.

InputOutputType, argument

L’argument InputOutputType spécifie le type du paramètre. Cet argument définit le champ SQL_DESC_PARAMETER_TYPE de l’ADRESSE IPD. Tous les paramètres des instructions SQL qui n’appellent pas de procédures, telles que les instructions INSERT, sont des paramètres d’entrée. Les paramètres des appels de procédure peuvent être des paramètres d’entrée, d’entrée/sortie ou de sortie. (Un appel d’applicationSQLProcedureColumns pour déterminer le type d’un paramètre dans un appel de procédure ; les paramètres dont le type ne peut pas être déterminé sont supposés être des paramètres d’entrée.)

L’argument InputOutputType est l’une des valeurs suivantes :

  • SQL_PARAM_INPUT. Le paramètre marque un paramètre dans une instruction SQL qui n’appelle pas de procédure, telle qu’une instruction INSERT , ou marque un paramètre d’entrée dans une procédure. Par exemple, les paramètres dans INSERT INTO Employee VALUES (?, ?, ?) sont des paramètres d’entrée, tandis que les paramètres de {call AddEmp(?, ?, ?)} peuvent être, mais ne sont pas nécessairement des paramètres d’entrée.

    Lorsque l’instruction est exécutée, le pilote envoie des données pour le paramètre à la source de données ; la mémoire tampon *ParameterValuePtr doit contenir une valeur d’entrée valide, ou la mémoire tampon *StrLen_or_IndPtr doit contenir SQL_NULL_DATA, SQL_DATA_AT_EXEC ou le résultat de la macro SQL_LEN_DATA_AT_EXEC.

    Si une application ne peut pas déterminer le type d’un paramètre dans un appel de procédure, elle définit InputOutputType sur SQL_PARAM_INPUT ; si la source de données retourne une valeur pour le paramètre, le pilote l’ignore.

  • SQL_PARAM_INPUT_OUTPUT. Le paramètre marque un paramètre d’entrée/sortie dans une procédure. Par exemple, le paramètre dans {call GetEmpDept( ?)} est un paramètre d’entrée/sortie qui accepte le nom d’un employé et retourne le nom du service de l’employé.

    Lorsque l’instruction est exécutée, le pilote envoie des données pour le paramètre à la source de données ; la mémoire tampon *ParameterValuePtr doit contenir une valeur d’entrée valide, ou la mémoire tampon *StrLen_or_IndPtr doit contenir SQL_NULL_DATA, SQL_DATA_AT_EXEC ou le résultat de la macro SQL_LEN_DATA_AT_EXEC. Une fois l’instruction exécutée, le pilote retourne des données pour le paramètre à l’application ; si la source de données ne retourne pas de valeur pour un paramètre d’entrée/sortie, le pilote définit la mémoire tampon *StrLen_or_IndPtr sur SQL_NULL_DATA.

    Remarque

    Lorsqu’une application ODBC 1.0 appelle SQLSetParam dans un pilote ODBC 2.0, le Gestionnaire de pilotes le convertit en appel à SQLBindParameter dans lequel l’argument InputOutputType est défini sur SQL_PARAM_INPUT_OUTPUT.

  • SQL_PARAM_OUTPUT. Le paramètre marque la valeur de retour d’une procédure ou d’un paramètre de sortie dans une procédure ; dans les deux cas, ces paramètres sont appelés paramètres de sortie. Par exemple, le paramètre dans { ?=call GetNextEmpID} est un paramètre de sortie qui retourne l’ID d’employé suivant.

    Une fois l’instruction exécutée, le pilote retourne des données pour le paramètre à l’application, sauf si les arguments ParameterValuePtr et StrLen_or_IndPtr sont les deux pointeurs Null, auquel cas le pilote ignore la valeur de sortie. Si la source de données ne retourne pas de valeur pour un paramètre de sortie, le pilote définit la mémoire tampon *StrLen_or_IndPtr sur SQL_NULL_DATA.

  • SQL_PARAM_INPUT_OUTPUT_STREAM. Indique qu’un paramètre d’entrée/sortie doit être diffusé en continu. SQLGetData peut lire les valeurs des paramètres en parties. BufferLength est ignoré, car la longueur de la mémoire tampon est déterminée à l’appel de SQLGetData. La valeur de la mémoire tampon StrLen_or_IndPtr doit contenir SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_DATA_AT_EXEC ou le résultat de la macro SQL_LEN_DATA_AT_EXEC. Un paramètre doit être lié en tant que paramètre DAE (Data-At-Execution) à l’entrée s’il sera diffusé en continu à la sortie. ParameterValuePtr peut être n’importe quelle valeur de pointeur non null qui sera retournée par SQLParamData en tant que jeton défini par l’utilisateur dont la valeur a été passée avec ParameterValuePtr pour l’entrée et la sortie. Pour plus d'informations, voir Récupération des paramètres de sortie à l'aide de SQLGetData.

  • SQL_PARAM_OUTPUT_STREAM. Identique à SQL_PARAM_INPUT_OUTPUT_STREAM, pour un paramètre de sortie. * StrLen_or_IndPtr est ignoré à l’entrée.

Le tableau suivant répertorie différentes combinaisons d’InputOutputType et *StrLen_or_IndPtr :

InputOutputType *StrLen_or_IndPtr Résultat Remarque sur ParameterValuePtr
SQL_PARAM_INPUT SQL_LEN_DATA_AT_EXEC(len) ou SQL_DATA_AT_EXEC Entrée en parties ParameterValuePtr peut être n’importe quelle valeur de pointeur qui sera retournée par SQLParamData en tant que jeton défini par l’utilisateur dont la valeur a été passée avec ParameterValuePtr.
SQL_PARAM_INPUT Pas SQL_LEN_DATA_AT_EXEC(len) ou SQL_DATA_AT_EXEC Mémoire tampon liée à l’entrée ParameterValuePtr est l’adresse de la mémoire tampon d’entrée.
SQL_PARAM_OUTPUT Ignoré à l’entrée. Mémoire tampon liée à la sortie ParameterValuePtr est l’adresse de la mémoire tampon de sortie.
SQL_PARAM_OUTPUT_STREAM Ignoré à l’entrée. Sortie diffusée en continu ParameterValuePtr peut être n’importe quelle valeur de pointeur, qui sera retournée par SQLParamData en tant que jeton défini par l’utilisateur dont la valeur a été passée avec ParameterValuePtr.
SQL_PARAM_INPUT_OUTPUT SQL_LEN_DATA_AT_EXEC(len) ou SQL_DATA_AT_EXEC Entrée dans les parties et mémoire tampon liée à la sortie ParameterValuePtr est l’adresse de la mémoire tampon de sortie, qui sera également retournée par SQLParamData en tant que jeton défini par l’utilisateur dont la valeur a été passée avec ParameterValuePtr.
SQL_PARAM_INPUT_OUTPUT Pas SQL_LEN_DATA_AT_EXEC(len) ou SQL_DATA_AT_EXEC Mémoire tampon liée aux entrées et mémoire tampon liée à la sortie ParameterValuePtr est l’adresse de la mémoire tampon d’entrée/sortie partagée.
SQL_PARAM_INPUT_OUTPUT_STREAM SQL_LEN_DATA_AT_EXEC(len) ou SQL_DATA_AT_EXEC Entrée dans les parties et sortie diffusée en continu ParameterValuePtr peut être n’importe quelle valeur de pointeur non null, qui sera retournée par SQLParamData en tant que jeton défini par l’utilisateur dont la valeur a été passée avec ParameterValuePtr pour l’entrée et la sortie.

Remarque

Le pilote doit décider quels types SQL sont autorisés lorsqu’une application lie un paramètre de sortie ou de sortie d’entrée en continu. Le gestionnaire de pilotes ne génère pas d’erreur pour un type SQL non valide.

ValueType, argument

L’argument ValueType spécifie le type de données C du paramètre. Cet argument définit les champs SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE et SQL_DESC_DATETIME_INTERVAL_CODE de l’APD. Il doit s’agir de l’une des valeurs de la section Types de données C de l’Annexe D : Types de données.

Si l’argument ValueType est l’un des types de données d’intervalle, le champ SQL_DESC_TYPE de l’enregistrement ParameterNumber de l’APD est défini sur SQL_INTERVAL, le champ SQL_DESC_CONCISE_TYPE de l’APD est défini sur le type de données d’intervalle concis et le champ SQL_DESC_DATETIME_INTERVAL_CODE de l’enregistrement ParameterNumber est défini sur un sous-code pour le type de données d’intervalle spécifique. (Voir Annexe D : Types de données.) La précision d’intervalle par défaut (2) et la précision d’intervalle par défaut (6), comme défini dans les champs SQL_DESC_DATETIME_INTERVAL_PRECISION et SQL_DESC_PRECISION de l’APD, sont respectivement utilisés pour les données. Si la précision par défaut n’est pas appropriée, l’application doit définir explicitement le champ descripteur par un appel à SQLSetDescField ou SQLSetDescRec.

Si l’argument ValueType est l’un des types de données datetime, le champ SQL_DESC_TYPE de l’enregistrement ParameterNumber de l’APD est défini sur SQL_DATETIME, le champ SQL_DESC_CONCISE_TYPE de l’enregistrement ParameterNumber de l’APD est défini sur le type de données datetime C concis et le champ SQL_DESC_DATETIME_INTERVAL_CODE de l’enregistrement ParameterNumber est défini sur un sous-code pour le type de données datetime spécifique. (Voir Annexe D : Types de données.)

Si l’argument ValueType est un type de données SQL_C_NUMERIC, la précision par défaut (qui est définie par le pilote) et l’échelle par défaut (0), comme défini dans les champs SQL_DESC_PRECISION et SQL_DESC_SCALE de l’APD, sont utilisées pour les données. Si la précision ou l’échelle par défaut n’est pas appropriée, l’application doit définir explicitement le champ descripteur par un appel à SQLSetDescField ou SQLSetDescRec.

SQL_C_DEFAULT spécifie que la valeur du paramètre doit être transférée du type de données C par défaut pour le type de données SQL spécifié avec ParameterType.

Vous pouvez également spécifier un type de données C étendu. Pour plus d'informations, voir Types de données C dans ODBC.

Pour plus d’informations, consultez Types de données C par défaut, conversion de données C en types de données SQL et conversion de données de SQL en types de données C dans l’annexe D : Types de données.

ParameterType, argument

Il doit s’agir de l’une des valeurs répertoriées dans la section Types de données SQL de l’Annexe D : Types de données, ou il doit s’agir d’une valeur spécifique au pilote. Cet argument définit les champs SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE et SQL_DESC_DATETIME_INTERVAL_CODE de l’IPD.

Si l’argument ParameterType est l’un des identificateurs datetime, le champ SQL_DESC_TYPE de l’IPD est défini sur SQL_DATETIME, le champ SQL_DESC_CONCISE_TYPE de l’IPD est défini sur le type de données SQL datetime concis et le champ SQL_DESC_DATETIME_INTERVAL_CODE est défini sur la valeur de sous-code datetime appropriée.

Si ParameterType est l’un des identificateurs d’intervalle, le champ SQL_DESC_TYPE de l’IPD est défini sur SQL_INTERVAL, le champ SQL_DESC_CONCISE_TYPE de l’IPD est défini sur le type de données d’intervalle SQL concis et le champ SQL_DESC_DATETIME_INTERVAL_CODE de l’IPD est défini sur le sous-code d’intervalle approprié. Le champ SQL_DESC_DATETIME_INTERVAL_PRECISION de l’IPD est défini sur la précision de début de l’intervalle et le champ SQL_DESC_PRECISION est défini sur la précision de l’intervalle de secondes, le cas échéant. Si la valeur par défaut de SQL_DESC_DATETIME_INTERVAL_PRECISION ou de SQL_DESC_PRECISION n’est pas appropriée, l’application doit la définir explicitement en appelant SQLSetDescField. Pour plus d’informations sur l’un de ces champs, consultez SQLSetDescField.

Si l’argument ValueType est un type de données SQL_NUMERIC, la précision par défaut (définie par le pilote) et l’échelle par défaut (0), comme défini dans les champs SQL_DESC_PRECISION et SQL_DESC_SCALE de l’IPD, sont utilisés pour les données. Si la précision ou l’échelle par défaut n’est pas appropriée, l’application doit définir explicitement le champ descripteur par un appel à SQLSetDescField ou SQLSetDescRec.

Pour plus d’informations sur la façon dont les données sont converties, consultez Conversion de données de C en types de données SQL et conversion de données de SQL en types de données C dans l’annexe D : Types de données.

ColumnSize, argument

L’argument ColumnSize spécifie la taille de la colonne ou de l’expression qui correspond au marqueur de paramètre, à la longueur de ces données ou aux deux. Cet argument définit différents champs de l’IPD, en fonction du type de données SQL ( argument ParameterType ). Les règles suivantes s’appliquent à ce mappage :

  • Si ParameterType est SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY ou l’un des types de données sql datetime ou intervalle concis, le champ SQL_DESC_LENGTH de l’IPD est défini sur la valeur columnSize. (Pour plus d’informations, consultez le Taille de colonne, chiffres décimaux, longueur du transfert d’octets et section Taille d’affichage dans l’annexe D : Types de données.)

  • Si ParameterType est SQL_DECIMAL, SQL_NUMERIC, SQL_FLOAT, SQL_REAL ou SQL_DOUBLE, le champ SQL_DESC_PRECISION de l’IPD est défini sur la valeur de ColumnSize.

  • Pour les autres types de données, l’argument ColumnSize est ignoré.

Pour plus d’informations, consultez « Passage de valeurs de paramètre » et SQL_DATA_AT_EXEC dans « argument StrLen_or_IndPtr ».

DecimalDigits Argument

Si ParameterType est SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_INTERVAL_SECOND, SQL_INTERVAL_DAY_TO_SECOND, SQL_INTERVAL_HOUR_TO_SECOND ou SQL_INTERVAL_MINUTE_TO_SECOND, le champ SQL_DESC_PRECISION de l’IPD est défini sur DecimalDigits. Si ParameterType est SQL_NUMERIC ou SQL_DECIMAL, le champ SQL_DESC_SCALE de l’IPD est défini sur DecimalDigits. Pour tous les autres types de données, l’argument DecimalDigits est ignoré.

ParameterValuePtr, argument

L’argument ParameterValuePtr pointe vers une mémoire tampon qui, lorsque SQLExecute ou SQLExecDirect est appelé, contient les données réelles du paramètre. Les données doivent se trouver sous la forme spécifiée par l’argument ValueType . Cet argument définit le champ SQL_DESC_DATA_PTR de l’APD. Une application peut définir l’argument ParameterValuePtr sur un pointeur Null, tant que *StrLen_or_IndPtr est SQL_NULL_DATA ou SQL_DATA_AT_EXEC. (Cela s’applique uniquement aux paramètres d’entrée ou d’entrée/sortie.)

Si *StrLen_or_IndPtr est le résultat de la macro SQL_LEN_DATA_AT_EXEC(length) ou SQL_DATA_AT_EXEC, ParameterValuePtr est une valeur de pointeur définie par l’application associée au paramètre. Elle est retournée à l’application via SQLParamData. Par exemple, ParameterValuePtr peut être un jeton autre que zéro, tel qu’un numéro de paramètre, un pointeur vers des données ou un pointeur vers une structure utilisée par l’application pour lier des paramètres d’entrée. Toutefois, notez que si le paramètre est un paramètre d’entrée/sortie, ParameterValuePtr doit être un pointeur vers une mémoire tampon où la valeur de sortie sera stockée. Si la valeur de l’attribut d’instruction SQL_ATTR_PARAMSET_SIZE est supérieure à 1, l’application peut utiliser la valeur pointée par l’attribut d’instruction SQL_ATTR_PARAMS_PROCESSED_PTR avec l’argument ParameterValuePtr . Par exemple, ParameterValuePtr peut pointer vers un tableau de valeurs et l’application peut utiliser la valeur pointée par SQL_ATTR_PARAMS_PROCESSED_PTR pour récupérer la valeur correcte du tableau. Pour plus d’informations, consultez « Passage de valeurs de paramètre » plus loin dans cette section.

Si l’argument InputOutputType est SQL_PARAM_INPUT_OUTPUT ou SQL_PARAM_OUTPUT, ParameterValuePtr pointe vers une mémoire tampon dans laquelle le pilote retourne la valeur de sortie. Si la procédure retourne un ou plusieurs jeux de résultats, la mémoire tampon *ParameterValuePtr n’est pas garantie d’être définie tant que tous les jeux de résultats/nombres de lignes n’ont pas été traités. Si la mémoire tampon n’est pas définie tant que le traitement n’est pas terminé, les paramètres de sortie et les valeurs de retour ne sont pas disponibles tant que SQLMoreResults ne retourne SQL_NO_DATA. L’appel de SQLCloseCursor ou SQLFreeStmt avec une option de SQL_CLOSE entraîne l’abandon de ces valeurs.

Si la valeur de l’attribut d’instruction SQL_ATTR_PARAMSET_SIZE est supérieure à 1, ParameterValuePtr pointe vers un tableau. Une instruction SQL unique traite le tableau complet de valeurs d’entrée pour un paramètre d’entrée ou d’entrée/sortie et retourne un tableau de valeurs de sortie pour un paramètre d’entrée/sortie ou de sortie.

BufferLength Argument

Pour les données C caractère et binaire, l’argument BufferLength spécifie la longueur de la mémoire tampon *ParameterValuePtr (s’il s’agit d’un élément unique) ou la longueur d’un élément dans le tableau *ParameterValuePtr (si la valeur de l’attribut d’instruction SQL_ATTR_PARAMSET_SIZE est supérieure à 1). Cet argument définit le champ d’enregistrement SQL_DESC_OCTET_LENGTH de l’APD. Si l’application spécifie plusieurs valeurs, BufferLength est utilisé pour déterminer l’emplacement des valeurs dans le tableau *ParameterValuePtr , à la fois sur l’entrée et sur la sortie. Pour les paramètres d’entrée/sortie et de sortie, il est utilisé pour déterminer s’il faut tronquer des données C de caractères et binaires sur la sortie :

  • Pour les données C de caractère, si le nombre d’octets disponibles à retourner est supérieur ou égal à BufferLength, les données de *ParameterValuePtr sont tronquées en BufferLength moins la longueur d’un caractère d’arrêt Null et sont terminées par null par le pilote.

  • Pour les données C binaires, si le nombre d’octets disponibles à retourner est supérieur à BufferLength, les données dans *ParameterValuePtr sont tronquées en octets BufferLength .

Pour tous les autres types de données C, l’argument BufferLength est ignoré. La longueur de la mémoire tampon *ParameterValuePtr (s’il s’agit d’un élément unique) ou de la longueur d’un élément dans le tableau *ParameterValuePtr (si l’application appelle SQLSetStmtAttr avec un argument Attribute de SQL_ATTR_PARAMSET_SIZE pour spécifier plusieurs valeurs pour chaque paramètre) est supposée être la longueur du type de données C.

Pour la sortie en continu ou les paramètres d’entrée/sortie en continu, l’argument BufferLength est ignoré, car la longueur de la mémoire tampon est spécifiée dans SQLGetData.

Remarque

Lorsqu’une application ODBC 1.0 appelle SQLSetParam dans un ODBC 3.x driver, le Gestionnaire de pilotes le convertit en un appel à SQLBindParameter dans lequel l’argument BufferLength est toujours SQL_SETPARAM_VALUE_MAX. Étant donné que le Gestionnaire de pilotes retourne une erreur si odbc 3.x application définit BufferLength sur SQL_SETPARAM_VALUE_MAX, un ODBC 3.Le pilote x peut l’utiliser pour déterminer quand il est appelé par une application ODBC 1.0.

Remarque

Dans SQLSetParam, la façon dont une application spécifie la longueur de la mémoire tampon *ParameterValuePtr afin que le pilote puisse retourner des données caractères ou binaires et la façon dont une application envoie un tableau de valeurs de caractères ou de paramètres binaires au pilote, sont définies par le pilote.

StrLen_or_IndPtr Argument

L’argument StrLen_or_IndPtr pointe vers une mémoire tampon qui, lorsque SQLExecute ou SQLExecDirect est appelé, contient l’un des éléments suivants. (Cet argument définit les champs d’enregistrement SQL_DESC_OCTET_LENGTH_PTR et SQL_DESC_INDICATOR_PTR des pointeurs des paramètres d’application.)

  • Longueur de la valeur du paramètre stockée dans *ParameterValuePtr. Cela est ignoré à l’exception des données C caractère ou binaire.

  • SQL_NTS. La valeur du paramètre est une chaîne terminée par null.

  • SQL_NULL_DATA. La valeur du paramètre est NULL.

  • SQL_DEFAULT_PARAM. Une procédure consiste à utiliser la valeur par défaut d’un paramètre, au lieu d’une valeur récupérée à partir de l’application. Cette valeur est valide uniquement dans une procédure appelée dans la syntaxe canonique ODBC, puis uniquement si l’argument InputOutputType est SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT ou SQL_PARAM_INPUT_OUTPUT_STREAM. Lorsque *StrLen_or_IndPtr est SQL_DEFAULT_PARAM, les arguments ValueType, ParameterType, ColumnSize, DecimalDigits, BufferLength et ParameterValuePtr sont ignorés pour les paramètres d’entrée et sont utilisés uniquement pour définir la valeur du paramètre de sortie pour les paramètres d’entrée/sortie.

  • Résultat de la macro SQL_LEN_DATA_AT_EXEC(length). Les données du paramètre seront envoyées avec SQLPutData. Si l’argument ParameterType est SQL_LONGVARBINARY, SQL_LONGVARCHAR ou un type de données spécifique à la source de données long et que le pilote retourne « Y » pour le type d’informations SQL_NEED_LONG_DATA_LEN dans SQLGetInfo, la longueur est le nombre d’octets de données à envoyer pour le paramètre ; sinon, la longueur doit être une valeur non négative et est ignorée. Pour plus d’informations, consultez « Passage de valeurs de paramètre », plus loin dans cette section.

    Par exemple, pour spécifier que 10 000 octets de données seront envoyés avec SQLPutData dans un ou plusieurs appels, pour un paramètre SQL_LONGVARCHAR, une application définit *StrLen_or_IndPtr sur SQL_LEN_DATA_AT_EXEC(10000).

  • SQL_DATA_AT_EXEC. Les données du paramètre seront envoyées avec SQLPutData. Cette valeur est utilisée par les applications ODBC 1.0 lorsqu’elles appellent ODBC 3.pilotes x . Pour plus d’informations, consultez « Passage de valeurs de paramètre », plus loin dans cette section.

Si StrLen_or_IndPtr est un pointeur Null, le pilote suppose que toutes les valeurs de paramètre d’entrée ne sont pas NULL et que les données caractères et binaires sont terminées par null. Si InputOutputType est SQL_PARAM_OUTPUT ou SQL_PARAM_OUTPUT_STREAM et ParameterValuePtr et StrLen_or_IndPtr sont tous deux des pointeurs Null, le pilote ignore la valeur de sortie.

Remarque

Les développeurs d’applications sont fortement déconseillés de spécifier un pointeur Null pour StrLen_or_IndPtr lorsque le type de données du paramètre est SQL_C_BINARY. Pour vous assurer qu’un pilote ne tronque pas de manière inattendue SQL_C_BINARY données, StrLen_or_IndPtr doit contenir un pointeur vers une valeur de longueur valide.

Si l’argument InputOutputType est SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM ou SQL_PARAM_OUTPUT_STREAM, StrLen_or_IndPtr pointe vers une mémoire tampon dans laquelle le pilote retourne SQL_NULL_DATA, le nombre d’octets disponibles pour retourner dans *ParameterValuePtr (à l’exclusion de l’octet de terminaison null des données de caractères) ou SQL_NO_TOTAL (si le nombre d’octets disponibles pour retourner ne peut pas être déterminé). Si la procédure retourne un ou plusieurs jeux de résultats, la mémoire tampon *StrLen_or_IndPtr n’est pas garantie d’être définie tant que tous les résultats n’ont pas été récupérés.

Si la valeur de l’attribut d’instruction SQL_ATTR_PARAMSET_SIZE est supérieure à 1, StrLen_or_IndPtr pointe vers un tableau de valeurs SQLLEN. Il peut s’agir de l’une des valeurs répertoriées précédemment dans cette section et traitées avec une seule instruction SQL.

Passage de valeurs de paramètre

Une application peut transmettre la valeur d’un paramètre dans la mémoire tampon *ParameterValuePtr ou avec un ou plusieurs appels à SQLPutData. Les paramètres dont les données sont transmises avec SQLPutData sont appelés paramètres de données au niveau de l’exécution . Ils sont généralement utilisés pour envoyer des données pour des paramètres SQL_LONGVARBINARY et SQL_LONGVARCHAR, et peuvent être mélangés avec d’autres paramètres.

Pour passer des valeurs de paramètre, une application effectue la séquence d’étapes suivante :

  1. Appelle SQLBindParameter pour chaque paramètre afin de lier des mémoires tampons pour la valeur du paramètre (argument ParameterValuePtr ) et la longueur/indicateur (argument StrLen_or_IndPtr ). Pour les paramètres de données au niveau de l’exécution, ParameterValuePtr est une valeur de pointeur définie par l’application, telle qu’un numéro de paramètre ou un pointeur vers des données. La valeur sera retournée ultérieurement et peut être utilisée pour identifier le paramètre.

  2. Place les valeurs des paramètres d’entrée et d’entrée/sortie dans les mémoires tampons *ParameterValuePtr et *StrLen_or_IndPtr :

    • Pour les paramètres normaux, l’application place la valeur du paramètre dans la mémoire tampon *ParameterValuePtr et la longueur de cette valeur dans la mémoire tampon *StrLen_or_IndPtr . Pour plus d’informations, consultez Définition des valeurs de paramètre.

    • Pour les paramètres de données au niveau de l’exécution, l’application place le résultat de la macro SQL_LEN_DATA_AT_EXEC(length) (lors de l’appel d’un pilote ODBC 2.0) dans la mémoire tampon *StrLen_or_IndPtr .

  3. Appelle SQLExecute ou SQLExecDirect pour exécuter l’instruction SQL.

    • S’il n’existe aucun paramètre de données au niveau de l’exécution, le processus est terminé.

    • S’il existe des paramètres de données au niveau de l’exécution, la fonction retourne SQL_NEED_DATA.

  4. Appelle SQLParamData pour récupérer la valeur définie par l’application spécifiée dans l’argument ParameterValuePtr de SQLBindParameter pour le premier paramètre data-at-execution à traiter. SQLParamData retourne SQL_NEED_DATA.

    Remarque

    Bien que les paramètres de données à l’exécution ressemblent à des colonnes data-at-execution, la valeur retournée par SQLParamData est différente pour chacune d’elles. Les paramètres de données au niveau de l’exécution sont des paramètres dans une instruction SQL pour laquelle les données seront envoyées avec SQLPutData lorsque l’instruction est exécutée avec SQLExecDirect ou SQLExecute. Elles sont liées à SQLBindParameter. La valeur retournée par SQLParamData est une valeur de pointeur passée à SQLBindParameter dans l’argument ParameterValuePtr . Les colonnes data-at-execution sont des colonnes d’un ensemble de lignes pour lequel les données seront envoyées avec SQLPutData lorsqu’une ligne est mise à jour ou ajoutée avec SQLBulkOperations ou mise à jour avec SQLSetPos. Elles sont liées à SQLBindCol. La valeur retournée par SQLParamData est l’adresse de la ligne dans la mémoire tampon *TargetValuePtr (définie par un appel à SQLBindCol) en cours de traitement.

  5. Appelle SQLPutData une ou plusieurs fois pour envoyer des données pour le paramètre. Plusieurs appels sont nécessaires si la valeur de données est supérieure à la mémoire tampon *ParameterValuePtr spécifiée dans SQLPutData ; plusieurs appels à SQLPutData pour le même paramètre sont autorisés uniquement lors de l’envoi de données C de caractère à une colonne avec un type de données spécifique à une source de données, ou lors de l’envoi de données C binaires à une colonne avec un caractère, type de données binaire ou spécifique à la source de données.

  6. Appelle à nouveau SQLParamData pour signaler que toutes les données ont été envoyées pour le paramètre.

    • S’il existe davantage de paramètres de données au niveau de l’exécution, SQLParamData retourne SQL_NEED_DATA et la valeur définie par l’application pour le paramètre de données au niveau de l’exécution suivant à traiter. L’application répète les étapes 4 et 5.

    • S’il n’y a plus de paramètres de données au niveau de l’exécution, le processus est terminé. Si l’instruction a été correctement exécutée, SQLParamData retourne SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO ; si l’exécution a échoué, elle retourne SQL_ERROR. À ce stade, SQLParamData peut retourner n’importe quel SQLSTATE qui peut être retourné par la fonction utilisée pour exécuter l’instruction (SQLExecDirect ou SQLExecute).

      Les valeurs de sortie pour tous les paramètres d’entrée/sortie ou de sortie sont disponibles dans les mémoires tampons *ParameterValuePtr et *StrLen_or_IndPtr une fois que l’application a récupéré tous les jeux de résultats générés par l’instruction.

L’appel de SQLExecute ou SQLExecDirect place l’instruction dans un état SQL_NEED_DATA. À ce stade, l’application peut appeler uniquement SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData ou SQLPutData avec l’instruction ou le handle de connexion associé à l’instruction. Si elle appelle une autre fonction avec l’instruction ou la connexion associée à l’instruction, la fonction retourne SQLSTATE HY010 (erreur de séquence de fonction). L’instruction laisse l’état SQL_NEED_DATA lorsque SQLParamData ou SQLPutData retourne une erreur, SQLParamData retourne SQL_SUCCESS ou SQL_SUCCESS_WITH_INFO, ou l’instruction est annulée.

Si l’application appelle SQLCancel alors que le pilote a toujours besoin de données pour les paramètres de données au niveau de l’exécution, le pilote annule l’exécution de l’instruction ; l’application peut alors appeler à nouveau SQLExecute ou SQLExecDirect .

Récupération des paramètres de sortie diffusés en continu

Lorsqu’une application définit InputOutputType sur SQL_PARAM_INPUT_OUTPUT_STREAM ou SQL_PARAM_OUTPUT_STREAM, la valeur du paramètre de sortie doit être récupérée par un ou plusieurs appels à SQLGetData. Lorsque le pilote a une valeur de paramètre de sortie diffusée en continu pour revenir à l’application, il retourne SQL_PARAM_DATA_AVAILABLE en réponse à un appel aux fonctions suivantes : SQLMoreResults, SQLExecute et SQLExecDirect. Une application appelle SQLParamData pour déterminer la valeur de paramètre 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.

Utilisation de tableaux de paramètres

Lorsqu’une application prépare une instruction avec des marqueurs de paramètres et passe dans un tableau de paramètres, il existe deux façons différentes d’exécuter cette instruction. L’une des façons est que le pilote s’appuie sur les fonctionnalités de traitement de tableau du back-end, auquel cas l’instruction entière avec le tableau de paramètres est traitée comme une unité atomique. Oracle est un exemple de source de données qui prend en charge les fonctionnalités de traitement de tableau. Une autre façon d’implémenter cette fonctionnalité est que le pilote génère un lot d’instructions SQL, une instruction SQL pour chaque ensemble de paramètres dans le tableau de paramètres et exécute le lot. Les tableaux de paramètres ne peuvent pas être utilisés avec une instruction UPDATE WHERE CURRENT OF .

Lorsqu’un tableau de paramètres est traité, les jeux de résultats individuels/nombres de lignes (un pour chaque jeu de paramètres) peuvent être disponibles ou les jeux de résultats/nombres de lignes peuvent être regroupés en un. L’option SQL_PARAM_ARRAY_ROW_COUNTS dans SQLGetInfo indique si le nombre de lignes est disponible pour chaque jeu de paramètres (SQL_PARC_BATCH) ou qu’un seul nombre de lignes est disponible (SQL_PARC_NO_BATCH).

L’option SQL_PARAM_ARRAY_SELECTS dans SQLGetInfo indique si un jeu de résultats est disponible pour chaque jeu de paramètres (SQL_PAS_BATCH) ou qu’un seul jeu de résultats est disponible (SQL_PAS_NO_BATCH). Si le pilote n’autorise pas l’exécution d’une instruction de génération de jeux de résultats avec un tableau de paramètres, SQL_PARAM_ARRAY_SELECTS retourne SQL_PAS_NO_SELECT.

Pour plus d’informations, consultez la fonction SQLGetInfo.

Pour prendre en charge les tableaux de paramètres, l’attribut d’instruction SQL_ATTR_PARAMSET_SIZE est défini pour spécifier le nombre de valeurs pour chaque paramètre. Si le champ est supérieur à 1, le SQL_DESC_DATA_PTR, le SQL_DESC_INDICATOR_PTR et les champs SQL_DESC_OCTET_LENGTH_PTR de l’APD doivent pointer vers des tableaux. La cardinalité de chaque tableau est égale à la valeur de SQL_ATTR_PARAMSET_SIZE.

Le champ SQL_DESC_ROWS_PROCESSED_PTR de l’APD pointe vers une mémoire tampon qui contient le nombre de jeux de paramètres qui ont été traités, y compris les jeux d’erreurs. À mesure que chaque jeu de paramètres est traité, le pilote stocke une nouvelle valeur dans la mémoire tampon. Aucun nombre ne sera retourné s’il s’agit d’un pointeur Null. Lorsque des tableaux de paramètres sont utilisés, la valeur pointée par le champ SQL_DESC_ROWS_PROCESSED_PTR de l’APD est remplie même si SQL_ERROR est retournée par la fonction de paramètre. Si SQL_NEED_DATA est retourné, la valeur pointée par le champ SQL_DESC_ROWS_PROCESSED_PTR de l’APD est définie sur l’ensemble de paramètres en cours de traitement.

Ce qui se produit lorsqu’un tableau de paramètres est lié et qu’une instruction UPDATE WHERE CURRENT OF est exécutée est définie par le pilote.

Liaison de paramètre Column-Wise

Dans la liaison à l’échelle des colonnes, l’application lie des tableaux de paramètres et de longueur/indicateurs distincts à chaque paramètre.

Pour utiliser la liaison à l’échelle des colonnes, l’application définit d’abord l’attribut d’instruction SQL_ATTR_PARAM_BIND_TYPE sur SQL_PARAM_BIND_BY_COLUMN. (Il s’agit de la valeur par défaut.) Pour que chaque colonne soit liée, l’application effectue les étapes suivantes :

  1. Alloue un tableau de mémoires tampons de paramètres.

  2. Alloue un tableau de mémoires tampons de longueur/indicateur.

    Remarque

    Si l’application écrit directement dans des descripteurs lorsque la liaison à l’échelle des colonnes est utilisée, des tableaux distincts peuvent être utilisés pour la longueur et les données d’indicateur.

  3. Appelle SQLBindParameter avec les arguments suivants :

    • ValueType est le type C d’un élément unique dans le tableau de mémoires tampons de paramètres.

    • ParameterType est le type SQL du paramètre.

    • ParameterValuePtr est l’adresse du tableau de mémoires tampons de paramètres.

    • BufferLength est la taille d’un élément unique dans le tableau de mémoires tampons de paramètres. L’argument BufferLength est ignoré lorsque les données sont de longueur fixe.

    • StrLen_or_IndPtr est l’adresse du tableau de longueur/indicateur.

Pour plus d’informations sur l’utilisation de ces informations, consultez « ParameterValuePtr Argument » dans « Comments », plus loin dans cette section. Pour plus d’informations sur la liaison à l’échelle des colonnes des paramètres, consultez Tableaux de liaisons de paramètres.

Liaison de paramètre ligne/sage

Dans la liaison à l’échelle des lignes, l’application définit une structure qui contient des mémoires tampons de paramètre et de longueur/indicateur pour chaque paramètre à lier.

Pour utiliser la liaison en ligne, l’application effectue les étapes suivantes :

  1. Définit une structure pour contenir un ensemble unique de paramètres (y compris les mémoires tampons de paramètre et de longueur/indicateur) et alloue un tableau de ces structures.

    Remarque

    Si l’application écrit directement dans des descripteurs lorsque la liaison en ligne est utilisée, des champs distincts peuvent être utilisés pour la longueur et les données d’indicateur.

  2. Définit l’attribut d’instruction SQL_ATTR_PARAM_BIND_TYPE à la taille de la structure qui contient un ensemble unique de paramètres ou à la taille d’une instance d’une mémoire tampon dans laquelle les paramètres seront liés. La longueur doit inclure de l’espace pour tous les paramètres liés et tout remplissage de la structure ou de la mémoire tampon, pour vous assurer que lorsque l’adresse d’un paramètre lié est incrémentée avec la longueur spécifiée, le résultat pointe vers le début du même paramètre dans la ligne suivante. Lorsque vous utilisez l’opérateur sizeof dans ANSI C, ce comportement est garanti.

  3. Appelle SQLBindParameter avec les arguments suivants pour que chaque paramètre soit lié :

    • ValueType est le type du membre de mémoire tampon de paramètre à lier à la colonne.

    • ParameterType est le type SQL du paramètre.

    • ParameterValuePtr est l’adresse du membre de la mémoire tampon de paramètres dans le premier élément de tableau.

    • BufferLength est la taille du membre de la mémoire tampon de paramètre.

    • StrLen_or_IndPtr est l’adresse du membre longueur/indicateur à lier.

Pour plus d’informations sur l’utilisation de ces informations, consultez « ParameterValuePtr Argument », plus loin dans cette section. Pour plus d’informations sur la liaison en ligne des paramètres, consultez les tableaux de liaisons de paramètres.

Informations sur l’erreur

Si un pilote n’implémente pas de tableaux de paramètres en tant que lots (l’option SQL_PARAM_ARRAY_ROW_COUNTS est égale à SQL_PARC_NO_BATCH), les situations d’erreur sont gérées comme si une instruction a été exécutée. Si le pilote implémente des tableaux de paramètres en tant que lots, une application peut utiliser le champ d’en-tête SQL_DESC_ARRAY_STATUS_PTR de l’IPD pour déterminer quel paramètre d’une instruction SQL ou quel paramètre dans un tableau de paramètres a provoqué le retour d’une erreur SQLExecDirect ou SQLExecute . Ce champ contient des informations d’état pour chaque ligne de valeurs de paramètre. Si le champ indique qu’une erreur s’est produite, les champs de la structure des données de diagnostic indiquent la ligne et le numéro de paramètre du paramètre ayant échoué. Le nombre d’éléments du tableau sera défini par le champ d’en-tête SQL_DESC_ARRAY_SIZE dans l’APD, qui peut être défini par l’attribut d’instruction SQL_ATTR_PARAMSET_SIZE.

Remarque

Le champ d’en-tête SQL_DESC_ARRAY_STATUS_PTR dans l’APD est utilisé pour ignorer les paramètres. Pour plus d’informations sur l’ignorance des paramètres, consultez la section suivante , « Ignorer un ensemble de paramètres ».

Lorsque SQLExecute ou SQLExecDirect retourne SQL_ERROR, les éléments du tableau pointés par le champ SQL_DESC_ARRAY_STATUS_PTR dans l’IPD contiennent SQL_PARAM_ERROR, SQL_PARAM_SUCCESS, SQL_PARAM_SUCCESS_WITH_INFO, SQL_PARAM_UNUSED ou SQL_PARAM_DIAG_UNAVAILABLE.

Pour chaque élément de ce tableau, la structure des données de diagnostic contient un ou plusieurs enregistrements d’état. Le champ SQL_DIAG_ROW_NUMBER de la structure indique le numéro de ligne des valeurs de paramètre qui ont provoqué l’erreur. S’il est possible de déterminer le paramètre particulier dans une ligne de paramètres qui a provoqué l’erreur, le numéro de paramètre est entré dans le champ SQL_DIAG_COLUMN_NUMBER.

SQL_PARAM_UNUSED est entré lorsqu’un paramètre n’a pas été utilisé, car une erreur s’est produite dans un paramètre antérieur qui a forcé SQLExecute ou SQLExecDirect à abandonner. Par exemple, s’il existe 50 paramètres et qu’une erreur s’est produite lors de l’exécution du jeu de paramètres qui a provoqué l’abandon de SQLExecute ou SQLExecDirect , SQL_PARAM_UNUSED est entré dans le tableau d’état pour les paramètres 41 à 50.

SQL_PARAM_DIAG_UNAVAILABLE est entré lorsque le pilote traite les tableaux de paramètres comme une unité monolithique, de sorte qu’il ne génère pas ce niveau de paramètre individuel d’informations d’erreur.

Certaines erreurs dans le traitement d’un seul ensemble de paramètres entraînent l’arrêt du traitement des ensembles de paramètres suivants dans le tableau. D’autres erreurs n’affectent pas le traitement des paramètres suivants. Les erreurs qui arrêtent le traitement sont définies par le pilote. Si le traitement n’est pas arrêté, tous les paramètres du tableau sont traités, SQL_SUCCESS_WITH_INFO est retourné suite à l’erreur et la mémoire tampon définie par SQL_ATTR_PARAMS_PROCESSED_PTR est définie sur le nombre total de jeux de paramètres traités (tel que défini par l’attribut d’instruction SQL_ATTR_PARAMSET_SIZE), qui inclut des jeux d’erreurs.

Attention

Le comportement ODBC lorsqu’une erreur se produit dans le traitement d’un tableau de paramètres est différente dans ODBC 3.x que dans ODBC 2.x. Dans ODBC 2.x, la fonction a retourné SQL_ERROR et le traitement a cessé. La mémoire tampon pointée par l’argument pirow de SQLParamOptions contenait le nombre de lignes d’erreur. Dans ODBC 3.x, la fonction retourne SQL_SUCCESS_WITH_INFO et le traitement peut s’arrêter ou continuer. Si elle se poursuit, la mémoire tampon spécifiée par SQL_ATTR_PARAMS_PROCESSED_PTR est définie sur la valeur de tous les paramètres traités, y compris ceux qui ont entraîné une erreur. Ce changement de comportement peut entraîner des problèmes pour les applications existantes.

Lorsque SQLExecute ou SQLExecDirect retourne avant d’effectuer le traitement de tous les jeux de paramètres dans un tableau de paramètres, par exemple lorsque SQL_ERROR ou SQL_NEED_DATA est retourné, le tableau d’état contient des états pour ces paramètres qui ont déjà été traités. L’emplacement pointé par le champ SQL_DESC_ROWS_PROCESSED_PTR dans l’IPD contient le numéro de ligne dans le tableau de paramètres qui a provoqué le code d’erreur SQL_ERROR ou SQL_NEED_DATA. Lorsqu’un tableau de paramètres est envoyé à une instruction SELECT, la disponibilité des valeurs de tableau d’état est définie par le pilote ; elles peuvent être disponibles une fois l’instruction exécutée ou en tant que jeux de résultats récupérés.

Ignorer un ensemble de paramètres

Le champ SQL_DESC_ARRAY_STATUS_PTR de l’APD (tel que défini par l’attribut d’instruction SQL_ATTR_PARAM_STATUS_PTR) peut être utilisé pour indiquer qu’un ensemble de paramètres liés dans une instruction SQL doit être ignoré. Pour diriger le pilote pour ignorer un ou plusieurs ensembles de paramètres pendant l’exécution, une application doit suivre les étapes suivantes :

  1. Appelez SQLSetDescField pour définir le champ d’en-tête SQL_DESC_ARRAY_STATUS_PTR de l’APD pour pointer vers un tableau de valeurs SQLUSMALLINT pour contenir des informations d’état. Ce champ peut également être défini en appelant SQLSetStmtAttr avec un attribut de SQL_ATTR_PARAM_OPERATION_PTR, ce qui permet à une application de définir le champ sans obtenir de handle de descripteur.

  2. Définissez chaque élément du tableau défini par le champ SQL_DESC_ARRAY_STATUS_PTR de l’APD sur l’une des deux valeurs suivantes :

    • SQL_PARAM_IGNORE, pour indiquer que la ligne est exclue de l’exécution de l’instruction.

    • SQL_PARAM_PROCEED, pour indiquer que la ligne est incluse dans l’exécution de l’instruction.

  3. Appelez SQLExecDirect ou SQLExecute pour exécuter l’instruction préparée.

Les règles suivantes s’appliquent au tableau défini par le champ SQL_DESC_ARRAY_STATUS_PTR de l’APD :

  • Le pointeur est défini sur Null par défaut.

  • Si le pointeur a la valeur Null, tous les ensembles de paramètres sont utilisés, comme si tous les éléments étaient définis sur SQL_ROW_PROCEED.

  • La définition d’un élément sur SQL_PARAM_PROCEED ne garantit pas que l’opération utilisera cet ensemble de paramètres particulier.

  • SQL_PARAM_PROCEED est défini comme 0 dans le fichier d’en-tête.

Une application peut définir le champ SQL_DESC_ARRAY_STATUS_PTR dans l’APD pour qu’il pointe vers le même tableau que celui vers lequel pointe le champ SQL_DESC_ARRAY_STATUS_PTR dans l’IRD. Cela est utile lors de la liaison de paramètres aux données de ligne. Les paramètres peuvent ensuite être ignorés en fonction de l’état des données de ligne. Outre SQL_PARAM_IGNORE, les codes suivants entraînent l’ignorer d’un paramètre dans une instruction SQL : SQL_ROW_DELETED, SQL_ROW_UPDATED et SQL_ROW_ERROR. En plus de SQL_PARAM_PROCEED, les codes suivants entraînent la poursuite d’une instruction SQL : SQL_ROW_SUCCESS, SQL_ROW_SUCCESS_WITH_INFO et SQL_ROW_ADDED.

Paramètres de liaison

Une application peut effectuer l’une des deux opérations pour modifier une liaison :

  • Appelez SQLBindParameter pour spécifier une nouvelle liaison pour une colonne déjà liée. Le pilote remplace l’ancienne liaison avec la nouvelle.

  • Spécifiez un décalage à ajouter à l’adresse de mémoire tampon spécifiée par l’appel de liaison à SQLBindParameter. Pour plus d’informations, consultez la section suivante : « Rebinding with Offsets ».

Rebinding avec offsets

La liaison de paramètres est particulièrement utile lorsqu’une application a une configuration de zone tampon qui peut contenir de nombreux paramètres, mais qu’un appel à SQLExecDirect ou SQLExecute n’utilise que quelques-uns des paramètres. L’espace restant dans la zone de mémoire tampon peut être utilisé pour le jeu de paramètres suivant en modifiant la liaison existante par un décalage.

Le champ d’en-tête SQL_DESC_BIND_OFFSET_PTR dans l’APD pointe vers le décalage de liaison. Si le champ n’est pas null, le pilote déréférence le pointeur et, si aucune des valeurs de l’SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR et SQL_DESC_OCTET_LENGTH_PTR champs est un pointeur Null, ajoute la valeur déréférence à ces champs dans les enregistrements de descripteur au moment de l’exécution. Les nouvelles valeurs de pointeur sont utilisées lorsque les instructions SQL sont exécutées. Le décalage reste valide après la liaison. Étant donné que SQL_DESC_BIND_OFFSET_PTR est un pointeur vers le décalage plutôt que le décalage lui-même, une application peut modifier directement le décalage, sans avoir à appeler SQLSetDescField ou SQLSetDescRec pour modifier le champ descripteur. Le pointeur est défini sur Null par défaut. Le champ SQL_DESC_BIND_OFFSET_PTR de l’ARD peut être défini par un appel à SQLSetDescField ou par un appel à SQLSetStmtAttr avec un fAttribute de SQL_ATTR_PARAM_BIND_OFFSET_PTR.

Le décalage de liaison est toujours ajouté directement aux valeurs des champs SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR et SQL_DESC_OCTET_LENGTH_PTR. Si le décalage est remplacé par une valeur différente, la nouvelle valeur est toujours ajoutée directement à la valeur dans chaque champ de descripteur. Le nouveau décalage n’est pas ajouté à la somme de la valeur du champ et des décalages antérieurs.

Descripteurs

La façon dont un paramètre est lié est déterminé par les champs des API et des IPD. Les arguments de SQLBindParameter sont utilisés pour définir ces champs de descripteur. Les champs peuvent également être définis par les fonctions SQLSetDescField, bien que SQLBindParameter soit plus efficace à utiliser, car l’application n’a pas besoin d’obtenir un handle de descripteur pour appeler SQLBindParameter.

Attention

L’appel de SQLBindParameter pour une instruction peut affecter d’autres instructions. Cela se produit lorsque l’ARD associé à l’instruction est explicitement alloué et est également associé à d’autres instructions. Étant donné que SQLBindParameter modifie les champs de l’APD, les modifications s’appliquent à toutes les instructions auxquelles ce descripteur est associé. Si ce n’est pas le comportement requis, l’application doit dissocier ce descripteur des autres instructions avant d’appeler SQLBindParameter.

Conceptuellement, SQLBindParameter effectue les étapes suivantes dans la séquence :

  1. Appelle SQLGetStmtAttr pour obtenir le handle APD.

  2. Appelle SQLGetDescField pour obtenir le champ SQL_DESC_COUNT DPD, et si la valeur de l’argument ColumnNumber dépasse la valeur de SQL_DESC_COUNT, appelle SQLSetDescField pour augmenter la valeur de SQL_DESC_COUNT à ColumnNumber.

  3. Appelle SQLSetDescField plusieurs fois pour affecter des valeurs aux champs suivants de l’APD :

    • Définit SQL_DESC_TYPE et SQL_DESC_CONCISE_TYPE à la valeur de ValueType, sauf que si ValueType est l’un des identificateurs concis d’un sous-type datetime ou d’intervalle, il définit SQL_DESC_TYPE sur SQL_DATETIME ou SQL_INTERVAL, respectivement, définit SQL_DESC_CONCISE_TYPE à l’identificateur concis et définit SQL_DESC_DATETIME_INTERVAL_CODE au sous-code datetime ou intervalle correspondant.

    • Définit le champ SQL_DESC_OCTET_LENGTH sur la valeur de BufferLength.

    • Définit le champ SQL_DESC_DATA_PTR sur la valeur de ParameterValue.

    • Définit le champ SQL_DESC_OCTET_LENGTH_PTR sur la valeur de StrLen_or_Ind.

    • Définit également le champ SQL_DESC_INDICATOR_PTR sur la valeur de StrLen_or_Ind.

    Le paramètre StrLen_or_Ind spécifie à la fois les informations d’indicateur et la longueur de la valeur du paramètre.

  4. Appelle SQLGetStmtAttr pour obtenir le handle IPD.

  5. Appelle SQLGetDescField pour obtenir le champ SQL_DESC_COUNT de l’IPD, et si la valeur de l’argument ColumnNumber dépasse la valeur de SQL_DESC_COUNT, appelle SQLSetDescField pour augmenter la valeur de SQL_DESC_COUNT à ColumnNumber.

  6. Appelle SQLSetDescField plusieurs fois pour affecter des valeurs aux champs suivants de l’IPD :

    • Définit SQL_DESC_TYPE et SQL_DESC_CONCISE_TYPE à la valeur de ParameterType, sauf que si ParameterType est l’un des identificateurs concis d’un sous-type datetime ou d’intervalle, il définit SQL_DESC_TYPE sur SQL_DATETIME ou SQL_INTERVAL, respectivement, définit SQL_DESC_CONCISE_TYPE à l’identificateur concis et définit SQL_DESC_DATETIME_INTERVAL_CODE au sous-code datetime ou intervalle correspondant.

    • Définit une ou plusieurs SQL_DESC_LENGTH, SQL_DESC_PRECISION et SQL_DESC_DATETIME_INTERVAL_PRECISION, le cas échéant pour ParameterType.

    • Définit SQL_DESC_SCALE la valeur DecimalDigits.

Si l’appel à SQLBindParameter échoue, le contenu des champs de descripteur qu’il aurait définis dans l’APD n’est pas défini et le champ SQL_DESC_COUNT de l’APD n’est pas modifié. En outre, les champs SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE et SQL_DESC_TYPE de l’enregistrement approprié dans l’IPD ne sont pas définis et le champ SQL_DESC_COUNT de l’IPD n’est pas modifié.

Conversion des appels vers et depuis SQLSetParam

Lorsqu’une application ODBC 1.0 appelle SQLSetParam dans un ODBC 3.pilote x , ODBC 3.x Driver Manager mappe l’appel comme indiqué dans le tableau suivant.

Appel par application ODBC 1.0 Appelez ODBC 3.pilote x
SQLSetParam( StatementHandle, ParameterNumber, ValueType, ParameterType, LengthPrecision, ParameterScale, ParameterValuePtr, StrLen_or_IndPtr) ; SQLBindParameter( StatementHandle, ParameterNumber, SQL_PARAM_INPUT_OUTPUT, ValueType, ParameterType, ColumnSize, DecimalDigits, ParameterValuePtr, SQL_SETPARAM_VALUE_MAX, StrLen_or_IndPtr) ;

Exemples

R. Utiliser la fonction SQLBindParameter

Dans l’exemple suivant, une application prépare une instruction SQL pour insérer des données dans la table ORDERS. Pour chaque paramètre de l’instruction, l’application appelle SQLBindParameter pour spécifier le type de données ODBC C et le type de données SQL du paramètre et lier une mémoire tampon à chaque paramètre. Pour chaque ligne de données, l’application affecte des valeurs de données à chaque paramètre et appelle SQLExecute pour exécuter l’instruction.

L’exemple suivant suppose que vous disposez d’une source de données ODBC sur votre ordinateur appelé Northwind associé à la base de données Northwind.

Pour plus d’exemples de code, consultez SQLBulkOperations Function, SQLProcedures Function, SQLPutData Function et SQLSetPos, Function.

// SQLBindParameter_Function.cpp  
// compile with: ODBC32.lib  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
#define EMPLOYEE_ID_LEN 10  
  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLSMALLINT sCustID;  
  
SQLCHAR szEmployeeID[EMPLOYEE_ID_LEN];  
SQL_DATE_STRUCT dsOrderDate;  
SQLINTEGER cbCustID = 0, cbOrderDate = 0, cbEmployeeID = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, EMPLOYEE_ID_LEN, 0, szEmployeeID, 0, &cbEmployeeID);  
   retcode = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_INTEGER, 0, 0, &sCustID, 0, &cbCustID);  
   retcode = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TIMESTAMP, sizeof(dsOrderDate), 0, &dsOrderDate, 0, &cbOrderDate);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"INSERT INTO Orders(CustomerID, EmployeeID, OrderDate) VALUES (?, ?, ?)", SQL_NTS);  
  
   strcpy_s((char*)szEmployeeID, _countof(szEmployeeID), "BERGS");  
   sCustID = 5;  
   dsOrderDate.year = 2006;  
   dsOrderDate.month = 3;  
   dsOrderDate.day = 17;  
  
   retcode = SQLExecute(hstmt);  
}

B. Exécuter une procédure stockée à l’aide d’un paramètre nommé

Dans l’exemple suivant, une application exécute une procédure stockée SQL Server à l’aide d’un paramètre nommé.

// SQLBindParameter_Function_2.cpp  
// compile with: ODBC32.lib  
// sample assumes the following stored procedure:  
// use northwind  
// DROP PROCEDURE SQLBindParameter  
// GO  
//   
// CREATE PROCEDURE SQLBindParameter @quote int  
// AS  
// delete from orders where OrderID >= @quote  
// GO  
#include <windows.h>  
#include <sqltypes.h>  
#include <sqlext.h>  
  
SQLHDESC hIpd = NULL;  
SQLHENV henv = NULL;  
SQLHDBC hdbc = NULL;  
SQLRETURN retcode;  
SQLHSTMT hstmt = NULL;  
SQLCHAR szQuote[50] = "100084";  
SQLINTEGER cbValue = SQL_NTS;  
  
int main() {  
   retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);  
   retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);   
  
   retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);   
   retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);  
  
   retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);  
   retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);  
  
   retcode = SQLPrepare(hstmt, (SQLCHAR*)"{call SQLBindParameter(?)}", SQL_NTS);  
   retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 0, szQuote, 0, &cbValue);  
   retcode = SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);  
   retcode = SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);  
  
   retcode = SQLExecute(hstmt);  
}
Pour plus d’informations sur Consultez
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
Libération des mémoires tampons de paramètres sur l’instruction SQLFreeStmt, fonction
Renvoi du nombre de paramètres d’instruction SQLNumParams, fonction
Retour du paramètre suivant pour lequel envoyer des données SQLParamData, fonction
Spécification de plusieurs valeurs de paramètre SQLParamOptions, 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