Большие определяемые пользователем типы данных CLR (OLE DB)

Статья
05/23/2023

Применимо к: SQL Server Azure SQL Database Управляемый экземпляр SQL Azure Azure Synapse Analytics Analytics Platform System (PDW)

Скачать драйвер OLE DB

В этой статье описываются изменения OLE DB в драйвере OLE DB для SQL Server, связанные с поддержкой больших пользовательских типов данных среды CLR.

Дополнительные сведения о поддержке больших определяемых пользователем типов данных CLR в OLE DB Driver for SQL Server см. в этой статье. Пример см. в статье Использование определяемых пользователем типов больших данных CLR (OLE DB).

Формат данных

Драйвер OLE DB для SQL Server использует значение ~0 для представления значений с неограниченным размером типа больших объектов. Значение ~0 также представляет размер определяемых пользователем типов данных CLR, превышающий 8 000 байт.

В следующей таблице показано сопоставление типов данных в параметрах и наборах строк.

Тип данных SQL Server	Тип данных OLE DB	Организация памяти	Значение
определяемый пользователем тип среды CLR	DBTYPE_UDT	BYTE[] (массив байт)	132 (oledb.h)

Значения определяемых пользователем типов представляются в виде массивов байт. Поддерживается преобразование данных в шестнадцатеричные строки и из шестнадцатеричных строк. Литеральные значения представляются в виде шестнадцатеричных строк с префиксом «0x». Шестнадцатеричная строка является текстовым представлением двоичных данных с основанием 16. Например, при преобразовании из серверного типа varbinary(10) в тип DBTYPE_STR получается шестнадцатеричное представление длиной в 20 символов, в котором каждая пара символов представляет один байт.

Свойства параметра

Набор свойств DBPROPSET_SQLSERVERPARAMETER поддерживает определяемый пользователем тип через OLE DB. Дополнительные сведения см. в статье Использование пользовательских типов.

Свойства столбца

Набор свойств DBPROPSET_SQLSERVERCOLUMN поддерживает создание таблиц через OLE DB. Дополнительные сведения см. в статье Использование пользовательских типов.

Сопоставление типов данных в методе ITableDefinition::CreateTable

Следующие сведения используются в структурах DBCOLUMNDESC, применяемых методом ITableDefinition::CreateTable, когда требуются столбцы пользовательских типов:

тип данных OLE DB (wType)	pwszTypeName	Тип данных SQL Server	rgPropertySets
DBTYPE_UDT	Не учитывается	(UDT)	Должен включать набор свойств DBPROPSET_SQLSERVERCOLUMN.

ICommandWithParameters::GetParameterInfo

В структуру DBPARAMINFO через prgParamInfo возвращаются указанные ниже сведения.

Тип параметра	wType	ulParamSize	bPrecision	bScale	dwFlags DBPARAMFLAGS_ISLONG
DBTYPE_UDT (длина не более 8 000 байт)	"DBTYPE_UDT"	n	неопределенный	неопределенный	clear
DBTYPE_UDT (длина более 8 000 байт)	"DBTYPE_UDT"	~0	неопределенный	неопределенный	set

ICommandWithParameters::SetParameterInfo

Сведения, предоставленные в структуре DBPARAMBINDINFO, должны соответствовать следующим требованиям.

Тип параметра	pwszDataSourceType	ulParamSize	bPrecision	bScale	dwFlags DBPARAMFLAGS_ISLONG
DBTYPE_UDT (длина не более 8 000 байт)	DBTYPE_UDT	n	не учитывается	не учитывается	Должен быть задан, если параметр передается с помощью DBTYPE_IUNKNOWN.
DBTYPE_UDT (длина более 8 000 байт)	DBTYPE_UDT	~0	не учитывается	не учитывается	не учитывается

ISSCommandWithParameters

Чтобы вернуть и задать свойства параметров, определенные в разделе "Свойства параметров", приложения используют интерфейс ISSCommandWithParameters.

IColumnsRowset::GetColumnsRowset

Возвращаются следующие столбцы.

Тип столбца	DBCOLUMN_TYPE	DBCOLUMN_COLUMNSIZE	DBCOLUMN_PRECISION	DBCOLUMN_SCALE	DBCOLUMN_FLAGS_ISLONG	DBCOLUMNS_ISSEARCHABLE	DBCOLUMN_OCTETLENGTH
DBTYPE_UDT (длина не более 8 000 байт)	DBTYPE_UDT	n	NULL	NULL	Clear	DB_ALL_EXCEPT_LIKE	n
DBTYPE_UDT (длина более 8 000 байт)	DBTYPE_UDT	~0	NULL	NULL	Присвойте параметру	DB_ALL_EXCEPT_LIKE	0

