Penggunaan Parameter Table-Valued ODBC

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

Topik ini membahas skenario pengguna utama untuk menggunakan parameter bernilai tabel dengan ODBC:

• Parameter Table-Valued dengan Buffer Multirow Terikat Penuh (Kirim Data sebagai TVP dengan Semua Nilai dalam Memori)

• Parameter Table-Valued dengan Streaming Baris (Kirim Data sebagai TVP Menggunakan Data Saat Eksekusi)

• Mengambil Metadata Parameter Table-Valued dari Katalog Sistem

• Mengambil Metadata Parameter Table-Valued untuk Pernyataan yang Disiapkan

Parameter Table-Valued dengan Buffer Multirow Terikat Penuh (Kirim Data sebagai TVP dengan Semua Nilai dalam Memori)

Ketika digunakan dengan buffer multirow yang sepenuhnya terikat, semua nilai parameter tersedia dalam memori. Ini khas, misalnya, dari transaksi OLTP, di mana parameter bernilai tabel dapat dipaketkan ke dalam satu prosedur tersimpan. Tanpa parameter bernilai tabel, ini akan melibatkan pembuatan batch multi-pernyataan yang kompleks secara dinamis, atau melakukan beberapa panggilan ke server.

Parameter bernilai tabel itu sendiri terikat dengan menggunakan SQLBindParameter bersama dengan parameter lainnya. Setelah semua parameter terikat, aplikasi mengatur atribut fokus parameter, SQL_SOPT_SS_PARAM_FOCUS, pada setiap parameter bernilai tabel dan memanggil SQLBindParameter untuk kolom parameter bernilai tabel.

Jenis server untuk parameter bernilai tabel adalah jenis khusus SQL Server baru, SQL_SS_TABLE. Jenis C pengikatan untuk SQL_SS_TABLE harus selalu SQL_C_DEFAULT. Tidak ada data yang ditransfer untuk parameter terikat parameter bernilai tabel; ini digunakan untuk meneruskan metadata tabel dan untuk mengontrol cara meneruskan data di kolom konstituen parameter bernilai tabel.

Panjang parameter bernilai tabel diatur ke jumlah baris yang dikirim ke server. Parameter ColumnSize SQLBindParameter untuk parameter bernilai tabel menentukan jumlah maksimum baris yang dapat dikirim; ini adalah ukuran array buffer kolom. ParameterValuePtr adalah buffer parameter; untuk parameter bernilai tabel di SQLBindParameter, ParameterValuePtr dan BufferLength terkait digunakan untuk meneruskan nama jenis parameter bernilai tabel saat diperlukan. Nama jenis tidak diperlukan untuk panggilan prosedur tersimpan, tetapi diperlukan untuk pernyataan SQL.

Ketika nama jenis parameter bernilai tabel ditentukan pada panggilan ke SQLBindParameter, nama tersebut harus selalu ditentukan sebagai nilai Unicode, bahkan dalam aplikasi yang dibangun sebagai aplikasi ANSI. Saat Anda menentukan nama jenis parameter bernilai tabel dengan menggunakan SQLSetDescField, Anda dapat menggunakan harfiah yang sesuai dengan cara aplikasi dibangun. Manajer Driver ODBC akan melakukan konversi Unicode yang diperlukan.

Metadata untuk parameter bernilai tabel dan kolom parameter bernilai tabel dapat dimanipulasi secara individual dan eksplisit dengan menggunakan SQLGetDescRec, SQLSetDescRec, SQLGetDescField, dan SQLSetDescField. Namun, kelebihan beban SQLBindParameter biasanya lebih nyaman dan tidak memerlukan akses deskriptor eksplisit dalam banyak kasus. Pendekatan ini konsisten dengan definisi SQLBindParameter untuk jenis data lain, kecuali bahwa untuk parameter bernilai tabel, bidang deskriptor yang terpengaruh sedikit berbeda.

Terkadang, aplikasi menggunakan parameter bernilai tabel dengan SQL dinamis dan nama jenis parameter bernilai tabel harus disediakan. Jika ini masalahnya dan parameter bernilai tabel tidak ditentukan dalam skema default saat ini untuk koneksi, SQL_CA_SS_SCHEMA_NAME harus diatur dengan menggunakan SQLSetDescField. Karena definisi jenis tabel dan parameter bernilai tabel harus berada dalam database yang sama, SQL_CA_SS_CATALOG_NAME tidak boleh diatur jika aplikasi menggunakan parameter bernilai tabel. Jika tidak, SQLSetDescField akan melaporkan kesalahan.

