SQL Server Native Client에서 사용자 정의 형식 사용

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

Important

SQL Server Native Client(약칭 SNAC)는 SQL Server 2022(16.x) 및 SSMS(SQL Server Management Studio) 19에서 제거되었습니다. SQLNCLI 또는 SQLNCLI11(SQL Server Native Client) 및 레거시 Microsoft OLE DB Provider for SQL Server(SQLOLEDB)는 새 애플리케이션 개발에 권장되지 않습니다. 앞으로 새 SQL Server용 Microsoft OLE DB 드라이버(MSOLEDBSQL) 또는 최신 Microsoft ODBC Driver for SQL Server로 전환합니다. SQL Server 데이터베이스 엔진(버전 2012~2019)의 구성 요소로 제공되는 SQLNCLI의 경우 이 지원 수명 주기 예외를 참조하세요.

SQL Server 2005(9.x)에는 UDT(사용자 정의 형식)가 도입되었습니다. UDT는 SQL Server 데이터베이스에 개체 및 사용자 지정 데이터 구조를 저장할 수 있도록 하여 SQL 형식 시스템을 확장합니다. UDT는 여러 데이터 형식을 포함할 수 있으며 단일 SQL Server 시스템 데이터 형식으로 구성된 기존 별칭 데이터 형식과 구분하여 동작을 가질 수 있습니다. UDT는 확인 가능한 코드를 생성하는 .NET CLR(공용 언어 런타임)에서 지원하는 언어를 사용하여 정의됩니다. 여기에는 C# 및 Visual Basic .NET이 포함됩니다. 데이터는 .NET 클래스 또는 구조체의 필드 및 속성으로 노출되며 동작은 클래스 또는 구조체의 메서드에 의해 정의됩니다.

UDT를 테이블의 열 정의, Transact-SQL 일괄 처리의 변수 또는 Transact-SQL 함수나 저장 프로시저의 인수로 사용할 수 있습니다.

SQL Server Native Client OLE DB 공급자

SQL Server Native Client OLE DB 공급자는 메타데이터 정보를 사용하여 UDT를 이진 형식으로 지원하므로 UDT를 개체로 관리할 수 있습니다. UDT 열은 DBTYPE_UDT 노출되고 해당 메타데이터는 핵심 OLE DB 인터페이스 IColumnRowset 및 새 ISSCommandWithParameters 인터페이스를 통해 노출됩니다 .

참고 항목

IRowsetFind::FindNextRow 메서드는 UDT 데이터 형식과 함께 사용할 수 없습니다. UDT가 검색 열 유형으로 사용되는 경우 DB_E_BADCOMPAREOP가 반환됩니다.

데이터 바인딩 및 강제 변환

다음 표에서는 SQL Server UDT와 함께 나열된 데이터 형식을 사용할 때 발생하는 바인딩 및 강제 변환에 대해 설명합니다. UDT 열은 SQL Server Native Client OLE DB 공급자를 통해 DBTYPE_UDT 노출됩니다. 사용자 고유의 정의된 형식을 개체로 관리할 수 있도록 적절한 스키마 행 집합을 통해 메타데이터를 가져올 수 있습니다.

데이터 형식	To Server UDT	To Server 비 UDT	서버에서 UDT	서버에서 비 UDT
DBTYPE_UDT	지원됨6	오류1	지원됨6	오류5
DBTYPE_BYTES	지원됨6	N/A2	지원됨6	N/A2
DBTYPE_WSTR	지원됨3,6	N/A2	지원되는4,6	N/A2
DBTYPE_BSTR	지원됨3,6	N/A2	지원되는4	N/A2
DBTYPE_STR	지원됨3,6	N/A2	지원되는4,6	N/A2
DBTYPE_IUNKNOWN	지원되지 않음	N/A2	지원되지 않음	N/A2
DBTYPE_VARIANT(VT_UI1 | VT_ARRAY)	지원됨6	N/A2	지원되는4	N/A2
DBTYPE_VARIANT (VT_BSTR)	지원됨3,6	N/A2	해당 없음	N/A2

¹DBTYPE_UDT 이외의 서버 형식이 ICommandWithParameters::SetParameterInfo로 지정되고 접근자 형식이 DBTYPE_UDT 경우 문이 실행될 때 오류가 발생합니다(DB_E_ERRORSOCCURRED; 매개 변수 상태 DBSTATUS_E_BADACCESSOR). 그렇지 않으면 데이터가 서버로 전송되지만 서버는 UDT에서 매개 변수의 데이터 형식으로의 암시적 변환이 없음을 나타내는 오류를 반환합니다.