Для определяемых пользователем типов определяются также следующие столбцы.

Идентификатор столбца	Тип	Description
DBCOLUMN_UDT_CATALOGNAME	DBTYPE_WSTR	Для столбцов определяемого пользователем типа — имя каталога, в котором определен тип, определяемый пользователем.
DBCOLUMN_UDT_SCHEMANAME	DBTYPE_WSTR	Для столбцов определяемого пользователем типа — имя схемы, в которой определен тип, определяемый пользователем.
DBCOLUMN_UDT_NAME	DBTYPE_WSTR	Для столбцов определяемого пользователем типа — однокомпонентное имя типа.
DBCOLUMN_ASSEMBLY_TYPENAME	DBTYPE_WSTR	Для столбцов определяемого пользователем типа — полное имя типа. Полное имя типа сборки позволяет создать экземпляр объекта этого типа с помощью метода Type.GetType.

IColumnsInfo::GetColumnInfo

В структуру DBCOLUMNINFO возвращаются следующие сведения.

Тип параметра	wType	ulColumnSize	bPrecision	bScale	dwFlags DBCOLUMNFLAGS_ISLONG
DBTYPE_UDT (длина не более 8 000 байт)	DBTYPE_UDT	n	~0	~0	Clear
DBTYPE_UDT (длина более 8 000 байт)	DBTYPE_UDT	~0	~0	~0	Присвойте параметру

Набор строк COLUMNS (наборы строк схемы)

Для определяемых пользователем типов возвращаются значения следующих столбцов.

Тип столбца	DATA_TYPE	COLUMN_FLAGS, DBCOLUMFLAGS_ISLONG	CHARACTER_OCTET_LENGTH
DBTYPE_UDT (длина не более 8 000 байт)	DBTYPE_UDT	Clear	n
DBTYPE_UDT (длина более 8 000 байт)	DBTYPE_UDT	Присвойте параметру	0

Для определяемых пользователем типов определяются также следующие дополнительные столбцы.

Идентификатор столбца	Тип	Description
SS_UDT_CATALOGNAME	DBTYPE_WSTR	Для столбцов определяемого пользователем типа — имя каталога, в котором определен тип, определяемый пользователем.
SS_UDT_SCHEMANAME	DBTYPE_WSTR	Для столбцов определяемого пользователем типа — имя схемы, в которой определен тип, определяемый пользователем.
SS_UDT_NAME	DBTYPE_WSTR	Для столбцов определяемого пользователем типа — однокомпонентное имя типа.
SS_ASSEMBLY_TYPENAME	DBTYPE_WSTR	Для столбцов определяемого пользователем типа — полное имя типа. Полное имя типа сборки позволяет создать экземпляр объекта этого типа с помощью метода Type.GetType.

Что касается набора строк PROCEDURE_PARAMETERS, DATA_TYPE содержит те же значения, что и набор строк схемы COLUMNS, а TYPE_NAME содержит определяемые пользователем типы. Такие же дополнительные столбцы также определены.

Определяемые пользователем типы не появятся в наборе строк схемы PROVIDER_TYPES.

Привязки и преобразования

Привязка типов данных	Определяемый пользователем тип к серверному типу	Тип, не определяемый пользователем, к серверному типу	Серверный тип к определяемому пользователем типу	Серверный тип к типу, не определяемому пользователем
DBTYPE_UDT	Поддерживается (5)	Ошибка (1)	Поддерживается (5)	Ошибка (4)
DBTYPE_BYTES	Поддерживается (5)	Недоступно	Поддерживается (5)	Недоступно
DBTYPE_WSTR	Поддерживается (2), (5)	Недоступно	Поддерживается (3), (5), (6)	Недоступно
DBTYPE_BSTR	Поддерживается (2), (5)	Недоступно	Поддерживается (3), (5)	Недоступно
DBTYPE_STR	Поддерживается (2), (5)	Недоступно	Поддерживается (3), (5)	Недоступно
DBTYPE_IUNKNOWN	Поддерживается (6)	Недоступно	Поддерживается (6)	Недоступно
DBTYPE_VARIANT (VT_UI1 \| VT_ARRAY)	Поддерживается (5)	Недоступно	Поддерживается (3), (5)	Недоступно
DBTYPE_VARIANT (VT_BSTR)	Поддерживается (2), (5)	Недоступно	Н/Д	Недоступно

Расшифровка символов

