Tipos de User-Defined CLR grandes em SQL Server Native Client (OLE DB)
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 provedor OLE DB do 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. Alterne para o novo Driver do Microsoft OLE DB para SQL Server (MSOLEDBSQL) no futuro.
Este tópico discute as alterações no OLE DB em SQL Server Native Client para dar suporte a grandes UDTs (tipos definidos pelo usuário) do CLR (Common Language Runtime).
Para obter mais informações sobre o suporte para UDTs CLR grandes em SQL Server Native Client, consulte Tipos de User-Defined CLR grandes. Para obter um exemplo, confira Usar UDTs CLR grandes (OLE DB).
Formato de Dados
SQL Server Native Client usa ~0 para representar o comprimento dos valores de tamanho ilimitado para tipos LOB (objeto grande). ~ 0 também representa o tamanho de UDTs CLR maiores que 8.000 bytes.
A seguinte tabela mostra o mapeamento de tipo de dados em parâmetros e conjuntos de linhas:
| Tipo de dados do SQL Server | Tipo de dados OLE DB | Layout de memória | Valor |
|---|---|---|---|
| CLR UDT | DBTYPE_UDT | BYTE[](matriz de bytes) | 132 (oledb.h) |
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". Uma cadeia de caracteres hexadecimal é a representação textual de dados binários na base 16. Um exemplo é uma conversão do tipo de servidor varbinary(10) em DBTYPE_STR, que resulta em uma representação hexadecimal de 20 caracteres, em que cada par de caracteres representa um único byte.
Propriedades de parâmetro
O conjunto de propriedades DBPROPSET_SQLSERVERPARAMETER dá suporte a UDTs através do OLE DB. Para obter mais informações, confira Usando tipos definidos pelo usuário.
Propriedades de coluna
O conjunto de propriedades DBPROPSET_SQLSERVERCOLUMN dá suporte à criação de tabelas através do OLE DB. Para obter mais informações, confira Usando tipos definidos pelo usuário.
Mapeamento de tipo de dados em ITableDefinition::CreateTable
As seguintes informações são usadas em estruturas DBCOLUMNDESC usadas por ITableDefinition::CreateTable quando as colunas UDT são obrigatórias:
| Tipo de dados OLE DB (wType) | pwszTypeName | Tipo de dados do SQL Server | rgPropertySets |
|---|---|---|---|
| DBTYPE_UDT | Ignored | UDT | Deve incluir um conjunto de propriedades DBPROPSET_SQLSERVERCOLUMN. |
ICommandWithParameters::GetParameterInfo
As informações retornadas na estrutura DBPARAMINFO por meio de prgParamInfo são as seguintes:
| Tipo de parâmetro | wType | ulParamSize | bPrecision | bScale | dwFlags DBPARAMFLAGS_ISLONG |
|---|---|---|---|---|---|
| DBTYPE_UDT (comprimento inferior ou igual a 8.000 bytes) |
"DBTYPE_UDT" | n | não definido | não definido | clear |
| DBTYPE_UDT (comprimento maior que 8.000 bytes) |
"DBTYPE_UDT" | ~0 | não definido | não definido | set |
ICommandWithParameters::SetParameterInfo
As informações fornecidas na estrutura DBPARAMBINDINFO devem estar de acordo com o seguinte:
| Tipo de parâmetro | pwszDataSourceType | ulParamSize | bPrecision | bScale | dwFlags DBPARAMFLAGS_ISLONG |
|---|---|---|---|---|---|
| DBTYPE_UDT (comprimento inferior ou igual a 8.000 bytes) |
DBTYPE_UDT | n | ignorado | ignorado | Deve ser definido se o parâmetro for passado usando DBTYPE_IUNKNOWN. |
| DBTYPE_UDT (comprimento maior que 8.000 bytes) |
DBTYPE_UDT | ~0 | ignorado | ignorado | ignorado |
ISSCommandWithParameters
Os aplicativos usam ISSCommandWithParameters para obter e definir as propriedades de parâmetro definidas na seção Propriedades de parâmetro.
IColumnsRowset::GetColumnsRowset
As colunas são retornadas da seguinte maneira:
| Tipo de coluna | DBCOLUMN_TYPE | DBCOLUMN_COLUMNSIZE | DBCOLUMN_PRECISION | DBCOLUMN_SCALE | DBCOLUMN_FLAGS_ISLONG | DBCOLUMNS_ISSEARCHABLE | DBCOLUMN_OCTETLENGTH |
|---|---|---|---|---|---|---|---|
| DBTYPE_UDT (comprimento inferior ou igual a 8.000 bytes) |
DBTYPE_UDT | n | NULO | NULO | Liberada | DB_ALL_EXCEPT_LIKE | n |
| DBTYPE_UDT (comprimento maior que 8.000 bytes) |
DBTYPE_UDT | ~0 | NULO | NULO | Definir | DB_ALL_EXCEPT_LIKE | 0 |
As seguintes colunas também são definidas para UDTs:
| Identificador de coluna | Type | DESCRIÇÃO |
|---|---|---|
| DBCOLUMN_UDT_CATALOGNAME | DBTYPE_WSTR | Para colunas de UDT, o nome do catálogo onde o UDT foi definido. |
| DBCOLUMN_UDT_SCHEMANAME | DBTYPE_WSTR | Para colunas de UDT, o nome do esquema onde o UDT foi definido. |
| DBCOLUMN_UDT_NAME | DBTYPE_WSTR | Para colunas de UDT, o nome de uma única parte do UDT. |
| DBCOLUMN_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Para colunas de UDT, o nome de tipo completo do UDT. O nome totalmente qualificado do tipo de assembly permite que você crie uma instância de um objeto daquele tipo usando o método Type.GetType. |
IColumnsInfo::GetColumnInfo
As informações retornadas na estrutura DBCOLUMNINFO são as seguintes:
| Tipo de parâmetro | wType | ulColumnSize | bPrecision | bScale | dwFlags DBCOLUMNFLAGS_ISLONG |
|---|---|---|---|---|---|
| DBTYPE_UDT (comprimento inferior ou igual a 8.000 bytes) |
DBTYPE_UDT | n | ~0 | ~0 | Liberada |
| DBTYPE_UDT (comprimento maior que 8.000 bytes) |
DBTYPE_UDT | ~0 | ~0 | ~0 | Definir |
Conjunto de linhas COLUMNS (conjuntos de linhas de esquema)
Os seguintes valores de coluna são retornados para tipos UDT:
| Tipo de coluna | DATA_TYPE | COLUMN_FLAGS, DBCOLUMFLAGS_ISLONG | CHARACTER_OCTET_LENGTH |
|---|---|---|---|
| DBTYPE_UDT (comprimento inferior ou igual a 8.000 bytes) |
DBTYPE_UDT | Liberada | n |
| DBTYPE_UDT (comprimento maior que 8.000 bytes) |
DBTYPE_UDT | Definir | 0 |
As seguintes colunas adicionais são definidas para UDTs:
| Identificador de coluna | Type | DESCRIÇÃO |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Para colunas de UDT, o nome do catálogo onde o UDT foi definido. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Para colunas de UDT, o nome do esquema onde o UDT foi definido. |
| SS_UDT_NAME | DBTYPE_WSTR | Para colunas de UDT, o nome de uma única parte do UDT. |
| SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Para colunas de UDT, este é o nome de tipo completo do UDT. O nome totalmente qualificado do tipo de assembly permite que você crie uma instância de um objeto daquele tipo usando o método Type.GetType. |
Relativo ao conjunto de linhas PROCEDURE_PARAMETERS, DATA_TYPE contém os mesmos valores que o conjunto de linhas de esquema COLUMNS e TYPE_NAME contém o UDT. As mesmas colunas adicionais também são definidas.
Os tipos definidos pelo usuário não aparecerão no conjunto de linhas de esquema PROVIDER_TYPES.
Associações e conversões
| Tipo de dados de associação | UDT para servidor | Não UDT para servidor | UDT de servidor | Não UDT de servidor |
|---|---|---|---|---|
| DBTYPE_UDT | Compatível (5) | Erro (1) | Compatível (5) | Erro (4) |
| DBTYPE_BYTES | Compatível (5) | N/D | Compatível (5) | N/D |
| DBTYPE_WSTR | Com suporte (2), (5) | N/D | Com suporte (3), (5), (6) | N/D |
| DBTYPE_BSTR | Com suporte (2), (5) | N/D | Compatível (3), (5) | N/D |
| DBTYPE_STR | Com suporte (2), (5) | N/D | Compatível (3), (5) | N/D |
| DBTYPE_IUNKNOWN | Compatível (6) | N/D | Compatível (6) | N/D |
| DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) | Compatível (5) | N/D | Compatível (3), (5) | N/D |
| DBTYPE_VARIANT (VT_BSTR) | Com suporte (2), (5) | N/D | N/D | N/D |
Legenda dos símbolos
| Símbolo | Significado |
|---|---|
| 1 | Se um tipo de servidor diferente de DBTYPE_UDT for especificado com ICommandWithParameters::SetParameterInfo e o tipo de acessador for DBTYPE_UDT, ocorrerá um erro quando a instrução for executada. O erro será DB_E_ERRORSOCCURRED e o status do parâmetro será DBSTATUS_E_BADACCESSOR. É um erro especificar um parâmetro de tipo UDT para um parâmetro de servidor que não seja UDT. |
| 2 | Os dados são convertidos de cadeia de caracteres hexadecimal em dados binários. |
| 3 | Os dados são convertidos de dados binários em cadeia de caracteres hexadecimal. |
| 4 | A validação pode ser feita usando CreateAccessor ou GetNextRows. O erro é DB_E_ERRORSOCCURRED. O status de associação é definido como DBBINDSTATUS_UNSUPPORTEDCONVERSION. |
| 5 | BY_REF pode ser usado. |
| 6 | Os parâmetros de UDT podem ser associados como DBTYPE_IUNKNOWN no DBBINDING. A associação a DBTYPE_IUNKNOWN indica que o aplicativo deseja processar os dados como um fluxo usando a interface ISequentialStream. Quando um consumidor especifica wType em uma associação como tipo DBTYPE_IUNKNOWN e o parâmetro de coluna ou saída correspondente do procedimento armazenado é um UDT, SQL Server Native Client retornará ISequentialStream. Para um parâmetro de entrada, SQL Server Native Client consultará o para a interface ISequentialStream. Você pode optar por não associar o comprimento de dados de UDT enquanto estiver usando a associação DBTYPE_IUNKNOWN, no caso de UDTs grandes. Porém, o comprimento deve estar associado a UDTs pequenos. Um parâmetro DBTYPE_UDT poderá ser especificado como um UDT grande nos seguintes casos: ulParamParamSize é ~0. Se DBPARAMFLAGS_ISLONG estiver definido na estrutura DBPARAMBINDINFO. Para dados de linha, a associação de DBTYPE_IUNKNOWN é permitida só para UDTs grandes. Você pode descobrir se uma coluna é um tipo UDT grande usando o método IColumnsInfo::GetColumnInfo em uma interface IColumnsInfo um objeto de comando ou de conjunto de linhas. Uma coluna DBTYPE_UDT será uma coluna de UDT grande se uma ou mais destas condições for verdadeira: O sinalizador DBCOLUMNFLAGS_ISLONG é definido no membro dwFlags da estrutura DBCOLUMNINFO. O membro ulColumnSize de DBCOLUMNINFO é ~0. |
DBTYPE_NULL e DBTYPE_EMPTY podem ser associados aos parâmetros de entrada, mas não a parâmetros ou resultados de saída. Quando associado a parâmetros de entrada, o status deve ser definido como DBSTATUS_S_ISNULL para DBTYPE_NULL ou DBSTATUS_S_DEFAULT para DBTYPE_EMPTY. DBTYPE_BYREF não pode ser usado com DBTYPE_NULL ou DBTYPE_EMPTY.
DBTYPE_UDT também pode ser convertido em DBTYPE_EMPTY e DBTYPE_NULL. No entanto, DBTYPE_NULL e DBTYPE_EMPTY não podem ser convertidos em DBTYPE_UDT. Isso é consistente com DBTYPE_BYTES. ISSCommandWithParameters é usado para processar UDTs como parâmetros.
As conversões de dados fornecidas pelos serviços principais do OLE DB (IDataConvert) não são aplicáveis a DBTYPE_UDT.
As demais associações não têm suporte.
Comparações de IRowsetFind
Para os tipos UDT, apenas as seguintes comparações têm suporte:
EQ
NE
IGNORE
Se qualquer outra comparação for tentada, DB_E_BADCOMPAREOP será retornado.
Suporte BCP para UDTs
Os valores UDT podem ser importados e exportados apenas como caractere ou valores binários.
Comportamento de cliente de nível inferior para UDTs
Os UDTs estão sujeitos ao mapeamento de tipo com clientes de baixo nível, conforme indicado a seguir:
| Versão do cliente | DBTYPE_UDT (comprimento inferior ou igual a 8.000 bytes) |
DBTYPE_UDT (comprimento maior que 8.000 bytes) |
|---|---|---|
| SQL Server 2005 | UDT | varbinary(max) |
| SQL Server 2008 e posterior | UDT | UDT |
Quando DataTypeCompatibility (SSPROP_INIT_DATATYPECOMPATIBILITY) é definido como "80", os tipos UDT grandes são exibidos para os clientes da mesma forma que para clientes de nível inferior.
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