Kode sampel untuk skenario ini ada dalam prosedur demo_fixed_TVP_binding dalam Gunakan Parameter Table-Valued (ODBC).

Parameter Table-Valued dengan Streaming Baris (Kirim Data sebagai TVP Menggunakan Data Saat Eksekusi)

Dalam skenario ini, aplikasi memasok baris ke driver saat memintanya dan mereka dialirkan ke server. Ini menghindari harus buffer semua baris dalam memori. Ini mewakili skenario sisipkan/perbarui massal. Parameter bernilai tabel menyediakan titik performa di suatu tempat antara array parameter dan salinan massal. Artinya, parameter bernilai tabel mudah diprogram sebagai array parameter, tetapi memberikan fleksibilitas yang lebih besar di server.

Parameter bernilai tabel dan kolomnya terikat seperti yang dibahas di bagian sebelumnya, Table-Valued Parameter dengan Buffer Multirow Terikat Penuh, tetapi indikator panjang parameter bernilai tabel itu sendiri diatur ke SQL_DATA_AT_EXEC. Driver merespons SQLExecute atau SQLExecuteDirect dengan cara biasa untuk parameter data-at-execution-yaitu, dengan mengembalikan SQL_NEED_DATA. Ketika driver siap menerima data untuk parameter bernilai tabel, SQLParamData mengembalikan nilai ParameterValuePtr di SQLBindParameter.

Aplikasi menggunakan SQLPutData untuk parameter bernilai tabel untuk menunjukkan ketersediaan data untuk kolom konstituen parameter bernilai tabel. Ketika SQLPutData dipanggil untuk parameter bernilai tabel, DataPtr harus selalu null dan StrLen_or_Ind harus 0 atau angka yang kurang dari atau sama dengan ukuran array yang ditentukan untuk buffer parameter bernilai tabel (parameter ColumnSize SQLBindParameter). 0 menandakan bahwa tidak ada lagi baris untuk parameter bernilai tabel, dan driver akan melanjutkan untuk memproses ke parameter prosedur aktual berikutnya. Saat StrLen_or_Ind bukan 0, driver akan memproses kolom konstituen parameter bernilai tabel dengan cara yang sama seperti parameter terikat parameter bernilai non-tabel: Setiap kolom parameter bernilai tabel dapat menentukan panjang data aktual, SQL_NULL_DATA, atau dapat menentukan data saat eksekusi melalui buffer panjang/indikatornya. Nilai kolom parameter bernilai tabel dapat diteruskan dengan panggilan berulang ke SQLPutData seperti biasa ketika karakter atau nilai biner akan diteruskan dalam potongan-potongan.

Ketika semua kolom parameter bernilai tabel telah diproses, driver kembali ke parameter bernilai tabel untuk memproses baris lebih lanjut dari data parameter bernilai tabel. Oleh karena itu, untuk parameter bernilai tabel data-at-execution, driver tidak mengikuti pemindaian berurutan biasa dari parameter terikat. Parameter bernilai tabel terikat akan dijajaki hingga SQLPutData dipanggil dengan StrLen_Or_IndPtr sama dengan 0, saat driver melewati kolom parameter bernilai tabel dan berpindah ke parameter prosedur tersimpan berikutnya yang sebenarnya. Ketika SQLPutData meneruskan nilai indikator yang lebih besar dari atau sama dengan 1, driver memproses kolom parameter dan baris bernilai tabel secara berurutan hingga memiliki nilai untuk semua baris dan kolom terikat. Kemudian driver kembali ke parameter bernilai tabel. Antara menerima token untuk parameter bernilai tabel dari SQLParamData dan memanggil SQLPutData(hstmt, NULL, n) untuk parameter bernilai tabel, aplikasi harus mengatur data kolom konstituen parameter bernilai tabel dan konten buffer indikator untuk baris atau baris berikutnya yang akan diteruskan ke server.

Kode sampel untuk skenario ini ada dalam rutinitas demo_variable_TVP_binding dalam Gunakan Parameter Table-Valued (ODBC).

Mengambil Metadata Parameter Table-Valued dari Katalog Sistem

