Menyisipkan Data ke dalam Parameter Bernilai Tabel

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

Unduh driver OLE DB

Driver OLE DB untuk SQL Server 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 adalah 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 Table-Valued 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 set 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 set baris parameter bernilai tabel memaparkan 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 set 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 set baris parameter bernilai tabel dihitung referensi, mirip dengan objek streaming.

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

Setelah Driver OLE DB untuk SQL Server 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 Table-Valued Sesuai Permintaan dari Konsumen)

Model penarikan berguna untuk dua skenario:

• Untuk mengalirkan 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 objek rowset mereka sendiri. 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

Driver OLE DB untuk SQL Server akan membaca satu atau beberapa baris pada satu waktu dari objek rowset 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 mengimplementasikan fungsionalitas untuk membaca data dari disk ketika diperlukan oleh Driver OLE DB untuk SQL Server.

Konsumen akan mengkomunikasikan format datanya ke Driver OLE DB untuk SQL Server dengan menggunakan IAccessor::CreateAccessor pada objek set baris parameter bernilai tabel. Saat membaca data dari buffer konsumen, penyedia memverifikasi bahwa semua kolom bisa-tulis 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, Driver OLE DB untuk 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 Table-Valued (OLE DB)