Tipos de dados CLR grandes definidos pelo usuário (ODBC)
Aplica-se a: 
SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics Analytics Platform System (PDW)
Importante
O SQL Server Native Client (SNAC) não é fornecido com:
- SQL Server 2022 (16.x) e versões posteriores
- SQL Server Management Studio 19 e versões posteriores
O SQL Server Native Client (SQLNCLI ou SQLNCLI11) e o provedor OLE DB para SQL Server (SQLOLEDB) da Microsoft herdado não são recomendados para desenvolver um novo aplicativo.
Para novos projetos, use um dos seguintes drivers:
Para SQLNCLI que é fornecido como um componente do Mecanismo de Banco de Dados do SQL Server (versões 2012 a 2019), confira esta exceção de Ciclo de Vida de Suporte.
Este tópico aborda as alterações feitas ao ODBC no SQL Server Native Client para dar suporte aos UDTs (tipos definidos pelo usuário) de CLR (Common Language Runtime) grande.
Para obter um exemplo que mostra o suporte ODBC para UDTs CLR grandes, consulte Suporte para UDTs grandes.
Para obter mais informações sobre o suporte para UDTs CLR grandes no SQL Server Native Client, consulte Tipos CLR grandes definidos pelo usuário.
Formato de Dados
O SQL Server Native Client usa SQL_SS_LENGTH_UNLIMITED para indicar que o tamanho de uma coluna é maior que 8.000 bytes para tipos LOB. A partir do SQL Server 2008, o mesmo valor é usado para UDTs do CLR quando seu tamanho for maior que 8.000 bytes.
Os valores UDT são representados como matrizes de bytes. Há suporte para conversões de cadeias hexadecimais e para cadeias hexadecimais. Os valores literais são representados como cadeias de caracteres hexadecimais com um prefixo "0x".
A seguinte tabela mostra o mapeamento de tipos de dados em parâmetros e conjuntos de resultados:
| Tipo de dados do SQL Server | Tipo de dados SQL | Valor |
|---|---|---|
| CLR UDT | SQL_SS_UDT | -151 (sqlncli.h) |
A seguinte tabela discute a estrutura correspondente e o tipo do C do ODBC. Essencialmente, o CLR UDT é um tipo varbinary com metadados adicionais.
| Tipo de dados SQL | Layout de memória | Tipos de dados do C | Valor (sqlext.h) |
|---|---|---|---|
| SQL_SS_UDT | SQLCHAR *(caractere não assinado *) | SQL_C_BINARY | SQL_BINARY (-2) |
Campos do descritor dos parâmetros
As informações são retornadas nos campos IPD são as seguintes:
| Campo do descritor | SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT (comprimento maior que 8.000 bytes) |
|---|---|---|
| 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 | O nome do catálogo que contém o UDT. | O nome do catálogo que contém o UDT. |
| SQL_CA_SS_UDT_SCHEMA_NAME | O nome do esquema que contém o UDT. | O nome do esquema que contém o UDT. |
| SQL_CA_SS_UDT_TYPE_NAME | O nome do UDT. | O nome do UDT. |
| SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME | O nome totalmente qualificado do assembly do UDT. | O nome totalmente qualificado do assembly do UDT. |
Para parâmetros UDT, SQL_CA_SS_UDT_TYPE_NAME sempre deve ser definido por meio de SQLSetDescField. SQL_CA_SS_UDT_CATALOG_NAME e SQL_CA_SS_UDT_SCHEMA_NAME são opcionais.
Se o UDT for definido no mesmo banco de dados com um esquema diferente que a tabela, SQL_CA_SS_UDT_SCHEMA_NAME deve ser definido.
Se o UDT for definido em um banco de dados diferente da tabela, SQL_CA_SS_UDT_CATALOG_NAME e SQL_CA_SS_UDT_SCHEMA_NAME devem ser definidos.
Se houver quaisquer erros ou omissões nas definições de SQL_CA_SS_UDT_TYPE_NAME, SQL_CA_SS_UDT_CATALOG_NAME ou SQL_CA_SS_UDT_SCHEMA_NAME, é gerado um registro de diagnóstico com SQLSTATE HY000 e texto de mensagem específico do servidor.
Campos do descritor dos resultados
As informações retornadas nos campos IRD são as seguintes:
| Campo do descritor | SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT (comprimento maior que 8.000 bytes) |
|---|---|---|
| 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 | O nome do catálogo que contém o UDT. | O nome do catálogo que contém o UDT. |
| SQL_CA_SS_UDT_SCHEMA_NAME | O nome do esquema que contém o UDT. | O nome do esquema que contém o UDT. |
| SQL_CA_SS_UDT_TYPE_NAME | O nome do UDT. | O nome do UDT. |
| SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME | O nome totalmente qualificado do assembly do UDT. | O nome totalmente qualificado do assembly do UDT. |
Metadados de coluna retornados por SQLColumns e SQLProcedureColumns (metadados de catálogo)
Os seguintes valores de coluna são retornados para UDTs:
| Nome da coluna | SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT (comprimento maior que 8.000 bytes) |
|---|---|---|
| DATA_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| TYPE_NAME | O nome do UDT. | O nome do UDT. |
| COLUMN_SIZE | n | SQL_SS_LENGTH_UNLIMITED (0) |
| BUFFER_LENGTH | n | SQL_SS_LENGTH_UNLIMITED (0) |
| DECIMAL_DIGITS | NULO | NULO |
| SQL_DATA_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| SQL_DATETIME_SUB | NULO | NULO |
| CHAR_OCTET_LENGTH | n | SQL_SS_LENGTH_UNLIMITED (0) |
| SS_UDT_CATALOG_NAME | O nome do catálogo que contém o UDT. | O nome do catálogo que contém o UDT. |
| SS_UDT_SCHEMA_NAME | O nome do esquema que contém o UDT. | O nome do esquema que contém o UDT. |
| SS_UDT_ASSEMBLY_TYPE_NAME | O nome totalmente qualificado do assembly do UDT. | O nome totalmente qualificado do assembly do UDT. |
As últimas três colunas são específicas do driver. Eles são adicionados após qualquer coluna definida pelo ODBC, mas antes de qualquer coluna específica do driver existente do conjunto de resultados de SQLColumns ou SQLProcedureColumns.
Nenhuma linha é retornada por SQLGetTypeInfo, para UDTs individuais ou para o tipo genérico "udt".
Associações e conversões
As conversões de tipos de dados de C para SQL com suporte são as seguintes:
| Conversão para e de: | SQL_SS_UDT |
|---|---|
| SQL_C_WCHAR | Com suporte* |
| SQL_C_BINARY | Com suporte |
| SQL_C_CHAR | Com suporte* |
* Os dados binários são convertidos em uma string hexadecimal.
As conversões com suporte dos tipos de dados do C para SQL são as seguintes:
| Conversão para e de: | SQL_SS_UDT |
|---|---|
| SQL_C_WCHAR | Com suporte* |
| SQL_C_BINARY | Com suporte |
| SQL_C_CHAR | Com suporte* |
* Ocorre a conversão de string hexadecimal para dados binários.
Suporte SQL_VARIANT para UDTs
Não há suporte para UDTs em colunas de SQL_VARIANT.
Suporte BCP para UDTs
Valores de UDTs podem ser importados e exportados somente como valores de caracteres ou binários.
Comportamento do cliente de baixo nível para UDTs
Os UDTs estão sujeitos ao mapeamento de tipo com clientes de baixo nível, conforme indicado a seguir:
| Versão do servidor | SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT (comprimento maior que 8.000 bytes) |
|---|---|---|
| SQL Server 2005 | UDT | varbinary(max) |
| SQL Server 2008 e posterior | UDT | UDT |
Funções ODBC que dão suporte a UDTs de CLR grande
Esta seção discute as alterações feitas nas funções ODBC do SQL Server Native Client para dar suporte a UDTs de CLR grande.
SQLBindCol
Os valores da coluna de resultado do UDT são convertidos de tipos de dados SQL para C, conforme descrito na seção "Associações e conversões", anteriormente neste tópico.
SQLBindParameter
Os valores necessários para UDTs são os seguintes:
| Tipo de dados SQL | Tipo de parâmetro | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (comprimento maior que 8.000 bytes) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLColAttribute
Os valores retornados para UDTs são os descritos na seção "Campos do descritor dos resultados", anteriormente neste tópico.
SQLColumns
Os valores retornados para UDTs são descritos na seção "Metadados de coluna retornados por SQLColumns e SQLProcedureColumns (metadados de catálogo)", anteriormente neste tópico.
SQLDescribeCol
Os valores retornados para UDTs são os seguintes:
| Tipo de dados SQL | DataTypePtr | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (comprimento maior que 8.000 bytes) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLDescribeParam
Os valores retornados para UDTs são os seguintes:
| Tipo de dados SQL | DataTypePtr | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (comprimento maior que 8.000 bytes) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLFetch
Os valores da coluna de resultado do UDT são convertidos de tipos de dados SQL para C, conforme descrito na seção "Associações e conversões", anteriormente neste tópico.
SQLFetchScroll
Os valores da coluna de resultado do UDT são convertidos de tipos de dados SQL para C, conforme descrito na seção "Associações e conversões", anteriormente neste tópico.
SQLGetData
Os valores da coluna de resultado do UDT são convertidos de tipos de dados SQL para C, conforme descrito na seção "Associações e conversões", anteriormente neste tópico.
SQLGetDescField
Os campos de descritor disponíveis como os novos tipos são descritos nas seções "Campos do descritor dos parâmetros" e "Campos do descritor dos resultados", anteriormente neste tópico.
SQLGetDescRec
Os valores retornados para UDTs são os seguintes:
| Tipo de dados SQL | Tipo | SubType | Length | Precisão | Escala |
|---|---|---|---|---|---|
| SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT | 0 | n | n | 0 |
| SQL_SS_UDT (comprimento maior que 8.000 bytes) |
SQL_SS_UDT | 0 | SQL_SS_LENGTH_UNLIMITED (0) | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLGetTypeInfo
Os valores retornados para UDTs são os descritos na seção "Metadados de coluna retornados por SQLColumns e SQLProcedureColumns (metadados de catálogo)", anteriormente neste tópico.
SQLProcedureColumns
Os valores retornados para UDTs são os descritos na seção "Metadados de coluna retornados por SQLColumns e SQLProcedureColumns (metadados de catálogo)", anteriormente neste tópico.
SQLPutData
Os valores de parâmetro UDT são convertidos de tipos de dados C para SQL, conforme descrito na seção "Associações e conversões", anteriormente neste tópico.
SQLSetDescField
Os campos descritores disponíveis com os novos tipos são descritos nas seções "Campos descritores para parâmetros" e "Campos descritores para resultados", anteriormente neste tópico.
SQLSetDescRec
Os valores permitidos para UDTs são os seguintes:
| Tipo de dados SQL | Tipo | SubType | Length | Precisão | Escala |
|---|---|---|---|---|---|
| SQL_SS_UDT (comprimento inferior ou igual a 8.000 bytes) |
SQL_SS_UDT | 0 | n | n | 0 |
| SQL_SS_UDT (comprimento maior que 8.000 bytes) |
SQL_SS_UDT | 0 | SQL_SS_LENGTH_UNLIMITED (0) | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLSpecialColumns
Os valores retornados para os UDTs das colunas DATA_TYPE, TYPE_NAME, COLUMN_SIZE, BUFFER_LENGTH e DECIMAL_DIGITS são os descritos na seção "Metadados de coluna retornados por SQLColumns e SQLProcedureColumns (metadados de catálogo)", anteriormente neste tópico.