Menggunakan Jenis yang Didefinisikan oleh Pengguna
Berlaku untuk: 
SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)
SQL Server 2005 (9.x) memperkenalkan jenis yang ditentukan pengguna (UDT). UDT memperluas sistem jenis SQL dengan memungkinkan Anda menyimpan objek dan struktur data kustom dalam database SQL Server. UDT dapat berisi beberapa jenis data dan dapat memiliki perilaku, membedakannya dari jenis data alias tradisional yang terdiri dari satu jenis data sistem SQL Server. UDT didefinisikan menggunakan salah satu bahasa yang didukung oleh runtime bahasa umum .NET (CLR) yang menghasilkan kode yang dapat diverifikasi. Ini termasuk C# dan Visual Basic .NET. Data diekspos sebagai bidang dan properti kelas atau struktur .NET, dan perilaku didefinisikan oleh metode kelas atau struktur.
UDT dapat digunakan sebagai definisi kolom tabel, sebagai variabel dalam batch Transact-SQL, atau sebagai argumen fungsi Transact-SQL atau prosedur tersimpan.
Menggunakan ADO dengan Driver OLE DB untuk SQL Server
Driver OLE DB untuk SQL Server mendukung UDT sebagai jenis biner dengan informasi metadata, yang memungkinkan Anda mengelola UDT sebagai objek. Kolom UDT diekspos sebagai DBTYPE_UDT, dan metadatanya diekspos melalui antarmuka inti OLE DB IColumnRowset, dan antarmuka ISSCommandWithParameters baru.
Catatan
Metode IRowsetFind::FindNextRow tidak berfungsi dengan jenis data UDT. DB_E_BADCOMPAREOP dikembalikan jika UDT digunakan sebagai jenis kolom pencarian.
Pengikatan dan Koersi Data
Tabel berikut ini menjelaskan pengikatan dan pemakaian yang terjadi saat menggunakan jenis data yang tercantum dengan UDT SQL Server. Kolom UDT diekspos melalui Driver OLE DB untuk SQL Server sebagai DBTYPE_UDT. Anda bisa mendapatkan metadata melalui kumpulan baris skema yang sesuai sehingga Anda dapat mengelola jenis yang ditentukan sendiri sebagai objek.
| Jenis Data | Ke Server UDT |
Ke Server non-UDT |
Dari Server UDT |
Dari Server non-UDT |
|---|---|---|---|---|
| DBTYPE_UDT | Didukung6 | Kesalahan1 | Didukung6 | Kesalahan5 |
| DBTYPE_BYTES | Didukung6 | N/A2 | Didukung6 | N/A2 |
| DBTYPE_WSTR | Didukung3,6 | N/A2 | Didukung4,6 | N/A2 |
| DBTYPE_BSTR | Didukung3,6 | N/A2 | Didukung4 | N/A2 |
| DBTYPE_STR | Didukung3,6 | N/A2 | Didukung4,6 | N/A2 |
| DBTYPE_IUNKNOWN | Tidak didukung | N/A2 | Tidak didukung | N/A2 |
| DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) | Didukung6 | N/A2 | Didukung4 | N/A2 |
| DBTYPE_VARIANT (VT_BSTR) | Didukung3,6 | N/A2 | T/A | N/A2 |
1Jika jenis server selain DBTYPE_UDT ditentukan dengan ICommandWithParameters::SetParameterInfo dan jenis aksesor DBTYPE_UDT, kesalahan terjadi ketika pernyataan dijalankan (DB_E_ERRORSOCCURRED; status parameter DBSTATUS_E_BADACCESSOR). Jika tidak, data dikirim ke server, tetapi server mengembalikan kesalahan yang menunjukkan bahwa tidak ada konversi implisit dari UDT ke jenis data parameter.
2Di luar cakupan artikel ini.
3 Konversi data dari string heks ke data biner terjadi.
4 Konversi data dari data biner ke string hex terjadi.
5Validasi dapat terjadi pada waktu pembuatan aksesor, atau pada waktu pengambilan, kesalahan DB_E_ERRORSOCCURRED, status pengikatan diatur ke DBBINDSTATUS_UNSUPPORTEDCONVERSION.
6BY_REF dapat digunakan.
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 atau DBSTATUS_S_DEFAULT.
DBTYPE_UDT juga dapat dikonversi ke DBTYPE_EMPTY dan DBTYPE_NULL, tetapi DBTYPE_NULL dan DBTYPE_EMPTY tidak dapat dikonversi ke DBTYPE_UDT. Ini konsisten dengan DBTYPE_BYTES.
Catatan
Antarmuka baru digunakan untuk menangani UDT sebagai parameter, ISSCommandWithParameters, yang diwarisi dari ICommandWithParameters. Aplikasi harus menggunakan antarmuka ini untuk mengatur setidaknya SSPROP_PARAM_UDT_NAME properti DBPROPSET_SQLSERVERPARAMETER yang ditetapkan untuk parameter UDT. Jika ini tidak dilakukan, ICommand::Execute akan mengembalikan DB_E_ERRORSOCCURRED. Antarmuka dan set properti ini dijelaskan nanti dalam artikel ini.
Jika jenis yang ditentukan pengguna dimasukkan ke dalam kolom yang tidak cukup besar untuk menyimpan semua datanya, ICommand::Execute akan mengembalikan S_OK dengan status DB_E_ERRORSOCCURRED.
Konversi data yang disediakan oleh layanan inti OLE DB (IDataConvert) tidak berlaku untuk DBTYPE_UDT. Tidak ada pengikatan lain yang didukung.
Penambahan dan Perubahan Set Baris OLE DB
Driver OLE DB untuk SQL Server menambahkan nilai atau perubahan baru ke banyak kumpulan baris skema OLE DB inti.
Kumpulan Baris Skema PROCEDURE_PARAMETERS
Penambahan berikut telah dilakukan ke kumpulan baris skema PROCEDURE_PARAMETERS.
| Nama kolom | Tipe | Deskripsi |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Pengidentifikasi nama tiga bagian. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Pengidentifikasi nama tiga bagian. |
| SS_UDT_NAME | DBTYPE_WSTR | Pengidentifikasi nama tiga bagian. |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Nama Memenuhi Syarat Assembly, yang mencakup nama jenis dan semua identifikasi rakitan yang diperlukan untuk dirujuk oleh CLR. |
Kumpulan Baris Skema SQL_ASSEMBLIES
Driver OLE DB untuk SQL Server mengekspos set baris skema khusus penyedia baru yang menjelaskan UDT terdaftar. Server ASSEMBLY dapat ditentukan sebagai DBTYPE_WSTR, tetapi tidak ada dalam set baris. Jika tidak ditentukan, kumpulan baris akan default ke server saat ini. Kumpulan baris skema SQL_ASSEMBLIES ditentukan dalam tabel berikut:
| Nama kolom | Tipe | Deskripsi |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | Nama katalog rakitan yang berisi jenis . |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | Nama skema, atau nama pemilik, dari rakitan yang berisi jenis . Meskipun rakitan dicakup oleh database dan bukan oleh skema, mereka masih memiliki pemilik yang tercermin di sini. |
| ASSEMBLY_NAME | DBTYPE_WSTR | Nama rakitan yang berisi jenis . |
| ASSEMBLY_ID | DBTYPE_UI4 | ID objek rakitan yang berisi jenis . |
| PERMISSION_SET | DBTYPE_WSTR | Nilai yang menunjukkan cakupan akses untuk perakitan. Nilai termasuk "AMAN", "EXTERNAL_ACCESS", dan "TIDAK AMAN". |
| ASSEMBLY_BINARY | DBTYPE_BYTES | Representasi biner rakitan. |
Kumpulan Baris Skema DEPENDENSI SQL_ASSEMBLIES_
Driver OLE DB untuk SQL Server mengekspos set baris skema khusus penyedia baru yang menjelaskan dependensi rakitan untuk server tertentu. ASSEMBLY_SERVER dapat ditentukan oleh pemanggil sebagai DBTYPE_WSTR, tetapi tidak ada dalam set baris. Jika tidak ditentukan, kumpulan baris akan default ke server saat ini. Kumpulan baris skema SQL_ASSEMBLY_DEPENDENCIES ditentukan dalam tabel berikut:
| Nama kolom | Tipe | Deskripsi |
|---|---|---|
| ASSEMBLY_CATALOG | DBTYPE_WSTR | Nama katalog rakitan yang berisi jenis . |
| ASSEMBLY_SCHEMA | DBTYPE_WSTR | Nama skema, atau nama pemilik, dari rakitan yang berisi jenis . Meskipun rakitan dicakup oleh database dan bukan oleh skema, mereka masih memiliki pemilik, yang tercermin di sini. |
| ASSEMBLY_ID | DBTYPE_UI4 | ID objek rakitan. |
| REFERENCED_ASSEMBLY_ID | DBTYPE_UI4 | ID objek dari rakitan yang dirujuk. |
Kumpulan Baris Skema SQL_USER_TYPES
Driver OLE DB untuk SQL Server mengekspos set baris skema baru, SQL_USER_TYPES, yang menjelaskan kapan UDT terdaftar untuk server tertentu ditambahkan. UDT_SERVER harus ditentukan sebagai DBTYPE_WSTR oleh pemanggil tetapi tidak ada di set baris. Kumpulan baris skema SQL_USER_TYPES ditentukan dalam tabel berikut.
| Nama kolom | Tipe | Deskripsi |
|---|---|---|
| UDT_CATALOGNAME | DBTYPE_WSTR | Untuk kolom UDT, properti ini adalah string yang menentukan nama katalog tempat UDT ditentukan. |
| UDT_SCHEMANAME | DBTYPE_WSTR | Untuk kolom UDT, properti ini adalah string yang menentukan nama skema tempat UDT ditentukan. |
| UDT_NAME | DBTYPE_WSTR | Nama assembly yang berisi kelas UDT. |
| UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Nama jenis lengkap (AQN) menyertakan nama jenis yang diawali oleh namespace jika berlaku. |
Kumpulan Baris Skema KOLOM
Penambahan pada kumpulan baris skema KOLOM menyertakan kolom berikut:
| Nama kolom | Tipe | Deskripsi |
|---|---|---|
| SS_UDT_CATALOGNAME | DBTYPE_WSTR | Untuk kolom UDT, properti ini adalah string yang menentukan nama katalog tempat UDT ditentukan. |
| SS_UDT_SCHEMANAME | DBTYPE_WSTR | Untuk kolom UDT, properti ini adalah string yang menentukan nama skema tempat UDT ditentukan. |
| SS_UDT_NAME | DBTYPE_WSTR | Nama UDT |
| SS_UDT_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Nama jenis lengkap (AQN) menyertakan nama jenis yang diawali oleh namespace jika berlaku. |
Penambahan dan Perubahan Kumpulan Properti OLE DB
Driver OLE DB untuk SQL Server menambahkan nilai atau perubahan baru ke banyak kumpulan properti OLE DB inti.
Kumpulan Properti DBPROPSET_SQLSERVERPARAMETER
Untuk mendukung UDT melalui OLE DB, Driver OLE DB untuk SQL Server mengimplementasikan kumpulan properti DBPROPSET_SQLSERVERPARAMETER baru, yang berisi nilai berikut:
| Nama | Tipe | Deskripsi |
|---|---|---|
| SSPROP_PARAM_UDT_CATALOGNAME | DBTYPE_WSTR | Pengidentifikasi nama tiga bagian. Untuk parameter UDT, properti ini adalah string yang menentukan nama katalog tempat jenis yang ditentukan pengguna ditentukan. |
| SSPROP_PARAM_UDT_SCHEMANAME | DBTYPE_WSTR | Pengidentifikasi nama tiga bagian. Untuk parameter UDT, properti ini adalah string yang menentukan nama skema tempat jenis yang ditentukan pengguna ditentukan. |
| SSPROP_PARAM_UDT_NAME | DBTYPE_WSTR | Pengidentifikasi nama tiga bagian. Untuk kolom UDT, properti ini adalah string yang menentukan nama bagian tunggal dari jenis yang ditentukan pengguna. |
SSPROP_PARAM_UDT_NAME wajib. SSPROP_PARAM_UDT_CATALOGNAME dan SSPROP_PARAM_UDT_SCHEMANAME bersifat opsional. Jika salah satu properti ditentukan dengan tidak benar, DB_E_ERRORSINCOMMAND akan dikembalikan. Jika SSPROP_PARAM_UDT_CATALOGNAME dan SSPROP_PARAM_UDT_SCHEMANAME tidak ditentukan, maka UDT harus didefinisikan dalam database dan skema yang sama dengan tabel. Jika definisi UDT tidak dalam skema yang sama dengan tabel (tetapi berada dalam database yang sama), maka SSPROP_PARAM_UDT_SCHEMANAME harus ditentukan. Jika definisi UDT berada dalam database yang berbeda, maka SSPROP_PARAM_UDT_CATALOGNAME dan SSPROP_PARAM_UDT_SCHEMANAME harus ditentukan.
Kumpulan Properti DBPROPSET_SQLSERVERCOLUMN
Untuk mendukung pembuatan tabel di antarmuka ITableDefinition , Driver OLE DB untuk SQL Server menambahkan tiga kolom baru berikut ke kumpulan properti DBPROPSET_SQLSERVERCOLUMN.
| Nama | Deskripsi | Tipe | Deskripsi |
|---|---|---|---|
| SSPROP_COL_UDT_CATALOGNAME | UDT_CATALOGNAME | VT_BSTR | Untuk kolom jenis DBTYPE_UDT, properti ini adalah string yang menentukan nama katalog tempat UDT ditentukan. |
| SSPROP_COL_UDT_SCHEMANAME | UDT_SCHEMANAME | VT_BSTR | Untuk kolom jenis DBTYPE_UDT, properti ini adalah string yang menentukan nama skema tempat UDT ditentukan. |
| SSPROP_COL_UDT_NAME | UDT_NAME | VT_BSTR | Untuk kolom jenis DBTYPE_UDT, properti ini adalah string yang menentukan nama bagian tunggal UDT. Untuk jenis kolom lainnya, properti ini mengembalikan string kosong. |
Catatan
UDT tidak muncul di kumpulan baris skema PROVIDER_TYPES. Semua kolom memiliki akses baca dan tulis.
ADO akan merujuk ke properti ini dengan menggunakan entri terkait di kolom Deskripsi.
SSPROP_COL_UDTNAME wajib. SSPROP_COL_UDT_CATALOGNAME dan SSPROP_COL_UDT_SCHEMANAME bersifat opsional. Jika salah satu properti ditentukan dengan tidak benar, DB_E_ERRORSINCOMMAND akan dikembalikan.
Jika tidak ada SSPROP_COL_UDT_CATALOGNAME atau SSPROP_COL_UDT_SCHEMANAME yang ditentukan, UDT harus didefinisikan dalam database dan skema yang sama dengan tabel.
Jika definisi UDT tidak dalam skema yang sama dengan tabel (tetapi berada dalam database yang sama), SSPROP_COL_UDT_SCHEMANAME harus ditentukan.
Jika definisi UDT berada dalam database yang berbeda, SSPROP_COL_UDT_CATALOGNAME dan SSPROP_COL_UDT_SCHEMANAME harus ditentukan.
Penambahan dan Perubahan Antarmuka OLE DB
Driver OLE DB untuk SQL Server menambahkan nilai atau perubahan baru ke banyak antarmuka OLE DB inti.
Antarmuka ISSCommandWithParameters
Untuk mendukung UDT melalui OLE DB, Driver OLE DB untuk SQL Server menerapkan sejumlah perubahan, termasuk penambahan antarmuka ISSCommandWithParameters . Antarmuka baru ini mewarisi dari antarmuka inti OLE DB ICommandWithParameters. Selain tiga metode yang diwarisi dari ICommandWithParameters; GetParameterInfo, MapParameterNames, dan SetParameterInfo; ISSCommandWithParameters menyediakan metode GetParameterProperties dan SetParameterProperties yang digunakan untuk menangani jenis data spesifik server.
Catatan
Antarmuka ISSCommandWithParameters juga menggunakan struktur SSPARAMPROPS baru.
Antarmuka IColumnsRowset
Selain antarmuka ISSCommandWithParameters , Driver OLE DB untuk SQL Server juga menambahkan nilai baru ke set baris yang dikembalikan dari memanggil metode IColumnsRowset::GetColumnRowset termasuk yang berikut ini.
| Nama kolom | Tipe | Deskripsi |
|---|---|---|
| DBCOLUMN_SS_UDT_CATALOGNAME | DBTYPE_WSTR | Pengidentifikasi nama katalog UDT. |
| DBCOLUMN_SS_UDT_SCHEMANAME | DBTYPE_WSTR | Pengidentifikasi nama skema UDT. |
| DBCOLUMN_SS_UDT_NAME | DBTYPE_WSTR | Pengidentifikasi nama UDT. |
| DBCOLUMN_SS_ASSEMBLY_TYPENAME | DBTYPE_WSTR | Nama assembly yang memenuhi syarat, yang mencakup nama jenis dan semua identifikasi perakitan yang diperlukan untuk dirujuk oleh CLR. |
Anda dapat membedakan kolom UDT server dari jenis biner lain saat DBCOLUMN_TYPE diatur ke DBTYPE_UDT dengan melihat metadata UDT yang ditambahkan yang ditentukan dalam tabel sebelumnya. Jika data tersebut sebagian lengkap, jenis server adalah UDT. Untuk jenis server non-UDT, kolom ini selalu dikembalikan sebagai NULL.
Lihat Juga
Driver OLE DB untuk Fitur SQL Server
ISSCommandWithParameters (OLE DB)
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