Usando tipos definidos pelo usuário

O SQL Server 2005 introduziu os UDTs (tipos definidos pelo usuário). Os UDTs estendem o sistema de tipos do SQL, permitindo armazenar objetos e estruturas de dados personalizadas em um banco de dados do SQL Server. Os UDTs podem conter vários tipos de dados e ter comportamentos, o que os diferencia dos tipos de dados de alias tradicionais, que consistem em um único tipo de dado do sistema SQL Server. UDTs são definidos usando quaisquer dos idiomas com suporte pelo .NET CRL (Common Language Runtime) que gera código verificável. Isto inclui Microsoft Visual C#® e Visual Basic® .NET. Os dados são expostos como campos e propriedades de uma classe ou estrutura .NET e os comportamentos são definidos pelos métodos da classe ou estrutura.

Um UDT pode ser usado como definição da coluna de uma tabela, como uma variável em um lote Transact-SQL ou como um argumento de uma função Transact-SQL ou procedimento armazenado.

Provedor OLE DB do SQL Server Native Client

O provedor OLE DB do SQL Server Native Client oferece suporte a UDTs como tipos binários com informações de metadados, o que permite gerenciar UDTs como objetos. As colunas de UDT são expostas como DBTYPE_UDT e seus metadados são expostos pela interface principal do OLE DB IColumnRowset e a nova interface ISSCommandWithParameters.

Observação
O método IRowsetFind::FindNextRow não funciona com o tipo de dados UDT. DB_E_BADCOMPAREOP será retornado se o UDT for usado como um tipo de coluna de pesquisa.

Coerções e associações de dados

A tabela a seguir descreve a associação e a coerção que ocorrem ao usar os tipos de dados listados com o UDT SQL Server. Colunas de UDT são expostas pelo provedor OLE DB do SQL Server Native Client como DBTYPE_UDT. Você pode obter metadados por meio dos conjuntos de linhas de esquema apropriados de forma que possa gerenciar seus próprios tipos definidos como objetos.

Tipo de dados	Para servidor UDT	Para servidor não UDT	Do servidor UDT	Do servidor não UDT
DBTYPE_UDT	Com suporte6	Erro1	Com suporte6	Erro5
DBTYPE_BYTES	Com suporte6	N/D2	Com suporte6	N/D2
DBTYPE_WSTR	Com suporte3,6	N/D2	Com suporte4,6	N/D2
DBTYPE_BSTR	Com suporte3,6	N/D2	Com suporte4	N/D2
DBTYPE_STR	Com suporte3,6	N/D2	Com suporte4,6	N/D2
DBTYPE_IUNKNOWN	Sem suporte	N/D2	Sem suporte	N/D2
DBTYPE_VARIANT (VT_UI1 | VT_ARRAY)	Com suporte6	N/D2	Com suporte4	N/D2
DBTYPE_VARIANT (VT_BSTR)	Com suporte3,6	N/D2	N/D	N/D2

1Se 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 (para DB_E_ERRORSOCCURRED, o status do parâmetro é DBSTATUS_E_BADACCESSOR). Caso contrário, os dados serão enviados para o servidor, mas ele retornará um erro indicando que não há conversão implícita do UDT para o tipo de dados do parâmetro.

2Foge ao escopo deste tópico.

3 Ocorre conversão de dados de cadeia de caracteres hexadecimal para dados binários.

4 Ocorre conversão de dados binários para cadeia de caracteres hexadecimal.

5 Pode ocorrer validação no momento de criação do acessador ou, no momento da busca, o erro é DB_E_ERRORSOCCURRED, associando o conjunto de status a DBBINDSTATUS_UNSUPPORTEDCONVERSION.

6BY_REF pode ser usado.

DBTYPE_NULL e DBTYPE_EMPTY podem ser associados a parâmetros de entrada, mas não a parâmetros ou resultados de saída. Quando eles são associados a parâmetros de entrada, o status precisa ser definido como DBSTATUS_S_ISNULL ou DBSTATUS_S_DEFAULT.

