Menyisipkan Data ke dalam Parameter Bernilai Tabel (Penyedia OLE DB Klien Asli)

Berlaku untuk:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)

Penyedia SQL Server Native Client OLE DB mendukung dua model bagi konsumen untuk menentukan data untuk baris parameter bernilai tabel: model pendorongan dan model penarikan.

Catatan

Kolom parameter bernilai tabel harus memiliki nilai non-default di semua baris atau nilai default di semua baris. Tidak dimungkinkan untuk memiliki nilai default di beberapa baris tetapi tidak yang lain. Oleh karena itu, dalam pengikatan parameter bernilai tabel, satu-satunya nilai status yang diizinkan untuk data kolom kumpulan baris parameter bernilai tabel DBSTATUS_S_ISNULL dan DBSTATUS_S_OK. DBSTATUS_S_DEFAULT akan mengakibatkan kegagalan dan nilai status terikat akan diatur ke DBSTATUS_E_BADSTATUS.

Model Pendorongan (Memuat Semua Data Parameter Bernilai Tabel dalam Memori)

Model pendorongan mirip dengan penggunaan set parameter (yaitu, parameter DBPARAMS di ICommand::Execute). Model pendorongan hanya digunakan jika objek set baris parameter bernilai tabel digunakan tanpa implementasi antarmuka IRowset yang disesuaikan. Model pendorongan direkomendasikan ketika jumlah baris dalam himpunan baris parameter bernilai tabel kecil dan tidak diharapkan untuk memberikan tekanan memori yang berlebihan pada aplikasi. Ini lebih sederhana daripada model penarikan, karena tidak memerlukan fungsionalitas lagi dari aplikasi konsumen daripada apa yang saat ini umum dalam aplikasi OLE DB biasa.

Konsumen diharapkan untuk memberikan semua data parameter bernilai tabel kepada penyedia sebelum menjalankan perintah. Untuk menyediakan data, konsumen mengisi objek set baris parameter bernilai tabel untuk setiap parameter bernilai tabel. Objek kumpulan baris parameter bernilai tabel mengekspos operasi Sisipkan, Atur, dan Hapus set baris, yang akan digunakan konsumen untuk memanipulasi data parameter bernilai tabel. Penyedia akan mengambil data dari objek set baris parameter bernilai tabel ini pada waktu eksekusi.

Saat objek set baris parameter bernilai tabel diberikan kepada konsumen, konsumen dapat memprosesnya sebagai objek set baris. Konsumen dapat memperoleh informasi jenis setiap kolom (jenis, panjang maksimum, presisi, dan skala) dengan menggunakan metode antarmuka IColumnsInfo::GetColumnInfo atau IColumnsRowset::GetColumnsRowset. Konsumen kemudian membuat aksesor untuk menentukan pengikatan untuk data. Langkah selanjutnya adalah menyisipkan baris data ke dalam kumpulan baris parameter bernilai tabel. Ini dapat dilakukan dengan menggunakan IRowsetChange::InsertRow. IRowsetChange::SetData atau IRowsetChange::D eleteRows juga dapat digunakan pada objek set baris parameter bernilai tabel jika Anda harus memanipulasi data. Objek kumpulan baris parameter bernilai tabel dihitung referensi, mirip dengan objek streaming.

Jika IColumnsRowset::GetColumnsRowset digunakan, akan ada panggilan berikutnya ke IRowset::GetNextRows, IRowset::GetData, dan metode IRowset::ReleaseRows pada objek set baris kolom yang dihasilkan.

Setelah Penyedia SQL Server Native Client OLE DB mulai menjalankan perintah, nilai parameter bernilai tabel akan diambil dari objek set baris parameter bernilai tabel ini dan dikirim ke server.

Model pendorongan memerlukan pekerjaan minimal oleh konsumen, tetapi menggunakan lebih banyak memori daripada model penarikan, karena semua data parameter bernilai tabel harus berada dalam memori pada waktu eksekusi.

