Menggunakan Array Parameter

Untuk menggunakan array parameter, aplikasi memanggil SQLSetStmtAttr dengan argumen Atribut SQL_ATTR_PARAMSET_SIZE untuk menentukan jumlah set parameter. Ini memanggil SQLSetStmtAttr dengan argumen Atribut SQL_ATTR_PARAMS_PROCESSED_PTR untuk menentukan alamat variabel di mana driver dapat mengembalikan jumlah set parameter yang diproses, termasuk set kesalahan. Ini memanggil SQLSetStmtAttr dengan argumen Atribut SQL_ATTR_PARAM_STATUS_PTR untuk menunjuk ke array untuk mengembalikan informasi status untuk setiap baris nilai parameter. Driver menyimpan alamat ini dalam struktur yang dipertahankan untuk pernyataan.

Catatan

Di ODBC 2.x, SQLParamOptions dipanggil untuk menentukan beberapa nilai untuk parameter. Di ODBC 3.x, panggilan ke SQLParamOptions telah digantikan oleh panggilan ke SQLSetStmtAttr untuk mengatur atribut SQL_ATTR_PARAMSET_SIZE dan SQL_ATTR_PARAMS_PROCESSED_ARRAY.

Sebelum menjalankan pernyataan, aplikasi menetapkan nilai setiap elemen dari setiap array terikat. Ketika pernyataan dijalankan, driver menggunakan informasi yang disimpannya untuk mengambil nilai parameter dan mengirimkannya ke sumber data; jika memungkinkan, driver harus mengirim nilai-nilai ini sebagai array. Meskipun penggunaan array parameter paling baik diimplementasikan dengan menjalankan pernyataan SQL dengan semua parameter dalam array dengan satu panggilan ke sumber data, kemampuan ini tidak tersedia secara luas di DBMSs saat ini. Namun, driver dapat mensimulasikannya dengan menjalankan pernyataan SQL beberapa kali, masing-masing dengan satu set parameter.

Sebelum aplikasi menggunakan array parameter, harus yakin bahwa mereka didukung oleh driver yang digunakan oleh aplikasi. Ada dua cara untuk melakukannya:

• Gunakan hanya driver yang diketahui untuk mendukung array parameter. Aplikasi dapat mengkodekan nama driver ini secara permanen, atau pengguna hanya dapat diinstruksikan untuk menggunakan driver ini. Aplikasi kustom dan aplikasi vertikal biasanya menggunakan sekumpulan driver terbatas.

• Periksa dukungan array parameter pada waktu proses. Driver mendukung array parameter jika memungkinkan untuk mengatur atribut pernyataan SQL_ATTR_PARAMSET_SIZE ke nilai yang lebih besar dari 1. Aplikasi generik dan aplikasi vertikal biasanya memeriksa dukungan array parameter pada waktu proses.

Ketersediaan jumlah baris dan tataan hasil dalam eksekusi berparameter dapat ditentukan dengan memanggil SQLGetInfo dengan opsi SQL_PARAM_ARRAY_ROW_COUNTS dan SQL_PARAM_ARRAY_SELECTS. Untuk pernyataan INSERT, UPDATE, dan DELETE , opsi SQL_PARAM_ARRAY_ROW_COUNTS menunjukkan apakah jumlah baris individual (satu untuk setiap set parameter) tersedia (SQL_PARC_BATCH) atau apakah jumlah baris digulung menjadi satu (SQL_PARC_NO_BATCH). Untuk pernyataan SELECT , opsi SQL_PARAM_ARRAY_SELECTS menunjukkan apakah kumpulan hasil tersedia untuk setiap set parameter (SQL_PAS_BATCH) atau apakah hanya satu kumpulan hasil yang tersedia (SQL_PAS_NO_BATCH). Jika driver tidak mengizinkan pernyataan pembuatan set hasil dijalankan dengan array parameter, SQL_PARAM_ARRAY_SELECTS mengembalikan SQL_PAS_NO_SELECT. Ini adalah sumber data khusus apakah array parameter dapat digunakan dengan jenis pernyataan lain, terutama karena penggunaan parameter dalam pernyataan ini akan spesifik sumber data dan tidak akan mengikuti tata bahasa ODBC SQL.

Array yang ditunjukkan oleh atribut pernyataan SQL_ATTR_PARAM_OPERATION_PTR dapat digunakan untuk mengabaikan baris parameter. Jika elemen array diatur ke SQL_PARAM_IGNORE, kumpulan parameter yang sesuai dengan elemen tersebut dikecualikan dari panggilan SQLExecute atau SQLExecDirect . Array yang ditujukkan oleh atribut SQL_ATTR_PARAM_OPERATION_PTR dialokasikan dan diisi oleh aplikasi dan dibaca oleh driver. Jika baris yang diambil digunakan sebagai parameter input, nilai array status baris dapat digunakan dalam array operasi parameter.

Pemrosesan Kesalahan

