Jenis Yang Ditentukan Pengguna CLR Besar (ODBC)
Berlaku untuk:
SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)
Penting
SQL Server Native Client (sering disingkat SNAC) telah dihapus dari SQL Server 2022 (16.x) dan SQL Server Management Studio 19 (SSMS). SQL Server Native Client (SQLNCLI atau SQLNCLI11) dan Penyedia Microsoft OLE DB warisan untuk SQL Server (SQLOLEDB) tidak direkomendasikan untuk pengembangan aplikasi baru. Beralih ke Microsoft OLE DB Driver (MSOLEDBSQL) baru untuk SQL Server atau Microsoft ODBC Driver terbaru untuk SQL Server ke depannya. Untuk SQLNCLI yang dikirim sebagai komponen SQL Server Database Engine (versi 2012 hingga 2019), lihat pengecualian Siklus Hidup Dukungan ini.
Topik ini membahas perubahan pada ODBC di SQL Server Native Client untuk mendukung jenis (UDT) yang ditentukan pengguna (UDT) runtime bahasa umum (CLR) yang besar.
Untuk sampel yang menunjukkan dukungan ODBC untuk UDT CLR besar, lihat Dukungan untuk UDT Besar.
Untuk informasi selengkapnya tentang dukungan untuk UDT CLR besar di Klien Asli SQL Server, lihat Jenis Yang Ditentukan Pengguna CLR Besar.
Format data
SQL Server Native Client menggunakan SQL_SS_LENGTH_UNLIMITED untuk menunjukkan bahwa ukuran kolom lebih besar dari 8.000 byte untuk jenis objek besar (LOB). Dimulai dengan SQL Server 2008, nilai yang sama digunakan untuk UDT CLR ketika ukurannya lebih besar dari 8.000 byte.
Nilai UDT direpresentasikan sebagai array byte. Konversi ke dan dari string hex didukung. Nilai harfiah direpresentasikan sebagai string heksa dengan awalan "0x".
Tabel berikut ini memperlihatkan pemetaan jenis data dalam parameter dan tataan hasil:
| Tipe data SQL Server | Tipe data SQL | Nilai |
|---|---|---|
| runtime bahasa umum UDT | SQL_SS_UDT | -151 (sqlncli.h) |
Tabel berikut membahas struktur yang sesuai dan tipe ODBC C. Pada dasarnya, CLR UDT adalah jenis varbinary dengan metadata tambahan.
| Tipe data SQL | Tata letak memori | Jenis data C | Nilai (sqlext.h) |
|---|---|---|---|
| SQL_SS_UDT | SQLCHAR *(karakter tidak ditandatangani *) | SQL_C_BINARY | SQL_BINARY (-2) |
Bidang Deskriptor untuk Parameter
Informasi yang dikembalikan di bidang IPD adalah sebagai berikut:
| Bidang deskriptor | SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
|---|---|---|
| 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 | Nama katalog yang berisi UDT. | Nama katalog yang berisi UDT. |
| SQL_CA_SS_UDT_SCHEMA_NAME | Nama skema yang berisi UDT. | Nama skema berisi UDT. |
| SQL_CA_SS_UDT_TYPE_NAME | Nama UDT. | Nama UDT. |
| SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME | Nama UDT yang sepenuhnya memenuhi syarat. | Nama UDT yang sepenuhnya memenuhi syarat. |
Untuk parameter UDT, SQL_CA_SS_UDT_TYPE_NAME harus selalu diatur melalui SQLSetDescField. SQL_CA_SS_UDT_CATALOG_NAME dan SQL_CA_SS_UDT_SCHEMA_NAME bersifat opsional.
Jika UDT didefinisikan dalam database yang sama dengan skema yang berbeda dari tabel, SQL_CA_SS_UDT_SCHEMA_NAME harus diatur.
Jika UDT ditentukan dalam database yang berbeda dari tabel, SQL_CA_SS_UDT_CATALOG_NAME dan SQL_CA_SS_UDT_SCHEMA_NAME harus diatur.
Jika ada kesalahan atau kelalaian dalam pengaturan untuk SQL_CA_SS_UDT_TYPE_NAME, SQL_CA_SS_UDT_CATALOG_NAME, atau SQL_CA_SS_UDT_SCHEMA_NAME, rekaman diagnostik dihasilkan dengan SQLSTATE HY000 dan teks pesan khusus server.
Bidang Deskriptor untuk Hasil
Informasi yang dikembalikan dalam bidang IRD adalah sebagai berikut:
| Bidang deskriptor | SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
|---|---|---|
| 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 | Nama katalog yang berisi UDT. | Nama katalog yang berisi UDT. |
| SQL_CA_SS_UDT_SCHEMA_NAME | Nama skema yang berisi UDT. | Nama skema yang berisi UDT. |
| SQL_CA_SS_UDT_TYPE_NAME | Nama UDT. | Nama UDT. |
| SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME | Nama UDT yang sepenuhnya memenuhi syarat. | Nama UDT yang sepenuhnya memenuhi syarat. |
Metadata Kolom yang Dikembalikan oleh SQLColumns dan SQLProcedureColumns (Metadata Katalog)
Nilai kolom berikut dikembalikan untuk UDT:
| Nama kolom | SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
|---|---|---|
| DATA_TYPE | SQL_SS_UDT | SQL_SS_UDT |
| TYPE_NAME | Nama UDT. | Nama 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 | Nama katalog yang berisi UDT. | Nama katalog yang berisi UDT. |
| SS_UDT_SCHEMA_NAME | Nama skema yang berisi UDT. | Nama skema yang berisi UDT. |
| SS_UDT_ASSEMBLY_TYPE_NAME | Nama UDT yang sepenuhnya memenuhi syarat. | Nama UDT yang sepenuhnya memenuhi syarat. |
Tiga kolom terakhir adalah kolom khusus driver. Kolom ditambahkan setelah kolom yang ditentukan ODBC, tetapi sebelum kolom khusus driver yang ada dari kumpulan hasil SQLColumns atau SQLProcedureColumns.
Tidak ada baris yang dikembalikan oleh SQLGetTypeInfo, untuk UDT individual atau untuk jenis generik "udt".
Pengikatan dan Konversi
Konversi yang didukung dari jenis data SQL ke C adalah sebagai berikut:
| Konversi ke dan dari: | SQL_SS_UDT |
|---|---|
| SQL_C_WCHAR | Didukung* |
| SQL_C_BINARY | Didukung |
| SQL_C_CHAR | Didukung* |
* Data biner dikonversi menjadi string hex.
Konversi yang didukung dari jenis data C ke SQL adalah sebagai berikut:
| Konversi ke dan dari: | SQL_SS_UDT |
|---|---|
| SQL_C_WCHAR | Didukung* |
| SQL_C_BINARY | Didukung |
| SQL_C_CHAR | Didukung* |
* String Hex ke konversi data biner terjadi.
Dukungan SQL_VARIANT untuk UDT
UDT tidak didukung di kolom SQL_VARIANT.
Dukungan BCP untuk UDT
Nilai UDT hanya dapat diimpor dan diekspor sebagai nilai karakter atau biner.
Perilaku Klien Tingkat Bawah untuk UDT
UDT tunduk pada pemetaan jenis dengan klien tingkat bawah, sebagai berikut:
| Versi server | SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
|---|---|---|
| SQL Server 2005 | UDT | varbinary(max) |
| SQL Server 2008 dan yang lebih baru | UDT | UDT |
Fungsi ODBC Mendukung UDT CLR Besar
Bagian ini membahas perubahan pada fungsi ODBC SQL Server Native Client untuk mendukung UDT CLR besar.
SQLBindCol
Nilai kolom hasil UDT dikonversi dari jenis data SQL ke C seperti yang dijelaskan di bagian "Pengikatan dan Konversi", sebelumnya dalam topik ini.
SQLBindParameter
Nilai yang diperlukan untuk UDT adalah sebagai berikut:
| Tipe data SQL | Jenis parameter | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLColAttribute
Nilai yang dikembalikan untuk UDT seperti yang dijelaskan di bagian "Bidang Deskriptor untuk Hasil", sebelumnya dalam topik ini.
SQLColumns
Nilai yang dikembalikan untuk UDT seperti yang dijelaskan di bagian "Metadata Kolom yang Dikembalikan oleh SQLColumns dan SQLProcedureColumns (Metadata Katalog)", sebelumnya dalam topik ini.
SQLDescribeCol
Nilai yang dikembalikan untuk UDT adalah sebagai berikut:
| Tipe data SQL | DataTypePtr | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLDescribeParam
Nilai yang dikembalikan untuk UDT adalah sebagai berikut:
| Tipe data SQL | DataTypePtr | ColumnSizePtr | DecimalDigitsPtr |
|---|---|---|---|
| SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT | n | 0 |
| SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
SQL_SS_UDT | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLFetch
Nilai kolom hasil UDT dikonversi dari jenis data SQL ke C seperti yang dijelaskan di bagian "Pengikatan dan Konversi", sebelumnya dalam topik ini.
SQLFetchScroll
Nilai kolom hasil UDT dikonversi dari jenis data SQL ke C seperti yang dijelaskan di bagian "Pengikatan dan Konversi", sebelumnya dalam topik ini.
SQLGetData
Nilai kolom hasil UDT dikonversi dari jenis data SQL ke C seperti yang dijelaskan di bagian "Pengikatan dan Konversi", sebelumnya dalam topik ini.
SQLGetDescField
Bidang deskriptor yang tersedia dengan jenis baru dijelaskan di bagian "Bidang Deskriptor untuk Parameter" dan "Bidang Deskriptor untuk Hasil", sebelumnya dalam topik ini.
SQLGetDescRec
Nilai yang dikembalikan untuk UDT adalah sebagai berikut:
| Tipe data SQL | Jenis | SubType | Panjang | Presisi | Skala |
|---|---|---|---|---|---|
| SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT | 0 | n | n | 0 |
| SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
SQL_SS_UDT | 0 | SQL_SS_LENGTH_UNLIMITED (0) | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLGetTypeInfo
Nilai yang dikembalikan untuk UDT seperti yang dijelaskan di bagian "Metadata Dikembalikan oleh SQLColumns dan SQLProcedureColumns (Metadata Katalog)", sebelumnya dalam topik ini.
SQLProcedureColumns
Nilai yang dikembalikan untuk UDT seperti yang dijelaskan di bagian "Metadata Dikembalikan oleh SQLColumns dan SQLProcedureColumns (Metadata Katalog)", sebelumnya dalam topik ini.
SQLPutData
Nilai parameter UDT dikonversi dari jenis data C ke SQL seperti yang dijelaskan di bagian "Pengikatan dan Konversi", sebelumnya dalam topik ini.
SQLSetDescField
Bidang deskriptor yang tersedia dengan jenis baru dijelaskan di bagian "Bidang Deskriptor untuk Parameter" dan "Bidang Deskriptor untuk Hasil", sebelumnya dalam topik ini.
SQLSetDescRec
Nilai yang diizinkan untuk UDT adalah sebagai berikut:
| Tipe data SQL | Jenis | SubType | Panjang | Presisi | Skala |
|---|---|---|---|---|---|
| SQL_SS_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
SQL_SS_UDT | 0 | n | n | 0 |
| SQL_SS_UDT (panjang lebih besar dari 8.000 byte) |
SQL_SS_UDT | 0 | SQL_SS_LENGTH_UNLIMITED (0) | SQL_SS_LENGTH_UNLIMITED (0) | 0 |
SQLSpecialColumns
Nilai yang dikembalikan untuk kolom DATA_TYPE, TYPE_NAME, COLUMN_SIZE, BUFFER_LENGTH, dan UDT DECIMAL_DIGTS seperti yang dijelaskan di bagian "Metadata Dikembalikan oleh SQLColumns dan SQLProcedureColumns (Catalog Metadata)", sebelumnya dalam topik ini.
Lihat Juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk