SQLDescribeParam

SQL Server Native Client ODBC ドライバでは、SQL ステートメントのパラメータを説明するために、準備された ODBC ステートメント ハンドルで SQLDescribeParam が呼び出されると、Transact-SQL SELECT ステートメントが構築され、実行されます。ドライバでは、このクエリの実行時に SET FMTONLY ステートメントを使用します。この結果セットのメタデータにより、準備されたステートメント内のパラメータの特性が決まります。

例として、次の ODBC SQL ステートメントを使用します。

INSERT INTO Shippers (ShipperID, CompanyName, Phone) VALUES (?, ?, ?)

SQLDescribeParam を呼び出すと、この ODBC SQL ステートメントにより、ドライバで次の Transact-SQL ステートメントが実行されます。

SET FMTONLY ON
SELECT ShipperID, CompanyName, Phone FROM Shippers
SET FMTONLY OFF

この結果、SQLDescribeParam によって、SQLExecute または SQLExecDirect から返されるエラー コードが返されます。

また、次の場合、ドライバで SQLDescribeParam を呼び出すことはできません。

  • FROM 句が含まれている Transact-SQL UPDATE ステートメントや DELETE ステートメントに対して SQLExecDirect を呼び出した後。

  • ODBC ステートメントまたは Transact-SQL ステートメントが HAVING 句にパラメータを含んでいる場合、または SUM 関数の結果と比較される場合。

  • ODBC ステートメントまたは Transact-SQL ステートメントがパラメータを含んでいるサブクエリに依存している場合。

  • ODBC SQL ステートメントが、比較の両方の式、LIKE、定量化された述語内にパラメータ マーカーを含んでいる場合。

  • クエリのいずれかのパラメータが関数に対するパラメータである場合。

  • Transact-SQL コマンド内にコメント (/* */) がある場合。

Transact-SQL ステートメントのバッチを処理しているときは、バッチ内の最初のステートメントの後にあるステートメント内のパラメータ マーカーに対して SQLDescribeParam を呼び出すこともできません。

SQLDescribeParam では、準備されたストアド プロシージャのパラメータを説明するときに、システム ストアド プロシージャ sp_sproc_columns を使用してパラメータの特性を取得します。sp_sproc_columns では、現在のユーザー データベース内のストアド プロシージャのデータを報告できます。ストアド プロシージャの完全修飾名を準備すると、SQLDescribeParam を複数のデータベースに対して実行できるようになります。たとえば、システム ストアド プロシージャ sp_who は、次のように準備して任意のデータベースで実行できます。

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

master 以外の任意のデータベースに接続している場合、正しく準備を行った後に SQLDescribeParam を実行すると、空の行セットが返されます。また、同じ呼び出しを次のように準備して実行すると、現在のユーザー データベースとは無関係に SQLDescribeParam が成功します。

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

大きな値のデータ型の場合、DataTypePtr に返される値は、SQL_VARCHAR、SQL_VARBINARY、SQL_NVARCHAR のいずれかになります。大きな値のデータ型パラメータのサイズが "無制限" であることを示すために、SQL Server Native Client ODBC ドライバでは ParameterSizePtr が 0 に設定されます。標準の varchar 型パラメータでは実際のサイズ値が返されます。

注意注意

パラメータが SQL_VARCHAR、SQL_VARBINARY、SQL_WVARCHAR のいずれかのパラメータの最大サイズに既にバインドされている場合は、"無制限" ではなく、バインドされたパラメータのサイズが返されます。

サイズが "無制限" の入力パラメータをバインドするには、実行時データを使用する必要があります。また、サイズが "無制限" の出力パラメータをバインドすることはできません。これは、SQLGetData が結果セットに対して行うように、出力パラメータからデータをストリーミングするメソッドが存在しないためです。

出力パラメータの場合は、バッファをバインドする必要があります。値が大きすぎる場合はバッファがいっぱいになり、SQL_SUCCESS_WITH_INFO メッセージが "文字列データの右側が切り捨てられました。" という警告と共に返されます。その後、切り捨てられたデータが破棄されます。

SQLDescribeParam とテーブル値パラメータ

アプリケーションでは、SQLDescribeParam を呼び出すことで、準備されたステートメントのテーブル値パラメータの情報を取得できます。詳細については、「準備されたステートメント用のテーブル値パラメータのメタデータ」を参照してください。

テーブル値パラメータ全般の詳細については、「テーブル値パラメータ (ODBC)」を参照してください。

SQLDescribeParam による機能強化された日付と時刻のサポート

日付型または時刻型に対して返される値を次に示します。

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

詳細については、「日付/時刻の強化 (ODBC)」を参照してください。

SQLDescribeParam による大きな CLR UDT のサポート

SQLDescribeParam は、大きな CLR ユーザー定義型 (UDT) をサポートしています。詳細については、「大きな CLR ユーザー定義型 (ODBC)」を参照してください。

関連項目

概念

その他の技術情報