Menggunakan Larik Parameter

Untuk menggunakan array parameter, aplikasi memanggil SQLSetStmtAttr dengan argumen Atribut SQL_ATTR_PARAMSET_SIZE untuk menentukan jumlah set parameter. Fungsi ini memanggil SQLSetStmtAttr dengan argumen Attribute bernilai SQL_ATTR_PARAMS_PROCESSED_PTR untuk menentukan alamat variabel tempat driver dapat mengembalikan jumlah kumpulan parameter yang telah diproses, termasuk kumpulan yang mengalami kesalahan. Fungsi ini memanggil SQLSetStmtAttr dengan nilai argumen Attribute berupa SQL_ATTR_PARAM_STATUS_PTR, yang menunjuk ke sebuah array tempat informasi status untuk setiap baris nilai parameter dikembalikan. Driver tersebut menyimpan alamat ini dalam struktur yang dikelolanya untuk statement tersebut.

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 kumpulan parameter) tersedia (SQL_PARC_BATCH) atau apakah jumlah baris digabungkan 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 yang menghasilkan set hasil dieksekusi dengan array parameter, SQL_PARAM_ARRAY_SELECTS mengembalikan SQL_PAS_NO_SELECT. Apakah larik parameter dapat digunakan dengan jenis pernyataan lain bergantung pada sumber data, terutama karena penggunaan parameter dalam pernyataan tersebut juga akan bergantung pada sumber data dan tidak akan mengikuti tata bahasa SQL ODBC.

Array yang ditunjuk 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 dirujuk oleh atribut SQL_ATTR_PARAM_OPERATION_PTR dialokasikan dan diisi oleh aplikasi serta dibaca oleh driver. Jika baris yang diambil digunakan sebagai parameter masukan, nilai dalam array status baris dapat digunakan pada 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. Bergantung pada sumber data, apakah semua baris selain kumpulan kesalahan dieksekusi atau apakah semua baris sebelum (tetapi tidak setelah) kumpulan kesalahan dieksekusi. Karena memproses sekumpulan parameter, driver tersebut mengatur buffer yang ditentukan oleh atribut statement SQL_ATTR_PARAMS_PROCESSED_PTR menjadi nomor baris yang sedang diproses saat ini. 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 memberikan status untuk setiap kumpulan parameter. Larik status parameter dialokasikan oleh aplikasi dan kemudian 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.

Cara penggunaan array status parameter ditentukan oleh opsi SQL_PARAM_ARRAY_ROW_COUNTS dan SQL_PARAM_ARRAY_SELECTS yang dikembalikan oleh pemanggilan 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 akan diisi jika SQL_PAS_BATCH dikembalikan untuk SQL_PARAM_ARRAY_SELECT, tetapi tidak akan diisi jika SQL_PAS_NO_BATCH atau SQL_PAS_NO_SELECT dikembalikan.

Parameter Data saat Eksekusi

Jika salah satu nilai dalam array panjang/indikator adalah SQL_DATA_AT_EXEC atau merupakan hasil dari 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 menafsirkan nilai dalam argumen ParameterValuePtr dari SQLBindParameter untuk parameter data-saat-eksekusi, jika aplikasi menyediakan penunjuk ke array, SQLParamData tidak mengekstrak dan mengembalikan elemen dari array tersebut 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 dari array parameter yang merupakan parameter data-at-execution, aplikasi harus meneruskan alamat sebuah array dalam 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 diberikan SQLParamData kepada aplikasi, yang biasanya dapat digunakan untuk mengidentifikasi data yang sedang diminta oleh driver dalam hal ini, selalu berupa alamat array.