DBTYPE_UDT pode ser convertido em DBTYPE_EMPTY e DBTYPE_NULL, porém DBTYPE_NULL e DBTYPE_EMPTY não podem ser convertidos em DBTYPE_UDT. Isso é consistente com DBTYPE_BYTES.

Observação

Uma interface nova é usada para lidar com UDTs como parâmetros, ISSCommandWithParameters, herdada de ICommandWithParameters. Os aplicativos devem usar esta interface para definir pelo menos o SSPROP_PARAM_UDT_NAME da propriedade DBPROPSET_SQLSERVERPARAMETER definida para os parâmetros de UDT. Se isto não for feito, ICommand::Execute retornará DB_E_ERRORSOCCURRED. Esta interface e conjunto de propriedades serão descritos posteriormente neste tópico.

Se um tipo definido pelo usuário for inserido em uma coluna que não seja grande o suficiente para reter todos os dados, ICommand::Execute retornará S_OK com status de DB_E_ERRORSOCCURRED.

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.

Adições e alterações do conjunto de linhas do OLE DB

O SQL Server Native Client adiciona novos valores ou alterações a muitos dos conjuntos de linhas de esquema principais do OLE DB.

O conjunto de linhas do esquema PROCEDURE_PARAMETERS

As adições a seguir foram feitas ao conjunto de linhas de esquema de PROCEDURE_PARAMETERS.

Nome da coluna	Tipo	Descrição
SS_UDT_CATALOGNAME	DBTYPE_WSTR	O identificador de nome de três partes.
SS_UDT_SCHEMANAME	DBTYPE_WSTR	O identificador de nome de três partes.
SS_UDT_NAME	DBTYPE_WSTR	O identificador de nome de três partes.
SS_UDT_ASSEMBLY_TYPENAME	DBTYPE_WSTR	O Nome Qualificado do Assembly, que inclui o nome de tipo e toda a identificação de assembly necessários para referência pelo CLR.

O conjunto de linhas do esquema SQL_ASSEMBLIES

O provedor OLE DB do SQL Server Native Client expõe um novo conjunto de linhas de esquema específico que descreve os UDTs registrados. O servidor de ASSEMBLY pode ser especificado como um DBTYPE_WSTR, mas não está presente no conjunto de linhas. Se não estiver especificado, o conjunto de linhas seguirá o padrão do servidor atual. O conjunto de linhas de esquema de SQL_ASSEMBLIES é definido na tabela a seguir.

Nome da coluna	Tipo	Descrição
ASSEMBLY_CATALOG	DBTYPE_WSTR	O nome de catálogo do assembly que contém o tipo.
ASSEMBLY_SCHEMA	DBTYPE_WSTR	O nome do esquema ou nome do proprietário do assembly que contém o tipo. Embora os assemblies tenham escopo por banco de dados e não por esquema, eles ainda têm um proprietário que é refletido aqui.
ASSEMBLY_NAME	DBTYPE_WSTR	O nome do assembly que contém o tipo.
ASSEMBLY_ID	DBTYPE_UI4	A id do objeto do assembly que contém o tipo.
PERMISSION_SET	DBTYPE_WSTR	Um valor que indica o escopo de acesso para o assembly. Valores incluem "SAFE", "EXTERNAL_ACCESS" e "UNSAFE".
ASSEMBLY_BINARY	DBTYPE_BYTES	A representação binária do assembly.

O conjunto de linhas do esquema SQL_ASSEMBLIES_ DEPENDENCIES

O provedor OLE DB do SQL Server Native Client expõe um novo conjunto de linhas de esquema específico que descreve as dependências de assembly para um servidor especificado. O ASSEMBLY_SERVER pode ser especificado pelo chamador como um DBTYPE_WSTR, mas não está presente no conjunto de linhas. Se não estiver especificado, o conjunto de linhas seguirá o padrão do servidor atual. O conjunto de linhas de esquema de SQL_ASSEMBLY_DEPENDENCIES é definido na tabela a seguir.