Saat aplikasi memanggil SQLProcedureColumns untuk prosedur yang memiliki parameter parameter bernilai tabel, DATA_TYPE dikembalikan sebagai SQL_SS_TABLE dan TYPE_NAME adalah nama jenis tabel untuk parameter bernilai tabel. Dua kolom tambahan ditambahkan ke kumpulan hasil yang dikembalikan oleh SQLProcedureColumns: SS_TYPE_CATALOG_NAME mengembalikan nama katalog tempat jenis tabel parameter nilai tabel ditentukan, dan SS_TYPE_SCHEMA_NAME mengembalikan nama skema tempat jenis tabel parameter nilai tabel ditentukan. Sesuai dengan spesifikasi ODBC, SS_TYPE_CATALOG_NAME dan SS_TYPE_SCHEMA_NAME muncul sebelum semua kolom spesifik driver yang ditambahkan dalam versi SQL Server sebelumnya, dan setelah semua kolom yang diamanatkan oleh ODBC itu sendiri.

Kolom baru akan diisi tidak hanya untuk parameter bernilai tabel, tetapi juga untuk parameter jenis yang ditentukan pengguna CLR. Kolom skema dan katalog parameter UDT yang ada masih akan diisi, tetapi memiliki skema umum dan kolom katalog untuk jenis data yang mengharuskannya akan menyederhanakan pengembangan aplikasi di masa mendatang. (Perhatikan bahwa koleksi skema XML agak berbeda dan tidak disertakan dalam perubahan ini.)

Aplikasi menggunakan SQLTables untuk menentukan nama jenis tabel dengan cara yang sama seperti untuk tabel persisten, tabel sistem, dan tampilan. Jenis tabel baru, JENIS TABEL, diperkenalkan untuk memungkinkan aplikasi mengidentifikasi jenis tabel yang terkait dengan parameter bernilai tabel. Jenis tabel dan tabel reguler menggunakan namespace yang berbeda. Ini berarti Anda dapat menggunakan nama yang sama untuk jenis tabel dan tabel aktual. Untuk menangani ini, atribut pernyataan baru, SQL_SOPT_SS_NAME_SCOPE, telah diperkenalkan. Atribut ini menentukan apakah SQLTables dan fungsi katalog lainnya yang mengambil nama tabel sebagai parameter harus menginterpretasikan nama tabel sebagai nama tabel aktual atau nama jenis tabel.

Aplikasi menggunakan SQLColumns untuk menentukan kolom untuk jenis tabel dengan cara yang sama seperti yang dilakukannya untuk tabel persisten, tetapi harus terlebih dahulu mengatur SQL_SOPT_SS_NAME_SCOPE untuk menunjukkan bahwa kolom berfungsi dengan jenis tabel daripada tabel aktual. SQLPrimaryKeys juga dapat digunakan dengan jenis tabel, sekali lagi menggunakan SQL_SOPT_SS_NAME_SCOPE.

Kode sampel untuk skenario ini ada dalam rutinitas demo_metadata_from_catalog_APIs dalam Gunakan Parameter Table-Valued (ODBC).

Mengambil Metadata Parameter Table-Valued untuk Pernyataan yang Disiapkan

Dalam skenario ini, aplikasi menggunakan SQLNumParameters dan SQLDescribeParam untuk mengambil metadata untuk parameter bernilai tabel.

Bidang IPD SQL_CA_SS_TYPE_NAME digunakan untuk mengambil nama jenis untuk parameter bernilai tabel. Bidang IPD SQL_CA_SS_SCHEMA_NAME dan SQL_CA_SS_CATALOG_NAME digunakan untuk mengambil katalog dan skemanya.

Definisi jenis tabel dan parameter bernilai tabel harus berada dalam database yang sama. SQLSetDescField akan melaporkan kesalahan jika aplikasi menetapkan SQL_CA_SS_CATALOG_NAME saat menggunakan parameter bernilai tabel.

SQL_CA_SS_CATALOG_NAME dan SQL_CA_SS_SCHEMA_NAME juga dapat digunakan untuk mengambil katalog dan skema yang terkait dengan parameter jenis yang ditentukan pengguna CLR. SQL_CA_SS_CATALOG_NAME dan SQL_CA_SS_SCHEMA_NAME adalah alternatif untuk atribut skema katalog khusus jenis yang ada untuk jenis UDT CLR.

Aplikasi juga menggunakan SQLColumns untuk mengambil metadata kolom untuk parameter bernilai tabel dalam skenario ini, karena SQLDescribeParam tidak mengembalikan metadata untuk kolom kolom parameter bernilai tabel.

Kode sampel untuk kasus penggunaan ini ada dalam rutinitas demo_metadata_from_prepared_statement dalam Gunakan Parameter Table-Valued (ODBC).

Lihat juga

Parameter Bernilai Tabel (ODBC)