Bagikan melalui

Menggunakan Jenis Data XML

  • Artikel

Berlaku untuk: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

Unduh driver OLE DB

SQL Server 2005 (9.x) memperkenalkan jenis data xml yang memungkinkan Anda menyimpan dokumen XML dan fragmen dalam database SQL Server. Jenis data xml adalah jenis data bawaan di SQL Server, dan dalam beberapa cara mirip dengan jenis bawaan lainnya, seperti int dan varchar. Seperti jenis bawaan lainnya, Anda dapat menggunakan jenis data xml sebagai jenis kolom saat membuat tabel; sebagai jenis variabel, jenis parameter, atau jenis pengembalian fungsi; atau dalam fungsi CAST dan CONVERT.

Pertimbangan Pemrograman

XML dapat menjelaskan sendiri karena dapat secara opsional menyertakan header XML yang menentukan pengodean dokumen, misalnya:

<?xml version="1.0" encoding="windows-1252"?><doc/>

Standar XML menjelaskan bagaimana prosesor XML dapat mendeteksi pengodean yang digunakan untuk dokumen dengan memeriksa beberapa byte pertama dokumen. Ada peluang untuk pengodean yang ditentukan oleh aplikasi untuk bertentangan dengan pengodean yang ditentukan oleh dokumen. Untuk dokumen yang diteruskan sebagai parameter terikat, XML diperlakukan sebagai data biner oleh SQL Server, sehingga tidak ada konversi yang dibuat dan pengurai XML dapat menggunakan pengodean yang ditentukan dalam dokumen tanpa masalah. Namun, untuk data XML yang terikat sebagai WSTR, maka aplikasi harus memastikan bahwa dokumen dikodekan sebagai Unicode. Skenario ini mungkin memerlukan pemuatan dokumen ke dalam DOM, mengubah pengodean ke Unicode, dan menserialisasikan dokumen. Jika langkah ini tidak dilakukan, konversi data dapat terjadi, yang mengakibatkan XML tidak valid atau rusak.

Ada juga potensi konflik ketika XML ditentukan dalam literal. Misalnya berikut ini tidak valid:

INSERT INTO xmltable(xmlcol) VALUES('<?xml version="1.0" encoding="UTF-16"?><doc/>')

INSERT INTO xmltable(xmlcol) VALUES(N'<?xml version="1.0" encoding="UTF-8"?><doc/>')

Menggunakan ADO dengan Driver OLE DB untuk SQL Server

DBTYPE_XML adalah jenis data baru khusus untuk XML di Driver OLE DB untuk SQL Server. Selain itu, data XML dapat diakses melalui jenis DBTYPE_BYTES, DBTYPE_WSTR, DBTYPE_BSTR, DBTYPE_XML, DBTYPE_STR, DBTYPE_VARIANT, dan DBTYPE_IUNKNOWN OLE DB yang ada. Data yang disimpan dalam kolom jenis XML dapat diambil dari kolom dalam kumpulan baris Driver OLE DB untuk SQL Server dalam format berikut:

  • String teks

  • ISequentialStream

Catatan

Driver OLE DB untuk SQL Server tidak menyertakan pembaca SAX, tetapi ISequentialStream dapat dengan mudah diteruskan ke objek SAX dan DOM di MSXML.

ISequentialStream harus digunakan untuk pengambilan dokumen XML besar. Teknik yang sama yang digunakan untuk jenis nilai besar lainnya juga berlaku untuk XML. Untuk informasi selengkapnya, lihat Menggunakan Jenis Nilai Besar.

Data yang disimpan dalam kolom jenis XML dalam set baris juga dapat diambil, disisipkan, atau diperbarui oleh aplikasi melalui antarmuka yang biasa seperti IRow::GetColumns, IRowChange::SetColumns, dan ICommand::Execute. Demikian pula dengan kasus pengambilan, program aplikasi dapat meneruskan string teks atau ISequentialStream ke Driver OLE DB untuk SQL Server.

Catatan

Untuk mengirim data XML dalam format string melalui antarmuka ISequentialStream , Anda harus mendapatkan ISequentialStream dengan menentukan DBTYPE_IUNKNOWN dan mengatur argumen pObject ke null dalam pengikatan.