Jika terjadi kesalahan saat menjalankan pernyataan, fungsi eksekusi mengembalikan kesalahan dan mengatur variabel nomor baris ke jumlah baris yang berisi kesalahan. Ini adalah sumber data khusus apakah semua baris kecuali kumpulan kesalahan dijalankan atau apakah semua baris sebelum (tetapi tidak setelah) set kesalahan dijalankan. Karena memproses set parameter, driver mengatur buffer yang ditentukan oleh atribut pernyataan SQL_ATTR_PARAMS_PROCESSED_PTR ke jumlah baris yang saat ini sedang diproses. Jika semua set kecuali set kesalahan dijalankan, driver mengatur buffer ini ke SQL_ATTR_PARAMSET_SIZE setelah semua baris diproses.

Jika atribut pernyataan SQL_ATTR_PARAM_STATUS_PTR telah diatur, SQLExecute atau SQLExecDirect mengembalikan array status parameter, yang menyediakan status setiap set parameter. Array status parameter dialokasikan oleh aplikasi dan diisi oleh driver. Elemennya menunjukkan apakah pernyataan SQL berhasil dijalankan untuk baris parameter atau apakah terjadi kesalahan saat memproses kumpulan parameter. Jika terjadi kesalahan, driver mengatur nilai yang sesuai dalam array status parameter ke SQL_PARAM_ERROR dan mengembalikan SQL_SUCCESS_WITH_INFO. Aplikasi dapat memeriksa array status untuk menentukan baris mana yang diproses. Dengan menggunakan nomor baris, aplikasi sering dapat memperbaiki kesalahan dan melanjutkan pemrosesan.

Bagaimana array status parameter digunakan ditentukan oleh opsi SQL_PARAM_ARRAY_ROW_COUNTS dan SQL_PARAM_ARRAY_SELECTS yang dikembalikan oleh panggilan ke SQLGetInfo. Untuk pernyataan INSERT, UPDATE, dan DELETE , array status parameter diisi dengan informasi status jika SQL_PARC_BATCH dikembalikan untuk SQL_PARAM_ARRAY_ROW_COUNTS, tetapi tidak jika SQL_PARC_NO_BATCH dikembalikan. Untuk pernyataan SELECT , array status parameter diisi jika SQL_PAS_BATCH dikembalikan untuk SQL_PARAM_ARRAY_SELECT, tetapi tidak jika SQL_PAS_NO_BATCH atau SQL_PAS_NO_SELECT dikembalikan.

Parameter Data-at-Execution

Jika salah satu nilai dalam array panjang/indikator SQL_DATA_AT_EXEC atau hasil makro SQL_LEN_DATA_AT_EXEC(panjang), data untuk nilai tersebut dikirim dengan SQLPutData dengan cara biasa. Aspek-aspek berikut dari proses ini memberikan komentar khusus karena tidak mudah jelas:

• Ketika driver mengembalikan SQL_NEED_DATA, driver harus mengatur alamat variabel nomor baris ke baris yang membutuhkan data. Seperti dalam kasus bernilai tunggal, aplikasi tidak dapat membuat asumsi apa pun tentang urutan di mana driver akan meminta nilai parameter dalam satu set parameter. Jika terjadi kesalahan dalam eksekusi parameter data-at-execution, buffer yang ditentukan oleh atribut pernyataan SQL_ATTR_PARAMS_PROCESSED_PTR diatur ke jumlah baris tempat kesalahan terjadi, status untuk baris dalam array status baris yang ditentukan oleh atribut pernyataan SQL_ATTR_PARAM_STATUS_PTR diatur ke SQL_PARAM_ERROR, dan panggilan ke SQLExecute, SQLExecDirect, SQLParamData, atau SQLPutData mengembalikan SQL_ERROR. Konten buffer ini tidak terdefinisi jika SQLExecute, SQLExecDirect, atau SQLParamData mengembalikan SQL_STILL_EXECUTING.

• Karena driver tidak menginterpretasikan nilai dalam argumen ParameterValuePtr SQLBindParameteruntuk parameter data-at-execution, jika aplikasi menyediakan penunjuk ke array, SQLParamData tidak mengekstrak dan mengembalikan elemen array ini ke aplikasi. Sebaliknya, ia mengembalikan nilai skalar yang telah disediakan aplikasi. Ini berarti nilai yang dikembalikan oleh SQLParamData tidak cukup untuk menentukan parameter yang perlu dikirim aplikasi data; aplikasi juga perlu mempertimbangkan nomor baris saat ini.

  Ketika hanya beberapa elemen array parameter yang merupakan parameter data-at-execution, aplikasi harus meneruskan alamat array di ParameterValuePtr yang berisi elemen untuk semua parameter. Array ini ditafsirkan secara normal untuk parameter yang bukan parameter data-at-execution. Untuk parameter data-at-execution, nilai yang disediakan SQLParamData ke aplikasi, yang biasanya dapat digunakan untuk mengidentifikasi data yang diminta driver pada kesempatan ini, selalu merupakan alamat array.