大型 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 中为支持大型公共语言运行时 (CLR) 用户定义类型 (UDT) 而对 ODBC 进行的更改。
有关显示对大型 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 开始，在其大小大于 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 （长度大于 8000 个字节） |
|---|---|---|
| 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 （长度大于 8000 个字节） |
|---|---|---|
| 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 （长度大于 8000 个字节） |
|---|---|---|
| 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 的结果集的任何现有特定于驱动程序的列之前。
对于单个 UDT 或泛型类型“udt”，SQLGetTypeInfo 不会返回任何行。
绑定和转换
支持的从 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 （长度大于 8000 个字节） |
|---|---|---|
| SQL Server 2005 | UDT | varbinary(max) |
| SQL Server 2008 和更高版本 | UDT | UDT |
支持大型 CLR UDT 的 ODBC 函数
本节讨论为支持大型 CLR UDT 而对 SQL Server Native Client ODBC 函数进行的更改。
SQLBindCol
如本主题前面的“绑定和转换”部分中所述，UDT 结果列值从 SQL 转换为 C 数据类型。
SQLBindParameter
UDT 所需的值如下所示：
| SQL 数据类型 | Parametertype | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT （长度小于或等于 8,000 个字节） |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT （长度大于 8000 个字节） |
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 （长度大于 8000 个字节） |
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 （长度大于 8000 个字节） |
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 （长度大于 8000 个字节） |
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 （长度大于 8000 个字节） |
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 返回的列元数据（目录元数据）”中所述。