SQLDescribeParam
Pour décrire les paramètres d'une instruction SQL, le pilote ODBC de SQL Server Native Client génère et exécute une instruction Transact-SQL SELECT lorsque SQLDescribeParam est appelé sur un handle d'instruction ODBC préparé. Les métadonnées du jeu de résultats déterminent les caractéristiques des paramètres dans l'instruction préparée. SQLDescribeParam peut retourner tout code d'erreur que SQLExecute ou SQLExecDirect peut retourner.
Les améliorations apportées au moteur de base de données introduit dans SQL Server 2012 permettent à SQLDescribeParam d'obtenir des descriptions plus exactes des résultats attendus. Ces résultats plus précis peuvent différer des valeurs retournées par SQLDescribeParamdans les versions précédentes de SQL Server. Pour plus d'informations, consultez Découverte des métadonnées.
Autre nouveauté de SQL Server 2012, ParameterSizePtr retourne maintenant une valeur qui s'aligne avec la définition de la taille, en caractères, de la colonne ou de l'expression du marqueur de paramètre correspondant, comme défini dans la spécification ODBC Dans les versions précédentes de SQL Server Native Client, ParameterSizePtr pouvait être la valeur correspondante de SQL_DESC_OCTET_LENGTH pour le type, ou une valeur de taille de colonne peu pertinente, fournie à SQLBindParameter pour un type, dont la valeur devait être ignorée (SQL_INTEGER, par exemple).
Le pilote ne prend pas en charge l'appel à SQLDescribeParam dans les situations suivantes :
après SQLExecDirect pour toute instruction Transact-SQL UPDATE ou DELETE contenant la clause FROM ;
pour toute instruction ODBC ou Transact-SQL contenant un paramètre dans une clause HAVING, ou en comparaison au résultat d'une fonction SUM ;
pour toute instruction ODBC ou Transact-SQL qui dépend d'une sous-requête contenant des paramètres ;
pour les instructions SQL ODBC contenant des marqueurs de paramètre dans les deux expressions d'un prédicat de comparaison, like ou quantifié ;
pour les requêtes dans lesquelles l'un des paramètres est un paramètre d'une fonction ;
en présence de commentaires (/* */) dans la commande Transact-SQL ;
Lors du traitement d'un lot d'instructions Transact-SQL, le pilote ne prend pas non plus en charge l'appel à SQLDescribeParam pour les marqueurs de paramètre dans les instructions après la première instruction dans le lot.
Lorsque vous décrivez les paramètres de procédures stockées préparées, SQLDescribeParam utilise la procédure stockée système sp_sproc_columns pour récupérer les caractéristiques des paramètres. sp_sproc_columns peut signaler des données pour les procédures stockées dans la base de données utilisateur active. La préparation d'un nom de procédure stockée complet permet l'exécution de SQLDescribeParam dans différentes bases de données. Par exemple, la procédure stockée système sp_who peut être préparée et exécutée dans n'importe quelle base de données comme suit :
SQLPrepare(hstmt, "{call sp_who(?)}", SQL_NTS);
Le fait d'exécuter SQLDescribeParam après une préparation réussie retourne un ensemble de lignes vide en cas de connexion à une base de données autre que master. Le même appel, préparé comme suit, entraîne la réussite de SQLDescribeParam indépendamment de la base de données utilisateur active :
SQLPrepare(hstmt, "{call master..sp_who(?)}", SQL_NTS);
Pour les types de données de valeur élevée, la valeur retournée dans DataTypePtr est SQL_VARCHAR, SQL_VARBINARY ou SQL_NVARCHAR. Pour indiquer que la taille du paramètre de type de données de valeur élevée est « illimitée », le pilote ODBC de SQL Server Native Client attribue la valeur 0 à ParameterSizePtr. Les valeurs de taille réelles sont retournées pour les paramètres varchar standard.
[!REMARQUE]
Si le paramètre a déjà été lié à une taille maximale pour les paramètres SQL_VARCHAR, SQL_VARBINARY ou SQL_WVARCHAR, la taille liée du paramètre est retournée, et non « illimitée ».
Pour lier un paramètre d'entrée de taille « illimitée », des données en cours d'exécution doivent être utilisées. Il est impossible de lier un paramètre de sortie de taille « illimitée » (contrairement à SQLGetData pour les jeux de résultats, aucune méthode ne permet de diffuser en continu des données à partir d'un paramètre de sortie).
Pour les paramètres de sortie, une mémoire tampon doit être liée et si la valeur est trop grande, la mémoire tampon est remplie et un message SQL_SUCCESS_WITH_INFO est retourné avec l'avertissement « Troncation à droite de la chaîne de données ». Les données tronquées sont alors ignorées.
SQLDescribeParam et paramètres table
Une application peut récupérer des informations de paramètre table pour une instruction préparée avec SQLDescribeParam. Pour plus d'informations, consultez Métadonnées de paramètre table pour les instructions préparées.
Pour plus d'informations générales sur les paramètres table, consultez Paramètres table (ODBC).
Prise en charge de SQLDescribeParam pour les fonctionnalités de date et heure améliorées
Les valeurs retournées pour les types date/heure sont les suivantes :
DataTypePtr |
ParameterSizePtr |
DecimalDigitsPtr |
|
|---|---|---|---|
datetime |
SQL_TYPE_TIMESTAMP |
23 |
3 |
smalldatetime |
SQL_TYPE_TIMESTAMP |
16 |
0 |
date |
SQL_TYPE_DATE |
10 |
0 |
time |
SQL_SS_TIME2 |
8, 10..16 |
0..7 |
datetime2 |
SQL_TYPE_TIMESTAMP |
19, 21..27 |
0..7 |
datetimeoffset |
SQL_SS_TIMESTAMPOFFSET |
26, 28..34 |
0..7 |
Pour plus d'informations, consultez Améliorations de la date et de l'heure (ODBC).
Prise en charge SQLDescribeParam pour les types CLR volumineux définis par l'utilisateur
SQLDescribeParam prend en charge les types CLR volumineux définis par l'utilisateur. Pour plus d'informations, consultez Types CLR volumineux définis par l'utilisateur (ODBC).
Voir aussi
Concepts
Détails d'implémentation d'une API ODBC