²이 항목의 범위를 벗어나봅니다.

³ 16진수 문자열에서 이진 데이터로의 데이터 변환이 발생합니다.

⁴ 이진 데이터에서 16진수 문자열로의 데이터 변환이 발생합니다.

⁵유효성 검사는 만들기 접근자 시간 또는 인출 시 오류가 DB_E_ERRORSOCCURRED 바인딩 상태 DBBINDSTATUS_UNSUPPORTEDCONVERSION 설정할 때 발생할 수 있습니다.

⁶BY_REF 사용할 수 있습니다.

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

DBTYPE_UDT DBTYPE_EMPTY 및 DBTYPE_NULL 변환할 수도 있지만 DBTYPE_NULL 및 DBTYPE_EMPTY DBTYPE_UDT 변환할 수 없습니다. 이는 DBTYPE_BYTES 일치합니다.

참고 항목

새 인터페이스는 ICommandWithParameters에서 상속되는 매개 변수인 ISSCommandWithParameters로 UDT를 처리하는 데 사용됩니다. 애플리케이션은 이 인터페이스를 사용하여 UDT 매개 변수에 대해 설정된 DBPROPSET_SQLSERVERPARAMETER 속성의 SSPROP_PARAM_UDT_NAME 이상 설정해야 합니다. 이 작업이 수행 되지 않으면 ICommand::Execute 가 DB_E_ERRORSOCCURRED 반환합니다. 이 인터페이스 및 속성 집합은 이 항목의 뒷부분에 설명되어 있습니다.

사용자 정의 형식이 모든 데이터를 저장할 만큼 크지 않은 열에 삽입되는 경우 ICommand::Execute는 DB_E_ERRORSOCCURRED 상태 있는 S_OK 반환합니다.

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

OLE DB 행 집합 추가 및 변경 내용

SQL Server Native Client는 많은 핵심 OLE DB 스키마 행 집합에 새 값 또는 변경 내용을 추가합니다.

PROCEDURE_PARAMETERS 스키마 행 집합

PROCEDURE_PARAMETERS 스키마 행 집합에 다음이 추가되었습니다.

열 이름	Type	설명
SS_UDT_CATALOGNAME	DBTYPE_WSTR	세 부분으로 구성된 이름 식별자입니다.
SS_UDT_SCHEMANAME	DBTYPE_WSTR	세 부분으로 구성된 이름 식별자입니다.
SS_UDT_NAME	DBTYPE_WSTR	세 부분으로 구성된 이름 식별자입니다.
SS_UDT_ASSEMBLY_TYPENAME	DBTYPE_WSTR	CLR에서 참조하는 데 필요한 형식 이름 및 모든 어셈블리 ID를 포함하는 어셈블리 정규화된 이름입니다.

SQL_ASSEMBLIES 스키마 행 집합

SQL Server Native Client OLE DB 공급자는 등록된 UDT를 설명하는 새 공급자 특정 스키마 행 집합을 노출합니다. ASSEMBLY 서버가 DBTYPE_WSTR로 지정되지만 행 집합에는 없을 수 있습니다. 이 속성이 지정되지 않은 경우 행 집합은 기본적으로 현재 서버를 사용합니다. SQL_ASSEMBLIES 스키마 행 집합은 다음 표에 정의되어 있습니다.

열 이름	Type	설명
ASSEMBLY_CATALOG	DBTYPE_WSTR	형식을 포함하는 어셈블리의 카탈로그 이름입니다.
ASSEMBLY_SCHEMA	DBTYPE_WSTR	형식을 포함하는 어셈블리의 스키마 이름 또는 소유자 이름입니다. 어셈블리는 스키마가 아닌 데이터베이스로 범위가 지정되지만 여기에 반영된 소유자가 있습니다.
ASSEMBLY_NAME	DBTYPE_WSTR	형식을 포함하는 어셈블리의 이름입니다.
ASSEMBLY_ID	DBTYPE_UI4	형식을 포함하는 어셈블리의 개체 ID입니다.
PERMISSION_SET	DBTYPE_WSTR	어셈블리에 대한 액세스 범위를 나타내는 값입니다. 값에는 "SAFE", "EXTERNAL_ACCESS" 및 "UNSAFE"가 포함됩니다.
ASSEMBLY_BINARY	DBTYPE_BYTES	어셈블리의 이진 표현입니다.