Nome da coluna	Tipo	Descrição
ASSEMBLY_CATALOG	DBTYPE_WSTR	O nome de catálogo do assembly que contém o tipo.
ASSEMBLY_SCHEMA	DBTYPE_WSTR	O nome do esquema ou nome do proprietário do assembly que contém o tipo. Embora os assemblies tenham escopo por banco de dados e não por esquema, eles ainda têm um proprietário que é refletido aqui.
ASSEMBLY_ID	DBTYPE_UI4	A id do objeto do assembly.
REFERENCED_ASSEMBLY_ID	DBTYPE_UI4	A id do objeto do assembly referenciado.

O conjunto de linhas do esquema SQL_USER_TYPES

SQL Server O provedor OLE DB do Native Client expõe o novo conjunto de linhas de esquema, o SQL_USER_TYPES, que descreve quando os UDTs registrados para um servidor especificado são adicionados. O UDT_SERVER deve ser especificado pelo chamador como um DBTYPE_WSTR, mas não está presente no conjunto de linhas. O conjunto de linhas de esquema de SQL_USER_TYPES é definido na tabela a seguir.

Nome da coluna	Tipo	Descrição
UDT_CATALOGNAME	DBTYPE_WSTR	Para colunas de UDT esta propriedade é uma cadeia de caracteres que especifica o nome do catálogo onde o UDT é definido.
UDT_SCHEMANAME	DBTYPE_WSTR	Para colunas de UDT esta propriedade é uma cadeia de caracteres que especifica o nome do esquema onde o UDT é definido.
UDT_NAME	DBTYPE_WSTR	O nome do assembly que contém a classe do UDT.
UDT_ASSEMBLY_TYPENAME	DBTYPE_WSTR	O AQN (nome de tipo completo) inclui o nome do tipo prefixado pelo namespace, se aplicável.

O conjunto de linhas do esquema COLUMNS

Adições para o conjunto de linhas de esquema de COLUMNS incluem as colunas a seguir.

Nome da coluna	Tipo	Descrição
SS_UDT_CATALOGNAME	DBTYPE_WSTR	Para colunas de UDT esta propriedade é uma cadeia de caracteres que especifica o nome do catálogo onde o UDT é definido.
SS_UDT_SCHEMANAME	DBTYPE_WSTR	Para colunas de UDT esta propriedade é uma cadeia de caracteres que especifica o nome do esquema onde o UDT é definido.
SS_UDT_NAME	DBTYPE_WSTR	O nome do UDT
SS_UDT_ASSEMBLY_TYPENAME	DBTYPE_WSTR	O AQN (nome de tipo completo) inclui o nome do tipo prefixado pelo namespace, se aplicável.

Adições e alterações do conjunto de propriedades do OLE DB

O SQL Server Native Client adiciona novos valores ou alterações a muitos dos conjuntos de propriedades principais do OLE DB.

O conjunto de propriedades de DBPROPSET_SQLSERVERPARAMETER

Para oferecer suporte aos UDTs por meio do OLE DB, o SQL Server Native Client implementa o novo conjunto de propriedades de DBPROPSET_SQLSERVERPARAMETER, que contém os valores a seguir.

Nome	Tipo	Descrição
SSPROP_PARAM_UDT_CATALOGNAME	DBTYPE_WSTR	O identificador de nome de três partes. Para parâmetros de UDT, essa propriedade é uma cadeia de caracteres que especifica o nome do catálogo onde o tipo definido pelo usuário é definido.
SSPROP_PARAM_UDT_SCHEMANAME	DBTYPE_WSTR	O identificador de nome de três partes. Para parâmetros de UDT, essa propriedade é uma cadeia de caracteres que especifica o nome do esquema onde o tipo definido pelo usuário é definido.
SSPROP_PARAM_UDT_NAME	DBTYPE_WSTR	O identificador de nome de três partes. Para colunas de UDT, essa propriedade é uma cadeia de caracteres que especifica o nome de apenas uma parte do tipo definido pelo usuário.

