SQLDescribeParam

S’applique à :SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)

Pour décrire les paramètres d’une instruction SQL, le pilote ODBC 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 n’importe quel code d’erreur que SQLExecute ou SQLExecDirect peut retourner.

Les améliorations apportées au moteur de base de données à partir de SQL Server 2012 (11.x) permettent à SQLDescribeParam d’obtenir des descriptions plus précises des résultats attendus. Ces résultats plus précis peuvent différer des valeurs retournées par SQLDescribeParam dans les versions précédentes de SQL Server. Pour plus d’informations, consultez Découverte des métadonnées.

Nouveau dans SQL Server 2012 (11.x), ParameterSizePtr retourne désormais une valeur qui s’aligne sur la définition de la taille, en caractères, de la colonne ou de l’expression du marqueur de paramètre correspondant tel que défini dans la spécification ODBC. Dans les versions précédentes de SQL Server Native Client, ParameterSizePtr peut être la valeur correspondante de SQL_DESC_OCTET_LENGTH pour le type, ou une valeur de taille de colonne non pertinente fournie à SQLBindParameter pour un type, dont la valeur doit être ignorée (SQL_INTEGER, par exemple).

Le pilote ne prend pas en charge l’appel de SQLDescribeParam dans les situations suivantes :

• Après SQLExecDirect pour toutes les instructions 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 par rapport au résultat d’une fonction SUM.

• Pour toute instruction ODBC ou Transact-SQL en fonction 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 ;

• Lorsqu’il existe des commentaires (/* */) dans la commande Transact-SQL.

Lors du traitement d’un lot d’instructions Transact-SQL, le pilote ne prend pas également en charge l’appel de SQLDescribeParam pour les marqueurs de paramètres dans les instructions après la première instruction du lot.

Lors de la description des paramètres des 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 pouvez signaler des données pour les procédures stockées dans la base de données utilisateur actuelle. La préparation d’un nom de procédure stockée complète permet à SQLDescribeParam de s’exécuter entre les 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);  

Exécution de SQLDescribeParam après la préparation réussie retourne un jeu de lignes vide lorsqu’il est connecté à n’importe quelle base de données, mais master. Le même appel, préparé comme suit, entraîne la réussite de SQLDescribeParam, quelle que soit la base de données utilisateur actuelle :

SQLPrepare(hstmt, "{call master..sp_who(?)}", SQL_NTS);  

Pour les types de données à 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 grande valeur est « illimitée », le pilote ODBC SQL Server Native Client définit ParameterSizePtr sur 0. 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 n’est pas possible de lier un paramètre de sortie de taille « illimité » (il n’existe aucune méthode pour la diffusion en continu de données à partir d’un paramètre de sortie, comme SQLGetData pour les jeux de résultats).

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 sur les paramètres table en général, 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 :

Attribut	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 date et d’heure (ODBC).

Prise en charge SQLDescribeParam pour les types CLR volumineux définis par l'utilisateur

SQLDescribeParam prend en charge les types clR définis par l’utilisateur (UDT). Pour plus d’informations, consultez Les types CLR définis par l’utilisateur (ODBC) volumineux.

Voir aussi

SQLDescribeParam, fonction
Détails de l’implémentation d’API ODBC