Menggunakan Jenis yang Ditentukan Pengguna di Klien Asli SQL Server
Berlaku untuk:
SQL Server Azure SQL Database
Azure Synapse Analytics Analytics Platform 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 disarankan 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.
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.
Penyedia OLE DB Klien Asli SQL Server
Penyedia SQL Server Native Client OLE DB 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 penyedia SQL Server Native Client OLE DB 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 topik 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 topik 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
Klien Asli 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 | Jenis | 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
Penyedia SQL Server Native Client OLE DB mengekspos kumpulan 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 | Jenis | 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_
Penyedia SQL Server Native Client OLE DB mengekspos kumpulan 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 | Jenis | 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
Penyedia SQL Server Native Client OLE DB 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 | Jenis | 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 | Jenis | 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
SQL Server Native Client menambahkan nilai atau perubahan baru ke banyak kumpulan properti OLE DB inti.
Kumpulan Properti DBPROPSET_SQLSERVERPARAMETER
Untuk mendukung UDT melalui OLE DB, SQL Server Native Client 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 secara salah 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 , SQL Server Native Client menambahkan tiga kolom baru berikut ke kumpulan properti DBPROPSET_SQLSERVERCOLUMN.
| Nama | Deskripsi | Jenis | 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
SQL Server Native Client menambahkan nilai atau perubahan baru ke banyak antarmuka OLE DB inti.
Antarmuka ISSCommandWithParameters
Untuk mendukung UDT melalui OLE DB, SQL Server Native Client mengimplementasikan 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 , SQL Server Native Client juga menambahkan nilai baru ke set baris yang dikembalikan dari memanggil metode IColumnsRowset::GetColumnRowset termasuk yang berikut ini.
| Nama kolom | Jenis | 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 lainnya saat DBCOLUMN_TYPE diatur ke DBTYPE_UDT dengan melihat metadata UDT tambahan yang ditentukan di atas. Jika data tersebut sebagian lengkap, jenis server adalah UDT. Untuk jenis server non-UDT, kolom ini selalu dikembalikan sebagai NULL.
Driver ODBC Klien Asli SQL Server
Sejumlah perubahan telah dilakukan di driver ODBC SQL Server Native Client untuk mendukung UDT. Driver ODBC SQL Server Native Client memetakan UDT SQL Server ke SQL_SS_UDT pengidentifikasi jenis data SQL khusus driver. Kolom UDT muncul sebagai SQL_SS_UDT. Jika Anda memetakan kolom UDT secara eksplisit ke jenis lain dalam pernyataan SQL dengan menggunakan metode ToString atau ToXMLString dari UDT atau melalui fungsi CAST/CONVERT , jenis kolom dalam kumpulan hasil mencerminkan jenis aktual kolom yang dikonversi ke
SQLColAttribute, SQLDescribeParam, SQLGetDescField
Empat bidang deskriptor khusus driver baru telah ditambahkan untuk memberikan informasi tambahan untuk kolom UDT dari kumpulan hasil, atau parameter UDT dari prosedur tersimpan/kueri berparameter, yang akan diambil melalui fungsi SQLColAttribute, SQLDescribeParam, dan SQLGetDescField.
Empat bidang deskriptor baru yang telah ditambahkan adalah SQL_CA_SS_UDT_CATALOG_NAME, SQL_CA_SS_UDT_SCHEMA_NAME, SQL_CA_SS_UDT_TYPE_NAME, dan SQL_CA_SS_UDT_ASSEMBLY_TYPE_NAME.
SQLColumns, SQLProcedureColumns
Selain itu, tiga kolom khusus driver baru ditambahkan ke kumpulan hasil yang dikembalikan dari fungsi SQLColumns dan SQLProcedureColumns untuk memberikan informasi tambahan tentang kolom kumpulan hasil UDT atau parameter UDT. Ketiga kolom baru ini SS_UDT_CATALOG_NAME, SS_UDT_SCHEMA_NAME, dan SS_UDT_ASSEMBLY_TYPE_NAME.
Konversi yang Didukung
Saat mengonversi dari jenis data SQL ke C, SQL_C_WCHAR, SQL_C_BINARY, dan SQL_C_CHAR semuanya dapat dikonversi ke SQL_SS_UDT. Namun, perhatikan bahwa data biner dikonversi ke string hex saat mengonversi dari jenis data SQL SQL_C_WCHAR dan SQL_C_CHAR.
Saat mengonversi dari jenis data C ke SQL, SQL_C_WCHAR, SQL_C_BINARY, dan SQL_C_CHAR semuanya dapat dikonversi ke SQL_SS_UDT. Namun, perhatikan bahwa data biner dikonversi ke string hex saat mengonversi dari jenis data SQL SQL_C_WCHAR dan SQL_C_CHAR.
Lihat Juga
Fitur Klien Asli 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