Tipos de dados CLR grandes definidos pelo usuário (ODBC)
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 de ODBC a UDTs de CLR grande, consulte Suporte a UDTs grandes.
Para obter mais informações sobre o suporte a UDTs de CLR grande no SQL Server Native Client, consulte Tipos de dados CLR grandes definidos pelo usuário.
Formatos 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, UDT do CLR é 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 deve ser definido sempre através 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 |
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 |
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. Elas são adicionadas depois de quaisquer colunas definidas pelo ODBC, mas antes de quaisquer colunas específicas do driver existentes no conjunto de resultados de SQLColumns ou SQLProcedureColumns.
Nenhuma linha é retornada por SQLGetTypeInfo para UDTs individuais ou para o tipo "udt" genérico.
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 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 |
Com suporte * |
SQL_C_BINARY |
Com suporte |
SQL_C_CHAR |
Com suporte * |
* 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
Valores de colunas 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 os 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
Valores de colunas 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
Valores de colunas 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
Valores de colunas 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 |
Subtipo |
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
Valores de parâmetros UDT são convertidos de tipos de dados de C para SQL, conforme descrito na seção "Associações e conversões", anteriormente neste tópico.
SQLSetDescField
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.
SQLSetDescRec
Os valores permitidos para UDTs são os seguintes:
Tipo de dados SQL |
Tipo |
Subtipo |
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.