Compartir a través de


Usar tipos definidos por el usuario

Los tipos definidos por el usuario (UDT) se introdujeron en SQL Server 2005. Los UDT amplían el sistema de tipos SQL ya que permiten almacenar objetos y estructuras de datos personalizadas en una base de datos de SQL Server. Los UDT pueden contener varios tipos de datos y pueden presentar distintos comportamientos, lo que los diferencia de los tipos de datos de alias tradicionales que constan de un único tipo de datos del sistema de SQL Server. Los UDT pueden definirse mediante cualquiera de los lenguajes compatibles con .NET Common Language Runtime (CLR) que genere código comprobable, como Microsoft Visual C#® y Visual Basic® .NET. Los datos se exponen como campos y propiedades de una clase o estructura de .NET, y los métodos de esa clase o estructura definen los comportamientos.

Un UDT puede usarse como la definición de columna de una tabla, como una variable de un lote Transact-SQL o como un argumento de una función o procedimiento almacenado Transact-SQL. Para obtener más información acerca de los UDT, vea Trabajar con tipos definidos por el usuario para CLR.

Proveedor OLE DB de SQL Server Native Client

El proveedor OLE DB de SQL Server Native Client admite los UDT como tipos binarios con información de metadatos, lo que permite administrar los UDT como objetos. Las columnas UDT se exponen como DBTYPE_UDT y sus metadatos se exponen a través de la interfaz OLE DB básica IColumnRowset y la nueva interfaz ISSCommandWithParameters.

Nota

El método IRowsetFind::FindNextRow no funciona con el tipo de datos UDT. Si el UDT se usa como un tipo de columna de búsqueda, se devuelve DB_E_BADCOMPAREOP.

Enlaces y conversiones de datos

En la tabla siguiente se describe el enlace y la conversión que tiene lugar al usar los tipos de datos enumerados con un UDT de SQL Server. Las columnas UDT se exponen a través del proveedor OLE DB de SQL Server Native Client como DBTYPE_UDT. Puede obtener metadatos mediante los conjuntos de filas de esquema adecuados, de modo que pueda administrar sus propios tipos definidos como objetos.

Tipo de datos

A un tipo UDT

del servidor

A un tipo no UDT

del servidor

Desde un tipo UDT

del servidor

Desde un tipo no UDT

del servidor

DBTYPE_UDT

Compatible6

Error1

Compatible6

Error5

DBTYPE_BYTES

Compatible6

N/D2

Compatible6

N/D2

DBTYPE_WSTR

Compatible3,6

N/D2

Compatible4,6

N/D2

DBTYPE_BSTR

Compatible3,6

N/D2

Compatible4

N/D2

DBTYPE_STR

Compatible3,6

N/D2

Compatible4,6

N/D2

DBTYPE_IUNKNOWN

No compatible

N/D2

No compatible

N/D2

DBTYPE_VARIANT (VT_UI1 | VT_ARRAY)

Compatible6

N/D2

Compatible4

N/D2

DBTYPE_VARIANT (VT_BSTR)

Compatible3,6

N/D2

N/D

N/D2

1Si se especifica un tipo de servidor distinto de DBTYPE_UDT con ICommandWithParameters::SetParameterInfo y el tipo de descriptor de acceso es DBTYPE_UDT, se produce un error cuando se ejecuta la instrucción (DB_E_ERRORSOCCURRED; el estado del parámetro es DBSTATUS_E_BADACCESSOR). De lo contrario, los datos se envían al servidor, pero el servidor devuelve un error que indica que no hay ninguna conversión implícita de UDT al tipo de datos del parámetro.

2Más allá del ámbito de este tema.

3Las cadenas hexadecimales se convierten en datos binarios.

4Los datos binarios se convierten en cadenas hexadecimales.

5La validación puede tener lugar en el momento de creación del descriptor de acceso o en el momento de la captura; el error es DB_E_ERRORSOCCURRED, con el estado de enlace establecido en DBBINDSTATUS_UNSUPPORTEDCONVERSION.

6Puede usarse BY_REF.

