큰 CLR 사용자 정의 형식(ODBC)
적용 대상: 
SQL Server Azure SQL 데이터베이스 Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System(PDW)
Important
SNAC(SQL Server Native Client)는 다음과 함께 제공되지 않습니다.
- SQL Server 2022(16.x) 이상 버전
- SQL Server Management Studio 19 이상 버전
SQL Server Native Client(SQLNCLI 또는 SQLNCLI11)와 레거시 Microsoft OLE DB Provider for SQL Server(SQLOLEDB)는 새로운 응용 프로그램 개발에 권장되지 않습니다.
새 프로젝트의 경우 다음 드라이버 중 하나를 사용합니다.
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 | 하위 유형 | Length | Precision | 확장 |
|---|---|---|---|---|---|
| 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 | 하위 유형 | Length | Precision | 확장 |
|---|---|---|---|---|---|
| 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가 반환하는 열 메타데이터(카탈로그 메타데이터)" 섹션에 설명되어 있습니다.