大型 CLR 用户定义类型 (ODBC)
适用于：
SQL ServerAzure SQL 数据库Azure SQL 托管实例Azure Synapse AnalyticsAnalytics Platform System (PDW)
重要
已从 SQL Server 2022 (16.x) 和 SQL Server Management Studio 19 (SSMS) 中删除SQL Server Native Client（通常缩写为 SNAC）。 不建议在新应用程序开发工作中使用 SQL Server Native Client（SQLNCLI 或 SQLNCLI11）和旧版 Microsoft OLE DB Provider for SQL Server (SQLOLEDB)。 请在此后切换为使用新版 Microsoft OLE DB Driver (MSOLEDBSQL) for SQL Server 或最新版的 Microsoft OLE DB Driver for SQL Server。 对于作为 SQL Server 数据库引擎组件附带的 SQLNCLI (版本 2012 到 2019) ，请参阅此支持生命周期异常。
本主题讨论 SQL Server Native Client 中为支持大型公共语言运行时 (CLR) 用户定义类型 (UDT) 而对 ODBC 进行的更改。
有关显示对大型 CLR UDT 的 ODBC 支持的示例，请参阅 对大型 UDT 的支持。
有关支持 SQL Server Native Client 中大型 CLR UDT 的详细信息，请参阅大型 CLR User-Defined类型。
数据格式
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 *(unsigned char *) | 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 数据类型 | 类型 | 子类型 | 长度 | Precision | 缩放 |
|---|---|---|---|---|---|
| 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 数据类型 | 类型 | 子类型 | 长度 | Precision | 缩放 |
|---|---|---|---|---|---|
| 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 返回的列元数据（目录元数据）”中所述。
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