SQLDescribeParamSQLDescribeParam

適用対象: yesSQL Server yesAzure SQL Database yesAzure Synapse Analytics (SQL DW) yesParallel Data Warehouse APPLIES TO: yesSQL Server yesAzure SQL Database yesAzure Synapse Analytics (SQL DW) yesParallel Data Warehouse

SQL ステートメントのパラメーターを記述するために、SQL ServerSQL Server Native Client ODBC ドライバーは、準備された ODBC ステートメントハンドルで SQLDescribeParam が呼び出されたときに、Transact-SQLTransact-SQL SELECT ステートメントを構築して実行します。To describe the parameters of any SQL statement, the SQL ServerSQL Server Native Client ODBC driver builds and executes a Transact-SQLTransact-SQL SELECT statement when SQLDescribeParam is called on a prepared ODBC statement handle. この結果セットのメタデータにより、準備されたステートメント内のパラメーターの特性が決まります。The metadata of the result set determines the characteristics of the parameters in the prepared statement. SQLDescribeParam は、SQLExecute または SQLExecDirect が返す可能性のあるエラーコードを返すことができます。SQLDescribeParam can return any error code that SQLExecute or SQLExecDirect might return.

SQL Server 2012 (11.x)SQL Server 2012 (11.x) で始まるデータベースエンジンの機能強化により、SQLDescribeParam は予想される結果についてより正確な説明を取得できます。Improvements in the database engine starting with SQL Server 2012 (11.x)SQL Server 2012 (11.x) allow SQLDescribeParam to obtain more accurate descriptions of the expected results. これらのより正確な結果は、以前のバージョンの SQL ServerSQL Serverで SQLDescribeParam によって返される値とは異なる場合があります。These more accurate results may differ from the values returned by SQLDescribeParam in previous versions of SQL ServerSQL Server. 詳細については、「メタデータの検出」を参照してください。For more information, see Metadata Discovery.

また、SQL Server 2012 (11.x)SQL Server 2012 (11.x)の新しいParametersizeptrは、 ODBC 仕様で定義されている、対応するパラメーターマーカーの列または式のサイズの定義に合わせて値を返すようになりました。Also new in SQL Server 2012 (11.x)SQL Server 2012 (11.x), ParameterSizePtr now returns a value that aligns with the definition for the size, in characters, of the column or expression of the corresponding parameter marker as defined in the ODBC specification. 以前のバージョンの SQL ServerSQL Server Native Client では、 Parametersizeptrは、型のSQL_DESC_OCTET_LENGTHの対応する値、または型の SQLBindParameter に指定された関係のない列サイズの値になる可能性があります。この値は無視する必要があります (SQL_INTEGERなど)。In previous versions of SQL ServerSQL Server Native Client, ParameterSizePtr could be the corresponding value of SQL_DESC_OCTET_LENGTH for the type, or an irrelevant column size value that was supplied to SQLBindParameter for a type, the value of which should be ignored (SQL_INTEGER, for example).

ドライバーは、次の状況での SQLDescribeParam の呼び出しをサポートしていません。The driver does not support calling SQLDescribeParam in the following situations:

  • FROM 句を含む Transact-SQLTransact-SQL UPDATE ステートメントまたは DELETE ステートメントを SQLExecDirect した後。After SQLExecDirect for any Transact-SQLTransact-SQL UPDATE or DELETE statements containing the FROM clause.

  • ODBC ステートメントまたは Transact-SQLTransact-SQL ステートメントが HAVING 句にパラメーターを含んでいる場合、または SUM 関数の結果と比較される場合。For any ODBC or Transact-SQLTransact-SQL statement containing a parameter in a HAVING clause, or compared to the result of a SUM function.

  • ODBC ステートメントまたは Transact-SQLTransact-SQL ステートメントがパラメーターを含んでいるサブクエリに依存している場合。For any ODBC or Transact-SQLTransact-SQL statement depending on a subquery containing parameters.

  • ODBC SQL ステートメントが、比較の両方の式、LIKE、定量化された述語内にパラメーター マーカーを含んでいる場合。For ODBC SQL statements containing parameter markers in both expressions of a comparison, like, or quantified predicate.

  • クエリのいずれかのパラメーターが関数に対するパラメーターである場合。For any queries where one of the parameters is a parameter to a function.

  • コメント (/* */) が Transact-SQLTransact-SQL コマンドに含まれている場合。When there are comments (/* */) in the Transact-SQLTransact-SQL command.

Transact-SQLTransact-SQL ステートメントのバッチを処理する場合、ドライバーはバッチ内の最初のステートメントの後にあるステートメント内のパラメーターマーカーに対して SQLDescribeParam を呼び出すことをサポートしていません。When processing a batch of Transact-SQLTransact-SQL statements, the driver also does not support calling SQLDescribeParam for parameter markers in statements after the first statement in the batch.

SQLDescribeParam では、準備されたストアドプロシージャのパラメーターを記述するときに、システムストアドプロシージャsp_sproc_columnsを使用してパラメーターの特性を取得します。When describing the parameters of prepared stored procedures, SQLDescribeParam uses the system stored procedure sp_sproc_columns to retrieve parameter characteristics. sp_sproc_columns は、現在のユーザーデータベース内のストアドプロシージャのデータをレポートできます。sp_sproc_columns can report data for stored procedures within the current user database. 完全に修飾されたストアドプロシージャ名を準備すると、データベース間で SQLDescribeParam を実行できるようになります。Preparing a fully qualified stored procedure name allows SQLDescribeParam to execute across databases. たとえば、システムストアドプロシージャsp_whoを準備し、任意のデータベースで次のように実行できます。For example, the system stored procedure sp_who can be prepared and executed in any database as:

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

