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.
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 datos XML UDT |
A datos XML del servidor |
Desde datos XML UDT |
Desde datos XML 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 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 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 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 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 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.
Vea también
Referencia
ISSCommandWithParameters (OLE DB)