SQL_ASSEMBLIES_ 종속성 스키마 행 집합

SQL Server Native Client OLE DB 공급자는 지정된 서버에 대한 어셈블리 종속성을 설명하는 새 공급자별 스키마 행 집합을 노출합니다. ASSEMBLY_SERVER 호출자가 DBTYPE_WSTR 지정할 수 있지만 행 집합에는 없습니다. 이 속성이 지정되지 않은 경우 행 집합은 기본적으로 현재 서버를 사용합니다. SQL_ASSEMBLY_DEPENDENCIES 스키마 행 집합은 다음 표에 정의되어 있습니다.

열 이름	Type	설명
ASSEMBLY_CATALOG	DBTYPE_WSTR	형식을 포함하는 어셈블리의 카탈로그 이름입니다.
ASSEMBLY_SCHEMA	DBTYPE_WSTR	형식을 포함하는 어셈블리의 스키마 이름 또는 소유자 이름입니다. 어셈블리는 스키마가 아닌 데이터베이스로 범위가 지정되지만 여기에 반영된 소유자가 있습니다.
ASSEMBLY_ID	DBTYPE_UI4	어셈블리의 개체 ID입니다.
REFERENCED_ASSEMBLY_ID	DBTYPE_UI4	참조된 어셈블리의 개체 ID입니다.

SQL_USER_TYPES 스키마 행 집합

SQL Server Native Client OLE DB 공급자는 지정된 서버에 등록된 UDT가 추가되는 시기를 설명하는 새 스키마 행 집합인 SQL_USER_TYPES 노출합니다. UDT_SERVER 호출자가 DBTYPE_WSTR 지정해야 하지만 행 집합에는 없습니다. SQL_USER_TYPES 스키마 행 집합은 다음 표에 정의되어 있습니다.

열 이름	Type	설명
UDT_CATALOGNAME	DBTYPE_WSTR	UDT 열의 경우 이 속성은 UDT가 정의된 카탈로그의 이름을 지정하는 문자열입니다.
UDT_SCHEMANAME	DBTYPE_WSTR	UDT 열의 경우 이 속성이 UDT가 정의되어 있는 스키마의 이름을 지정하는 문자열입니다.
UDT_NAME	DBTYPE_WSTR	UDT 클래스를 포함하는 어셈블리의 이름입니다.
UDT_ASSEMBLY_TYPENAME	DBTYPE_WSTR	AQN(전체 형식 이름)에는 해당하는 경우 네임스페이스로 접두사로 지정된 형식 이름이 포함됩니다.

COLUMNS 스키마 행 집합

COLUMNS 스키마 행 집합에 추가된 열에는 다음 열이 포함됩니다.

열 이름	Type	설명
SS_UDT_CATALOGNAME	DBTYPE_WSTR	UDT 열의 경우 이 속성은 UDT가 정의된 카탈로그의 이름을 지정하는 문자열입니다.
SS_UDT_SCHEMANAME	DBTYPE_WSTR	UDT 열의 경우 이 속성이 UDT가 정의되어 있는 스키마의 이름을 지정하는 문자열입니다.
SS_UDT_NAME	DBTYPE_WSTR	UDT의 이름
SS_UDT_ASSEMBLY_TYPENAME	DBTYPE_WSTR	AQN(전체 형식 이름)에는 해당하는 경우 네임스페이스로 접두사로 지정된 형식 이름이 포함됩니다.

OLE DB 속성 집합 추가 및 변경 내용

SQL Server Native Client는 많은 핵심 OLE DB 속성 집합에 새 값 또는 변경 내용을 추가합니다.

DBPROPSET_SQLSERVERPARAMETER 속성 집합

OLE DB를 통해 UDT를 지원하기 위해 SQL Server Native Client는 다음 값을 포함하는 새 DBPROPSET_SQLSERVERPARAMETER 속성 집합을 구현합니다.

