大型 CLR 使用者定義型別 (ODBC)

  • 發行項

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

重要

SQL Server Native Client (通常縮寫為 SNAC) 已從 SQL Server 2022 (16.x) 和 SQL Server Management Studio 19 (SSMS) 中移除。 不建議使用 SQL Server Native Client (SQLNCLI 或 SQLNCLI11) 和舊版 Microsoft OLE DB Provider for SQL Server (SQLOLEDB) 開發新的應用程式。 往後請改用新的 Microsoft OLE DB Driver (MSOLEDBSQL) for SQL Server 或最新的 Microsoft ODBC Driver for SQL Server。 如需 SQL Server 資料庫引擎元件隨附的 SQLNCLI（版本 2012 到 2019），請參閱此 支援生命週期例外狀況 。

本主題討論 SQL Server Native Client 中 ODBC 的變更，以支援大型通用語言執行平臺 （CLR） 使用者定義型別 （UDT）。

如需顯示大型 CLR UDT 之 ODBC 支援的範例，請參閱 支援大型 UDT 。

如需 SQL Server Native Client 中大型 CLR UDT 支援的詳細資訊，請參閱 大型 CLR 使用者定義型別 。

資料格式

SQL Server Native Client 會使用 SQL_SS_LENGTH_UNLIMITED 來表示大型物件 （LOB） 類型的資料行大小大於 8，000 個位元組。 從 SQL Server 2008 開始，當 CLR UDT 的大小大於 8，000 個位元組時，會使用相同的值。

UDT 值會表示為位元組陣列。 支援與十六進位字串之間的來回轉換。 常值會表示為具有 "0x" 前置詞的十六進位字串。

下表顯示參數和結果集中的資料類型對應：

SQL Server 資料類型 SQL 資料類型 值
CLR UDT SQL_SS_UDT -151 （sqlncli.h）

下表討論對應的結構和 ODBC C 類型。 基本上，CLR UDT 是具有 其他中繼資料的 Varbinary 類型。

SQL 資料類型 記憶體配置 C 資料類型 值 （sqlext.h）
SQL_SS_UDT SQLCHAR *（不帶正負號的字元 *） SQL_C_BINARY SQL_BINARY (-2)

參數的描述項欄位

IPD 欄位中傳回的資訊如下所示：

描述項欄位 SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT

(長度大於 8,000 個位元組)
SQL_DESC_CASE_SENSITIVE SQL_FALSE SQL_FALSE
SQL_DESC_CONCISE_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DESC_DATETIME_INTERVAL_CODE 0 0
SQL_DESC_DATETIME_INTERVAL_PRECISION n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_FIXED_PREC_SCALE SQL_FALSE SQL_FALSE
SQL_DESC_LENGTH n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_LOCAL_TYPE_NAME 「udt」 「udt」
SQL_DESC_OCTET_LENGTH n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_PRECISION n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_SCALE 0 0
SQL_DESC_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DESC_TYPE_NAME 「udt」 「udt」
SQL_DESC_UNSIGNED SQL_TRUE SQL_TRUE
SQL_CA_SS_UDT_CATALOG_NAME 包含 UDT 的目錄名稱。 包含 UDT 的目錄名稱。
SQL_CA_SS_UDT_SCHEMA_NAME 包含 UDT 的架構名稱。 架構的名稱，包含 UDT。
SQL_CA_SS_UDT_TYPE_NAME UDT 的名稱。 UDT 的名稱。
SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME UDT 的完整名稱。 UDT 的完整名稱。

針對 UDT 參數，SQL_CA_SS_UDT_TYPE_NAME一律必須透過 SQLSetDescField 設定。 SQL_CA_SS_UDT_CATALOG_NAME和SQL_CA_SS_UDT_SCHEMA_NAME是選擇性的。

如果在與資料表不同的架構的相同資料庫中定義 UDT，則必須設定SQL_CA_SS_UDT_SCHEMA_NAME。

如果 UDT 定義于與資料表不同的資料庫中，則必須設定SQL_CA_SS_UDT_CATALOG_NAME和SQL_CA_SS_UDT_SCHEMA_NAME。