準備が正常に完了した後に SQLDescribeParam を実行すると、 masterデータベースに接続したときに空の行セットが返されます。Executing SQLDescribeParam after successful preparation returns an empty row set when connected to any database but master. 次のように準備された同じ呼び出しは、現在のユーザーデータベースに関係なく SQLDescribeParam を成功させます。The same call, prepared as follows, causes SQLDescribeParam to succeed regardless of the current user database:

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

大きな値のデータ型の場合、 DataTypePtrで返される値は SQL_VARCHAR、SQL_VARBINARY、または SQL_NVARCHAR です。For large value data types, the value returned in DataTypePtr is SQL_VARCHAR, SQL_VARBINARY, or SQL_NVARCHAR. 大きな値のデータ型パラメーターのサイズが "無制限" であることを示すために、SQL ServerSQL Server Native Client ODBC ドライバーはParametersizeptrを0に設定します。To indicate that the size of the large value data type parameter is "unlimited," the SQL ServerSQL Server Native Client ODBC driver sets ParameterSizePtr to 0. 実際のサイズ値は、標準のvarcharパラメーターに対して返されます。Actual size values are returned for standard varchar parameters.

注意

パラメーターが SQL_VARCHAR、SQL_VARBINARY、SQL_WVARCHAR のいずれかのパラメーターの最大サイズに既にバインドされている場合は、"無制限" ではなく、バインドされたパラメーターのサイズが返されます。If the parameter has already been bound with a maximum size for the SQL_VARCHAR, SQL_VARBINARY, or SQL_WVARCHAR parameters, the bound size of the parameter is returned, not "unlimited."

サイズが "無制限" の入力パラメーターをバインドするには、実行時データを使用する必要があります。To bind an "unlimited" size input parameter, data-at-execution must be used. "無制限" サイズの出力パラメーターをバインドすることはできません ( SQLGetDataが結果セットに対して行うように、出力パラメーターからデータをストリーミングする方法はありません)。It is not possible to bind an "unlimited" size output parameter (there is no method for streaming data from an output parameter, like SQLGetData does for result sets).

出力パラメーターの場合は、バッファーをバインドする必要があります。値が大きすぎる場合はバッファーがいっぱいになり、SQL_SUCCESS_WITH_INFO メッセージが "文字列データの右側が切り捨てられました。" という警告と共に返されます。For output parameters, a buffer must be bound and if the value is too large, the buffer is filled and a SQL_SUCCESS_WITH_INFO message and is returned along with the "string data; right truncation" warning. その後、切り捨てられたデータが破棄されます。The data that was truncated is then discarded.

SQLDescribeParam とテーブル値パラメーターSQLDescribeParam and Table-Valued Parameters

アプリケーションでは、SQLDescribeParam を使用して、準備されたステートメントのテーブル値パラメーター情報を取得できます。An application can retrieve table-valued parameter information for a prepared statement with SQLDescribeParam. 詳細については、「準備されたステートメントのテーブル値パラメーターのメタデータ」を参照してください。For more information, see Table-Valued Parameter Metadata for Prepared Statements.

一般的なテーブル値パラメーターの詳細については、「テーブル値パラメーター (の)ODBC」を参照してください。For more information about table-valued parameters in general, see Table-Valued Parameters (ODBC).

SQLDescribeParam による機能強化された日付と時刻のサポートSQLDescribeParam Support for Enhanced Date and Time Features

日付型または時刻型に対して返される値を次に示します。The values returned for date/time types are as follows:

DataTypePtrDataTypePtr ParameterSizePtrParameterSizePtr DecimalDigitsPtrDecimalDigitsPtr
DATETIMEdatetime SQL_TYPE_TIMESTAMPSQL_TYPE_TIMESTAMP 2323 33
smalldatetimesmalldatetime SQL_TYPE_TIMESTAMPSQL_TYPE_TIMESTAMP 1616 00
datedate SQL_TYPE_DATESQL_TYPE_DATE 1010 00
timetime SQL_SS_TIME2SQL_SS_TIME2 8、10..168, 10..16 0..70..7
datetime2datetime2 SQL_TYPE_TIMESTAMPSQL_TYPE_TIMESTAMP 19、21..2719, 21..27 0..70..7
datetimeoffsetdatetimeoffset SQL_SS_TIMESTAMPOFFSETSQL_SS_TIMESTAMPOFFSET 26、28..3426, 28..34 0..70..7

詳細については、「日付と(時刻)の機能強化 ODBC」を参照してください。For more information, see Date and Time Improvements (ODBC).

SQLDescribeParam による大きな CLR UDT のサポートSQLDescribeParam Support for Large CLR UDTs

SQLDescribeParamは、大きな CLR ユーザー定義型 (udt) をサポートしています。SQLDescribeParam supports large CLR user-defined types (UDTs). 詳細については、「 LARGE CLR ユーザー定義(型)ODBC」を参照してください。For more information, see Large CLR User-Defined Types (ODBC).

参照See Also

SQLDescribeParam 関数 SQLDescribeParam Function
ODBC API 実装の詳細ODBC API Implementation Details