SQL Server Native Client의 대규모 CLR 사용자 정의 형식(OLE DB)

적용 대상: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System(PDW)

Important

SQL Server Native Client(약칭 SNAC)는 SQL Server 2022(16.x) 및 SSMS(SQL Server Management Studio) 19에서 제거되었습니다. SQL Server Native Client OLE DB 공급자(SQLNCLI 또는 SQLNCLI11)와 레거시 Microsoft OLE DB Provider for SQL Server(SQLOLEDB)는 모두 새로운 개발에 권장되지 않습니다. 앞으로 SQL Server용 새 Microsoft OLE DB 드라이버(MSOLEDBSQL)로 전환합니다.

이 항목에서는 큰 CLR(공용 언어 런타임) UDT(사용자 정의 형식)를 지원하도록 SQL Server Native Client의 OLE DB 변경 내용에 대해 설명합니다.

SQL Server Native Client의 큰 CLR UDT 지원에 대한 자세한 내용은 큰 CLR 사용자 정의 형식을 참조 하세요. 샘플은 큰 CLR UDT 사용(OLE DB)을 참조하세요.

데이터 형식

SQL Server Native Client는 ~0을 사용하여 LOB(큰 개체) 형식의 크기가 무제한인 값의 길이를 나타냅니다. ~0은 8,000바이트보다 큰 CLR UDT의 크기도 나타냅니다.

다음 표에서는 매개 변수 및 행 집합의 데이터 형식 매핑을 보여 줍니다.

SQL Server 데이터 형식	OLE DB 데이터 형식	메모리 레이아웃	값
CLR UDT	DBTYPE_UDT	BYTE[](바이트 배열)	132(oledb.h)

UDT 값은 바이트 배열로 나타납니다. 16진수 문자열과 16진수 문자열의 변환이 지원됩니다. 리터럴 값은 접두사 "0x"가 있는 16진수 문자열로 표시됩니다. 16진수 문자열은 base 16에서 이진 데이터의 텍스트 표현입니다. 예를 들어 서버 형식 varbinary(10)를 DBTYPE_STR로 변환하는 경우 모든 문자 쌍이 단일 바이트를 나타내는 20자의 16진수 표현이 생성됩니다.

매개 변수 속성

DBPROPSET_SQLSERVERPARAMETER 속성 집합은 OLE DB를 통해 UDT를 지원합니다. 자세한 내용은 사용자 정의 형식 사용을 참조 하세요.

열 속성

DBPROPSET_SQLSERVERCOLUMN 속성 집합은 OLE DB를 통해 테이블 만들기를 지원합니다. 자세한 내용은 사용자 정의 형식 사용을 참조 하세요.

ITableDefinition::CreateTable의 데이터 형식 매핑

다음 정보는 UDT 열이 필요한 경우 ITableDefinition::CreateTable에서 사용하는 DBCOLUMNDESC 구조체에 사용됩니다.

OLE DB 데이터 형식(wType)	pwszTypeName	SQL Server 데이터 형식	rgPropertySets
DBTYPE_UDT	무시됨	UDT	DBPROPSET_SQLSERVERCOLUMN 속성 집합을 포함해야 합니다.

ICommandWithParameters::GetParameterInfo

prgParamInfo를 통해 DBPARAMINFO 구조에 반환된 정보는 다음과 같습니다.

매개 변수 형식	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	초기화	DB_ALL_EXCEPT_LIKE	n
DBTYPE_UDT (길이가 8,000바이트보다 큼)	DBTYPE_UDT	~0	NULL	NULL	설정	DB_ALL_EXCEPT_LIKE	0

UDT에 대해 다음 열도 정의됩니다.

