Fungsi SQLBindParameter
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 2.0: ODBC
Ringkasan
SQLBindParameter mengikat buffer ke penanda parameter dalam pernyataan SQL. SQLBindParameter mendukung pengikatan ke jenis data Unicode C, bahkan jika driver yang mendasar tidak mendukung data Unicode.
Catatan
Fungsi ini menggantikan fungsi ODBC 1.0 SQLSetParam. Untuk informasi selengkapnya, lihat "Komentar."
Sintaks
SQLRETURN SQLBindParameter(
SQLHSTMT StatementHandle,
SQLUSMALLINT ParameterNumber,
SQLSMALLINT InputOutputType,
SQLSMALLINT ValueType,
SQLSMALLINT ParameterType,
SQLULEN ColumnSize,
SQLSMALLINT DecimalDigits,
SQLPOINTER ParameterValuePtr,
SQLLEN BufferLength,
SQLLEN * StrLen_or_IndPtr);
Argumen
StatementHandle
[Input] Handel pernyataan.
ParameterNumber
[Input] Nomor parameter, diurutkan secara berurutan dalam meningkatkan urutan parameter, mulai dari 1.
InputOutputType
[Input] Jenis parameter. Untuk informasi selengkapnya, lihat "Argumen InputOutputType " di "Komentar."
ValueType
[Input] Jenis data C parameter. Untuk informasi selengkapnya, lihat "Argumen ValueType " di "Komentar."
ParameterType
[Input] Jenis data SQL parameter. Untuk informasi selengkapnya, lihat "ParameterType Argument" di "Komentar."
Ukuran Kolom
[Input] Ukuran kolom atau ekspresi penanda parameter yang sesuai. Untuk informasi selengkapnya, lihat "Argumen ColumnSize " di "Komentar."
Jika aplikasi Anda akan berjalan pada sistem operasi Windows 64-bit, lihat Informasi ODBC 64-Bit.
DecimalDigits
[Input] Digit desimal kolom atau ekspresi penanda parameter terkait. Untuk informasi selengkapnya tentang ukuran kolom, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Ukuran Tampilan.
ParameterValuePtr
[Input Yang Ditangguhkan] Penunjuk ke buffer untuk data parameter. Untuk informasi selengkapnya, lihat "ParameterValuePtr Argumen" di "Komentar."
BufferLength
[Input/Output] Panjang buffer ParameterValuePtr dalam byte. Untuk informasi selengkapnya, lihat "Argumen BufferLength " di "Komentar."
Lihat Informasi ODBC 64-Bit, jika aplikasi Anda akan berjalan pada sistem operasi 64-bit.
StrLen_or_IndPtr
[Input Yang Ditangguhkan] Penunjuk ke buffer untuk panjang parameter. Untuk informasi selengkapnya, lihat "argumen StrLen_or_IndPtr " di "Komentar."
Mengembalikan
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLBindParameter mengembalikan SQL_ERROR atau SQL_SUCCESS_WITH_INFO, nilai SQLSTATE terkait dapat diperoleh dengan memanggil SQLGetDiagRec dengan HandleType SQL_HANDLE_STMT dan Handle of StatementHandle. Tabel berikut mencantumkan nilai SQLSTATE yang biasanya dikembalikan oleh SQLBindParameter dan menjelaskan masing-masing dalam konteks fungsi ini; notasi "(DM)" mendahului deskripsi SQLSTATEs yang dikembalikan oleh Driver Manager. Kode pengembalian yang terkait dengan setiap nilai SQLSTATE SQL_ERROR, kecuali disebutkan sebaliknya.
| SQLSTATE | Kesalahan | Deskripsi |
|---|---|---|
| 01000 | Peringatan umum | Pesan informasi khusus driver. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 07006 | Pelanggaran atribut jenis data terbatas | Jenis data yang diidentifikasi oleh argumen ValueType tidak dapat dikonversi ke jenis data yang diidentifikasi oleh argumen ParameterType . Perhatikan bahwa kesalahan ini dapat dikembalikan oleh SQLExecDirect, SQLExecute, atau SQLPutData pada waktu eksekusi, bukan oleh SQLBindParameter. |
| 07009 | Indeks deskriptor tidak valid | (DM) Nilai yang ditentukan untuk parameter ParameterNumber kurang dari 1. |
| HY000 | Kesalahan umum | Terjadi kesalahan yang tidak ada SQLSTATE tertentu dan tidak ada SQLSTATE khusus implementasi yang ditentukan. Pesan kesalahan yang dikembalikan oleh SQLGetDiagRec di buffer *MessageText menjelaskan kesalahan dan penyebabnya. |
| HY001 | Kesalahan alokasi memori | Driver tidak dapat mengalokasikan memori yang diperlukan untuk mendukung eksekusi atau penyelesaian fungsi. |
| HY003 | Jenis buffer aplikasi tidak valid | Nilai yang ditentukan oleh argumen ValueType bukan tipe data C yang valid atau SQL_C_DEFAULT. |
| HY004 | Tipe data SQL tidak valid | Nilai yang ditentukan untuk argumen ParameterType bukan pengidentifikasi tipe data ODBC SQL yang valid atau pengidentifikasi jenis data SQL khusus driver yang didukung oleh driver. |
| HY009 | Nilai argumen tidak valid | (DM) ParameterValuePtr argumen adalah penunjuk null, argumen StrLen_or_IndPtr adalah penunjuk null, dan argumen InputOutputType tidak SQL_PARAM_OUTPUT. (DM) SQL_PARAM_OUTPUT, di mana parameter ParameterValuePtr adalah pointer null, jenis C adalah karakter atau biner, dan BufferLength (cbValueMax) lebih besar dari 0. |
| HY010 | Kesalahan urutan fungsi | (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi asinkron ini masih dijalankan ketika SQLBindParameter dipanggil. (DM) SQLExecute, SQLExecDirect, atau SQLMoreResults dipanggil untuk StatementHandle dan dikembalikan SQL_PARAM_DATA_AVAILABLE. Fungsi ini dipanggil sebelum data diambil untuk semua parameter yang dialirkan. (DM) Fungsi eksekusi asinkron dipanggil untuk StatementHandle dan masih dijalankan ketika fungsi ini dipanggil. (DM) SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk StatementHandle dan dikembalikan SQL_NEED_DATA. Fungsi ini dipanggil sebelum data dikirim untuk semua parameter atau kolom data-at-execution. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY021 | Informasi deskriptor yang tidak konsisten | Informasi deskriptor yang diperiksa selama pemeriksaan konsistensi tidak konsisten. (Lihat bagian "Pemeriksaan Konsistensi" di SQLSetDescField.) Nilai yang ditentukan untuk argumen DecimalDigits berada di luar rentang nilai yang didukung oleh sumber data untuk kolom jenis data SQL yang ditentukan oleh argumen ParameterType . |
| HY090 | String atau panjang buffer tidak valid | (DM) Nilai dalam BufferLength kurang dari 0. (Lihat deskripsi bidang SQL_DESC_DATA_PTR di SQLSetDescField.) |
| HY104 | Presisi atau nilai skala tidak valid | Nilai yang ditentukan untuk argumen ColumnSize atau DecimalDigits berada di luar rentang nilai yang didukung oleh sumber data untuk kolom jenis data SQL yang ditentukan oleh argumen ParameterType. |
| HY105 | Jenis parameter tidak valid | (DM) Nilai yang ditentukan untuk argumen InputOutputType tidak valid. (Lihat "Komentar.") |
| HY117 | Koneksi ditangguhkan karena status transaksi yang tidak diketahui. Hanya fungsi putuskan sambungan dan baca-saja yang diizinkan. | (DM) Untuk informasi selengkapnya tentang status ditangguhkan, lihat Fungsi SQLEndTran. |
| HYC00 | Fitur opsional tidak diimplementasikan | Driver atau sumber data tidak mendukung konversi yang ditentukan oleh kombinasi nilai yang ditentukan untuk argumen ValueType dan nilai khusus driver yang ditentukan untuk argumen ParameterType. Nilai yang ditentukan untuk argumen ParameterType adalah pengidentifikasi tipe data ODBC SQL yang valid untuk versi ODBC yang didukung oleh driver tetapi tidak didukung oleh driver atau sumber data. Driver hanya mendukung ODBC 2.x dan argumen ValueType adalah salah satu dari berikut ini: SQL_C_NUMERIC SQL_C_SBIGINT SQL_C_UBIGINT dan semua jenis data C interval yang tercantum dalam Tipe Data C di Lampiran D: Jenis Data. Driver hanya mendukung versi ODBC sebelum 3.50, dan argumen ValueType SQL_C_GUID. |
| HYT01 | Kesalahan waktu habis koneksi kedaluwarsa | Periode batas waktu koneksi kedaluwarsa sebelum sumber data merespons permintaan. Periode batas waktu koneksi diatur melalui SQLSet Koneksi Attr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver tidak mendukung fungsi ini | (DM) Driver yang terkait dengan StatementHandle tidak mendukung fungsi. |
Komentar
Aplikasi memanggil SQLBindParameter untuk mengikat setiap penanda parameter dalam pernyataan SQL. Pengikatan tetap berlaku sampai aplikasi memanggil SQLBindParameter lagi, memanggil SQLFreeStmt dengan opsi SQL_RESET_PARAMS, atau memanggil SQLSetDescField untuk mengatur bidang header SQL_DESC_COUNT APD ke 0.
Untuk informasi selengkapnya tentang parameter, lihat Parameter Pernyataan. Untuk informasi selengkapnya tentang jenis data parameter dan penanda parameter, lihat Jenis Data Parameter dan Penanda Parameter di Lampiran C: Tata Bahasa SQL.
Argumen ParameterNumber
Jika ParameterNumber dalam panggilan ke SQLBindParameter lebih besar dari nilai SQL_DESC_COUNT, SQLSetDescField dipanggil untuk meningkatkan nilai SQL_DESC_COUNT ke ParameterNumber.
Argumen InputOutputType
Argumen InputOutputType menentukan jenis parameter. Argumen ini mengatur bidang SQL_DESC_PARAMETER_TYPE IPD. Semua parameter dalam pernyataan SQL yang tidak memanggil prosedur, seperti pernyataan INSERT, adalah parameter input. Parameter dalam panggilan prosedur dapat berupa parameter input, input/output, atau output. (Panggilan aplikasiSQLProcedureColumns untuk menentukan jenis parameter dalam panggilan prosedur; parameter yang jenisnya tidak dapat ditentukan diasumsikan sebagai parameter input.)
Argumen InputOutputType adalah salah satu nilai berikut:
SQL_PARAM_INPUT. Parameter menandai parameter dalam pernyataan SQL yang tidak memanggil prosedur, seperti pernyataan INSERT , atau menandai parameter input dalam prosedur. Misalnya, parameter dalam INSERT INTO Employee VALUES (?, ?, ?) adalah parameter input, sedangkan parameter dalam {call AddEmp(?, ?, ?)} bisa, tetapi belum tentu, parameter input.
Ketika pernyataan dijalankan, driver mengirim data untuk parameter ke sumber data; buffer *ParameterValuePtr harus berisi nilai input yang valid, atau buffer *StrLen_or_IndPtr harus berisi SQL_NULL_DATA, SQL_DATA_AT_EXEC, atau hasil makro SQL_LEN_DATA_AT_EXEC.
Jika aplikasi tidak dapat menentukan jenis parameter dalam panggilan prosedur, aplikasi mengatur InputOutputType ke SQL_PARAM_INPUT; jika sumber data mengembalikan nilai untuk parameter, driver akan membuangnya.
SQL_PARAM_INPUT_OUTPUT. Parameter menandai parameter input/output dalam prosedur. Misalnya, parameter di {call GetEmpDept(?)} adalah parameter input/output yang menerima nama karyawan dan mengembalikan nama departemen karyawan.
Ketika pernyataan dijalankan, driver mengirim data untuk parameter ke sumber data; buffer *ParameterValuePtr harus berisi nilai input yang valid, atau buffer *StrLen_or_IndPtr harus berisi SQL_NULL_DATA, SQL_DATA_AT_EXEC, atau hasil makro SQL_LEN_DATA_AT_EXEC. Setelah pernyataan dijalankan, driver mengembalikan data untuk parameter ke aplikasi; jika sumber data tidak mengembalikan nilai untuk parameter input/output, driver mengatur buffer *StrLen_or_IndPtr ke SQL_NULL_DATA.
Catatan
Ketika aplikasi ODBC 1.0 memanggil SQLSetParam dalam driver ODBC 2.0, Driver Manager mengonversi ini ke panggilan ke SQLBindParameter tempat argumen InputOutputType diatur ke SQL_PARAM_INPUT_OUTPUT.
SQL_PARAM_OUTPUT. Parameter menandai nilai pengembalian prosedur atau parameter output dalam prosedur; dalam kedua kasus, ini dikenal sebagai parameter output. Misalnya, parameter di {?=call GetNextEmpID} adalah parameter output yang mengembalikan ID karyawan berikutnya.
Setelah pernyataan dijalankan, driver mengembalikan data untuk parameter ke aplikasi, kecuali argumen ParameterValuePtr dan StrLen_or_IndPtr keduanya adalah pointer null, dalam hal ini driver membuang nilai output. Jika sumber data tidak mengembalikan nilai untuk parameter output, driver mengatur buffer *StrLen_or_IndPtr ke SQL_NULL_DATA.
SQL_PARAM_INPUT_OUTPUT_STREAM. Menunjukkan bahwa parameter input/output harus dialirkan. SQLGetData dapat membaca nilai parameter dalam beberapa bagian. BufferLength diabaikan karena panjang buffer akan ditentukan pada panggilan SQLGetData. Nilai buffer StrLen_or_IndPtr harus berisi SQL_NULL_DATA, SQL_DEFAULT_PARAM, SQL_DATA_AT_EXEC, atau hasil makro SQL_LEN_DATA_AT_EXEC. Parameter harus terikat sebagai parameter data-at-execution (DAE) pada input jika akan dialirkan pada output. ParameterValuePtr dapat berupa nilai pointer non-null yang akan dikembalikan oleh SQLParamData sebagai token yang ditentukan pengguna yang nilainya diteruskan dengan ParameterValuePtr untuk input dan output. Untuk informasi selengkapnya, lihat Mengambil Parameter Output Menggunakan SQLGetData.
SQL_PARAM_OUTPUT_STREAM. Sama seperti SQL_PARAM_INPUT_OUTPUT_STREAM, untuk parameter output. * StrLen_or_IndPtr diabaikan saat input.
Tabel berikut mencantumkan kombinasi InputOutputType dan *StrLen_or_IndPtr yang berbeda:
| InputOutputType | *StrLen_or_IndPtr | Hasil | Komentar pada ParameterValuePtr |
|---|---|---|---|
| SQL_PARAM_INPUT | SQL_LEN_DATA_AT_EXEC(len) atau SQL_DATA_AT_EXEC | Input dalam bagian | ParameterValuePtr dapat menjadi nilai penunjuk apa pun yang akan dikembalikan oleh SQLParamData sebagai token yang ditentukan pengguna yang nilainya diteruskan dengan ParameterValuePtr. |
| SQL_PARAM_INPUT | Bukan SQL_LEN_DATA_AT_EXEC(lensa) atau SQL_DATA_AT_EXEC | Buffer terikat input | ParameterValuePtr adalah alamat buffer input. |
| SQL_PARAM_OUTPUT | Diabaikan saat input. | Buffer terikat output | ParameterValuePtr adalah alamat buffer output. |
| SQL_PARAM_OUTPUT_STREAM | Diabaikan saat input. | Output yang dialirkan | ParameterValuePtr dapat menjadi nilai penunjuk apa pun, yang akan dikembalikan oleh SQLParamData sebagai token yang ditentukan pengguna yang nilainya diteruskan dengan ParameterValuePtr. |
| SQL_PARAM_INPUT_OUTPUT | SQL_LEN_DATA_AT_EXEC(len) atau SQL_DATA_AT_EXEC | Input dalam bagian dan buffer terikat output | ParameterValuePtr adalah alamat buffer output, yang juga akan dikembalikan oleh SQLParamData sebagai token yang ditentukan pengguna yang nilainya diteruskan dengan ParameterValuePtr. |
| SQL_PARAM_INPUT_OUTPUT | Bukan SQL_LEN_DATA_AT_EXEC(lensa) atau SQL_DATA_AT_EXEC | Buffer terikat input dan buffer terikat output | ParameterValuePtr adalah alamat buffer input/output bersama. |
| SQL_PARAM_INPUT_OUTPUT_STREAM | SQL_LEN_DATA_AT_EXEC(len) atau SQL_DATA_AT_EXEC | Input dalam bagian dan output yang dialirkan | ParameterValuePtr dapat berupa nilai pointer non-null apa pun, yang akan dikembalikan oleh SQLParamData sebagai token yang ditentukan pengguna yang nilainya diteruskan dengan ParameterValuePtr untuk input dan output. |
Catatan
Driver harus memutuskan jenis SQL mana yang diizinkan ketika aplikasi mengikat parameter output atau input-output seperti yang dialirkan. Manajer driver tidak akan menghasilkan kesalahan untuk jenis SQL yang tidak valid.
Argumen ValueType
Argumen ValueType menentukan jenis data C dari parameter . Argumen ini mengatur bidang APD SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE, dan SQL_DESC_DATETIME_INTERVAL_CODE. Ini harus menjadi salah satu nilai di bagian Tipe Data C lampiran D: Jenis Data.
Jika argumen ValueType adalah salah satu jenis data interval, bidang SQL_DESC_TYPE dari catatan ParameterNumber APD diatur ke SQL_INTERVAL, bidang SQL_DESC_CONCISE_TYPE APD diatur ke jenis data interval ringkas, dan bidang SQL_DESC_DATETIME_INTERVAL_CODE catatan ParameterNumber diatur ke subkode untuk jenis data interval tertentu. (Lihat Lampiran D: Jenis Data.) Presisi terdepan interval default (2) dan presisi detik interval default (6), sebagaimana diatur dalam bidang SQL_DESC_DATETIME_INTERVAL_PRECISION dan SQL_DESC_PRECISION APD, masing-masing, digunakan untuk data. Jika presisi default tidak sesuai, aplikasi harus secara eksplisit mengatur bidang deskriptor dengan panggilan ke SQLSetDescField atau SQLSetDescRec.
Jika argumen ValueType adalah salah satu jenis data tanggalwaktu, bidang SQL_DESC_TYPE dari catatan ParameterNumber APD diatur ke SQL_DATETIME, bidang SQL_DESC_CONCISE_TYPE dari catatan ParameterNumber APD diatur ke jenis data C tanggalwaktu yang ringkas, dan bidang SQL_DESC_DATETIME_INTERVAL_CODE catatan ParameterNumber diatur ke subkode untuk jenis data tanggalwaktu tertentu. (Lihat Lampiran D: Jenis Data.)
Jika argumen ValueType adalah jenis data SQL_C_NUMERIC, presisi default (yang ditentukan driver) dan skala default (0), sebagaimana diatur dalam bidang SQL_DESC_PRECISION dan SQL_DESC_SCALE APD, digunakan untuk data. Jika presisi atau skala default tidak sesuai, aplikasi harus secara eksplisit mengatur bidang deskriptor dengan panggilan ke SQLSetDescField atau SQLSetDescRec.
SQL_C_DEFAULT menentukan bahwa nilai parameter ditransfer dari jenis data C default untuk jenis data SQL yang ditentukan dengan ParameterType.
Anda juga dapat menentukan jenis data C yang diperluas. Untuk informasi selengkapnya, lihat Jenis Data C di ODBC.
Untuk informasi selengkapnya, lihat Jenis Data C Default, Mengonversi Data dari Jenis Data C ke SQL, dan Mengonversi Data dari SQL ke Tipe Data C di Lampiran D: Jenis Data.
Argumen ParameterType
Ini harus menjadi salah satu nilai yang tercantum di bagian Jenis Data SQL dari Lampiran D: Jenis Data, atau harus berupa nilai khusus driver. Argumen ini mengatur bidang IPD SQL_DESC_TYPE, SQL_DESC_CONCISE_TYPE, dan SQL_DESC_DATETIME_INTERVAL_CODE.
Jika argumen ParameterType adalah salah satu pengidentifikasi tanggalwaktu, bidang SQL_DESC_TYPE IPD diatur ke SQL_DATETIME, bidang SQL_DESC_CONCISE_TYPE IPD diatur ke jenis data SQL tanggalwaktu ringkas, dan bidang SQL_DESC_DATETIME_INTERVAL_CODE diatur ke nilai subkode tanggalwaktu yang sesuai.
Jika ParameterType adalah salah satu pengidentifikasi interval, bidang SQL_DESC_TYPE IPD diatur ke SQL_INTERVAL, bidang SQL_DESC_CONCISE_TYPE IPD diatur ke jenis data interval SQL ringkas, dan bidang SQL_DESC_DATETIME_INTERVAL_CODE IPD diatur ke subkode interval yang sesuai. Bidang SQL_DESC_DATETIME_INTERVAL_PRECISION IPD diatur ke presisi terdepan interval, dan bidang SQL_DESC_PRECISION diatur ke presisi interval detik, jika berlaku. Jika nilai default SQL_DESC_DATETIME_INTERVAL_PRECISION atau SQL_DESC_PRECISION tidak sesuai, aplikasi harus secara eksplisit mengaturnya dengan memanggil SQLSetDescField. Untuk informasi selengkapnya tentang salah satu bidang ini, lihat SQLSetDescField.
Jika argumen ValueType adalah jenis data SQL_NUMERIC, presisi default (yang ditentukan driver) dan skala default (0), sebagaimana diatur dalam bidang SQL_DESC_PRECISION dan SQL_DESC_SCALE IPD, digunakan untuk data. Jika presisi atau skala default tidak sesuai, aplikasi harus secara eksplisit mengatur bidang deskriptor dengan panggilan ke SQLSetDescField atau SQLSetDescRec.
Untuk informasi tentang cara data dikonversi, lihat Mengonversi Data dari C ke Jenis Data SQL dan Mengonversi Data dari SQL ke Tipe Data C di Lampiran D: Jenis Data.
Argumen Ukuran Kolom
Argumen ColumnSize menentukan ukuran kolom atau ekspresi yang sesuai dengan penanda parameter, panjang data tersebut, atau keduanya. Argumen ini mengatur bidang IPD yang berbeda, tergantung pada jenis data SQL ( argumen ParameterType ). Aturan berikut berlaku untuk pemetaan ini:
Jika ParameterType SQL_CHAR, SQL_VARCHAR, SQL_LONGVARCHAR, SQL_BINARY, SQL_VARBINARY, SQL_LONGVARBINARY, atau salah satu jenis data datetime atau interval SQL ringkas, bidang SQL_DESC_LENGTH IPD diatur ke nilai ColumnSize. (Untuk informasi selengkapnya, lihat Ukuran Kolom, Digit Desimal, Panjang Oktet Transfer, dan Bagian Ukuran Tampilan di Lampiran D: Jenis Data.)
Jika ParameterType SQL_DECIMAL, SQL_NUMERIC, SQL_FLOAT, SQL_REAL, atau SQL_DOUBLE, bidang SQL_DESC_PRECISION IPD diatur ke nilai ColumnSize.
Untuk jenis data lainnya, argumen ColumnSize diabaikan.
Untuk informasi selengkapnya, lihat "Meneruskan Nilai Parameter" dan SQL_DATA_AT_EXEC dalam "Argumen StrLen_or_IndPtr ."
Argumen DecimalDigits
Jika ParameterType SQL_TYPE_TIME, SQL_TYPE_TIMESTAMP, SQL_INTERVAL_SECOND, SQL_INTERVAL_DAY_TO_SECOND, SQL_INTERVAL_HOUR_TO_SECOND, atau SQL_INTERVAL_MINUTE_TO_SECOND, bidang SQL_DESC_PRECISION IPD diatur ke DecimalDigits. Jika ParameterType SQL_NUMERIC atau SQL_DECIMAL, bidang SQL_DESC_SCALE IPD diatur ke DecimalDigits. Untuk semua jenis data lainnya, argumen DecimalDigits diabaikan.
Argumen ParameterValuePtr
Argumen ParameterValuePtr menunjuk ke buffer yang, ketika SQLExecute atau SQLExecDirect dipanggil, berisi data aktual untuk parameter . Data harus dalam formulir yang ditentukan oleh argumen ValueType . Argumen ini mengatur bidang SQL_DESC_DATA_PTR APD. Aplikasi dapat mengatur argumen ParameterValuePtr ke penunjuk null, selama *StrLen_or_IndPtr SQL_NULL_DATA atau SQL_DATA_AT_EXEC. (Ini hanya berlaku untuk parameter input atau input/output.)
Jika *StrLen_or_IndPtr adalah hasil dari makro SQL_LEN_DATA_AT_EXEC(panjang) atau SQL_DATA_AT_EXEC, maka ParameterValuePtr adalah nilai penunjuk yang ditentukan aplikasi yang terkait dengan parameter . Ini dikembalikan ke aplikasi melalui SQLParamData. Misalnya, ParameterValuePtr mungkin merupakan token non-nol seperti nomor parameter, penunjuk ke data, atau penunjuk ke struktur yang digunakan aplikasi untuk mengikat parameter input. Namun, perhatikan bahwa jika parameter adalah parameter input/output, ParameterValuePtr harus menjadi penunjuk ke buffer tempat nilai output akan disimpan. Jika nilai dalam atribut pernyataan SQL_ATTR_PARAMSET_SIZE lebih besar dari 1, aplikasi dapat menggunakan nilai yang ditujukkan oleh atribut pernyataan SQL_ATTR_PARAMS_PROCESSED_PTR bersama dengan argumen ParameterValuePtr . Misalnya, ParameterValuePtr mungkin menunjuk ke array nilai dan aplikasi mungkin menggunakan nilai yang ditunjukkan oleh SQL_ATTR_PARAMS_PROCESSED_PTR untuk mengambil nilai yang benar dari array. Untuk informasi selengkapnya, lihat "Meneruskan Nilai Parameter" nanti di bagian ini.
Jika argumen InputOutputType SQL_PARAM_INPUT_OUTPUT atau SQL_PARAM_OUTPUT, ParameterValuePtr menunjuk ke buffer tempat driver mengembalikan nilai output. Jika prosedur mengembalikan satu atau beberapa tataan hasil, buffer *ParameterValuePtr tidak dijamin akan diatur hingga semua kumpulan hasil/jumlah baris telah diproses. Jika buffer tidak diatur hingga pemrosesan selesai, parameter output dan nilai pengembalian tidak tersedia sampai SQLMoreResults mengembalikan SQL_NO_DATA. Memanggil SQLCloseCursor atau SQLFreeStmt dengan Opsi SQL_CLOSE akan menyebabkan nilai-nilai ini dibuang.
Jika nilai dalam atribut pernyataan SQL_ATTR_PARAMSET_SIZE lebih besar dari 1, ParameterValuePtr menunjuk ke array. Satu pernyataan SQL memproses array lengkap nilai input untuk parameter input atau input/output dan mengembalikan array nilai output untuk parameter input/output atau output.
Argumen BufferLength
Untuk data karakter dan biner C, argumen BufferLength menentukan panjang buffer *ParameterValuePtr (jika merupakan elemen tunggal) atau panjang elemen dalam array *ParameterValuePtr (jika nilai dalam atribut pernyataan SQL_ATTR_PARAMSET_SIZE lebih besar dari 1). Argumen ini mengatur bidang rekaman SQL_DESC_OCTET_LENGTH APD. Jika aplikasi menentukan beberapa nilai, BufferLength digunakan untuk menentukan lokasi nilai dalam array *ParameterValuePtr , baik pada input maupun pada output. Untuk parameter input/output dan output, ini digunakan untuk menentukan apakah akan memotong karakter dan data C biner pada output:
Untuk data karakter C, jika jumlah byte yang tersedia untuk dikembalikan lebih besar dari atau sama dengan BufferLength, data dalam *ParameterValuePtr dipotong menjadi BufferLength lebih sedikit panjang karakter penghentian null dan dihentikan null oleh driver.
Untuk data C biner, jika jumlah byte yang tersedia untuk dikembalikan lebih besar dari BufferLength, data di *ParameterValuePtr dipotong menjadi byte BufferLength .
Untuk semua jenis data C lainnya, argumen BufferLength diabaikan. Panjang buffer *ParameterValuePtr (jika merupakan elemen tunggal) atau panjang elemen dalam array *ParameterValuePtr (jika aplikasi memanggil SQLSetStmtAttr dengan argumen Atribut SQL_ATTR_PARAMSET_SIZE untuk menentukan beberapa nilai untuk setiap parameter) diasumsikan sebagai panjang jenis data C.
Untuk output yang dialirkan atau parameter input/output yang dialirkan, argumen BufferLength diabaikan karena panjang buffer ditentukan dalam SQLGetData.
Catatan
Ketika aplikasi ODBC 1.0 memanggil SQLSetParam di ODBC 3.driver x , Driver Manager mengonversi ini menjadi panggilan ke SQLBindParameter di mana argumen BufferLength selalu SQL_SETPARAM_VALUE_MAX. Karena Driver Manager mengembalikan kesalahan jika ODBC 3.aplikasi x mengatur BufferLength ke SQL_SETPARAM_VALUE_MAX, ODBC 3.driver x dapat menggunakan ini untuk menentukan kapan dipanggil oleh aplikasi ODBC 1.0.
Catatan
Di SQLSetParam, cara aplikasi menentukan panjang buffer *ParameterValuePtr sehingga driver dapat mengembalikan karakter atau data biner, dan cara aplikasi mengirim array karakter atau nilai parameter biner ke driver, ditentukan driver.
Argumen StrLen_or_IndPtr
Argumen StrLen_or_IndPtr menunjuk ke buffer yang, ketika SQLExecute atau SQLExecDirect dipanggil, berisi salah satu hal berikut ini. (Argumen ini mengatur bidang rekaman SQL_DESC_OCTET_LENGTH_PTR dan SQL_DESC_INDICATOR_PTR dari penunjuk parameter aplikasi.)
Panjang nilai parameter yang disimpan dalam *ParameterValuePtr. Ini diabaikan kecuali untuk data karakter atau biner C.
SQL_NTS. Nilai parameter adalah string null-terminated.
SQL_NULL_DATA. Nilai parameter adalah NULL.
SQL_DEFAULT_PARAM. Prosedurnya adalah menggunakan nilai default parameter, bukan nilai yang diambil dari aplikasi. Nilai ini hanya valid dalam prosedur yang disebut dalam sintaksis kanonis ODBC, lalu hanya jika argumen InputOutputType SQL_PARAM_INPUT, SQL_PARAM_INPUT_OUTPUT, atau SQL_PARAM_INPUT_OUTPUT_STREAM. Saat *StrLen_or_IndPtr SQL_DEFAULT_PARAM, argumen ValueType, ParameterType, ColumnSize, DecimalDigits, BufferLength, dan ParameterValuePtr diabaikan untuk parameter input dan hanya digunakan untuk menentukan nilai parameter output untuk parameter input/output.
Hasil makro SQL_LEN_DATA_AT_EXEC(panjang). Data untuk parameter akan dikirim dengan SQLPutData. Jika argumen ParameterType SQL_LONGVARBINARY, SQL_LONGVARCHAR, atau tipe data spesifik sumber data yang panjang, dan driver mengembalikan "Y" untuk jenis informasi SQL_NEED_LONG_DATA_LEN di SQLGetInfo, panjangnya adalah jumlah byte data yang akan dikirim untuk parameter; jika tidak, panjang harus berupa nilai nonnegatif dan diabaikan. Untuk informasi selengkapnya, lihat "Meneruskan Nilai Parameter," nanti di bagian ini.
Misalnya, untuk menentukan bahwa 10.000 byte data akan dikirim dengan SQLPutData dalam satu atau beberapa panggilan, untuk parameter SQL_LONGVARCHAR, aplikasi menetapkan *StrLen_or_IndPtr ke SQL_LEN_DATA_AT_EXEC(10000).
SQL_DATA_AT_EXEC. Data untuk parameter akan dikirim dengan SQLPutData. Nilai ini digunakan oleh aplikasi ODBC 1.0 saat mereka memanggil ODBC 3.x driver. Untuk informasi selengkapnya, lihat "Meneruskan Nilai Parameter," nanti di bagian ini.
Jika StrLen_or_IndPtr adalah penunjuk null, driver mengasumsikan bahwa semua nilai parameter input non-NULL dan karakter dan data biner dihentikan null. Jika InputOutputType SQL_PARAM_OUTPUT atau SQL_PARAM_OUTPUT_STREAM dan ParameterValuePtr dan StrLen_or_IndPtr keduanya adalah penunjuk null, driver akan membuang nilai output.
Catatan
Pengembang aplikasi sangat tidak dianjurkan untuk menentukan pointer null untuk StrLen_or_IndPtr ketika jenis data parameter SQL_C_BINARY. Untuk memastikan bahwa driver tidak secara tiba-tiba memotong data SQL_C_BINARY, StrLen_or_IndPtr harus berisi penunjuk ke nilai panjang yang valid.
Jika argumen InputOutputType SQL_PARAM_INPUT_OUTPUT, SQL_PARAM_OUTPUT, SQL_PARAM_INPUT_OUTPUT_STREAM, atau SQL_PARAM_OUTPUT_STREAM, StrLen_or_IndPtr menunjuk ke buffer tempat driver mengembalikan SQL_NULL_DATA, jumlah byte yang tersedia untuk dikembalikan dalam *ParameterValuePtr (tidak termasuk byte null-termination data karakter), atau SQL_NO_TOTAL (jika jumlah byte yang tersedia untuk dikembalikan tidak dapat ditentukan). Jika prosedur mengembalikan satu atau beberapa tataan hasil, buffer *StrLen_or_IndPtr tidak dijamin akan diatur hingga semua hasil diambil.
Jika nilai dalam atribut pernyataan SQL_ATTR_PARAMSET_SIZE lebih besar dari 1, StrLen_or_IndPtr menunjuk ke array nilai SQLLEN. Ini bisa menjadi salah satu nilai yang tercantum sebelumnya di bagian ini dan diproses dengan satu pernyataan SQL.
Meneruskan Nilai Parameter
Aplikasi dapat meneruskan nilai untuk parameter baik di buffer *ParameterValuePtr atau dengan satu atau beberapa panggilan ke SQLPutData. Parameter yang datanya diteruskan dengan SQLPutData dikenal sebagai parameter data-at-execution . Ini biasanya digunakan untuk mengirim data untuk parameter SQL_LONGVARBINARY dan SQL_LONGVARCHAR, dan dapat dicampur dengan parameter lain.
Untuk meneruskan nilai parameter, aplikasi melakukan urutan langkah-langkah berikut:
Memanggil SQLBindParameter untuk setiap parameter untuk mengikat buffer untuk nilai parameter (argumen ParameterValuePtr) dan panjang/indikator (argumen StrLen_or_IndPtr). Untuk parameter data-at-execution, ParameterValuePtr adalah nilai penunjuk yang ditentukan aplikasi seperti nomor parameter atau pointer ke data. Nilai akan dikembalikan nanti dan dapat digunakan untuk mengidentifikasi parameter.
Tempatkan nilai untuk parameter input dan input/output dalam buffer *ParameterValuePtr dan *StrLen_or_IndPtr :
Untuk parameter normal, aplikasi menempatkan nilai parameter dalam buffer *ParameterValuePtr dan panjang nilai tersebut dalam buffer *StrLen_or_IndPtr . Untuk informasi selengkapnya, lihat Mengatur Nilai Parameter.
Untuk parameter data-at-execution, aplikasi menempatkan hasil makro SQL_LEN_DATA_AT_EXEC(length) (saat memanggil driver ODBC 2.0) di buffer *StrLen_or_IndPtr .
Memanggil SQLExecute atau SQLExecDirect untuk menjalankan pernyataan SQL.
Jika tidak ada parameter data-at-execution, proses selesai.
Jika ada parameter data-at-execution, fungsi mengembalikan SQL_NEED_DATA.
Memanggil SQLParamData untuk mengambil nilai yang ditentukan aplikasi yang ditentukan dalam argumen ParameterValuePtr dari SQLBindParameter untuk parameter data-at-execution pertama yang akan diproses. SQLParamData mengembalikan SQL_NEED_DATA.
Catatan
Meskipun parameter data-at-execution menyerupai kolom data-at-execution, nilai yang dikembalikan oleh SQLParamData berbeda untuk masing-masing. Parameter data-at-execution adalah parameter dalam pernyataan SQL tempat data akan dikirim dengan SQLPutData ketika pernyataan dijalankan dengan SQLExecDirect atau SQLExecute. Mereka terikat dengan SQLBindParameter. Nilai yang dikembalikan oleh SQLParamData adalah nilai penunjuk yang diteruskan ke SQLBindParameter dalam argumen ParameterValuePtr. Kolom data yang dieksekusi adalah kolom dalam kumpulan baris yang datanya akan dikirim dengan SQLPutData saat baris diperbarui atau ditambahkan dengan SQLBulkOperations atau diperbarui dengan SQLSetPos. Mereka terikat dengan SQLBindCol. Nilai yang dikembalikan oleh SQLParamData adalah alamat baris dalam buffer *TargetValuePtr (diatur oleh panggilan ke SQLBindCol) yang sedang diproses.
Memanggil SQLPutData satu atau beberapa kali untuk mengirim data untuk parameter. Lebih dari satu panggilan diperlukan jika nilai data lebih besar dari buffer *ParameterValuePtr yang ditentukan dalam SQLPutData; beberapa panggilan ke SQLPutData untuk parameter yang sama hanya diperbolehkan saat mengirim data C karakter ke kolom dengan tipe data khusus karakter, biner, atau sumber data atau saat mengirim data C biner ke kolom dengan karakter, biner, atau jenis data khusus sumber data.
Memanggil SQLParamData lagi untuk memberi sinyal bahwa semua data telah dikirim untuk parameter .
Jika ada lebih banyak parameter data-at-execution, SQLParamData mengembalikan SQL_NEED_DATA dan nilai yang ditentukan aplikasi untuk parameter data-at-execution berikutnya yang akan diproses. Aplikasi mengulangi langkah 4 dan 5.
Jika tidak ada lagi parameter data-at-execution, proses selesai. Jika pernyataan berhasil dijalankan, SQLParamData mengembalikan SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO; jika eksekusi gagal, maka akan mengembalikan SQL_ERROR. Pada titik ini, SQLParamData dapat mengembalikan SQLSTATE apa pun yang dapat dikembalikan oleh fungsi yang digunakan untuk menjalankan pernyataan (SQLExecDirect atau SQLExecute).
Nilai output untuk parameter input/output atau output apa pun tersedia di buffer *ParameterValuePtr dan *StrLen_or_IndPtr setelah aplikasi mengambil semua kumpulan hasil yang dihasilkan oleh pernyataan.
Memanggil SQLExecute atau SQLExecDirect menempatkan pernyataan dalam status SQL_NEED_DATA. Pada titik ini, aplikasi hanya dapat memanggil SQLCancel, SQLGetDiagField, SQLGetDiagRec, SQLGetFunctions, SQLParamData, atau SQLPutData dengan pernyataan atau handel koneksi yang terkait dengan pernyataan. Jika memanggil fungsi lain dengan pernyataan atau koneksi yang terkait dengan pernyataan, fungsi mengembalikan SQLSTATE HY010 (Kesalahan urutan fungsi). Pernyataan meninggalkan status SQL_NEED_DATA saat SQLParamData atau SQLPutData mengembalikan kesalahan, SQLParamData mengembalikan SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO, atau pernyataan dibatalkan.
Jika aplikasi memanggil SQLCancel saat driver masih membutuhkan data untuk parameter data-at-execution, driver membatalkan eksekusi pernyataan; aplikasi kemudian dapat memanggil SQLExecute atau SQLExecDirect lagi.
Mengambil Parameter Output yang Dialirkan
Saat aplikasi mengatur InputOutputType ke SQL_PARAM_INPUT_OUTPUT_STREAM atau SQL_PARAM_OUTPUT_STREAM, nilai parameter output harus diambil oleh satu atau beberapa panggilan ke SQLGetData. Ketika driver memiliki nilai parameter output yang dialirkan untuk kembali ke aplikasi, driver akan mengembalikan SQL_PARAM_DATA_AVAILABLE sebagai respons terhadap panggilan ke fungsi berikut: SQLMoreResults, SQLExecute, dan SQLExecDirect. Aplikasi memanggil SQLParamData untuk menentukan nilai parameter mana yang tersedia.
Untuk informasi selengkapnya tentang parameter output SQL_PARAM_DATA_AVAILABLE dan streaming, lihat Mengambil Parameter Output Menggunakan SQLGetData.
Menggunakan Array Parameter
Saat aplikasi menyiapkan pernyataan dengan penanda parameter dan meneruskan array parameter, ada dua cara berbeda untuk menjalankannya. Salah satu caranya adalah agar driver mengandalkan kemampuan pemrosesan array dari ujung belakang, dalam hal ini seluruh pernyataan dengan array parameter diperlakukan sebagai satu unit atomik. Oracle adalah contoh sumber data yang mendukung kemampuan pemrosesan array. Cara lain untuk menerapkan fitur ini adalah agar driver menghasilkan batch pernyataan SQL, satu pernyataan SQL untuk setiap set parameter dalam array parameter, dan menjalankan batch. Array parameter tidak dapat digunakan dengan pernyataan UPDATE WHERE CURRENT OF .
Saat array parameter diproses, kumpulan hasil individu/jumlah baris (satu untuk setiap set parameter) dapat tersedia atau jumlah kumpulan/baris hasil dapat digulung menjadi satu. Opsi SQL_PARAM_ARRAY_ROW_COUNTS di SQLGetInfo menunjukkan apakah jumlah baris tersedia untuk setiap set parameter (SQL_PARC_BATCH) atau hanya satu jumlah baris yang tersedia (SQL_PARC_NO_BATCH).
Opsi SQL_PARAM_ARRAY_SELECTS di SQLGetInfo menunjukkan apakah kumpulan hasil tersedia untuk setiap set parameter (SQL_PAS_BATCH) atau 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.
Untuk informasi selengkapnya, lihat Fungsi SQLGetInfo.
Untuk mendukung array parameter, atribut pernyataan SQL_ATTR_PARAMSET_SIZE diatur untuk menentukan jumlah nilai untuk setiap parameter. Jika bidang lebih besar dari 1, bidang SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, dan SQL_DESC_OCTET_LENGTH_PTR APD harus menunjuk ke array. Kardinalitas setiap array sama dengan nilai SQL_ATTR_PARAMSET_SIZE.
Bidang SQL_DESC_ROWS_PROCESSED_PTR APD menunjuk ke buffer yang berisi jumlah set parameter yang telah diproses, termasuk set kesalahan. Saat setiap set parameter diproses, driver menyimpan nilai baru di buffer. Tidak ada angka yang akan dikembalikan jika ini adalah penunjuk null. Ketika array parameter digunakan, nilai yang ditujukkan oleh bidang SQL_DESC_ROWS_PROCESSED_PTR APD diisi bahkan jika SQL_ERROR dikembalikan oleh fungsi pengaturan. Jika SQL_NEED_DATA dikembalikan, nilai yang ditujukkan oleh bidang SQL_DESC_ROWS_PROCESSED_PTR APD diatur ke kumpulan parameter yang sedang diproses.
Apa yang terjadi ketika array parameter terikat dan pernyataan UPDATE WHERE CURRENT OF dijalankan ditentukan driver.
Pengikatan Parameter Bijaksana Kolom
Dalam pengikatan kolom yang bijaksana, aplikasi mengikat parameter terpisah dan array panjang/indikator ke setiap parameter.
Untuk menggunakan pengikatan kolom yang bijaksana, aplikasi pertama-tama mengatur atribut pernyataan SQL_ATTR_PARAM_BIND_TYPE ke SQL_PARAM_BIND_BY_COLUMN. (Ini adalah default.) Agar setiap kolom terikat, aplikasi melakukan langkah-langkah berikut:
Mengalokasikan array buffer parameter.
Mengalokasikan array buffer panjang/indikator.
Catatan
Jika aplikasi menulis langsung ke deskriptor saat pengikatan bijaksana kolom digunakan, array terpisah dapat digunakan untuk data panjang dan indikator.
Memanggil SQLBindParameter dengan argumen berikut:
ValueType adalah tipe C dari satu elemen dalam array buffer parameter.
ParameterType adalah jenis parameter SQL.
ParameterValuePtr adalah alamat array buffer parameter.
BufferLength adalah ukuran elemen tunggal dalam array buffer parameter. Argumen BufferLength diabaikan saat data adalah data dengan panjang tetap.
StrLen_or_IndPtr adalah alamat array panjang/indikator.
Untuk informasi selengkapnya tentang bagaimana informasi ini digunakan, lihat "ParameterValuePtr Argumen" di "Komentar," nanti di bagian ini. Untuk informasi selengkapnya tentang pengikatan parameter yang bijaksana kolom, lihat Mengikat Array Parameter.
Pengikatan Parameter Row-Wise
Dalam pengikatan baris-bijaksana, aplikasi mendefinisikan struktur yang berisi buffer parameter dan panjang/indikator untuk setiap parameter yang akan diikat.
Untuk menggunakan pengikatan baris yang bijaksana, aplikasi melakukan langkah-langkah berikut:
Mendefinisikan struktur untuk menahan satu set parameter (termasuk buffer parameter dan panjang/indikator) dan mengalokasikan array struktur ini.
Catatan
Jika aplikasi menulis langsung ke deskriptor saat pengikatan row-wise digunakan, bidang terpisah dapat digunakan untuk data panjang dan indikator.
Mengatur atribut pernyataan SQL_ATTR_PARAM_BIND_TYPE ke ukuran struktur yang berisi satu set parameter atau ke ukuran instans buffer tempat parameter akan terikat. Panjangnya harus mencakup ruang untuk semua parameter terikat, dan padding struktur atau buffer apa pun, untuk memastikan bahwa ketika alamat parameter terikat bertahap dengan panjang yang ditentukan, hasilnya akan menunjuk ke awal parameter yang sama di baris berikutnya. Saat Anda menggunakan operator sizeof di ANSI C, perilaku ini dijamin.
Memanggil SQLBindParameter dengan argumen berikut agar setiap parameter terikat:
ValueType adalah jenis anggota buffer parameter yang akan terikat ke kolom.
ParameterType adalah jenis parameter SQL.
ParameterValuePtr adalah alamat anggota buffer parameter dalam elemen array pertama.
BufferLength adalah ukuran anggota buffer parameter.
StrLen_or_IndPtr adalah alamat anggota panjang/indikator yang akan diikat.
Untuk informasi selengkapnya tentang bagaimana informasi ini digunakan, lihat "ParameterValuePtr Argumen," nanti di bagian ini. Untuk informasi selengkapnya tentang pengikatan parameter yang bijaksana baris, lihat Pengikatan Array Parameter.
Informasi Kesalahan
Jika driver tidak menerapkan array parameter sebagai batch (opsi SQL_PARAM_ARRAY_ROW_COUNTS sama dengan SQL_PARC_NO_BATCH), situasi kesalahan ditangani seolah-olah satu pernyataan dijalankan. Jika driver menerapkan array parameter sebagai batch, aplikasi dapat menggunakan bidang header SQL_DESC_ARRAY_STATUS_PTR IPD untuk menentukan parameter pernyataan SQL atau parameter mana dalam array parameter yang menyebabkan SQLExecDirect atau SQLExecute mengembalikan kesalahan. Bidang ini berisi informasi status untuk setiap baris nilai parameter. Jika bidang menunjukkan bahwa terjadi kesalahan, bidang dalam struktur data diagnostik akan menunjukkan baris dan nomor parameter parameter yang gagal. Jumlah elemen dalam array akan ditentukan oleh bidang header SQL_DESC_ARRAY_SIZE di APD, yang dapat diatur oleh atribut pernyataan SQL_ATTR_PARAMSET_SIZE.
Catatan
Bidang header SQL_DESC_ARRAY_STATUS_PTR di APD digunakan untuk mengabaikan parameter. Untuk informasi selengkapnya tentang mengabaikan parameter, lihat bagian berikutnya, "Mengabaikan Sekumpulan Parameter."
Ketika SQLExecute atau SQLExecDirect mengembalikan SQL_ERROR, elemen dalam array yang ditunjukkan oleh bidang SQL_DESC_ARRAY_STATUS_PTR di IPD akan berisi SQL_PARAM_ERROR, SQL_PARAM_SUCCESS, SQL_PARAM_SUCCESS_WITH_INFO, SQL_PARAM_UNUSED, atau SQL_PARAM_DIAG_UNAVAILABLE.
Untuk setiap elemen dalam array ini, struktur data diagnostik berisi satu atau beberapa rekaman status. Bidang SQL_DIAG_ROW_NUMBER struktur menunjukkan jumlah baris nilai parameter yang menyebabkan kesalahan. Jika memungkinkan untuk menentukan parameter tertentu dalam baris parameter yang menyebabkan kesalahan, nomor parameter akan dimasukkan di bidang SQL_DIAG_COLUMN_NUMBER.
SQL_PARAM_UNUSED dimasukkan ketika parameter belum digunakan karena terjadi kesalahan dalam parameter sebelumnya yang memaksa SQLExecute atau SQLExecDirect untuk membatalkan. Misalnya, jika ada 50 parameter dan kesalahan terjadi saat menjalankan kumpulan parameter yang berdasar yang menyebabkan SQLExecute atau SQLExecDirect dibatalkan, maka SQL_PARAM_UNUSED dimasukkan dalam array status untuk parameter 41 hingga 50.
SQL_PARAM_DIAG_UNAVAILABLE dimasukkan ketika driver memperlakukan array parameter sebagai unit monolitik, sehingga tidak menghasilkan tingkat parameter individual informasi kesalahan ini.
Beberapa kesalahan dalam pemrosesan satu set parameter menyebabkan pemrosesan set parameter berikutnya dalam array berhenti. Kesalahan lain tidak memengaruhi pemrosesan parameter berikutnya. Kesalahan mana yang akan berhenti diproses ditentukan driver. Jika pemrosesan tidak dihentikan, semua parameter dalam array diproses, SQL_SUCCESS_WITH_INFO dikembalikan sebagai akibat dari kesalahan, dan buffer yang ditentukan oleh SQL_ATTR_PARAMS_PROCESSED_PTR diatur ke jumlah total kumpulan parameter yang diproses (seperti yang ditentukan oleh atribut pernyataan SQL_ATTR_PARAMSET_SIZE), yang mencakup set kesalahan.
Perhatian
Perilaku ODBC ketika kesalahan terjadi dalam pemrosesan array parameter berbeda di ODBC 3.x dari itu di ODBC 2.x. Di ODBC 2.x, fungsi mengembalikan SQL_ERROR dan pemrosesan dihentikan. Buffer yang ditunjukkan oleh argumen pirow SQLParamOptionsberisi jumlah baris kesalahan. Di ODBC 3.x, fungsi mengembalikan SQL_SUCCESS_WITH_INFO dan pemrosesan dapat berhenti atau berlanjut. Jika berlanjut, buffer yang ditentukan oleh SQL_ATTR_PARAMS_PROCESSED_PTR akan diatur ke nilai semua parameter yang diproses, termasuk yang mengakibatkan kesalahan. Perubahan perilaku ini dapat menyebabkan masalah untuk aplikasi yang ada.
Ketika SQLExecute atau SQLExecDirect kembali sebelum menyelesaikan pemrosesan semua set parameter dalam array parameter, seperti ketika SQL_ERROR atau SQL_NEED_DATA dikembalikan, array status berisi status untuk parameter yang telah diproses. Lokasi yang ditunjukkan oleh bidang SQL_DESC_ROWS_PROCESSED_PTR di IPD berisi nomor baris dalam array parameter yang menyebabkan kode kesalahan SQL_ERROR atau SQL_NEED_DATA. Ketika array parameter dikirim ke pernyataan SELECT, ketersediaan nilai array status ditentukan driver; mereka mungkin tersedia setelah pernyataan dijalankan atau sebagai kumpulan hasil diambil.
Mengabaikan Sekumpulan Parameter
Bidang SQL_DESC_ARRAY_STATUS_PTR APD (sebagaimana ditetapkan oleh atribut pernyataan SQL_ATTR_PARAM_STATUS_PTR) dapat digunakan untuk menunjukkan bahwa sekumpulan parameter terikat dalam pernyataan SQL harus diabaikan. Untuk mengarahkan driver untuk mengabaikan satu atau beberapa set parameter selama eksekusi, aplikasi harus mengikuti langkah-langkah berikut:
Panggil SQLSetDescField untuk mengatur bidang header SQL_DESC_ARRAY_STATUS_PTR APD untuk menunjuk ke array nilai SQLUSMALLINT untuk berisi informasi status. Bidang ini juga dapat diatur dengan memanggil SQLSetStmtAttr dengan Atribut SQL_ATTR_PARAM_OPERATION_PTR, yang memungkinkan aplikasi untuk mengatur bidang tanpa mendapatkan handel deskriptor.
Atur setiap elemen array yang ditentukan oleh bidang SQL_DESC_ARRAY_STATUS_PTR APD ke salah satu dari dua nilai:
SQL_PARAM_IGNORE, untuk menunjukkan bahwa baris dikecualikan dari eksekusi pernyataan.
SQL_PARAM_PROCEED, untuk menunjukkan bahwa baris disertakan dalam eksekusi pernyataan.
Panggil SQLExecDirect atau SQLExecute untuk menjalankan pernyataan yang disiapkan.
Aturan berikut berlaku untuk array yang ditentukan oleh bidang SQL_DESC_ARRAY_STATUS_PTR APD:
Penunjuk diatur ke null secara default.
Jika pointer null, semua set parameter digunakan, seolah-olah semua elemen diatur ke SQL_ROW_PROCEED.
Mengatur elemen ke SQL_PARAM_PROCEED tidak menjamin bahwa operasi akan menggunakan serangkaian parameter tertentu.
SQL_PARAM_PROCEED didefinisikan sebagai 0 dalam file header.
Aplikasi dapat mengatur bidang SQL_DESC_ARRAY_STATUS_PTR di APD untuk menunjuk ke array yang sama seperti yang ditunjukkan oleh bidang SQL_DESC_ARRAY_STATUS_PTR di IRD. Ini berguna saat mengikat parameter ke data baris. Parameter kemudian dapat diabaikan sesuai dengan status data baris. Selain SQL_PARAM_IGNORE, kode berikut menyebabkan parameter dalam pernyataan SQL diabaikan: SQL_ROW_DELETED, SQL_ROW_UPDATED, dan SQL_ROW_ERROR. Selain SQL_PARAM_PROCEED, kode berikut menyebabkan pernyataan SQL dilanjutkan: SQL_ROW_SUCCESS, SQL_ROW_SUCCESS_WITH_INFO, dan SQL_ROW_ADDED.
Mengikat Ulang Parameter
Aplikasi dapat melakukan salah satu dari dua operasi untuk mengubah pengikatan:
Panggil SQLBindParameter untuk menentukan pengikatan baru untuk kolom yang sudah terikat. Driver menimpa pengikatan lama dengan yang baru.
Tentukan offset yang akan ditambahkan ke alamat buffer yang ditentukan oleh panggilan pengikatan ke SQLBindParameter. Untuk informasi selengkapnya, lihat bagian berikutnya, "Pengikatan ulang dengan Offset."
Pengikatan ulang dengan Offset
Pengikatan ulang parameter sangat berguna ketika aplikasi memiliki pengaturan area buffer yang dapat berisi banyak parameter tetapi panggilan ke SQLExecDirect atau SQLExecute hanya menggunakan beberapa parameter. Ruang yang tersisa di area buffer dapat digunakan untuk set parameter berikutnya dengan memodifikasi pengikatan yang ada dengan offset.
Bidang header SQL_DESC_BIND_OFFSET_PTR di APD menunjuk ke offset pengikatan. Jika bidang non-null, driver mendereferensikan penunjuk dan, jika tidak ada nilai dalam bidang SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, dan SQL_DESC_OCTET_LENGTH_PTR adalah pointer null, menambahkan nilai dereferensi ke bidang tersebut dalam rekaman deskriptor pada waktu eksekusi. Nilai pointer baru digunakan saat pernyataan SQL dijalankan. Offset tetap valid setelah pengikatan ulang. Karena SQL_DESC_BIND_OFFSET_PTR adalah penunjuk ke offset daripada offset itu sendiri, aplikasi dapat mengubah offset secara langsung, tanpa harus memanggil SQLSetDescField atau SQLSetDescRec untuk mengubah bidang deskriptor. Penunjuk diatur ke null secara default. Bidang SQL_DESC_BIND_OFFSET_PTR ARD dapat diatur dengan panggilan ke SQLSetDescField atau dengan panggilan ke SQLSetStmtAttr dengan fAttribute SQL_ATTR_PARAM_BIND_OFFSET_PTR.
Offset pengikatan selalu ditambahkan langsung ke nilai di bidang SQL_DESC_DATA_PTR, SQL_DESC_INDICATOR_PTR, dan SQL_DESC_OCTET_LENGTH_PTR. Jika offset diubah ke nilai yang berbeda, nilai baru masih ditambahkan langsung ke nilai di setiap bidang deskriptor. Offset baru tidak ditambahkan ke jumlah nilai bidang dan offset sebelumnya.
Deskriptor
Bagaimana parameter terikat ditentukan oleh bidang APD dan IPD. Argumen di SQLBindParameter digunakan untuk mengatur bidang deskriptor tersebut. Bidang juga dapat diatur oleh fungsi SQLSetDescField , meskipun SQLBindParameter lebih efisien untuk digunakan karena aplikasi tidak perlu mendapatkan handel deskriptor untuk memanggil SQLBindParameter.
Perhatian
Memanggil SQLBindParameter untuk satu pernyataan dapat memengaruhi pernyataan lain. Ini terjadi ketika ARD yang terkait dengan pernyataan dialokasikan secara eksplisit dan juga terkait dengan pernyataan lain. Karena SQLBindParameter memodifikasi bidang APD, modifikasi berlaku untuk semua pernyataan yang terkait dengan deskriptor ini. Jika ini bukan perilaku yang diperlukan, aplikasi harus memisahkan deskriptor ini dari pernyataan lain sebelum memanggil SQLBindParameter.
Secara konseptual, SQLBindParameter melakukan langkah-langkah berikut secara berurutan:
Memanggil SQLGetStmtAttr untuk mendapatkan handel APD.
Memanggil SQLGetDescField untuk mendapatkan bidang SQL_DESC_COUNT APD, dan jika nilai argumen ColumnNumber melebihi nilai SQL_DESC_COUNT, memanggil SQLSetDescField untuk meningkatkan nilai SQL_DESC_COUNT ke ColumnNumber.
Memanggil SQLSetDescField beberapa kali untuk menetapkan nilai ke bidang APD berikut:
Mengatur SQL_DESC_TYPE dan SQL_DESC_CONCISE_TYPE ke nilai ValueType, kecuali bahwa jika ValueType adalah salah satu pengidentifikasi ringkas dari subjenis tanggalwaktu atau interval, nilai tersebut mengatur SQL_DESC_TYPE ke SQL_DATETIME atau SQL_INTERVAL, masing-masing mengatur SQL_DESC_CONCISE_TYPE ke pengidentifikasi ringkas, dan mengatur SQL_DESC_DATETIME_INTERVAL_CODE ke subkode tanggal atau interval yang sesuai.
Mengatur bidang SQL_DESC_OCTET_LENGTH ke nilai BufferLength.
Mengatur bidang SQL_DESC_DATA_PTR ke nilai ParameterValue.
Mengatur bidang SQL_DESC_OCTET_LENGTH_PTR ke nilai StrLen_or_Ind.
Mengatur bidang SQL_DESC_INDICATOR_PTR juga ke nilai StrLen_or_Ind.
Parameter StrLen_or_Ind menentukan informasi indikator dan panjang untuk nilai parameter.
Memanggil SQLGetStmtAttr untuk mendapatkan handel IPD.
Memanggil SQLGetDescField untuk mendapatkan bidang SQL_DESC_COUNT IPD, dan jika nilai argumen ColumnNumber melebihi nilai SQL_DESC_COUNT, memanggil SQLSetDescField untuk meningkatkan nilai SQL_DESC_COUNT ke ColumnNumber.
Memanggil SQLSetDescField beberapa kali untuk menetapkan nilai ke bidang IPD berikut:
Mengatur SQL_DESC_TYPE dan SQL_DESC_CONCISE_TYPE ke nilai ParameterType, kecuali bahwa jika ParameterType adalah salah satu pengidentifikasi ringkas dari subjenis tanggalwaktu atau interval, ia mengatur SQL_DESC_TYPE ke SQL_DATETIME atau SQL_INTERVAL, masing-masing mengatur SQL_DESC_CONCISE_TYPE ke pengidentifikasi ringkas, dan mengatur SQL_DESC_DATETIME_INTERVAL_CODE ke subkode tanggal atau interval yang sesuai.
Mengatur satu atau beberapa SQL_DESC_LENGTH, SQL_DESC_PRECISION, dan SQL_DESC_DATETIME_INTERVAL_PRECISION, yang sesuai untuk ParameterType.
Mengatur SQL_DESC_SCALE ke nilai DecimalDigits.
Jika panggilan ke SQLBindParameter gagal, konten bidang deskriptor yang akan ditetapkannya di APD tidak terdefinisi, dan bidang SQL_DESC_COUNT APD tidak berubah. Selain itu, bidang SQL_DESC_LENGTH, SQL_DESC_PRECISION, SQL_DESC_SCALE, dan SQL_DESC_TYPE dari rekaman yang sesuai dalam IPD tidak ditentukan dan bidang SQL_DESC_COUNT IPD tidak berubah.
Konversi Panggilan ke dan dari SQLSetParam
Ketika aplikasi ODBC 1.0 memanggil SQLSetParam di ODBC 3.x driver, ODBC 3.x Driver Manager memetakan panggilan seperti yang ditunjukkan dalam tabel berikut.
| Aplikasi Call by ODBC 1.0 | Hubungi ODBC 3.driver x |
|---|---|
| SQLSetParam( StatementHandle, ParameterNumber, ValueType, ParameterType, LengthPrecision, ParameterScale, ParameterValuePtr, StrLen_or_IndPtr); | SQLBindParameter( StatementHandle, ParameterNumber, SQL_PARAM_INPUT_OUTPUT, ValueType, ParameterType, ColumnSize, DecimalDigits, ParameterValuePtr, SQL_SETPARAM_VALUE_MAX, StrLen_or_IndPtr); |
Contoh
J. Menggunakan Fungsi SQLBindParameter
Dalam contoh berikut, aplikasi menyiapkan pernyataan SQL untuk menyisipkan data ke dalam tabel ORDERS. Untuk setiap parameter dalam pernyataan, aplikasi memanggil SQLBindParameter untuk menentukan jenis data ODBC C dan jenis data SQL parameter, dan untuk mengikat buffer ke setiap parameter. Untuk setiap baris data, aplikasi menetapkan nilai data ke setiap parameter dan memanggil SQLExecute untuk menjalankan pernyataan.
Sampel berikut mengasumsikan bahwa Anda memiliki sumber data ODBC di komputer Anda yang disebut Northwind yang terkait dengan database Northwind.
Untuk contoh kode lainnya, lihat Fungsi SQLBulkOperations, Fungsi SQLProcedures, Fungsi SQLPutData, dan Fungsi SQLSetPos.
// SQLBindParameter_Function.cpp
// compile with: ODBC32.lib
#include <windows.h>
#include <sqltypes.h>
#include <sqlext.h>
#define EMPLOYEE_ID_LEN 10
SQLHENV henv = NULL;
SQLHDBC hdbc = NULL;
SQLRETURN retcode;
SQLHSTMT hstmt = NULL;
SQLSMALLINT sCustID;
SQLCHAR szEmployeeID[EMPLOYEE_ID_LEN];
SQL_DATE_STRUCT dsOrderDate;
SQLINTEGER cbCustID = 0, cbOrderDate = 0, cbEmployeeID = SQL_NTS;
int main() {
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, EMPLOYEE_ID_LEN, 0, szEmployeeID, 0, &cbEmployeeID);
retcode = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_SSHORT, SQL_INTEGER, 0, 0, &sCustID, 0, &cbCustID);
retcode = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_TYPE_DATE, SQL_TIMESTAMP, sizeof(dsOrderDate), 0, &dsOrderDate, 0, &cbOrderDate);
retcode = SQLPrepare(hstmt, (SQLCHAR*)"INSERT INTO Orders(CustomerID, EmployeeID, OrderDate) VALUES (?, ?, ?)", SQL_NTS);
strcpy_s((char*)szEmployeeID, _countof(szEmployeeID), "BERGS");
sCustID = 5;
dsOrderDate.year = 2006;
dsOrderDate.month = 3;
dsOrderDate.day = 17;
retcode = SQLExecute(hstmt);
}
B. Menjalankan prosedur tersimpan menggunakan parameter bernama
Dalam contoh berikut, aplikasi menjalankan prosedur tersimpan SQL Server menggunakan parameter bernama.
// SQLBindParameter_Function_2.cpp
// compile with: ODBC32.lib
// sample assumes the following stored procedure:
// use northwind
// DROP PROCEDURE SQLBindParameter
// GO
//
// CREATE PROCEDURE SQLBindParameter @quote int
// AS
// delete from orders where OrderID >= @quote
// GO
#include <windows.h>
#include <sqltypes.h>
#include <sqlext.h>
SQLHDESC hIpd = NULL;
SQLHENV henv = NULL;
SQLHDBC hdbc = NULL;
SQLRETURN retcode;
SQLHSTMT hstmt = NULL;
SQLCHAR szQuote[50] = "100084";
SQLINTEGER cbValue = SQL_NTS;
int main() {
retcode = SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER*)SQL_OV_ODBC3, 0);
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);
retcode = SQLSetConnectAttr(hdbc, SQL_LOGIN_TIMEOUT, (SQLPOINTER)5, 0);
retcode = SQLConnect(hdbc, (SQLCHAR*) "Northwind", SQL_NTS, (SQLCHAR*) NULL, 0, NULL, 0);
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
retcode = SQLPrepare(hstmt, (SQLCHAR*)"{call SQLBindParameter(?)}", SQL_NTS);
retcode = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR, 50, 0, szQuote, 0, &cbValue);
retcode = SQLGetStmtAttr(hstmt, SQL_ATTR_IMP_PARAM_DESC, &hIpd, 0, 0);
retcode = SQLSetDescField(hIpd, 1, SQL_DESC_NAME, "@quote", SQL_NTS);
retcode = SQLExecute(hstmt);
}
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengembalikan informasi tentang parameter dalam pernyataan | Fungsi SQLDescribeParam |
| Menjalankan pernyataan SQL | Fungsi SQLExecDirect |
| Menjalankan pernyataan SQL yang disiapkan | Fungsi SQLExecute |
| Merilis buffer parameter pada pernyataan | Fungsi SQLFreeStmt |
| Mengembalikan jumlah parameter pernyataan | Fungsi SQLNumParams |
| Mengembalikan parameter berikutnya untuk mengirim data | Fungsi SQLParamData |
| Menentukan beberapa nilai parameter | Fungsi SQLParamOptions |
| Mengirim data parameter pada waktu eksekusi | Fungsi SQLPutData |
Lihat Juga
Referensi API ODBC
File Header ODBC
Mengambil Parameter Output Menggunakan SQLGetData
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk