큰 CLR 사용자 정의 형식(ODBC)

적용 대상:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System(PDW)

Important

SQL Server Native Client(약칭 SNAC)는 SQL Server 2022(16.x) 및 SSMS(SQL Server Management Studio) 19에서 제거되었습니다. SQL Server Native Client(SQLNCLI 또는 SQLNCLI11) 및 레거시 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의 경우 이 지원 수명 주기 예외를 참조하세요.

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

큰 CLR UDT에 대한 ODBC 지원을 보여 주는 샘플은 큰 UDT에 대한 지원을 참조 하세요.

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

데이터 형식

SQL Server Native Client는 SQL_SS_LENGTH_UNLIMITED 사용하여 열 크기가 LOB(큰 개체) 형식에 대해 8,000바이트보다 크다는 것을 나타냅니다. SQL Server 2008부터 크기가 8,000바이트보다 큰 경우 CLR UDT에 동일한 값이 사용됩니다.

UDT 값은 바이트 배열로 나타납니다. 16진수 문자열과 16진수 문자열의 변환이 지원됩니다. 리터럴 값은 접두사 "0x"가 있는 16진수 문자열로 표시됩니다.

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

SQL Server 데이터 형식 SQL 데이터 형식
CLR UDT SQL_SS_UDT -151(sqlncli.h)

다음 표에서는 해당 구조체 및 ODBC C 형식에 대해 설명합니다. 기본적으로 CLR UDT는 추가 메타데이터가 있는 varbinary 형식입니다.

SQL 데이터 형식 메모리 레이아웃 C 데이터 형식 값(sqlext.h)
SQL_SS_UDT SQLCHAR *(unsigned char *) SQL_C_BINARY SQL_BINARY(-2)

매개 변수에 대한 설명자 필드

IPD 필드에 반환되는 정보는 다음과 같습니다.

설명자 필드 SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
SQL_DESC_CASE_SENSITIVE SQL_FALSE SQL_FALSE
SQL_DESC_CONCISE_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DESC_DATETIME_INTERVAL_CODE 0 0
SQL_DESC_DATETIME_INTERVAL_PRECISION n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_FIXED_PREC_SCALE SQL_FALSE SQL_FALSE
SQL_DESC_LENGTH n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_LOCAL_TYPE_NAME "udt" "udt"
SQL_DESC_OCTET_LENGTH n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_PRECISION n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_SCALE 0 0
SQL_DESC_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DESC_TYPE_NAME "udt" "udt"
SQL_DESC_UNSIGNED SQL_TRUE SQL_TRUE
SQL_CA_SS_UDT_CATALOG_NAME UDT를 포함하는 카탈로그의 이름입니다. UDT를 포함하는 카탈로그의 이름입니다.
SQL_CA_SS_UDT_SCHEMA_NAME UDT를 포함하는 스키마의 이름입니다. UDT를 포함하는 스키마의 이름입니다.
SQL_CA_SS_UDT_TYPE_NAME UDT의 이름입니다. UDT의 이름입니다.
SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME UDT의 정규화된 이름입니다. UDT의 정규화된 이름입니다.

UDT 매개 변수의 경우 SQL_CA_SS_UDT_TYPE_NAME 항상 SQLSetDescField를 통해 설정해야 합니다. SQL_CA_SS_UDT_CATALOG_NAME 및 SQL_CA_SS_UDT_SCHEMA_NAME 선택 사항입니다.

UDT가 테이블과 다른 스키마를 사용하여 동일한 데이터베이스에 정의된 경우 SQL_CA_SS_UDT_SCHEMA_NAME 설정해야 합니다.

UDT가 테이블과 다른 데이터베이스에 정의되어 있으면 SQL_CA_SS_UDT_CATALOG_NAME 및 SQL_CA_SS_UDT_SCHEMA_NAME을 설정해야 합니다.

SQL_CA_SS_UDT_TYPE_NAME, SQL_CA_SS_UDT_CATALOG_NAME 또는 SQL_CA_SS_UDT_SCHEMA_NAME 대한 설정에 오류 또는 누락이 있는 경우 SQLSTATE HY000 및 서버별 메시지 텍스트를 사용하여 진단 레코드가 생성됩니다.

결과에 대한 설명자 필드

IRD 필드에 반환되는 정보는 다음과 같습니다.

설명자 필드 SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
SQL_DESC_AUTO_UNIQUE_VALUE SQL_FALSE SQL_FALSE
SQL_DESC_CASE_SENSITIVE SQL_FALSE SQL_FALSE
SQL_DESC_CONCISE_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DESC_DATETIME_INTERVAL_CODE 0 0
SQL_DESC_DATETIME_INTERVAL_PRECISION n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_DISPLAY_SIZE 2n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_FIXED_PREC_SCALE SQL_FALSE SQL_FALSE
SQL_DESC_LENGTH n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_LITERAL_PREFIX "0x" "0x"
SQL_DESC_LITERAL_SUFFIX "" ""
SQL_DESC_LOCAL_TYPE_NAME "udt" "udt"
SQL_DESC_OCTET_LENGTH n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_PRECISION n SQL_SS_LENGTH_UNLIMITED (0)
SQL_DESC_SCALE 0 0
SQL_DESC_SEARCHABLE SQL_PRED_NONE SQL_PRED_NONE
SQL_DESC_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DESC_TYPE_NAME "udt" "udt"
SQL_DESC_UNSIGNED SQL_TRUE SQL_TRUE
SQL_CA_SS_UDT_CATALOG_NAME UDT를 포함하는 카탈로그의 이름입니다. UDT를 포함하는 카탈로그의 이름입니다.
SQL_CA_SS_UDT_SCHEMA_NAME UDT를 포함하는 스키마의 이름입니다. UDT를 포함하는 스키마의 이름입니다.
SQL_CA_SS_UDT_TYPE_NAME UDT의 이름입니다. UDT의 이름입니다.
SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME UDT의 정규화된 이름입니다. UDT의 정규화된 이름입니다.

SQLColumns 및 SQLProcedureColumns가 반환하는 열 메타데이터(카탈로그 메타데이터)

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

열 이름 SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
DATA_TYPE SQL_SS_UDT SQL_SS_UDT
TYPE_NAME UDT의 이름입니다. UDT의 이름입니다.
COLUMN_SIZE n SQL_SS_LENGTH_UNLIMITED (0)
BUFFER_LENGTH n SQL_SS_LENGTH_UNLIMITED (0)
DECIMAL_DIGITS NULL NULL
SQL_DATA_TYPE SQL_SS_UDT SQL_SS_UDT
SQL_DATETIME_SUB NULL NULL
CHAR_OCTET_LENGTH n SQL_SS_LENGTH_UNLIMITED (0)
SS_UDT_CATALOG_NAME UDT를 포함하는 카탈로그의 이름입니다. UDT를 포함하는 카탈로그의 이름입니다.
SS_UDT_SCHEMA_NAME UDT를 포함하는 스키마의 이름입니다. UDT를 포함하는 스키마의 이름입니다.
SS_UDT_ASSEMBLY_TYPE_NAME UDT의 정규화된 이름입니다. UDT의 정규화된 이름입니다.

마지막 세 열은 드라이버별 열입니다. ODBC 정의 열 뒤가 아니라 SQLColumns 또는 SQLProcedureColumns 결과 집합의 기존 드라이버별 열 앞에 추가됩니다.

SQLGetTypeInfo, 개별 UDT 또는 제네릭 형식 "udt"에 대해 반환되는 행은 없습니다.

바인딩 및 변환

SQL에서 C 데이터 형식으로의 지원되는 변환은 다음과 같습니다.

변환에서 다음을 수행합니다. SQL_SS_UDT
SQL_C_WCHAR 지원*
SQL_C_BINARY 지원됨
SQL_C_CHAR 지원*

* 이진 데이터는 16진수 문자열로 변환됩니다.

C에서 SQL 데이터 형식으로의 지원되는 변환은 다음과 같습니다.

변환에서 다음을 수행합니다. SQL_SS_UDT
SQL_C_WCHAR 지원*
SQL_C_BINARY 지원됨
SQL_C_CHAR 지원*

* 16진수 문자열을 이진 데이터로 변환합니다.

UDT에 대한 SQL_VARIANT 지원

UDT는 SQL_VARIANT 열에서 지원되지 않습니다.

UDT에 대한 BCP 지원

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

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

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

서버 버전 SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
SQL Server 2005 UDT varbinary(max)
SQL Server 2008 이상 UDT UDT

큰 CLR UDT를 지원하는 ODBC 함수

이 섹션에서는 큰 CLR UDT를 지원하는 SQL Server Native Client ODBC 함수의 변경 내용에 대해 설명합니다.

Sqlbindcol

UDT 결과 열 값은 이 항목의 앞부분에 있는 "바인딩 및 변환" 섹션에 설명된 대로 SQL에서 C 데이터 형식으로 변환됩니다.

SQLBindParameter

UDT에 필요한 값은 다음과 같습니다.

SQL 데이터 형식 Parametertype ColumnSizePtr DecimalDigitsPtr
SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT n 0
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
SQL_SS_UDT SQL_SS_LENGTH_UNLIMITED (0) 0

SQLColAttribute

UDT에 대해 반환되는 값은 이 항목의 앞부분에 있는 "결과의 설명자 필드" 섹션에 설명되어 있습니다.

SQLColumns

UDT에 대해 반환되는 값은 이 항목의 앞부분에 있는 "SQLColumns 및 SQLProcedureColumns(카탈로그 메타데이터)에서 반환된 열 메타데이터" 섹션에 설명되어 있습니다.

SQLDescribeCol

UDT에 대해 반환되는 값은 다음과 같습니다.

SQL 데이터 형식 DataTypePtr ColumnSizePtr DecimalDigitsPtr
SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT n 0
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
SQL_SS_UDT SQL_SS_LENGTH_UNLIMITED (0) 0

SQLDescribeParam

UDT에 대해 반환되는 값은 다음과 같습니다.

SQL 데이터 형식 DataTypePtr ColumnSizePtr DecimalDigitsPtr
SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT n 0
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
SQL_SS_UDT SQL_SS_LENGTH_UNLIMITED (0) 0

SQLFetch

UDT 결과 열 값은 이 항목의 앞부분에 있는 "바인딩 및 변환" 섹션에 설명된 대로 SQL에서 C 데이터 형식으로 변환됩니다.

SQLFetchScroll

UDT 결과 열 값은 이 항목의 앞부분에 있는 "바인딩 및 변환" 섹션에 설명된 대로 SQL에서 C 데이터 형식으로 변환됩니다.

SQLGetData

UDT 결과 열 값은 이 항목의 앞부분에 있는 "바인딩 및 변환" 섹션에 설명된 대로 SQL에서 C 데이터 형식으로 변환됩니다.

SQLGetDescField

새 형식에서 사용할 수 있는 설명자 필드는 이 항목의 앞부분에 나오는 "매개 변수 설명자 필드" 및 "결과에 대한 설명자 필드" 섹션에 설명되어 있습니다.

SQLGetDescRec

UDT에 대해 반환되는 값은 다음과 같습니다.

SQL 데이터 형식 Type 하위 유형 길이 자릿수 확장
SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT 0 n n 0
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
SQL_SS_UDT 0 SQL_SS_LENGTH_UNLIMITED (0) SQL_SS_LENGTH_UNLIMITED (0) 0

SQLGetTypeInfo

UDT에 대해 반환되는 값은 이 항목의 앞부분에 있는 "SQLColumns 및 SQLProcedureColumns(카탈로그 메타데이터)에서 반환된 메타데이터" 섹션에 설명되어 있습니다.

SQLProcedureColumns

UDT에 대해 반환되는 값은 이 항목의 앞부분에 있는 "SQLColumns 및 SQLProcedureColumns(카탈로그 메타데이터)에서 반환된 메타데이터" 섹션에 설명되어 있습니다.

SQLPutData

UDT 매개 변수 값은 이 항목의 앞부분에 있는 "바인딩 및 변환" 섹션에 설명된 대로 C에서 SQL 데이터 형식으로 변환됩니다.

SQLSetDescField

새 형식에서 사용할 수 있는 설명자 필드는 이 항목의 앞부분에 나오는 "매개 변수 설명자 필드" 및 "결과에 대한 설명자 필드" 섹션에 설명되어 있습니다.

SQLSetDescRec

UDT에 허용되는 값은 다음과 같습니다.

SQL 데이터 형식 Type 하위 유형 길이 자릿수 확장
SQL_SS_UDT

(길이가 8,000바이트보다 작거나 같음)
SQL_SS_UDT 0 n n 0
SQL_SS_UDT

(길이가 8,000바이트보다 큼)
SQL_SS_UDT 0 SQL_SS_LENGTH_UNLIMITED (0) SQL_SS_LENGTH_UNLIMITED (0) 0

SQLSpecialColumns

DATA_TYPE, TYPE_NAME, COLUMN_SIZE, BUFFER_LENGTH 및 DECIMAL_DIGTS UDT 열에 대해 반환되는 값은 이 항목의 앞부분에 있는 "SQLColumns 및 SQLProcedureColumns가 반환하는 열 메타데이터(카탈로그 메타데이터)" 섹션에 설명되어 있습니다.

참고 항목

큰 CLR 사용자 정의 형식