열 식별자	Type	설명
DBCOLUMN_UDT_CATALOGNAME	DBTYPE_WSTR	UDT 열의 경우 UDT가 정의된 카탈로그의 이름입니다.
DBCOLUMN_UDT_SCHEMANAME	DBTYPE_WSTR	UDT 열의 경우 UDT가 정의된 스키마의 이름입니다.
DBCOLUMN_UDT_NAME	DBTYPE_WSTR	UDT 열의 경우 UDT의 단일 부분 이름입니다.
DBCOLUMN_ASSEMBLY_TYPENAME	DBTYPE_WSTR	UDT 열의 경우 UDT의 전체 형식 이름입니다. 어셈블리 형식의 정규화된 이름을 사용하면 Type.GetType 메서드를 사용하여 해당 형식의 개체를 인스턴스화할 수 있습니다.

IColumnsInfo::GetColumnInfo

DBCOLUMNINFO 구조에 반환되는 정보는 다음과 같습니다.

매개 변수 형식	wType	ulColumnSize	bPrecision	bScale	dwFlags DBCOLUMNFLAGS_ISLONG
DBTYPE_UDT (길이가 8,000바이트보다 작거나 같음)	DBTYPE_UDT	n	~0	~0	초기화
DBTYPE_UDT (길이가 8,000바이트보다 큼)	DBTYPE_UDT	~0	~0	~0	설정

COLUMNS 행 집합(스키마 행 집합)

UDT 형식에 대해 다음 열 값이 반환됩니다.

열 유형	DATA_TYPE	COLUMN_FLAGS, DBCOLUMFLAGS_ISLONG	CHARACTER_OCTET_LENGTH
DBTYPE_UDT (길이가 8,000바이트보다 작거나 같음)	DBTYPE_UDT	초기화	n
DBTYPE_UDT (길이가 8,000바이트보다 큼)	DBTYPE_UDT	설정	0

다음 추가 열은 UDT에 대해 정의됩니다.

열 식별자	Type	설명
SS_UDT_CATALOGNAME	DBTYPE_WSTR	UDT 열의 경우 UDT가 정의된 카탈로그의 이름입니다.
SS_UDT_SCHEMANAME	DBTYPE_WSTR	UDT 열의 경우 UDT가 정의된 스키마의 이름입니다.
SS_UDT_NAME	DBTYPE_WSTR	UDT 열의 경우 UDT의 단일 부분 이름입니다.
SS_ASSEMBLY_TYPENAME	DBTYPE_WSTR	UDT 열의 경우 UDT의 전체 형식 이름입니다. 어셈블리 형식의 정규화된 이름을 사용하면 Type.GetType 메서드를 사용하여 해당 형식의 개체를 인스턴스화할 수 있습니다.

PROCEDURE_PARAMETERS 행 집합과 관련하여 DATA_TYPE COLUMNS 스키마 행 집합과 동일한 값을 포함하고 TYPE_NAME UDT를 포함합니다. 동일한 추가 열도 정의됩니다.

사용자 정의 형식은 PROVIDER_TYPES 스키마 행 집합에 표시되지 않습니다.

바인딩 및 변환

