SQLDescribeParam
SQL Server Native Client ODBC ドライバーでは、SQL ステートメントのパラメーターの詳細を示すために、準備された ODBC ステートメント ハンドルで SQLDescribeParam が呼び出されると、Transact-SQL SELECT ステートメントが構築され、実行されます。 この結果セットのメタデータにより、準備されたステートメント内のパラメーターの特性が決まります。SQLDescribeParam によって、SQLExecute または SQLExecDirect から返されるエラー コードが返されます。
SQL Server 2012 以降のデータベース エンジンの機能強化により、期待される結果のより正確な記述を SQLDescribeParam で取得できるようになりました。 これらの結果はより正確ですが、以前のバージョンの SQL Server の SQLDescribeParam によって返される結果とは異なる可能性があります。 詳細については、「メタデータの検出」を参照してください。
SQL Server 2012 では、ParameterSizePtr の動作も変更されています。ODBC 仕様で定義されているように、今後は、対応するパラメーター マーカーの式または列のサイズ (文字数) の定義に沿って調整された値が返されます。 以前のバージョンの SQL Server Native Client では、ParameterSizePtr は、その型の SQL_DESC_OCTET_LENGTH の対応する値になるか、型の SQLBindParameter に渡された無関係な列サイズ値となる場合があり、そのような値は、無視する必要がありました (SQL_INTEGER など)。
次の場合、ドライバーで 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 型パラメーターでは実際のサイズ値が返されます。
.gif "注意") 注 |
|---|
パラメーターが 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)」を参照してください。