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é. Le pilote utilise l'instruction SET FMTONLY lors de l'exécution de la requête. Les métadonnées du jeu de résultats déterminent les caractéristiques des paramètres dans l'instruction préparée.
Prenons par exemple l'instruction SQL ODBC suivante :
INSERT INTO Shippers (ShipperID, CompanyName, Phone) VALUES (?, ?, ?)
Lors d'un appel à SQLDescribeParam, cette instruction SQL ODBC force le pilote à exécuter les instructions Transact-SQL suivantes :
SET FMTONLY ON
SELECT ShipperID, CompanyName, Phone FROM Shippers
SET FMTONLY OFF
SQLDescribeParam peut, par conséquent, retourner tout code d'erreur pouvant être retourné par SQLExecute ou SQLExecDirect.
Par ailleurs, 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