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

適用範圍: 是SQL Server (所有支援的版本) 是Azure SQL Database 是Azure SQL 受控執行個體 是Azure Synapse Analytics 是平行處理資料倉儲

本主題討論 SQL Server Native Client 中 ODBC 的變更,以支援大型 Common Language Runtime (CLR) 使用者定義型別 (UDT)。

如需顯示 ODBC 支援大型 CLR Udt 的範例,請參閱 大型 udt 的支援

如需 SQL Server Native Client 中大型 clr udt 支援的詳細資訊,請參閱大型 clr User-Defined 類型

資料格式

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

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 * (不帶正負號的 char *) 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 參數,必須一律透過 SQLSetDescField 設定 SQL_CA_SS_UDT_TYPE_NAME。 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 支援

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

UDT 的 SQL_VARIANT 支援

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 傳回的值如同本主題稍早的「SQLColumns 和 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 資料類型 類型 子類型 長度 精確度 調整
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 傳回的值如同本主題稍早的「SQLColumns 和 SQLProcedureColumns 傳回的資料行中繼資料 (目錄中繼資料)」一節所述。

SQLProcedureColumns

針對 UDT 傳回的值如同本主題稍早的「SQLColumns 和 SQLProcedureColumns 傳回的資料行中繼資料 (目錄中繼資料)」一節所述。

SQLPutData

UDT 參數值會從 C 轉換成 SQL 的資料類型,如本主題稍早的「系結和轉換」一節中所述。

SQLSetDescField

有提供新類型的描述項欄位在本主題稍早的「參數的描述項欄位」和「結果的描述項欄位」章節中有加以描述。

SQLSetDescRec

UDT 允許的值如下所示:

SQL 資料類型 類型 子類型 長度 精確度 調整
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 傳回的值如同本主題稍早的「SQLColumns 和 SQLProcedureColumns 傳回的資料行中繼資料 (目錄中繼資料)」一節所述。

另請參閱

大型 CLR 使用者定義型別