이름	형식	설명
SSPROP_PARAM_UDT_CATALOGNAME	DBTYPE_WSTR	세 부분으로 구성된 이름 식별자입니다. UDT 매개 변수의 경우 이 속성은 사용자 정의 형식이 정의된 카탈로그의 이름을 지정하는 문자열입니다.
SSPROP_PARAM_UDT_SCHEMANAME	DBTYPE_WSTR	세 부분으로 구성된 이름 식별자입니다. UDT 매개 변수의 경우 이 속성은 사용자 정의 형식이 정의된 스키마의 이름을 지정하는 문자열입니다.
SSPROP_PARAM_UDT_NAME	DBTYPE_WSTR	세 부분으로 구성된 이름 식별자입니다. UDT 열의 경우 이 속성이 사용자 정의 형식의 단일 부분으로 구성된 이름을 지정하는 문자열입니다.

SSPROP_PARAM_UDT_NAME은 필수입니다. SSPROP_PARAM_UDT_CATALOGNAME 및 SSPROP_PARAM_UDT_SCHEMANAME 선택 사항입니다. 이러한 속성 중 하나가 잘못 지정되면 DB_E_ERRORSINCOMMAND가 반환됩니다. SSPROP_PARAM_UDT_CATALOGNAME 및 SSPROP_PARAM_UDT_SCHEMANAME 모두 지정되지 않은 경우 테이블과 동일한 데이터베이스 및 스키마에 UDT를 정의해야 합니다. UDT 정의가 테이블과 동일한 스키마에 있지 않지만 동일한 데이터베이스에 있는 경우 SSPROP_PARAM_UDT_SCHEMANAME 지정해야 합니다. UDT 정의가 다른 데이터베이스에 있는 경우 SSPROP_PARAM_UDT_CATALOGNAME 및 SSPROP_PARAM_UDT_SCHEMANAME 모두 지정해야 합니다.

DBPROPSET_SQLSERVERCOLUMN 속성 집합

ITableDefinition 인터페이스에서 테이블 만들기를 지원하기 위해 SQL Server Native Client는 DBPROPSET_SQLSERVERCOLUMN 속성 집합에 다음 세 개의 새 열을 추가합니다.

이름	Description	Type	설명
SSPROP_COL_UDT_CATALOGNAME	UDT_CATALOGNAME	VT_BSTR	DBTYPE_UDT 형식 열의 경우 이 속성은 UDT가 정의된 카탈로그의 이름을 지정하는 문자열입니다.
SSPROP_COL_UDT_SCHEMANAME	UDT_SCHEMANAME	VT_BSTR	DBTYPE_UDT 형식 열의 경우 이 속성은 UDT가 정의된 스키마의 이름을 지정하는 문자열입니다.
SSPROP_COL_UDT_NAME	UDT_NAME	VT_BSTR	DBTYPE_UDT 형식 열의 경우 이 속성은 UDT의 단일 부분 이름을 지정하는 문자열입니다. 다른 열 형식의 경우 이 속성은 빈 문자열을 반환합니다.

참고 항목

UDT는 PROVIDER_TYPES 스키마 행 집합에 표시되지 않습니다. 모든 열에는 읽기 및 쓰기 권한이 있습니다.

ADO는 설명 열의 해당 항목을 사용하여 이러한 속성을 참조합니다.

SSPROP_COL_UDTNAME 필수입니다. SSPROP_COL_UDT_CATALOGNAME 및 SSPROP_COL_UDT_SCHEMANAME 선택 사항입니다. 속성이 잘못 지정된 경우 DB_E_ERRORSINCOMMAND 반환됩니다.

SSPROP_COL_UDT_CATALOGNAME 및 SSPROP_COL_UDT_SCHEMANAME이 모두 지정되지 않은 경우 테이블과 동일한 데이터베이스와 스키마에서 UDT를 정의해야 합니다.

UDT 정의가 테이블과 동일한 스키마에 있지 않지만 동일한 데이터베이스에 있는 경우 SSPROP_COL_UDT_SCHEMANAME 지정해야 합니다.

UDT 정의가 다른 데이터베이스에 있는 경우 SSPROP_COL_UDT_CATALOGNAME 및 SSPROP_COL_UDT_SCHEMANAME 모두 지정해야 합니다.

OLE DB 인터페이스 추가 및 변경 내용

SQL Server Native Client는 많은 핵심 OLE DB 인터페이스에 새 값 또는 변경 내용을 추가합니다.

ISSCommandWithParameters 인터페이스

OLE DB를 통해 UDT를 지원하기 위해 SQL Server Native Client는 ISSCommandWithParameters 인터페이스 추가 를 포함하여 다양한 변경 내용을 구현합니다 . 이 새 인터페이스는 핵심 OLE DB 인터페이스인 ICommandWithParameters에서 상속됩니다. ICommandWithParameters에서 상속된 세 가지 메서드 외에; GetParameterInfo, MapParameterNames 및 SetParameterInfo; ISSCommandWithParameters는 서버 특정 데이터 형식을 처리하는 데 사용되는 GetParameterProperties 및 SetParameterProperties 메서드를 제공합니다.

