Jenis Yang Ditentukan Pengguna CLR Besar di Klien Asli SQL Server (OLE DB)
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). Penyedia SQL Server Native Client OLE DB (SQLNCLI atau SQLNCLI11) dan Penyedia Microsoft OLE DB warisan untuk SQL Server (SQLOLEDB) tidak direkomendasikan untuk pengembangan baru. Beralih ke Microsoft OLE DB Driver (MSOLEDBSQL) baru untuk SQL Server ke depannya.
Topik ini membahas perubahan pada OLE DB di SQL Server Native Client untuk mendukung jenis (UDT) yang ditentukan pengguna (UDT) runtime bahasa umum (CLR) yang besar.
Untuk informasi selengkapnya tentang dukungan untuk UDT CLR besar di Klien Asli SQL Server, lihat Jenis Yang Ditentukan Pengguna CLR Besar. Untuk sampel, lihat Menggunakan UDT CLR Besar (OLE DB).
Format data
SQL Server Native Client menggunakan ~0 untuk mewakili panjang nilai yang berukuran tidak terbatas untuk jenis objek besar (LOB). ~0 juga mewakili ukuran UDT CLR yang lebih besar dari 8.000 byte.
Tabel berikut ini memperlihatkan pemetaan jenis data dalam parameter dan set baris:
| Tipe data SQL Server | Jenis data OLE DB | Tata letak memori | Nilai |
|---|---|---|---|
| runtime bahasa umum UDT | DBTYPE_UDT | BYTE[](byte array) | 132 (oledb.h) |
Nilai UDT direpresentasikan sebagai array byte. Konversi ke dan dari string hex didukung. Nilai harfiah direpresentasikan sebagai string heksa dengan awalan "0x". String heks adalah representasi tekstual data biner di basis 16. Contohnya adalah konversi dari varbinary jenis server (10) ke DBTYPE_STR, yang menghasilkan representasi heksadesimal 20 karakter di mana setiap pasangan karakter mewakili satu byte.
Properti Parameter
Kumpulan properti DBPROPSET_SQLSERVERPARAMETER mendukung UDT melalui OLE DB. Untuk informasi selengkapnya, lihat Menggunakan Jenis yang Ditentukan Pengguna.
Properti Kolom
Kumpulan properti DBPROPSET_SQLSERVERCOLUMN mendukung pembuatan tabel melalui OLE DB. Untuk informasi selengkapnya, lihat Menggunakan Jenis yang Ditentukan Pengguna.
Pemetaan Tipe Data di ITableDefinition::CreateTable
Informasi berikut digunakan dalam struktur DBCOLUMNDESC yang digunakan oleh ITableDefinition::CreateTable saat kolom UDT diperlukan:
| Tipe data OLE DB (wType) | pwszTypeName | Tipe data SQL Server | rgPropertySets |
|---|---|---|---|
| DBTYPE_UDT | Diabaikan | UDT | Harus menyertakan kumpulan properti DBPROPSET_SQLSERVERCOLUMN. |
ICommandWithParameters::GetParameterInfo
Informasi yang dikembalikan dalam struktur DBPARAMINFO melalui prgParamInfo adalah sebagai berikut:
| Jenis parameter | wType | ulParamSize | bPresisi | bScale | dwFlags DBPARAMFLAGS_ISLONG |
|---|---|---|---|---|---|
| DBTYPE_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
"DBTYPE_UDT" | n | tidak ditentukan | tidak ditentukan | hapus |
| DBTYPE_UDT (panjang lebih besar dari 8.000 byte) |
"DBTYPE_UDT" | ~0 | tidak ditentukan | tidak ditentukan | set |
ICommandWithParameters::SetParameterInfo
Informasi yang diberikan dalam struktur DBPARAMBINDINFO harus sesuai dengan yang berikut:
| Jenis parameter | pwszDataSourceType | ulParamSize | bPresisi | bScale | dwFlags DBPARAMFLAGS_ISLONG |
|---|---|---|---|---|---|
| DBTYPE_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
DBTYPE_UDT | n | diabaikan | diabaikan | Harus diatur jika parameter akan diteruskan menggunakan DBTYPE_IUNKNOWN. |
| DBTYPE_UDT (panjang lebih besar dari 8.000 byte) |
DBTYPE_UDT | ~0 | diabaikan | diabaikan | diabaikan |
ISSCommandWithParameters
Aplikasi menggunakan ISSCommandWithParameters untuk mendapatkan dan mengatur properti parameter yang ditentukan di bagian Properti Parameter.
IColumnsRowset::GetColumnsRowset
Kolom yang dikembalikan adalah sebagai berikut:
| Jenis kolom | DBCOLUMN_TYPE | DBCOLUMN_COLUMNSIZE | DBCOLUMN_PRECISION | DBCOLUMN_SCALE | DBCOLUMN_FLAGS_ISLONG | DBCOLUMNS_ISSEARCHABLE | DBCOLUMN_OCTETLENGTH |
|---|---|---|---|---|---|---|---|
| DBTYPE_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
DBTYPE_UDT | n | NULL | NULL | Clear | DB_ALL_EXCEPT_LIKE | n |
| DBTYPE_UDT (panjang lebih besar dari 8.000 byte) |
DBTYPE_UDT | ~0 | NULL | NULL | Set | DB_ALL_EXCEPT_LIKE | 0 |
Kolom berikut juga ditentukan untuk UDT:
| Pengidentifikasi Kolom | Jenis | Deskripsi |
|---|---|---|
| DBCOLUMN_UDT_CATALOGNAME | DBTYPE_WSTR | Untuk kolom UDT, nama katalog tempat UDT ditentukan. |
| DBCOLUMN_UDT_SCHEMANAME | DBTYPE_WSTR | Untuk kolom UDT, nama skema tempat UDT ditentukan. |
| DBCOLUMN_UDT_NAME | DBTYPE_WSTR | Untuk kolom UDT, nama bagian tunggal UDT. |
| DBCOLUMN_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Untuk kolom UDT, nama jenis lengkap UDT. Nama yang sepenuhnya memenuhi syarat dari jenis rakitan memungkinkan Anda membuat instans objek dari jenis tersebut menggunakan metode Type.GetType. |
IColumnsInfo::GetColumnInfo
Informasi yang dikembalikan dalam struktur DBCOLUMNINFO adalah sebagai berikut:
| Jenis parameter | wType | ulColumnSize | bPresisi | bScale | dwFlags DBCOLUMNFLAGS_ISLONG |
|---|---|---|---|---|---|
| DBTYPE_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
DBTYPE_UDT | n | ~0 | ~0 | Clear |
| DBTYPE_UDT (panjang lebih besar dari 8.000 byte) |
DBTYPE_UDT | ~0 | ~0 | ~0 | Set |
Himpunan Baris KOLOM (Set Baris Skema)
Nilai kolom berikut dikembalikan untuk jenis UDT:
| Jenis kolom | DATA_TYPE | COLUMN_FLAGS, DBCOLUMFLAGS_ISLONG | CHARACTER_OCTET_LENGTH |
|---|---|---|---|
| DBTYPE_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
DBTYPE_UDT | Clear | n |
| DBTYPE_UDT (panjang lebih besar dari 8.000 byte) |
DBTYPE_UDT | Set | 0 |
Kolom tambahan berikut didefinisikan untuk UDT:
| Pengidentifikasi kolom | Jenis | Deskripsi |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Untuk kolom UDT, nama katalog tempat UDT ditentukan. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Untuk kolom UDT, nama skema tempat UDT ditentukan. |
| SS_UDT_NAME | DBTYPE_WSTR | Untuk kolom UDT, nama bagian tunggal UDT. |
| SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Untuk kolom UDT, ini adalah nama jenis lengkap UDT. Nama yang sepenuhnya memenuhi syarat dari jenis rakitan memungkinkan Anda membuat instans objek dari jenis tersebut menggunakan metode Type.GetType. |
Mengenai set baris PROCEDURE_PARAMETERS, DATA_TYPE berisi nilai yang sama dengan kumpulan baris skema KOLOM dan TYPE_NAME berisi UDT. Kolom tambahan yang sama juga ditentukan.
Jenis yang ditentukan pengguna tidak akan muncul di kumpulan baris skema PROVIDER_TYPES.
Pengikatan dan Konversi
| Tpe data pengikatan | UDT ke server | Non-UDT ke server | UDT dari server | Non-UDT dari server |
|---|---|---|---|---|
| DBTYPE_UDT | Didukung (5) | Kesalahan (1) | Didukung (5) | Kesalahan (4) |
| DBTYPE_BYTES | Didukung (5) | T/A | Didukung (5) | T/A |
| DBTYPE_WSTR | Didukung (2), (5) | T/A | Didukung (3), (5), (6) | T/A |
| DBTYPE_BSTR | Didukung (2), (5) | T/A | Didukung (3), (5) | T/A |
| DBTYPE_STR | Didukung (2), (5) | T/A | Didukung (3), (5) | T/A |
| DBTYPE_IUNKNOWN | Didukung (6) | T/A | Didukung (6) | T/A |
| DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) | Didukung (5) | T/A | Didukung (3), (5) | T/A |
| DBTYPE_VARIANT (VT_BSTR) | Didukung (2), (5) | T/A | T/A | T/A |
Kunci ke Simbol
| Simbol | Arti |
|---|---|
| 1 | Jika jenis server selain DBTYPE_UDT ditentukan dengan ICommandWithParameters::SetParameterInfo dan jenis aksesor DBTYPE_UDT, kesalahan terjadi saat pernyataan dijalankan. Kesalahan akan DB_E_ERRORSOCCURRED dan status parameter akan DBSTATUS_E_BADACCESSOR. Ini adalah kesalahan untuk menentukan parameter jenis UDT untuk parameter server yang bukan UDT. |
| 2 | Data dikonversi dari string hex ke data biner. |
| 3 | Data dikonversi dari data biner ke string hex. |
| 4 | Validasi dapat terjadi saat menggunakan CreateAccessor atau GetNextRows. Kesalahannya DB_E_ERRORSOCCURRED. Status pengikatan diatur ke DBBINDSTATUS_UNSUPPORTEDCONVERSION. |
| 5 | BY_REF dapat digunakan. |
| 6 | Parameter UDT dapat diikat sebagai DBTYPE_IUNKNOWN dalam DBBINDING. Pengikatan ke DBTYPE_IUNKNOWN menunjukkan bahwa aplikasi ingin memproses data sebagai aliran menggunakan antarmuka ISequentialStream. Ketika konsumen menentukan wType dalam pengikatan sebagai jenis DBTYPE_IUNKNOWN, dan parameter kolom atau output yang sesuai dari prosedur tersimpan adalah UDT, Klien Asli SQL Server akan mengembalikan ISequentialStream. Untuk parameter input, SQL Server Native Client akan meminta untuk antarmuka ISequentialStream. Anda dapat memilih untuk tidak mengikat panjang data UDT saat menggunakan pengikatan DBTYPE_IUNKNOWN, dalam kasus UDT besar. Namun, panjangnya harus terikat untuk UDT kecil. Parameter DBTYPE_UDT dapat ditentukan sebagai UDT besar jika satu atau beberapa hal berikut ini benar: ulParamParamSize adalah ~0. DBPARAMFLAGS_ISLONG diatur dalam struktur DBPARAMBINDINFO. Untuk data baris, pengikatan DBTYPE_IUNKNOWN hanya diizinkan untuk UDT besar. Anda dapat mengetahui apakah kolom adalah jenis UDT besar dengan menggunakan metode IColumnsInfo::GetColumnInfo pada antarmuka IColumnsInfo objek Rowset atau Command. Kolom DBTYPE_UDT adalah kolom UDT besar jika satu atau beberapa kolom berikut ini benar: bendera DBCOLUMNFLAGS_ISLONG diatur pada dwFlags anggota struktur DBCOLUMNINFO. Anggota ulColumnSize dari DBCOLUMNINFO adalah ~0. |
DBTYPE_NULL dan DBTYPE_EMPTY dapat terikat untuk parameter input, tetapi tidak untuk parameter atau hasil output. Saat terikat untuk parameter input, status harus diatur ke DBSTATUS_S_ISNULL untuk DBTYPE_NULL atau DBSTATUS_S_DEFAULT untuk DBTYPE_EMPTY. DBTYPE_BYREF tidak dapat digunakan dengan DBTYPE_NULL atau DBTYPE_EMPTY.
DBTYPE_UDT juga dapat dikonversi ke DBTYPE_EMPTY dan DBTYPE_NULL. Namun, DBTYPE_NULL dan DBTYPE_EMPTY tidak dapat dikonversi ke DBTYPE_UDT. Ini konsisten dengan DBTYPE_BYTES. ISSCommandWithParameters digunakan untuk memproses UDT sebagai parameter.
Konversi data yang disediakan oleh layanan inti OLE DB (IDataConvert) tidak berlaku untuk DBTYPE_UDT.
Tidak ada pengikatan lain yang didukung.
Perbandingan untuk IRowsetFind
Untuk jenis UDT, hanya perbandingan berikut yang didukung:
EQ
NE
IGNORE
Jika ada perbandingan lain yang dicoba DB_E_BADCOMPAREOP dikembalikan.
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 klien | DBTYPE_UDT (panjang kurang dari atau sama dengan 8.000 byte) |
DBTYPE_UDT (panjang lebih besar dari 8.000 byte) |
|---|---|---|
| SQL Server 2005 | UDT | varbinary(max) |
| SQL Server 2008 dan yang lebih baru | UDT | UDT |
Ketika DataTypeCompatibility (SSPROP_INIT_DATATYPECOMPATIBILITY) diatur ke "80", jenis UDT besar muncul ke klien dengan cara yang sama seperti yang muncul untuk klien tingkat bawah.
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