大型 CLR 使用者定義型別 (ODBC)
適用於： 
SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse Analytics Analytics 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) 進行新的應用開發。
針對新專案，請使用下列其中一個驅動程式：
針對 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 傳回的值如本主題稍早的
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
本主題稍早的