SQLDescribeParam

  • 發行項

適用於：SQL ServerAzure SQL DatabaseAzure SQL 受控執行個體Azure Synapse AnalyticsAnalytics Platform System (PDW)

為了描述任何 SQL 語句的參數，SQL Server Native Client ODBC 驅動程式會在備妥的 ODBC 語句句柄上呼叫 SQLDescribeParam 時，建置並執行 Transact-SQL SELECT 語句。 結果集的元數據會決定備妥語句中參數的特性。 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 語句，在比較的兩個表達式中包含參數標記，例如或量化述詞。

  • 對於其中一個參數是函式的參數的任何查詢。

  • 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 參數會傳回實際大小值。

注意

如果參數已經系結SQL_VARCHAR、SQL_VARBINARY或SQL_WVARCHAR參數的大小上限，則會傳回參數的系結大小，而不是「無限制」。

若要系結「無限制」大小的輸入參數，必須使用執行中的數據。 無法係結「無限制」大小的輸出參數（沒有從輸出參數串流數據的方法，就像 SQLGetData 對結果集所做的一樣）。

針對輸出參數，緩衝區必須系結，如果值太大，則緩衝區已填入，並傳回SQL_SUCCESS_WITH_INFO訊息，並傳回 「string data;右截斷“警告。 然後會捨棄截斷的數據。

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）。

大型 CLR UDT 的 SQLDescribeParam 支援

SQLDescribeParam 支援大型 CLR 使用者定義型別 （UDT）。 如需詳細資訊，請參閱 大型CLR使用者定義型別 （ODBC）。

另請參閱

SQLDescribeParam 函式
ODBC API 實作詳細數據