SSPROP_PARAM_UDT_NAME é obrigatório. SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME são opcionais. Se alguma propriedade for especificada incorretamente, o DB_E_ERRORSINCOMMAND será retornado. Se SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME não forem especificados, então o UDT deverá ser definido no mesmo banco de dados e esquema que a tabela. Se a definição de UDT não estiver no mesmo esquema que a tabela (mas estiver no mesmo banco de dados), então SSPROP_PARAM_UDT_SCHEMANAME deverá ser especificado. Se a definição de UDT estiver em um banco de dados diferente, SSPROP_PARAM_UDT_CATALOGNAME e SSPROP_PARAM_UDT_SCHEMANAME deverão ser especificados.

O conjunto de propriedades de DBPROPSET_SQLSERVERCOLUMN

Para oferecer suporte à criação de tabelas na interface ITableDefinition, o SQL Server o Native Client adiciona as três colunas novas a seguir ao conjunto de propriedades de DBPROPSET_SQLSERVERCOLUMN.

Nome	Descrição	Tipo	Descrição
SSPROP_COL_UDT_CATALOGNAME	UDT_CATALOGNAME	VT_BSTR	Para colunas de tipo DBTYPE_UDT, essa propriedade é uma cadeia de caracteres que especifica o nome do catálogo onde o UDT é definido.
SSPROP_COL_UDT_SCHEMANAME	UDT_SCHEMANAME	VT_BSTR	Para colunas de tipo DBTYPE_UDT, essa propriedade é uma cadeia de caracteres que especifica o nome do esquema onde o UDT é definido.
SSPROP_COL_UDT_NAME	UDT_NAME	VT_BSTR	Para colunas de tipo DBTYPE_UDT, essa propriedade é uma cadeia de caracteres que especifica o nome de apenas uma parte do UDT. Para outros tipos de coluna, essa propriedade retorna uma cadeia de caracteres vazia.

Observação
Os UDTs não aparecem no conjunto de linhas de esquema de PROVIDER_TYPES. Todas as colunas têm direito de leitura e gravação.

O ADO recorrerá a estas propriedades usando a entrada correspondente na coluna Descrição.

SSPROP_COL_UDTNAME é obrigatório. SSPROP_COL_UDT_CATALOGNAME e SSPROP_COL_UDT_SCHEMANAME são opcionais. Se alguma das propriedades for especificada incorretamente, DB_E_ERRORSINCOMMAND será retornado.

Se SSPROP_COL_UDT_CATALOGNAME nem SSPROP_COL_UDT_SCHEMANAME forem especificados, o UDT deverá ser definido no mesmo banco de dados e esquema que a tabela.

Se a definição de UDT não estiver no mesmo esquema que a tabela (mas estiver no mesmo banco de dados), então SSPROP_COL_UDT_SCHEMANAME deverá ser especificado.

Se a definição de UDT estiver em um banco de dados diferente, SSPROP_COL_UDT_CATALOGNAME e SSPROP_COL_UDT_SCHEMANAME devem ser especificados.

Adições e alterações de interface do OLE DB

O SQL Server Native Client adiciona novos valores ou alterações a muitas das interfaces do OLE DB de núcleo.

A interface ISSCommandWithParameters

Para dar suporte aos UDTs pelo OLE DB, o SQL Server Native Client implementa vários alterações, inclusive a adição da interface ISSCommandWithParameters. Essa nova interface herda as propriedades principais da interface do OLE DB ICommandWithParameters. Além dos três métodos herdados de ICommandWithParameters; GetParameterInfo, MapParameterNames e SetParameterInfo, ISSCommandWithParameters oferece os métodos GetParameterProperties e SetParameterProperties usados para manipular tipos de dados específicos de servidor.