如果SQL_CA_SS_UDT_TYPE_NAME、SQL_CA_SS_UDT_CATALOG_NAME或SQL_CA_SS_UDT_SCHEMA_NAME設定中有任何錯誤或遺漏，則會使用 SQLSTATE HY000 和伺服器特定的郵件內文產生診斷記錄。

結果的描述項欄位

IRD 欄位中傳回的資訊如下所示：

描述項欄位 SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT

(長度大於 8,000 個位元組)
SQL_DESC_AUTO_UNIQUE_VALUE SQL_FALSE SQL_FALSE
SQL_DESC_CASE_SENSITIVE SQL_FALSE SQL_FALSE
SQL_DESC_CONCISE_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DESC_DATETIME_INTERVAL_CODE 0 0
SQL_DESC_DATETIME_INTERVAL_PRECISION n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_DISPLAY_SIZE 2 n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_FIXED_PREC_SCALE SQL_FALSE SQL_FALSE
SQL_DESC_LENGTH n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_LITERAL_PREFIX 「0x」 「0x」
SQL_DESC_LITERAL_SUFFIX "" ""
SQL_DESC_LOCAL_TYPE_NAME 「udt」 「udt」
SQL_DESC_OCTET_LENGTH n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_PRECISION n SQL_SS_LENGTH_UNLIMITED （0）
SQL_DESC_SCALE 0 0
SQL_DESC_SEARCHABLE SQL_PRED_NONE SQL_PRED_NONE
SQL_DESC_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DESC_TYPE_NAME 「udt」 「udt」
SQL_DESC_UNSIGNED SQL_TRUE SQL_TRUE
SQL_CA_SS_UDT_CATALOG_NAME 包含 UDT 的目錄名稱。 包含 UDT 的目錄名稱。
SQL_CA_SS_UDT_SCHEMA_NAME 包含 UDT 的架構名稱。 包含 UDT 的架構名稱。
SQL_CA_SS_UDT_TYPE_NAME UDT 的名稱。 UDT 的名稱。
SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME UDT 的完整名稱。 UDT 的完整名稱。

SQLColumns 和 SQLProcedureColumns 傳回的資料行中繼資料（目錄中繼資料）

UDT 會傳回下列資料行值：

資料行名稱 SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT

(長度大於 8,000 個位元組)
DATA_TYPE SQL_SS_UDT SQL_SS_UDT
TYPE_NAME UDT 的名稱。 UDT 的名稱。
COLUMN_SIZE n SQL_SS_LENGTH_UNLIMITED （0）
BUFFER_LENGTH n SQL_SS_LENGTH_UNLIMITED （0）
DECIMAL_DIGITS NULL NULL
SQL_DATA_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DATETIME_SUB NULL NULL
CHAR_OCTET_LENGTH n SQL_SS_LENGTH_UNLIMITED （0）
SS_UDT_CATALOG_NAME 包含 UDT 的目錄名稱。 包含 UDT 的目錄名稱。
SS_UDT_SCHEMA_NAME 包含 UDT 的架構名稱。 包含 UDT 的架構名稱。
SS_UDT_ASSEMBLY_TYPE_NAME UDT 的完整名稱。 UDT 的完整名稱。

最後三個數據行是驅動程式特定的資料行。 它們會在任何 ODBC 定義的資料行之後加入，但在 SQLColumns 或 SQLProcedureColumns 結果集的任何現有驅動程式特定資料行之前。

SQLGetTypeInfo 不會針對個別 UDT 或泛型型別 「udt」 傳回任何資料列。

繫結和轉換

從 SQL 到 C 資料類型的支援轉換如下所示：

從中轉換至： SQL_SS_UDT
SQL_C_WCHAR 支援*
SQL_C_BINARY 支援
SQL_C_CHAR 支援*

* 二進位資料會轉換成十六進位字串。

從 C 到 SQL 資料類型的支援轉換如下所示：

從中轉換至： SQL_SS_UDT
SQL_C_WCHAR 支援*
SQL_C_BINARY 支援
SQL_C_CHAR 支援*