Ketika data XML yang diambil dipotong karena buffer konsumen terlalu kecil, panjangnya dapat dikembalikan sebagai 0xffffffff, yang berarti panjangnya tidak diketahui. Perilaku ini konsisten dengan implementasinya sebagai jenis data yang dialirkan ke klien tanpa mengirim informasi panjang di depan data aktual. Dalam beberapa kasus, panjang aktual dapat dikembalikan ketika penyedia telah menyangga seluruh nilai, seperti IRowset::GetData dan tempat konversi data dilakukan.

Data XML yang dikirim ke SQL Server diperlakukan sebagai data biner oleh server. Perilaku ini mencegah konversi apa pun yang terjadi dan memungkinkan pengurai XML mendeteksi pengodean XML secara otomatis. Ini memungkinkan berbagai dokumen XML yang lebih luas (misalnya yang dikodekan dalam UTF-8) diterima sebagai input ke SQL Server.

Jika XML input terikat sebagai DBTYPE_WSTR, aplikasi harus memastikannya sudah dikodekan Unicode untuk menghindari kemungkinan kerusakan oleh konversi data yang tidak diinginkan.

Pengikatan dan Koersi Data

Tabel berikut ini menjelaskan pengikatan dan koersi yang terjadi saat menggunakan jenis data yang tercantum dengan jenis data xml SQL Server.

Jenis Data Ke Server

XML		 Ke Server

Non-XML		 Dari Server

XML		 Dari Server

Non-XML
DBTYPE_XML Melewati 6,7 Kesalahan1 OK11, 6 Kesalahan8
DBTYPE_BYTES Melewati 6,7 N/A2 OK 11, 6 N/A 2
DBTYPE_WSTR Melewati 6,10 N/A 2 OK4, 6, 12 N/A 2
DBTYPE_BSTR Melewati 6,10 N/A 2 OK 3 N/A 2
DBTYPE_STR OK6, 9, 10 N/A 2 OK5, 6, 12 N/A 2
DBTYPE_IUNKNOWN Aliran byte melalui ISequentialStream7 N/A 2 Aliran byte melalui ISequentialStream11 N/A 2
DBTYPE_VARIANT (VT_UI1 | VT_ARRAY) Melewati 6,7 N/A 2 T/A N/A 2
DBTYPE_VARIANT (VT_BSTR) Melewati 6,10 N/A 2 OK3 N/A 2

1Jika jenis server selain DBTYPE_XML ditentukan dengan ICommandWithParameters::SetParameterInfo dan jenis aksesor DBTYPE_XML, 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 XML ke jenis data parameter.

2Di luar cakupan artikel ini.

3Format adalah UTF-16, tanpa tanda urutan bye (BOM), tidak ada spesifikasi pengodean, tidak ada penghentian null.

4Format adalah UTF-16, tidak ada BOM, tidak ada spesifikasi pengodean, penghentian null.

5Format adalah karakter multibyte yang dikodekan di halaman kode klien dengan terminator null. Konversi dari Unicode yang disediakan server dapat menyebabkan kerusakan data, sehingga pengikatan ini tidak disarankan.

6BY_REF dapat digunakan.

7data UTF-16 harus dimulai dengan BOM. Jika tidak, pengodean mungkin tidak dikenali dengan benar oleh server.

8Validasi dapat terjadi pada waktu pembuatan aksesor, atau pada waktu pengambilan. Kesalahannya adalah DB_E_ERRORSOCCURRED, status pengikatan diatur ke DBBINDSTATUS_UNSUPPORTEDCONVERSION.

9Data dikonversi ke Unicode menggunakan halaman kode klien sebelum dikirim ke server. Jika pengodean dokumen tidak cocok dengan halaman kode klien, kerusakan data dapat terjadi, sehingga pengikatan ini sangat tidak dianjurkan.

10BOM selalu ditambahkan ke data yang dikirim ke server. Jika data sudah dimulai dengan BOM, akan ada dua BOM di awal buffer. Server menggunakan BOM pertama untuk mengenali pengodean sebagai UTF-16 dan kemudian membuangnya. BOM kedua ditafsirkan sebagai karakter spasi nonbreaking lebar nol.

Format 11adalah UTF-16, tidak ada spesifikasi pengodean, BOM ditambahkan ke data yang diterima dari server. Jika string kosong dikembalikan oleh server, BOM masih dikembalikan ke aplikasi. Jika panjang buffer adalah jumlah byte ganjil, data dipotong dengan benar. Jika seluruh nilai dikembalikan dalam gugus, nilai tersebut dapat digabungkan untuk menyusun ulang nilai yang benar.