Model Penarikan (Mendapatkan Data Parameter Bernilai Tabel sesuai Permintaan dari Konsumen)

Model penarikan berguna untuk dua skenario:

• Untuk melakukan streaming baris.

• Jika kumpulan baris dari penyedia lain digunakan sebagai nilai parameter bernilai tabel.

Dalam model penarikan, konsumen menyediakan data sesuai permintaan kepada penyedia. Gunakan pendekatan ini jika aplikasi Anda memiliki banyak penyisipan data, dan data himpunan baris parameter bernilai tabel dalam memori akan menghasilkan akses memori yang berlebihan. Jika beberapa penyedia OLE DB digunakan, model penarikan konsumen memungkinkan konsumen untuk menyediakan objek set baris apa pun sebagai nilai parameter bernilai tabel.

Untuk menggunakan model penarikan, konsumen harus menyediakan implementasi mereka sendiri dari objek set baris. Saat menggunakan model penarikan dengan set baris parameter bernilai tabel (CLSID_ROWSET_TVP), konsumen diperlukan untuk mengagregasi objek set baris parameter bernilai tabel yang diekspos penyedia melalui metode ITableDefinitionWithConstraints::CreateTableWithConstraints atau metode IOpenRowset::OpenRowset. Objek konsumen hanya diharapkan untuk mengambil alih implementasi antarmuka IRowset. Anda harus mengambil alih fungsi berikut:

• IRowset::GetNextRows

• IRowset::AddRefRows

• IRowset::GetData

• IRowset::ReleaseRows

• IRowset::RestartPosition

Penyedia SQL Server Native Client OLE DB akan membaca satu atau beberapa baris pada satu waktu dari objek kumpulan baris konsumen untuk mendukung perilaku streaming dalam parameter bernilai tabel. Misalnya, pengguna mungkin memiliki data himpunan baris parameter bernilai tabel pada disk (bukan dalam memori) dan mungkin menerapkan fungsionalitas untuk membaca data dari disk ketika diperlukan oleh Penyedia OLE DB Klien Asli SQL Server.

Konsumen akan mengkomunikasikan format datanya ke Penyedia OLE DB Klien Asli SQL Server dengan menggunakan IAccessor::CreateAccessor pada objek set baris parameter bernilai tabel. Saat membaca data dari buffer konsumen, penyedia memverifikasi bahwa semua kolom yang dapat ditulis dan non-default tersedia melalui setidaknya satu handel aksesor, dan menggunakan handel yang sesuai untuk membaca data kolom. Untuk menghindari ambiguitas, harus ada korespondensi satu-ke-satu antara kolom set baris parameter bernilai tabel dan pengikatan. Pengikatan duplikat ke kolom yang sama akan mengakibatkan kesalahan. Selain itu, setiap pengakses diharapkan memiliki anggota iOrdinal DBBindings secara berurutan. Akan ada panggilan sebanyak mungkin ke IRowset::GetData sebagai jumlah pengakses per baris, dan urutan panggilan akan didasarkan pada urutan nilai iOrdinal dari nilai yang lebih rendah ke yang lebih tinggi.

Penyedia diharapkan untuk mengimplementasikan sebagian besar antarmuka yang diekspos oleh objek set baris parameter bernilai tabel. Konsumen akan menerapkan objek rowset dengan antarmuka minimal (IRowset). Karena agregasi buta, antarmuka objek set baris wajib yang tersisa akan diimplementasikan oleh objek set baris parameter bernilai tabel.

Untuk objek set baris lainnya, seperti objek set baris yang diperoleh untuk penyedia OLE DB apa pun, set baris yang disediakan konsumen harus mengimplementasikan semua antarmuka objek set baris wajib seperti yang ditentukan dalam spesifikasi OLE DB.

Pada saat eksekusi, Penyedia OLE DB Klien Asli SQL Server akan memanggil kembali ke objek set baris untuk mengambil baris dan membaca data kolom.

Lihat Juga

Parameter Bernilai Tabel (OLE DB)
Menggunakan Parameter Bernilai Tabel (OLE DB)