Liaison et transfert de données de paramètres table et de valeurs de colonnes
Les paramètres table, comme d'autres paramètres, doivent être liés avant d'être passés au serveur. L’application lie des paramètres table de la même façon qu’elle lie d’autres paramètres : à l’aide de SQLBindParameter ou d’appels équivalents à SQLSetDescField ou SQLSetDescRec. Le type de données serveur pour un paramètre table est SQL_SS_TABLE. Le type C peut être spécifié comme SQL_C_DEFAULT ou SQL_C_BINARY.
Dans SQL Server 2008 ou version ultérieure, seuls les paramètres table d’entrée sont pris en charge. Par conséquent, toute tentative de définition de SQL_DESC_PARAMETER_TYPE à une valeur autre que SQL_PARAM_INPUT retourne SQL_ERROR avec SQLSTATE = HY105 et le message « type de paramètre non valide ».
Des valeurs par défaut peuvent être assignées à des colonnes de paramètres table entières à l'aide de l'attribut SQL_CA_SS_COL_HAS_DEFAULT_VALUE. Toutefois, les valeurs par défaut des colonnes de paramètres table ne peuvent pas être attribuées à l’aide de SQL_DEFAULT_PARAM dans StrLen_or_IndPtr avec SQLBindParameter. Les paramètres table dans leur ensemble ne peuvent pas être définis sur une valeur par défaut à l’aide de SQL_DEFAULT_PARAM dans StrLen_or_IndPtr avec SQLBindParameter. Si ces règles ne sont pas suivies, SQLExecute ou SQLExecDirect retourne SQL_ERROR. Un enregistrement de diagnostic est généré avec SQLSTATE=07S01 et le message « Utilisation non valide du paramètre par défaut pour le paramètre <p> », où <p> est l’ordinal du TVP dans l’instruction de requête.
Après avoir lié le paramètre table, l'application doit lier chaque colonne de paramètre table. Pour ce faire, l’application appelle d’abord SQLSetStmtAttr pour définir SQL_SOPT_SS_PARAM_FOCUS sur l’ordinal d’un paramètre table. Ensuite, l’application lie les colonnes du paramètre table en appelant les routines suivantes : SQLBindParameter, SQLSetDescRec et SQLSetDescField. La définition de SQL_SOPT_SS_PARAM_FOCUS sur 0 restaure l’effet habituel de SQLBindParameter, SQLSetDescRec et SQLSetDescField dans le fonctionnement sur des paramètres de niveau supérieur standard.
Aucune donnée n'est réellement envoyée ou reçue pour le paramètre table lui-même, mais des données sont envoyées et reçues pour chacune de ses colonnes constituantes. Étant donné que le paramètre table est une pseudo colonne, les paramètres de SQLBindParameter sont utilisés pour faire référence à des attributs différents d’autres types de données, comme suit :
| Paramètre | Attribut associé pour les types de paramètres non table, y compris les colonnes | Attribut associé pour les paramètres table |
|---|---|---|
| InputOutputType | SQL_DESC_PARAMETER_TYPE dans IPD. Pour les colonnes de paramètre table, ce doit être identique au paramètre du paramètre table lui-même. |
SQL_DESC_PARAMETER_TYPE dans IPD. Ce doit être SQL_PARAM_INPUT. |
| ValueType | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE dans APD. | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE dans APD. Ce doit être SQL_C_DEFAULT ou SQL_C_BINARY. |
| ParameterType | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE dans IPD. | SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE dans IPD. Ce doit être SQL_SS_TABLE. |
| ColumnSize | SQL_DESC_LENGTH ou SQL_DESC_PRECISION dans IPD. Cela dépend de la valeur de ParameterType. |
SQL_DESC_ARRAY_SIZE Peut également être défini à l'aide de SQL_ATTR_PARAM_SET_SIZE lorsque le focus de paramètre est défini sur le paramètre table. Pour un paramètre table, il s'agit du nombre de lignes dans les mémoires tampons de colonnes de paramètres table. |
| DecimalDigits | SQL_DESC_PRECISION or SQL_DESC_SCALE dans IPD. | Inutilisé. Doit être 0. Si ce paramètre n’est pas 0, SQLBindParameter retourne SQL_ERROR, et un enregistrement de diagnostic est généré avec SQLSTATE= HY104 et le message « Précision ou échelle non valides ». |
| ParameterValuePtr | SQL_DESC_DATA_PTR dans APD. | SQL_CA_SS_TYPE_NAME. Ceci est facultatif pour les appels de procédure stockée et NULL peut être spécifié si ce n'est pas requis. Doit être spécifié pour les instructions SQL qui ne sont pas des appels de procédure. Ce paramètre sert également de valeur unique que l'application peut utiliser pour identifier ce paramètre table lorsque la liaison de ligne variable est utilisée. Pour plus d'informations, consultez la section « Liaison de ligne de paramètre table variable » plus loin dans cette rubrique. Lorsqu’un nom de type de paramètre table est spécifié sur un appel à SQLBindParameter, il doit être spécifié sous la forme d’une valeur Unicode, même dans les applications qui sont générées en tant qu’applications ANSI. La valeur utilisée pour le paramètre StrLen_or_IndPtr doit être SQL_NTS ou la longueur de chaîne du nom multipliée par sizeof(WCHAR). |
| BufferLength | SQL_DESC_OCTET_LENGTH dans APD. | Longueur du nom de type de paramètre table en octets. Cela peut être SQL_NTS si le nom de type se termine par une valeur Null ou 0 si le nom de type de paramètre table n'est pas requis. |
| StrLen_or_IndPtr | SQL_DESC_OCTET_LENGTH_PTR dans APD. | SQL_DESC_OCTET_LENGTH_PTR dans APD. Pour les paramètres table, il s'agit d'un nombre de lignes plutôt qu'une longueur de données. |
Deux modes de transfert de données sont pris en charge pour les paramètres table : la liaison de ligne fixe et la liaison de ligne variable.
Liaison de ligne de paramètre table fixe
Pour la liaison de ligne fixe, une application alloue des mémoires tampon (ou tableaux de mémoires tampon) suffisamment grandes pour toutes les valeurs de colonne d'entrée possibles. L'application effectue les actions suivantes :
Lie tous les paramètres à l’aide d’appels SQLBindParameter, SQLSetDescRec ou SQLSetDescField.
- Elle définit SQL_DESC_ARRAY_SIZE au nombre maximal de lignes qui peuvent être transférées pour chaque paramètre table. Cela peut être effectué dans l’appel SQLBindParameter.
Appelle SQLSetStmtAttr pour définir SQL_SOPT_SS_PARAM_FOCUS sur l’ordinal de chaque paramètre table.
Pour chaque paramètre table, lie des colonnes de paramètres table à l’aide d’appels SQLBindParameter, SQLSetDescRec ou SQLSetDescField.
Pour chaque colonne de paramètre table qui doit avoir des valeurs par défaut, appelle SQLSetDescField pour définir SQL_CA_SS_COL_HAS_DEFAULT_VALUE sur 1.
Appelle SQLSetStmtAttr pour définir SQL_SOPT_SS_PARAM_FOCUS sur 0. Cela doit être effectué avant d’appeler SQLExecute ou SQLExecDirect. Autrement, SQL_ERROR est retourné et un enregistrement de diagnostic est généré avec SQLSTATE=HY024 et le message « Valeur d'attribut non valide, SQL_SOPT_SS_PARAM_FOCUS (doit être égale à zéro au moment de l'exécution) ».
Définit StrLen_or_IndPtr ou SQL_DESC_OCTET_LENGTH_PTR pour SQL_DEFAULT_PARAM pour un paramètre table sans ligne, ou le nombre de lignes à transférer lors de l’appel suivant de SQLExecute ou SQLExecDirect si le paramètre table contient des lignes. StrLen_or_IndPtr ou SQL_DESC_OCTET_LENGTH_PTR ne peuvent pas être définis sur SQL_NULL_DATA pour un paramètre table, car les paramètres table ne sont pas nullables (bien que les colonnes de constituant des paramètres table puissent être nullables). Si cette valeur est définie sur une valeur non valide, SQLExecute ou SQLExecDirect retourne SQL_ERROR, et un enregistrement de diagnostic est généré avec SQLSTATE=HY090 et le message « Chaîne ou longueur de mémoire tampon non valide pour le paramètre <p> », où p est le numéro de paramètre.
Appelle SQLExecute ou SQLExecDirect.
Les valeurs de colonne de paramètres table d’entrée peuvent être transmises en morceaux si StrLen_or_IndPtr est défini sur SQL_LEN_DATA_AT_EXEC(length) ou SQL_DATA_AT_EXEC pour la colonne. Cela s'apparente au passage de valeurs en fragments lorsque des tableaux de paramètres sont utilisés. Comme pour tous les paramètres de données à l’exécution, SQLParamData n’indique pas la ligne du tableau pour laquelle le pilote demande des données ; l’application doit s’en occuper. L'application ne peut pas faire d'hypothèses concernant l'ordre dans lequel le pilote demandera des valeurs.
Liaison de ligne de paramètre table variable
Pour la liaison de ligne variable, les lignes sont transférées par lots au moment de l'exécution et l'application passe des lignes au pilote sur demande. Cela s'apparente à la fonctionnalité « data-at-execution » pour les valeurs de paramètre individuelles. Pour la liaison de ligne variable, l'application effectue les opérations suivantes :
Elle lie les paramètres et les colonnes de paramètre table comme décrit aux étapes 1 à 3 de la section précédente, « Liaison de ligne de paramètre table fixe ».
Définit StrLen_or_IndPtr ou SQL_DESC_OCTET_LENGTH_PTR pour tous les paramètres table qui doivent être passés au moment de l’exécution à SQL_DATA_AT_EXEC. Si ni l'un ni l'autre n'est défini, le paramètre est traité comme décrit dans la section précédente.
Appelle SQLExecute ou SQLExecDirect. Cela retourne SQL_NEED_DATA s'il y a des paramètres SQL_PARAM_INPUT ou SQL_PARAM_INPUT_OUTPUT à gérer comme paramètres « data-at-execution ». Dans ce cas, l'application effectue les opérations suivantes :
- Appelle SQLParamData. Cette opération retourne la valeur ParameterValuePtr pour un paramètre data-at-execution et un code de retour de SQL_NEED_DATA. Lorsque toutes les données de paramètre ont été transmises au pilote, SQLParamData retourne SQL_SUCCESS, SQL_SUCCESS_WITH_INFO ou SQL_ERROR. Pour les paramètres de données à l’exécution, ParameterValuePtr, qui est identique au champ de descripteur SQL_DESC_DATA_PTR, peut être considéré comme un jeton permettant d’identifier de manière unique un paramètre pour lequel une valeur est requise. Ce « jeton » est passé de l'application au pilote au moment de la liaison, puis repassé à l'application au moment de l'exécution.
Pour envoyer des données de ligne de paramètre table pour les paramètres table null, si le paramètre table n’a pas de lignes, une application appelle SQLPutData avec StrLen_or_Ind défini sur SQL_DEFAULT_PARAM.
Pour les paramètres table non nuls, une application :
Définit Str_Len_or_Ind pour toutes les colonnes de paramètres table sur les valeurs appropriées, et remplit les mémoires tampons de données pour les colonnes de paramètres table qui ne doivent pas être des paramètres de données lors de l’exécution. Vous pouvez utiliser la fonctionnalité « data-at-execution » pour les colonnes de paramètres table d'une manière semblable à celle employée lorsque des paramètres ordinaires sont passés au pilote par fragments.
Appelle SQLPutData avec Str_Len_or_Ind défini sur le nombre de lignes à envoyer au serveur. Toute valeur en dehors de la plage 0 à SQL_DESC_ARRAY_SIZE ou SQL_DEFAULT_PARAM est une erreur et retourne SQLSTATE HY090 avec le message « Longueur de chaîne ou de mémoire tampon non valide ». 0 indique que toutes les lignes ont été envoyées et qu'il n'y a plus de données pour un paramètre table (comme noté dans le deuxième élément de puce dans cette liste). SQL_DEFAULT_PARAM peut être utilisé uniquement la première fois que le pilote demande des données pour un paramètre table (comme décrit dans le premier élément de puce dans cette liste).
Lorsque toutes les lignes ont été envoyées, appelle SQLPutData pour le paramètre table avec une valeur Str_Len_or_Ind de 0, puis passe à l’étape 3a ci-dessus.
Appelle à nouveau SQLParamData. S’il existe des paramètres de données à l’exécution parmi les colonnes de paramètres table, ceux-ci sont identifiés par la valeur ValuePtrPtr retournée par SQLParamData. Lorsque toutes les valeurs de colonne sont disponibles, SQLParamData retourne à nouveau la valeur ParameterValuePtr pour le paramètre table, et l’application recommence.