* 發生二進位資料轉換的十六進位字串。

SQL_VARIANT UDT 的支援

SQL_VARIANT資料行不支援 UDT。

UDT 的 BCP 支援

UDT 值只能匯入和匯出為字元或二進位值。

UDT 的下層用戶端行為

UDT 受限於與下層用戶端對應的類型，如下所示：

伺服器版本 SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT

(長度大於 8,000 個位元組)
SQL Server 2005 UDT varbinary(max)
SQL Server 2008 及更新版本 UDT UDT

支援大型 CLR UDT 的 ODBC 函式

本節討論 SQL Server Native Client ODBC 函式的變更，以支援大型 CLR UDT。

SQLBindCol

本主題稍早的一節所述，UDT 結果資料行值會從 SQL 轉換成 C 資料類型。

SQLBindParameter

UDT 所需的值如下所示：

SQL 資料類型 Parametertype ColumnSizePtr DecimalDigitsPtr
SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT n 0
SQL_SS_UDT

(長度大於 8,000 個位元組)		 SQL_SS_UDT SQL_SS_LENGTH_UNLIMITED （0） 0

SQLColAttribute

UDT 傳回的值如本主題稍早的一節所述。

SQLColumns

UDT 傳回的值如本主題稍早的一節和 SQLProcedureColumns（目錄中繼資料）一節所述。

SQLDescribeCol

UDT 傳回的值如下所示：

SQL 資料類型 DataTypePtr ColumnSizePtr DecimalDigitsPtr
SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT n 0
SQL_SS_UDT

(長度大於 8,000 個位元組)		 SQL_SS_UDT SQL_SS_LENGTH_UNLIMITED （0） 0

SQLDescribeParam

UDT 傳回的值如下所示：

SQL 資料類型 DataTypePtr ColumnSizePtr DecimalDigitsPtr
SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT n 0
SQL_SS_UDT

(長度大於 8,000 個位元組)		 SQL_SS_UDT SQL_SS_LENGTH_UNLIMITED （0） 0

SQLFetch

本主題稍早的一節所述，UDT 結果資料行值會從 SQL 轉換成 C 資料類型。

SQLFetchScroll

本主題稍早的一節所述，UDT 結果資料行值會從 SQL 轉換成 C 資料類型。

SQLGetData

本主題稍早的一節所述，UDT 結果資料行值會從 SQL 轉換成 C 資料類型。

SQLGetDescField

本主題稍早的和一節會說明新類型的描述項欄位。

SQLGetDescRec

UDT 傳回的值如下所示：

SQL 資料類型 類型 子類型 長度 Precision 調整
SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT 0 n n 0
SQL_SS_UDT

(長度大於 8,000 個位元組)		 SQL_SS_UDT 0 SQL_SS_LENGTH_UNLIMITED （0） SQL_SS_LENGTH_UNLIMITED （0） 0

SQLGetTypeInfo

UDT 傳回的值如本主題稍早的一節中所述。

SQLProcedureColumns

UDT 傳回的值如本主題稍早的一節中所述。

SQLPutData

本主題稍早的一節中所述，UDT 參數值會從 C 轉換成 SQL 資料類型。

SQLSetDescField

本主題稍早的和一節會說明新類型可用的描述元欄位。

SQLSetDescRec

UDT 允許的值如下所示：

SQL 資料類型 類型 子類型 長度 Precision 調整
SQL_SS_UDT

(長度小於或等於 8,000 個位元組)		 SQL_SS_UDT 0 n n 0
SQL_SS_UDT

(長度大於 8,000 個位元組)		 SQL_SS_UDT 0 SQL_SS_LENGTH_UNLIMITED （0） SQL_SS_LENGTH_UNLIMITED （0） 0

SQLSpecialColumns

本主題稍早的一節所述，針對資料行傳回的值DATA_TYPE、TYPE_NAME、COLUMN_SIZE、BUFFER_LENGTH和DECIMAL_DIGTS UDT。

另請參閱

大型 CLR 使用者定義型別