Tipos de dados CLR grandes definidos pelo usuário (ODBC)
Aplica-se a:
SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsPDW (Analytics Platform System)
Importante
O SQL Server Native Client (geralmente abreviado como SNAC) foi removido do SQL Server 2022 (16.x) e do SSMS (SQL Server Management Studio) 19. O SQL Server Native Client (SQLNCLI ou SQLNCLI11) e o Provedor OLE DB herdado da Microsoft para o SQL Server (SQLOLEDB) não são recomendados para um novo desenvolvimento de aplicativo. Alterne para o novo Driver do Microsoft OLE DB para SQL Server (MSOLEDBSQL) ou o Microsoft ODBC Driver for SQL Server mais recente no futuro. Para SQLNCLI que é fornecido como um componente do Mecanismo de Banco de Dados SQL Server (versões 2012 a 2019), consulte 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 mostrando o suporte do ODBC para UDTs CLR grandes, consulte Suporte para UDTs grandes.
Para obter mais informações sobre o suporte para UDTs CLR grandes em SQL Server Native Client, consulte Tipos de User-Defined clr grandes.
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, 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 *(unsigned char *) | 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 | 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 | 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 por 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 | Suportado* |
| SQL_C_BINARY | Com suporte |
| SQL_C_CHAR | Suportado* |
* Os dados binários são convertidos para uma cadeia de caracteres 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 | Suportado* |
| SQL_C_BINARY | Com suporte |
| SQL_C_CHAR | Suportado* |
* Ocorre a conversão da cadeia de caracteres 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 de coluna de resultado 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 | Parametertype | 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 conforme descrito 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 de coluna de resultado 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 de coluna de resultado 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 de coluna de resultado 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 | Comprimento | 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
O campo Descritor disponível com os novos tipos é descrito nas seções "Campos de descritor para parâmetros" e "Campos de descritor para resultados", anteriormente neste tópico.
SQLSetDescRec
Os valores permitidos para UDTs são os seguintes:
| Tipo de dados SQL | Tipo | SubType | Comprimento | 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.
Consulte Também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de