Observação
A interface ISSCommandWithParameters também utiliza a nova estrutura SSPARAMPROPS.

A interface IColumnsRowset

Além da interface ISSCommandWithParameters, o SQL Server Native Client adiciona novos valores ao conjunto de linhas retornado ao chamar o método IColumnsRowset::GetColumnRowset, incluindo os seguintes:

Nome da coluna	Tipo	Descrição
DBCOLUMN_SS_UDT_CATALOGNAME	DBTYPE_WSTR	Um identificador do nome de catálogo do UDT.
DBCOLUMN_SS_UDT_SCHEMANAME	DBTYPE_WSTR	Um identificador do nome do esquema do UDT.
DBCOLUMN_SS_UDT_NAME	DBTYPE_WSTR	Um identificador de nome do UDT.
DBCOLUMN_SS_ASSEMBLY_TYPENAME	DBTYPE_WSTR	O nome qualificado do assembly, que inclui o nome de tipo e toda a identificação de assembly necessários para referência pelo CLR.

É possível diferenciar uma coluna de UDT do servidor de outros tipos binários quando DBCOLUMN_TYPE for definido como DBTYPE_UDT observando os metadados de UDT adicionados especificados acima. Se esses dados estiverem parcialmente completos, o tipo de servidor será um UDT. Para tipos de servidores não UDT, essas colunas são sempre retornadas como NULL.

Driver ODBC do SQL Server Native Client

Foram realizadas várias alterações no driver ODBC do SQL Server Native Client para dar suporte a UDTs. O driver ODBC do SQL Server Native Client mapeia o UDT SQL Server para o identificador do tipo de dados SQL específico do driver SQL_SS_UDT. São exibidas colunas de UDT como SQL_SS_UDT. Se você mapear uma coluna UDT explicitamente para outro tipo em uma instrução SQL usando os métodos ToString ou ToXMLString do UDT ou a função CAST/CONVERT, o tipo de coluna no conjunto de resultados refletirá o tipo real ao qual a coluna foi convertida.

SQLColAttribute, SQLDescribeParam, SQLGetDescField

Quatro novos campos do descritor específico do driver foram adicionados para fornecer mais informações para uma coluna UDT ou um conjunto de resultados, ou um parâmetro UDT de consulta parametrizada/de procedimento, a ser recuperado por meio das funções SQLColAttribute, SQLDescribeParam e SQLGetDescField.

Os quatro novos campos do descritor adicionados são SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME e SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.

SQLColumns, SQLProcedureColumns

Além disso, três novas colunas específicas do driver foram adicionadas ao conjunto de resultados retornado das funçõesSQLColumns e SQLProcedureColumns para fornecer mais informações sobre a coluna do conjunto de resultados de UDT ou um parâmetro UDT. Essas três colunas novas são SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME e SS_UDT_ASSEMBLY_TYPE_NAME.

Conversões com suporte

Na conversão de tipos de dados SQL para C, é possível converter SQL_C_WCHAR, SQL_C_BINARY e SQL_C_CHAR a SQL_SS_UDT. Porém, observe que os dados binários são convertidos a uma cadeia de caracteres hexadecimais na conversão dos tipos de dados SQL_C_WCHAR e SQL_C_CHAR SQL.

Na conversão de tipos de dados C para SQL, é possível converter SQL_C_WCHAR, SQL_C_BINARY e SQL_C_CHAR a SQL_SS_UDT. Porém, observe que os dados binários são convertidos a uma cadeia de caracteres hexadecimais na conversão dos tipos de dados SQL_C_WCHAR e SQL_C_CHAR SQL.

Consulte também

Referência

ISSCommandWithParameters (OLE DB)

Outros recursos

Recursos do SQL Server Native Client