참고 항목

또한 ISSCommandWithParameters 인터페이스는 새 SSPARAMPROPS 구조를 사용합니다.

IColumnsRowset 인터페이스

ISSCommandWithParameters 인터페이스 외에도 SQL Server Native Client는 다음을 포함하여 IColumnsRowset::GetColumnRowset 메서드를 호출하여 반환된 행 집합에 새 값을 추가합니다.

열 이름	Type	설명
DBCOLUMN_SS_UDT_CATALOGNAME	DBTYPE_WSTR	UDT 카탈로그 이름 식별자입니다.
DBCOLUMN_SS_UDT_SCHEMANAME	DBTYPE_WSTR	UDT 스키마 이름 식별자입니다.
DBCOLUMN_SS_UDT_NAME	DBTYPE_WSTR	UDT 이름 식별자입니다.
DBCOLUMN_SS_ASSEMBLY_TYPENAME	DBTYPE_WSTR	형식 이름 및 CLR에서 참조하는 데 필요한 모든 어셈블리 ID를 포함하는 어셈블리 정규화된 이름입니다.

DBCOLUMN_TYPE이 DBTYPE_UDT로 설정되어 있는 경우 위에 지정된 추가적인 UDT 메타데이터를 찾아 서버의 UDT 열을 다른 이진 형식과 구분할 수 있습니다. 해당 데이터가 부분적으로 완료된 경우 서버 유형은 UDT입니다. UDT가 아닌 서버 형식의 경우 이러한 열은 항상 NULL로 반환됩니다.

SQL Server Native Client ODBC 드라이버

UDT를 지원하기 위해 SQL Server Native Client ODBC 드라이버에서 여러 가지 변경 사항이 적용되었습니다. SQL Server Native Client ODBC 드라이버는 SQL Server UDT를 드라이버별 SQL 데이터 형식 식별자를 SQL_SS_UDT 매핑합니다. UDT 열은 SQL_SS_UDT로 표시됩니다. UDT의 ToString 또는 ToXMLString 메서드를 사용하거나 CAST/CONVERT 함수를 통해 SQL 문의 다른 형식에 UDT 열을 명시적으로 매핑하는 경우 결과 집합의 열 형식은 열이 변환된 실제 형식을 반영합니다.

SQLColAttribute, SQLDescribeParam, SQLGetDescField

SQLColAttribute, SQLDescribeParam 및 SQLGetDescField 함수를 통해 검색할 결과 집합의 UDT 열 또는 저장 프로시저/매개 변수가 있는 쿼리의 UDT 매개 변수에 대한 추가 정보를 제공하기 위해 4개의 새로운 드라이버 관련 설명자 필드가 추가되었습니다.

추가된 4개의 새 설명자 필드는 SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME 및 SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.

SQLColumns, SQLProcedureColumns

또한 UDT 결과 집합 열 또는 UDT 매개 변수에 대한 추가 정보를 제공하기 위해 SQLColumns 및 SQLProcedureColumns 함수에서 반환된 결과 집합에 세 개의 새 드라이버 특정 열이 추가됩니다. 이 새로운 세 개의 열은 SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME 및 SS_UDT_ASSEMBLY_TYPE_NAME입니다.

지원되는 변환

SQL에서 C 데이터 형식으로 변환할 때 SQL_C_WCHAR, SQL_C_BINARY 및 SQL_C_CHAR 모두 SQL_SS_UDT 변환할 수 있습니다. 그러나 이진 데이터는 SQL_C_WCHAR 변환하고 SQL 데이터 형식을 SQL_C_CHAR 때 16진수 문자열로 변환됩니다.

C에서 SQL 데이터 형식으로 변환할 때 SQL_C_WCHAR, SQL_C_BINARY 및 SQL_C_CHAR 모두 SQL_SS_UDT 변환할 수 있습니다. 그러나 이진 데이터는 SQL_C_WCHAR 변환하고 SQL 데이터 형식을 SQL_C_CHAR 때 16진수 문자열로 변환됩니다.

참고 항목

SQL Server Native Client 기능
ISSCommandWithParameters(OLE DB)