바인딩 데이터 형식	서버로 UDT	비 UDT에서 서버로	서버에서 UDT로	서버에서 비 UDT로
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가 됩니다. UDT가 아닌 서버 매개 변수에 대해 UDT 형식의 매개 변수를 지정하는 것은 오류입니다.
2	데이터는 16진수 문자열에서 이진 데이터로 변환됩니다.
3	데이터는 이진 데이터에서 16진수 문자열로 변환됩니다.
4	CreateAccessor 또는 GetNextRows를 사용할 때 유효성 검사가 수행됩니다. 오류는 DB_E_ERRORSOCCURRED이고 바인딩 상태는 DBBINDSTATUS_UNSUPPORTEDCONVERSION으로 설정됩니다.
5	BY_REF 사용할 수 있습니다.
6	UDT 매개 변수를 DBBINDING의 DBTYPE_IUNKNOWN으로 바인딩할 수 있습니다. DBTYPE_IUNKNOWN 바인딩은 애플리케이션이 ISequentialStream 인터페이스를 사용하여 데이터를 스트림으로 처리하려고 했음을 나타냅니다. 소비자가 바인딩의 wType을 DBTYPE_IUNKNOWN 형식으로 지정하고 저장 프로시저의 해당 열 또는 출력 매개 변수가 UDT인 경우 SQL Server Native Client는 ISequentialStream을 반환합니다. 입력 매개 변수의 경우 SQL Server Native Client는 ISequentialStream 인터페이스에 대해 쿼리합니다. 큰 UDT의 경우 DBTYPE_IUNKNOWN 바인딩을 사용하는 동안 UDT 데이터의 길이를 바인딩하지 않도록 선택할 수 있습니다. 그러나 길이는 작은 UDT에 바인딩되어야 합니다. 다음 중 하나 이상이 true이면 DBTYPE_UDT 매개 변수를 큰 UDT로 지정할 수 있습니다. ulParamParamSize 는 ~0입니다. DBPARAMFLAGS_ISLONG DBPARAMBINDINFO 구조체에 설정됩니다. 행 데이터의 경우 DBTYPE_IUNKNOWN 바인딩만 큰 UDT에 사용할 수 있습니다. Rowset 또는 Command 개체의 IColumnsInfo 인터페이스에서 IColumnsInfo::GetColumnInfo 메서드를 사용하여 열이 큰 UDT 형식인지 확인할 수 있습니다. 다음 중 하나 이상이 true인 경우 DBTYPE_UDT 열은 큰 UDT 열입니다. DBCOLUMNFLAGS_ISLONG 플래그가 DBCOLUMNINFO 구조의 dwFlags 멤버에 설정되어 있습니다. DBCOLUMNINFO의 ulColumnSize 멤버는 ~0입니다.

DBTYPE_NULL 및 DBTYPE_EMPTY 입력 매개 변수에 바인딩할 수 있지만 출력 매개 변수 또는 결과에는 바인딩할 수 없습니다. 입력 매개 변수에 바인딩된 경우 상태는 DBTYPE_EMPTY 대한 DBTYPE_NULL 또는 DBSTATUS_S_DEFAULT DBSTATUS_S_ISNULL 설정해야 합니다. DBTYPE_BYREF는 DBTYPE_NULL 또는 DBTYPE_EMPTY에 사용할 수 없습니다.

DBTYPE_UDT DBTYPE_EMPTY 및 DBTYPE_NULL 변환할 수도 있습니다. 그러나 DBTYPE_NULL 및 DBTYPE_EMPTY DBTYPE_UDT 변환할 수 없습니다. 이는 DBTYPE_BYTES 일치합니다. ISSCommandWithParameters 는 UDT를 매개 변수로 처리하는 데 사용됩니다.

OLE DB 핵심 서비스(IDataConvert)에서 제공하는 데이터 변환은 DBTYPE_UDT 적용되지 않습니다.

다른 바인딩은 지원되지 않습니다.

IRowsetFind 비교

UDT 형식의 경우 다음 비교만 지원됩니다.

• EQ

• NE

• IGNORE

다른 비교를 시도하면 DB_E_BADCOMPAREOP 반환됩니다.

UDT에 대한 BCP 지원

UDT 값은 문자나 이진 값으로만 가져오고 내보낼 수 있습니다.

UDT에 대한 하위 수준 클라이언트 동작

UDT에 적용되는 하위 수준 클라이언트와의 유형 매핑은 다음과 같습니다.

클라이언트 버전	DBTYPE_UDT (길이가 8,000바이트보다 작거나 같음)	DBTYPE_UDT (길이가 8,000바이트보다 큼)
SQL Server 2005	UDT	varbinary(max)
SQL Server 2008 이상	UDT	UDT

SSPROP_INIT_DATATYPECOMPATIBILITY(DataTypeCompatibility)를 "80"으로 설정하면 하위 수준 클라이언트에 대해 표시되는 것과 동일한 방식으로 큰 UDT 형식이 클라이언트에 표시됩니다.

참고 항목

큰 CLR 사용자 정의 형식