12Jika panjang buffer kurang dari dua karakter--yaitu, tidak cukup ruang untuk penghentian null--kesalahan luapan dilaporkan.

Catatan

Tidak ada data yang dikembalikan untuk nilai XML NULL.

Standar XML memerlukan XML yang dikodekan UTF-16 untuk memulai dengan tanda urutan byte (BOM), kode karakter UTF-16 0xFEFF. Saat bekerja dengan pengikatan WSTR dan BSTR, Driver OLE DB untuk SQL Server tidak memerlukan atau menambahkan BOM karena pengodean tersirat oleh pengikatan. Saat bekerja dengan pengikatan BYTES, XML, atau IUNKNOWN, niatnya adalah untuk memberikan kesederhanaan dalam menangani prosesor XML dan sistem penyimpanan lainnya. Dalam hal ini, BOM harus hadir dengan XML yang dikodekan UTF-16, dan aplikasi tidak perlu khawatir dengan pengodean aktual, karena sebagian besar prosesor XML (termasuk SQL Server) menyimpulkan pengodean dengan memeriksa beberapa byte pertama dari nilai. Data XML yang diterima dari Driver OLE DB untuk SQL Server menggunakan pengikatan BYTES, XML, atau IUNKNOWN selalu dikodekan dalam UTF-16 dengan BOM dan tanpa deklarasi pengodean yang disematkan.

Konversi data yang disediakan oleh layanan inti OLE DB (IDataConvert) tidak berlaku untuk DBTYPE_XML.

Validasi dilakukan ketika data dikirim ke server. Validasi sisi klien dan perubahan pengodean harus ditangani oleh aplikasi Anda. Disarankan agar Anda tidak memproses data XML secara langsung, tetapi sebaiknya gunakan pembaca DOM atau SAX untuk memprosesnya.

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_XML dapat dikonversi ke DBTYPE_EMPTY dan DBTYPE_NULL, DBTYPE_EMPTY dapat dikonversi ke DBTYPE_XML, tetapi DBTYPE_NULL tidak dapat dikonversi ke DBTYPE_XML. Ini konsisten dengan DBTYPE_WSTR.

DBTYPE_IUNKNOWN adalah pengikatan yang didukung (seperti yang ditunjukkan dalam tabel sebelumnya), tetapi tidak ada konversi antara DBTYPE_XML dan DBTYPE_IUNKNOWN. DBTYPE_IUNKNOWN mungkin tidak digunakan dengan DBTYPE_BYREF.

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 KOLOM dan PROCEDURE_PARAMETERS

Penambahan kolom dan kumpulan baris skema PROCEDURE_PARAMETERS mencakup kolom berikut:

Nama kolom Tipe Deskripsi
SS_XML_SCHEMACOLLECTION_CATALOGNAME DBTYPE_WSTR Nama katalog tempat koleksi skema XML ditentukan. NULL untuk kolom non-XML atau kolom XML yang tidak ditiru.
SS_XML_SCHEMACOLLECTION_SCHEMANAME DBTYPE_WSTR Nama skema tempat koleksi skema XML ditentukan. NULL untuk kolom non-XML atau kolom XML yang tidak ditiru.
SS_XML_SCHEMACOLLECTIONNAME DBTYPE_WSTR Nama koleksi skema XML. NULL untuk kolom non-XML atau kolom XML yang tidak ditiru.

Kumpulan Baris Skema PROVIDER_TYPES

Dalam kumpulan baris skema PROVIDER_TYPES, nilai COLUMN_SIZE adalah 0 untuk jenis data xml , dan DATA_TYPE DBTYPE_XML.

Kumpulan Baris Skema SS_XMLSCHEMA

Kumpulan baris skema baru SS_XMLSCHEMA diperkenalkan bagi klien untuk mengambil informasi skema XML. Kumpulan baris SS_XMLSCHEMA berisi kolom berikut:

Nama kolom Tipe Deskripsi
SCHEMACOLLECTION_CATALOGNAME DBTYPE_WSTR Katalog yang dimiliki koleksi XML.
SCHEMACOLLECTION_SCHEMANAME DBTYPE_WSTR Skema yang dimiliki koleksi XML.
SCHEMACOLLECTIONNAME DBTYPE_WSTR Nama kumpulan skema XML untuk kolom XML yang diketik, sebaliknya NULL.
TARGETNAMESPACEURI DBTYPE_WSTR Ruang nama target skema XML.
SCHEMACONTENT DBTYPE_WSTR Konten skema XML.

