大型 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 和更新版本

不建議使用 SQL Server Native Client (SQLNCLI 或 SQLNCLI11) 和舊版 Microsoft OLE DB Provider for SQL Server (SQLOLEDB) 開發新的應用程式。

針對新專案，請使用下列其中一個驅動程式：

• Microsoft ODBC Driver for SQL Server
• Microsoft OLE DB Driver (MSOLEDBSQL) for SQL Server

針對 SQL Server 資料庫引擎 (2012 到 2019 版) 的隨附元件 SQLNCLI，請參閱支援生命週期例外狀況。

本主題討論 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	2n	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 使用者定義型別