DBTYPE_NULL y DBTYPE_EMPTY pueden enlazarse en parámetros de entrada, pero no en parámetros de salida ni en resultados. Cuando se enlazan para parámetros de entrada, el estado debe establecerse en DBSTATUS_S_ISNULL o DBSTATUS_S_DEFAULT.

DBTYPE_UDT también puede convertirse en DBTYPE_EMPTY y DBTYPE_NULL, pero DBTYPE_NULL y DBTYPE_EMPTY no pueden convertirse en DBTYPE_UDT. Este comportamiento es coherente con el de DBTYPE_BYTES.

Nota

Se usa una nueva interfaz para tratar los UDT como parámetros, la interfaz ISSCommandWithParameters, que hereda de ICommandWithParameters. Las aplicaciones deben usar esta interfaz para establecer al menos la propiedad SSPROP_PARAM_UDT_NAME del conjunto de propiedades DBPROPSET_SQLSERVERPARAMETER para los parámetros UDT. De lo contrario, ICommand::Execute devolverá DB_E_ERRORSOCCURRED. Esta interfaz y este conjunto de propiedades se describen más adelante en este tema.

Si un tipo definido por el usuario se inserta en una columna que no es lo suficientemente grande como para contener todos sus datos, ICommand::Execute devuelve S_OK con un estado DB_E_ERRORSOCCURRED.

Las conversiones de datos que proporcionan los servicios principales de OLE DB (IDataConvert) no son aplicables a DBTYPE_UDT. No se admite ningún otro enlace.

Adiciones y cambios en los conjuntos de filas de OLE DB

SQL Server Native Client agrega nuevos valores o cambios a muchos de los conjuntos de filas de esquema básicos de OLE DB.

El conjunto de filas de esquema PROCEDURE_PARAMETERS

Se han realizado las siguientes adiciones al conjunto de filas de esquema PROCEDURE_PARAMETERS.

Nombre de la columna

Tipo

Descripción

SS_UDT_CATALOGNAME

DBTYPE_WSTR

Identificador de nombre de tres partes.

SS_UDT_SCHEMANAME

DBTYPE_WSTR

Identificador de nombre de tres partes.

SS_UDT_NAME

DBTYPE_WSTR

Identificador de nombre de tres partes.

SS_UDT_ASSEMBLY_TYPENAME

DBTYPE_WSTR

Nombre de ensamblado completo, que incluye el nombre de tipo y toda la identificación de ensamblado necesaria a la que debe hacer referencia CLR.

El conjunto de filas de esquema SQL_ASSEMBLIES

El proveedor OLE DB de SQL Server Native Client expone un nuevo conjunto de filas de esquema específico del proveedor que describe los UDT registrados. El servidor ASSEMBLY puede especificarse como DBTYPE_WSTR, pero no está presente en el conjunto de filas. Si no se especifica, el conjunto de filas tendrá como valor predeterminado el servidor actual. El conjunto de filas de esquema SQL_ASSEMBLIES se define en la tabla siguiente.

Nombre de la columna

Tipo

Descripción

ASSEMBLY_CATALOG

DBTYPE_WSTR

Nombre de catálogo del ensamblado que contiene el tipo.

ASSEMBLY_SCHEMA

DBTYPE_WSTR

Nombre de esquema o nombre de propietario del ensamblado que contiene el tipo. Aunque el ámbito de los ensamblados viene determinado por la base de datos y no por el esquema, los ensamblados tienen un propietario que se refleja aquí.

ASSEMBLY_NAME

DBTYPE_WSTR

Nombre del ensamblado que contiene el tipo.

ASSEMBLY_ID

DBTYPE_UI4

Identificador de objeto del ensamblado que contiene el tipo.

PERMISSION_SET

DBTYPE_WSTR

Valor que indica el ámbito de acceso del ensamblado. Entre los valores posibles se incluyen "SAFE", "EXTERNAL_ACCESS" y "UNSAFE".

ASSEMBLY_BINARY

DBTYPE_BYTES

Representación binaria del ensamblado.

El conjunto de filas de esquema SQL_ASSEMBLIES_DEPENDENCIES