Setiap skema XML dilingkup oleh nama katalog, nama skema, nama koleksi skema, dan ruang nama target Pengidentifikasi Sumber Daya Seragam (URI). Selain itu, GUID baru dengan nama DBSCHEMA_XML_COLLECTIONS juga ditentukan. Jumlah pembatasan dan kolom terbatas untuk kumpulan baris skema SS_XMLSCHEMA didefinisikan sebagai berikut.

GUID Jumlah pembatasan Kolom terbatas
DBSCHEMA_XML_COLLECTIONS 4 SCHEMACOLLECTION_CATALOGNAME

SCHEMACOLLECTION_SCHEMANAME

SCHEMACOLLECTIONNAME

TARGETNAMESPACEURI

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 jenis data xml melalui OLE DB, Driver OLE DB untuk SQL Server mengimplementasikan kumpulan properti DBPROPSET_SQLSERVERPARAMETER baru, yang berisi nilai berikut.

Nama Tipe Deskripsi
SSPROP_PARAM_XML_SCHEMACOLLECTION_CATALOGNAME DBTYPE_WSTR Nama katalog (database) tempat kumpulan skema XML ditentukan. Bagian dari pengidentifikasi nama tiga bagian SQL.
SSPROP_PARAM_XML_SCHEMACOLLECTION_SCHEMANAME DBTYPE_WSTR Nama skema XML dalam koleksi skema. Bagian dari pengidentifikasi nama tiga bagian SQL.
SSPROP_PARAM_XML_SCHEMACOLLECTIONNAME DBTYPE_WSTR Nama koleksi skema XML dalam katalog Bagian dari pengidentifikasi nama tiga bagian SQL.

Kumpulan Properti DBPROPSET_SQLSERVERCOLUMN

Untuk mendukung pembuatan tabel di antarmuka ITableDefinition , Driver OLE DB untuk SQL Server menambahkan tiga kolom baru ke kumpulan properti DBPROPSET_SQLSERVERCOLUMN.

Nama Tipe Deskripsi
SSPROP_COL_XML_SCHEMACOLLECTION_CATALOGNAME VT_BSTR Untuk kolom XML yang diketik, properti ini adalah string yang menentukan nama katalog tempat skema XML disimpan. Untuk jenis kolom lainnya, properti ini mengembalikan string kosong.
SSPROP_COL_XML_SCHEMACOLLECTION_SCHEMANAME VT_BSTR Untuk kolom XML yang diketik, properti ini adalah string yang menentukan nama skema XML yang menentukan kolom ini.
SSPROP_COL_XML_SCHEMACOLLECTIONNAME VT_BSTR Untuk kolom XML yang diketik, properti ini adalah string yang menentukan nama kumpulan skema XML skema yang menentukan nilai.

Seperti nilai SSPROP_PARAM, semua properti ini bersifat opsional dan default kosong. SSPROP_COL_XML_SCHEMACOLLECTION_CATALOGNAME dan SSPROP_COL_XML_SCHEMACOLLECTION_SCHEMANAME hanya dapat ditentukan jika SSPROP_COL_XML_SCHEMACOLLECTIONNAME ditentukan. Saat meneruskan XML ke server, jika nilai-nilai ini disertakan, nilai tersebut diperiksa keberadaannya (validitas) terhadap database saat ini dan data instans diperiksa terhadap skema. Dalam semua kasus, untuk menjadi valid, semuanya kosong atau semua diisi.

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 jenis data xml 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 khusus server.

Catatan

Antarmuka ISSCommandWithParameters juga menggunakan struktur SSPARAMPROPS baru.

Antarmuka IColumnsRowset

Driver OLE DB untuk SQL Server menambahkan kolom khusus SQL Server berikut ke set baris yang dikembalikan oleh metode IColumnRowset::GetColumnsRowset . Kolom ini berisi nama tiga bagian dari koleksi skema XML. Untuk kolom non-XML atau kolom XML yang tidak dititik, ketiga kolom mengambil nilai default NULL.

Nama kolom Tipe Deskripsi
DBCOLUMN_SS_XML_SCHEMACOLLECTION_CATALOGNAME DBTYPE_WSTR Katalog yang dimiliki koleksi skema XML,

NULL sebaliknya.
DBCOLUMN_SS_XML_SCHEMACOLLECTION_SCHEMANAME DBTYPE_WSTR Skema yang dimiliki koleksi skema XML. NULL sebaliknya.
DBCOLUMN_SS_XML_SCHEMACOLLECTIONNAME DBTYPE_WSTR Nama kumpulan skema XML untuk kolom XML yang diketik, sebaliknya NULL.

