SQLDescribeParam

  • [アーティクル]

適用対象:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)

SQL ステートメントのパラメーターを記述するために、SQL Server Native Client ODBC ドライバーは、準備された ODBC ステートメント ハンドルで SQLDescribeParam が呼び出されたときに Transact-SQL Standard Edition LECT ステートメントをビルドして実行します。 この結果セットのメタデータにより、準備されたステートメント内のパラメーターの特性が決まります。 SQLDescribeParam は、SQLExecute または SQLExecDirect が返す可能性があるエラー コードを返すことができます。

SQL Server 2012 (11.x) 以降のデータベース エンジンの機能強化により、SQLDescribeParam は予想される結果のより正確な説明を取得できます。 これらのより正確な結果は、以前のバージョンの SQL Server で SQLDescribeParam によって返される値とは異なる場合があります。 詳細については、「メタデータの検出」を参照してください。

また、SQL Server 2012 (11.x) の新機能である ParameterSizePtr は、ODBC 仕様で定義されている対応するパラメーター マーカーの列または式のサイズの定義に合わせた値を文字で返すようになりました。 以前のバージョンの SQL Server Native Client では、ParameterSizePtr は、型のSQL_DESC_OCTET_LENGTHの対応する値、または型の SQLBindParameter に指定された無関係な列サイズ値であり、その値は無視する必要があります (SQL_INTEGERなど)。

ドライバーは、次の状況で SQLDescribeParam の呼び出しをサポートしていません。

  • FROM 句を含む Transact-SQL UPDATE または DELETE ステートメントの SQLExecDirect の後。

  • HAVING 句にパラメーターを含む ODBC または Transact-SQL ステートメントの場合、または 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);

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

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

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

Note

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

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

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

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

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

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

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

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

Attribute DataTypePtr ParameterSizePtr DecimalDigitsPtr
datetime SQL_TYPE_TIMESTAMP 23 3
smalldatetime SQL_TYPE_TIMESTAMP 16 0
日付 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)」を参照してください。

参照

SQLDescribeParam 関数
ODBC API 実装の詳細