Символ	Значение
1	Если серверный тип, отличный от DBTYPE_UDT, указан с помощью метода ICommandWithParameters::SetParameterInfo, а тип метода доступа — DBTYPE_UDT, то при выполнении инструкции возникает ошибка. Будет возвращена ошибка DB_E_ERRORSOCCURRED, и состояние параметра будет DBSTATUS_E_BADACCESSOR. Ошибкой является указание параметра определяемого пользователем типа для серверного параметра, тип которого отличен от определяемого пользователем типа.
2	Данные преобразуются из шестнадцатеричной строки в двоичные данные.
3	Данные преобразуются из двоичных данных в шестнадцатеричную строку.
4	При использовании метода CreateAccessor или GetNextRows может быть выполнена проверка. Ошибка DB_E_ERRORSOCCURRED. Состояние привязки установлено в значение DBBINDSTATUS_UNSUPPORTEDCONVERSION.
5	Может использоваться BY_REF.
6	Параметры определяемого пользователем типа могут быть привязаны в структуре DBBINDING как DBTYPE_IUNKNOWN. Привязка к DBTYPE_IUNKNOWN показывает, что приложению необходимо обработать данные в виде потока с помощью интерфейса ISequentialStream. Если потребитель указывает в привязке wType как тип DBTYPE_IUNKNOWN, а соответствующий столбец или выходной параметр хранимой процедуры имеет определяемый пользователем тип, то OLE DB Driver for SQL Server возвратит интерфейс ISequentialStream. Для входного параметра OLE DB Driver for SQL Server запросит объект с интерфейсом ISequentialStream. В случае больших определяемых пользователем типов можно не привязывать длину данных определяемого пользователем типа при использовании привязки DBTYPE_IUNKNOWN. Однако для маленьких определяемых пользователем типов необходимо выполнять привязку длины. Для параметра DBTYPE_UDT можно указать большой определяемый пользователем тип, если выполняется одно или более из следующих условий. ulParamParamSize is ~0. В структуре DBPARAMBINDINFO установлен флаг DBPARAMFLAGS_ISLONG. Для строковых данных привязка DBTYPE_IUNKNOWN разрешена только для больших определяемых пользователем типов. Чтобы проверить, содержит ли столбец данные большого определяемого пользователем типа, примените метод IColumnsInfo::GetColumnInfo к интерфейсу IColumnsInfo объекта Rowset или Command. Столбец DBTYPE_UDT имеет большой определяемый пользователь тип, если выполняется по крайней мере одно из следующих условий. Установлен флаг DBCOLUMNFLAGS_ISLONG для элемента dwFlags структуры DBCOLUMNINFO. Элемент структуры DBCOLUMNINFO с номером ulColumnSize имеет значение ~0.

Типы DBTYPE_NULL и DBTYPE_EMPTY могут быть привязаны только для входных параметров. Они не могут быть привязаны для выходных параметров или результатов. Если они привязаны для входных параметров, состояние должно быть установлено в значение DBSTATUS_S_ISNULL для типа DBTYPE_NULL или DBSTATUS_S_DEFAULT для типа DBTYPE_EMPTY. DBTYPE_BYREF невозможно использовать с типом DBTYPE_NULL или DBTYPE_EMPTY.

Тип DBTYPE_UDT может также быть преобразован в тип DBTYPE_EMPTY или DBTYPE_NULL. Однако типы DBTYPE_NULL и DBTYPE_EMPTY невозможно преобразовать в тип DBTYPE_UDT. Это правило обеспечивает согласование с DBTYPE_BYTES. Чтобы обрабатывать пользовательские типы как параметры, используется интерфейс ISSCommandWithParameters.

Преобразования данных, выполняемые основными службами OLE DB (IDataConvert), неприменимы к типу DBTYPE_UDT.

Другие привязки не поддерживаются.

Сравнимость для IRowsetFind

Для определяемых пользователем типов поддерживаются только следующие сравнения:

EQ
NE
IGNORE

При попытке любого другого сравнения возвращается ошибка DB_E_BADCOMPAREOP.

Поддержка программы bcp для определяемых пользователем типов

Значения определяемых пользователем типов можно импортировать и экспортировать только в виде символьных и двоичных значений.

Поведение клиентов низкого уровня с определяемыми пользователем типами

Определяемые пользователем типы проходят сопоставление типов с клиентами низкого уровня, как показано далее.

Версия клиента	DBTYPE_UDT (длина не более 8 000 байт)	DBTYPE_UDT (длина более 8 000 байт)
SQL Server 2005	(UDT)	varbinary(max)
SQL Server 2008 и более поздние версии	(UDT)	(UDT)

Если DataTypeCompatibility (SSPROP_INIT_DATATYPECOMPATIBILITY) имеет значение 80, то большие пользовательские типы представляются всем клиентам так же, как клиентам низкого уровня.

См. также:

Большие определяемые пользователем типы данных CLR