Antarmuka IRowset

Instans XML dalam kolom XML diambil melalui metode IRowset::GetData . Bergantung pada pengikatan yang ditentukan oleh klien, instans XML dapat diambil sebagai DBTYPE_BSTR, DBTYPE_WSTR, DBTYPE_VARIANT, DBTYPE_XML, DBTYPE_STR, DBTYPE_BYTES, atau sebagai antarmuka melalui DBTYPE_IUNKNOWN. Jika konsumen menentukan DBTYPE_BSTR, DBTYPE_WSTR, atau DBTYPE_VARIANT, penyedia mengonversi instans XML ke jenis yang diminta pengguna dan memasukkannya ke lokasi yang ditentukan dalam pengikatan yang sesuai.

Jika konsumen menentukan DBTYPE_IUNKNOWN dan mengatur argumen pObject ke NULL, atau mengatur argumen pObject ke IID_ISequentialStream, penyedia mengembalikan antarmuka ISequentialStream ke konsumen sehingga konsumen dapat mengalirkan data XML dari kolom. ISequentialStream kemudian mengembalikan data XML sebagai aliran karakter Unicode.

Saat mengembalikan nilai XML yang terikat ke DBTYPE_IUNKNOWN, penyedia melaporkan nilai sizeof (IUnknown *)ukuran . Perilaku ini konsisten dengan pendekatan yang diambil ketika kolom terikat sebagai DBTYPE_IUnknown atau DBTYPE_IDISPATCH, dan dengan DBTYPE_IUNKNOWN/ISequentialStream ketika ukuran kolom yang tepat tidak dapat ditentukan.

Antarmuka IRowsetChange

Ada dua cara konsumen dapat memperbarui instans XML dalam kolom. Yang pertama adalah melalui objek penyimpanan ISequentialStream yang dibuat oleh penyedia. Konsumen dapat memanggil metode ISequentialStream::Write untuk langsung memperbarui instans XML yang dikembalikan oleh penyedia.

Pendekatan kedua adalah melalui metode IRowsetChange::SetData atau IRowsetChange::InsertRow . Dalam pendekatan ini, instans XML di buffer konsumen dapat ditentukan dalam pengikatan jenis DBTYPE_BSTR, DBTYPE_WSTR, DBTYPE_VARIANT, DBTYPE_XML, atau DBTYPE_IUNKNOWN.

Jika DBTYPE_BSTR, DBTYPE_WSTR, atau DBTYPE_VARIANT ditentukan, penyedia menyimpan instans XML yang berada di buffer konsumen ke kolom yang tepat.

Jika DBTYPE_IUNKNOWN/ISequentialStream ditentukan, jika konsumen tidak menentukan objek penyimpanan apa pun, konsumen harus membuat objek ISequentialStream terlebih dahulu, mengikat dokumen XML dengan objek, lalu meneruskan objek ke penyedia melalui metode IRowsetChange::SetData . Konsumen juga dapat membuat objek penyimpanan, mengatur argumen pObject ke IID_ISequentialStream, membuat objek ISequentialStream lalu meneruskan objek ISequentialStream ke metode IRowsetChange::SetData. Dalam kedua kasus, penyedia dapat mengambil objek XML melalui objek ISequentialStream dan menyisipkannya ke dalam kolom yang tepat.

Antarmuka IRowsetUpdate

Antarmuka IRowsetUpdate menyediakan fungsionalitas untuk pembaruan yang tertunda. Data yang tersedia untuk set baris tidak tersedia untuk transaksi lain hingga konsumen memanggil metode IRowsetUpdate::Update .

Antarmuka IRowsetFind

Metode IRowsetFind::FindNextRow tidak berfungsi dengan jenis data xml . Ketika IRowsetFind::FindNextRow dipanggil dan argumen hAccessor menentukan kolom DBTYPE_XML, DB_E_BADBINDINFO dikembalikan. Ini terjadi terlepas dari jenis kolom yang sedang dicari. Untuk jenis pengikatan lainnya, FindNextRow gagal dengan DB_E_BADCOMPAREOP jika kolom yang akan dicari adalah tipe data xml .

Lihat Juga

Driver OLE DB untuk Fitur SQL Server
ISSCommandWithParameters (OLE DB)