El proveedor OLE DB de SQL Server Native Client expone un nuevo conjunto de filas de esquema específico del proveedor que describe las dependencias de ensamblado de un servidor especificado. El autor de la llamada puede especificar ASSEMBLY_SERVER como DBTYPE_WSTR, pero no está presente en el conjunto de filas. Si no se especifica, el conjunto de filas tendrá como valor predeterminado el servidor actual. El conjunto de filas de esquema SQL_ASSEMBLY_DEPENDENCIES se define en la tabla siguiente.

Nombre de la columna

Tipo

Descripción

ASSEMBLY_CATALOG

DBTYPE_WSTR

Nombre de catálogo del ensamblado que contiene el tipo.

ASSEMBLY_SCHEMA

DBTYPE_WSTR

Nombre de esquema o nombre de propietario del ensamblado que contiene el tipo. Aunque el ámbito de los ensamblados viene determinado por la base de datos y no por el esquema, los ensamblados tienen un propietario que se refleja aquí.

ASSEMBLY_ID

DBTYPE_UI4

Identificador de objeto del ensamblado.

REFERENCED_ASSEMBLY_ID

DBTYPE_UI4

Identificador de objeto del ensamblado al que se hace referencia.

El conjunto de filas de esquema SQL_USER_TYPES

El proveedor OLE DB de SQL Server Native Client expone un nuevo conjunto de filas de esquema, SQL_USER_TYPES, que describe cuándo deben agregarse los UDT registrados para un servidor especificado. El autor de la llamada debe especificar UDT_SERVER como DBTYPE_WSTR, pero no está presente en el conjunto de filas. El conjunto de filas de esquema SQL_USER_TYPES se define en la tabla siguiente.

Nombre de la columna

Tipo

Descripción

UDT_CATALOGNAME

DBTYPE_WSTR

Para las columnas UDT, esta propiedad es una cadena que especifica el nombre del catálogo donde se define el UDT.

UDT_SCHEMANAME

DBTYPE_WSTR

Para las columnas UDT, esta propiedad es una cadena que especifica el nombre del esquema donde se define el UDT.

UDT_NAME

DBTYPE_WSTR

Nombre del ensamblado que contiene la clase UDT.

UDT_ASSEMBLY_TYPENAME

DBTYPE_WSTR

El nombre de tipo completo (AQN) incluye el nombre de tipo precedido del espacio de nombres, si procede.

El conjunto de filas de esquema COLUMNS

Las adiciones al conjunto de filas de esquema COLUMNS incluyen las columnas siguientes.

Nombre de la columna

Tipo

Descripción

SS_UDT_CATALOGNAME

DBTYPE_WSTR

Para las columnas UDT, esta propiedad es una cadena que especifica el nombre del catálogo donde se define el UDT.

SS_UDT_SCHEMANAME

DBTYPE_WSTR

Para las columnas UDT, esta propiedad es una cadena que especifica el nombre del esquema donde se define el UDT.

SS_UDT_NAME

DBTYPE_WSTR

Nombre del UDT.

SS_UDT_ASSEMBLY_TYPENAME

DBTYPE_WSTR

El nombre de tipo completo (AQN) incluye el nombre de tipo precedido del espacio de nombres, si procede.

Adiciones y cambios en los conjuntos de propiedades de OLE DB

SQL Server Native Client agrega nuevos valores o cambios a muchos de los conjuntos de propiedades de OLE DB.

El conjunto de propiedades DBPROPSET_SQLSERVERPARAMETER

Para admitir los UDT a través de OLE DB, SQL Server Native Client implementa el nuevo conjunto de propiedades DBPROPSET_SQLSERVERPARAMETER, que contiene los valores siguientes.

Nombre

Tipo

Descripción

SSPROP_PARAM_UDT_CATALOGNAME

DBTYPE_WSTR

Identificador de nombre de tres partes.

Para los parámetros UDT, esta propiedad es una cadena que especifica el nombre del catálogo donde se define el tipo definido por el usuario.

SSPROP_PARAM_UDT_SCHEMANAME

