大型 CLR 使用者定義型別 (ODBC)
本主題討論 SQL Server Native Client 中 ODBC 的變更，以支援大型 Common Language Runtime (CLR) 使用者定義型別 (UDT)。
如需示範 ODBC 對於大型 CLR UDT 之支援的範例，請參閱＜支援大型 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 個位元組時，將會針對 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 *(不帶正負號的字元 *) |
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 |
支援 * |
* 發生將十六進位字串轉換為二進位資料的轉換作業。
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 傳回的資料行中繼資料 (目錄中繼資料)」一節所述。