DBTYPE_WSTR

Identificador de nombre de tres partes.

Para los parámetros UDT, esta propiedad es una cadena que especifica el nombre del esquema donde se define el tipo definido por el usuario.

SSPROP_PARAM_UDT_NAME

DBTYPE_WSTR

Identificador de nombre de tres partes.

Para las columnas UDT, esta propiedad es una cadena que especifica el nombre de una sola parte del tipo definido por el usuario.

La propiedad SSPROP_PARAM_UDT_NAME es obligatoria. Las propiedades SSPROP_PARAM_UDT_CATALOGNAME y SSPROP_PARAM_UDT_SCHEMANAME son opcionales. Si alguna de las propiedades se especifica incorrectamente, se devolverá DB_E_ERRORSINCOMMAND. Si no se especifican las propiedades SSPROP_PARAM_UDT_CATALOGNAME y SSPROP_PARAM_UDT_SCHEMANAME, el UDT debe definirse en la misma base de datos y esquema que la tabla. Si la definición UDT no está en el mismo esquema que la tabla (pero está en la misma base de datos), debe especificarse la propiedad SSPROP_PARAM_UDT_SCHEMANAME. Si la definición UDT está en una base de datos diferente, deben especificarse las propiedades SSPROP_PARAM_UDT_CATALOGNAME y SSPROP_PARAM_UDT_SCHEMANAME.

El conjunto de propiedades DBPROPSET_SQLSERVERCOLUMN

Para admitir la creación de tablas en la interfaz ITableDefinition, SQL Server Native Client agrega las siguientes tres nuevas columnas al conjunto de propiedades DBPROPSET_SQLSERVERCOLUMN.

Nombre

Descripción

Tipo

Descripción

SSPROP_COL_UDT_CATALOGNAME

UDT_CATALOGNAME

VT_BSTR

Para las columnas de tipo DBTYPE_UDT, esta propiedad es una cadena que especifica el nombre del catálogo donde se define el UDT.

SSPROP_COL_UDT_SCHEMANAME

UDT_SCHEMANAME

VT_BSTR

Para las columnas de tipo DBTYPE_UDT, esta propiedad es una cadena que especifica el nombre del esquema donde se define el UDT.

SSPROP_COL_UDT_NAME

UDT_NAME

VT_BSTR

Para las columnas de tipo DBTYPE_UDT, esta propiedad es una cadena que especifica el nombre de una sola parte del UDT. Para otros tipos de columna, esta propiedad devuelve una cadena vacía.

Nota

Los UDT no aparecerán en el conjunto de filas de esquema PROVIDER_TYPES. Todas las columnas tienen acceso de lectura y escritura.

ADO hará referencia a estas propiedades utilizando la entrada correspondiente de la columna Descripción.

La propiedad SSPROP_COL_UDTNAME es obligatoria. Las propiedades SSPROP_COL_UDT_CATALOGNAME y SSPROP_COL_UDT_SCHEMANAME son opcionales. Si alguna de las propiedades se especifica incorrectamente, se devolverá DB_E_ERRORSINCOMMAND.

Si no se especifican las propiedades SSPROP_COL_UDT_CATALOGNAME y SSPROP_COL_UDT_SCHEMANAME, el UDT debe definirse en la misma base de datos y esquema que la tabla.

Si la definición UDT no está en el mismo esquema que la tabla (pero está en la misma base de datos), debe especificarse la propiedad SSPROP_COL_UDT_SCHEMANAME.

Si la definición UDT está en una base de datos diferente, deben especificarse las propiedades SSPROP_COL_UDT_CATALOGNAME y SSPROP_COL_UDT_SCHEMANAME.

Adiciones y cambios en las interfaces de OLE DB

SQL Server Native Client agrega nuevos valores o cambios a muchas de las interfaces básicas de OLE DB.

La interfaz ISSCommandWithParameters

Para admitir los UDT a través de OLE DB, SQL Server Native Client implementa diversos cambios, incluida la adición de la interfaz ISSCommandWithParameters. Esta nueva interfaz hereda de la interfaz OLE DB básica ICommandWithParameters. Además de los tres métodos heredados de ICommandWithParameters, GetParameterInfo, MapParameterNames y SetParameterInfo, ISSCommandWithParameters proporciona los métodos SetParameterProperties y GetParameterProperties, que se usan para administrar tipos de datos específicos del servidor.

Nota

La interfaz ISSCommandWithParameters también usa la nueva estructura SSPARAMPROPS.

La interfaz IColumnsRowset

Además de la interfaz ISSCommandWithParameters, SQL Server Native Client también agrega nuevos valores al conjunto de filas que se devuelve al llamar al método IColumnsRowset::GetColumnRowset, incluidos los siguientes.

Nombre de la columna

Tipo

Descripción

DBCOLUMN_SS_UDT_CATALOGNAME

DBTYPE_WSTR

Identificador de nombre de catálogo UDT.

DBCOLUMN_SS_UDT_SCHEMANAME

DBTYPE_WSTR

Identificador de nombre de esquema UDT.

DBCOLUMN_SS_UDT_NAME

DBTYPE_WSTR

Identificador de nombre UDT.

DBCOLUMN_SS_ASSEMBLY_TYPENAME

DBTYPE_WSTR

Nombre de ensamblado completo, que incluye el nombre de tipo y toda la identificación de ensamblado necesaria a la que debe hacer referencia CLR.

Es posible diferenciar una columna UDT del servidor de otros tipos binarios cuando el parámetro DBCOLUMN_TYPE está establecido en DBTYPE_UDT; para ello, hay que examinar los metadatos UDT agregados especificados anteriormente. Si esos datos están parcialmente completos, el tipo del servidor es un UDT. Para los tipos del servidor que no son UDT, estas columnas se devuelven siempre como NULL.

Controlador ODBC de SQL Server Native Client

Se han realizado varios cambios en el controlador ODBC de SQL Server Native Client para admitir los UDT. El controlador ODBC de SQL Server Native Client asigna el UDT de SQL Server al identificador de tipo de datos SQL específico del controlador SQL_SS_UDT. Las columnas UDT se exponen como SQL_SS_UDT. Si asigna explícitamente una columna UDT a otro tipo en una instrucción SQL utilizando los métodos ToXMLString o ToString del UDT o a través de la función CAST/CONVERT, el tipo de la columna del conjunto de resultados refleja el tipo real al que se ha convertido la columna.

SQLColAttribute, SQLDescribeParam, SQLGetDescField

Se han agregado cuatro nuevos campos descriptores específicos del controlador para proporcionar información adicional para una columna UDT de un conjunto de resultados o un parámetro UDT de un procedimiento almacenado o una consulta con parámetros, que deben recuperarse a través de las funciones SQLColAttribute, SQLDescribeParam y SQLGetDescField.

Estos cuatro nuevos campos descriptores que se han agregado son SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME y SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.

SQLColumns, SQLProcedureColumns

Además, se han agregado tres nuevas columnas específicas del controlador al conjunto de resultados devuelto por las funciones SQLColumns y SQLProcedureColumns, para proporcionar información adicional sobre una columna de conjunto de resultados UDT o un parámetro UDT. Estas tres nuevas columnas son SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME y SS_UDT_ASSEMBLY_TYPE_NAME.

Conversiones admitidas

Al convertir tipos de datos de SQL a C, SQL_C_WCHAR, SQL_C_BINARY y SQL_C_CHAR pueden convertirse en SQL_SS_UDT. Tenga en cuenta, no obstante, que los datos binarios se convierten en una cadena hexadecimal cuando se realizan conversiones desde los tipos de datos SQL SQL_C_CHAR y SQL_C_WCHAR.

Al convertir tipos de datos de C a SQL, SQL_C_WCHAR, SQL_C_BINARY y SQL_C_CHAR pueden convertirse en SQL_SS_UDT. Tenga en cuenta, no obstante, que los datos binarios se convierten en una cadena hexadecimal cuando se realizan conversiones desde los tipos de datos SQL SQL_C_CHAR y SQL_C_WCHAR.