Fungsi SQLParamData
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLParamData digunakan bersama dengan SQLPutData untuk menyediakan data parameter pada waktu eksekusi pernyataan, dan dengan SQLGetData untuk mengambil data parameter output yang dialirkan.
Sintaks
SQLRETURN SQLParamData(
SQLHSTMT StatementHandle,
SQLPOINTER * ValuePtrPtr);
Argumen
StatementHandle
[Input] Handel pernyataan.
ValuePtrPtr
[Output] Penunjuk ke buffer untuk mengembalikan alamat buffer ParameterValuePtr yang ditentukan dalam SQLBindParameter (untuk data parameter) atau alamat buffer TargetValuePtr yang ditentukan dalam SQLBindCol (untuk data kolom), seperti yang terkandung dalam bidang rekaman deskriptor SQL_DESC_DATA_PTR.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_NEED_DATA, SQL_NO_DATA, SQL_STILL_EXECUTING, SQL_ERROR, SQL_INVALID_HANDLE, atau SQL_PARAM_DATA_AVAILABLE.
Diagnostik
Saat SQLParamData 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 SQLParamData 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 | Nilai data yang diidentifikasi oleh argumen ValueType di SQLBindParameter untuk parameter terikat tidak dapat dikonversi ke jenis data yang diidentifikasi oleh argumen ParameterType di SQLBindParameter. Nilai data yang dikembalikan untuk parameter yang terikat sebagai SQL_PARAM_INPUT_OUTPUT atau SQL_PARAM_OUTPUT tidak dapat dikonversi ke jenis data yang diidentifikasi oleh argumen ValueType di SQLBindParameter. (Jika nilai data untuk satu atau beberapa baris tidak dapat dikonversi, tetapi satu atau beberapa baris berhasil dikembalikan, fungsi ini mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Kegagalan tautan komunikasi | Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses. |
| 22026 | Data string, ketidakcocokan panjang | Jenis informasi SQL_NEED_LONG_DATA_LEN di SQLGetInfo adalah "Y", dan lebih sedikit data dikirim untuk parameter panjang (jenis data SQL_LONGVARCHAR, SQL_LONGVARBINARY, atau jenis data khusus sumber data yang panjang) daripada yang ditentukan dengan argumen StrLen_or_IndPtr di SQLBindParameter. Jenis informasi SQL_NEED_LONG_DATA_LEN di SQLGetInfo adalah "Y", dan lebih sedikit data dikirim untuk kolom panjang (jenis data SQL_LONGVARCHAR, SQL_LONGVARBINARY, atau jenis data khusus sumber data panjang) daripada yang ditentukan dalam buffer panjang yang sesuai dengan kolom dalam baris data yang ditambahkan atau diperbarui dengan SQLBulkOperations atau diperbarui dengan SQLSetPos. |
| 40001 | Kegagalan serialisasi | Transaksi digulung balik karena kebuntuan sumber daya dengan transaksi lain. |
| 40003 | Penyelesaian pernyataan tidak diketahui | Koneksi terkait gagal selama eksekusi fungsi ini, dan status transaksi tidak dapat ditentukan. |
| 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. |
| HY008 | Operasi dibatalkan | Pemrosesan asinkron diaktifkan untuk StatementHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle; fungsi kemudian dipanggil lagi pada StatementHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle dari utas yang berbeda dalam aplikasi multithread. |
| HY010 | Kesalahan urutan fungsi | (DM) Panggilan fungsi sebelumnya bukan panggilan ke SQLExecDirect, SQLExecute, SQLBulkOperations, atau SQLSetPos tempat kode pengembalian SQL_NEED_DATA, atau panggilan fungsi sebelumnya adalah panggilan ke SQLPutData. Panggilan fungsi sebelumnya adalah panggilan ke SQLParamData. (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi asinkron ini masih dijalankan ketika fungsi SQLParamData dipanggil. (DM) Fungsi eksekusi asinkron (bukan yang ini) dipanggil untuk StatementHandle dan masih dijalankan ketika fungsi ini dipanggil. SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos dipanggil untuk StatementHandle dan dikembalikan SQL_NEED_DATA. SQLCancel 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. |
| 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. |
| HYT01 | Kesalahan waktu habis koneksi kedaluwarsa | Periode batas waktu koneksi kedaluwarsa sebelum sumber data merespons permintaan. Periode batas waktu koneksi diatur melalui SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
| IM001 | Driver tidak mendukung fungsi ini | (DM) Driver yang sesuai dengan StatementHandle tidak mendukung fungsi. |
| IM017 | Polling dinonaktifkan dalam mode pemberitahuan asinkron | Setiap kali model pemberitahuan digunakan, polling dinonaktifkan. |
| IM018 | SQLCompleteAsync belum dipanggil untuk menyelesaikan operasi asinkron sebelumnya pada handel ini. | Jika panggilan fungsi sebelumnya pada handel mengembalikan SQL_STILL_EXECUTING dan jika mode pemberitahuan diaktifkan, SQLCompleteAsync harus dipanggil pada handel untuk melakukan pasca-pemrosesan dan menyelesaikan operasi. |
Jika SQLParamData dipanggil saat mengirim data untuk parameter dalam pernyataan SQL, SQLSTATE dapat mengembalikan SQLSTATE yang dapat dikembalikan oleh fungsi yang disebut untuk menjalankan pernyataan (SQLExecute atau SQLExecDirect). Jika dipanggil saat mengirim data untuk kolom yang diperbarui atau ditambahkan dengan SQLBulkOperations atau diperbarui dengan SQLSetPos, itu dapat mengembalikan SQLSTATE apa pun yang dapat dikembalikan oleh SQLBulkOperations atau SQLSetPos.
Komentar
SQLParamData dapat dipanggil untuk menyediakan data yang tidak dijalankan untuk dua penggunaan: data parameter yang akan digunakan dalam panggilan ke SQLExecute atau SQLExecDirect, atau data kolom yang akan digunakan saat baris diperbarui atau ditambahkan oleh panggilan ke SQLBulkOperations atau diperbarui oleh panggilan ke SQLSetPos. Pada waktu eksekusi, SQLParamData kembali ke aplikasi indikator yang diperlukan driver data.
Ketika aplikasi memanggil SQLExecute, SQLExecDirect, SQLBulkOperations, atau SQLSetPos, driver mengembalikan SQL_NEED_DATA jika memerlukan data data yang sedang dieksekusi. Aplikasi kemudian memanggil SQLParamData untuk menentukan data mana yang akan dikirim. Jika driver memerlukan data parameter, driver akan kembali dalam buffer output *ValuePtrPtr , nilai yang dimasukkan aplikasi ke dalam buffer set baris. Aplikasi dapat menggunakan nilai ini untuk menentukan data parameter mana yang diminta driver. Jika driver memerlukan data kolom, driver akan kembali dalam buffer *ValuePtrPtr alamat tempat kolom awalnya terikat, sebagai berikut:
Offset Pengikatan Alamat + Terikat + ((Nomor Baris - 1) x Ukuran Elemen)
di mana variabel didefinisikan seperti yang ditunjukkan dalam tabel berikut.
| Variabel | Deskripsi |
|---|---|
| Alamat Terikat | Alamat yang ditentukan dengan argumen TargetValuePtr di SQLBindCol. |
| Offset Pengikatan | Nilai yang disimpan di alamat yang ditentukan dengan atribut pernyataan SQL_ATTR_ROW_BIND_OFFSET_PTR. |
| Nomor Baris | Jumlah baris berbasis 1 dalam set baris. Untuk pengambilan baris tunggal, yang merupakan default, ini adalah 1. |
| Ukuran Elemen | Nilai atribut pernyataan SQL_ATTR_ROW_BIND_TYPE untuk buffer data dan panjang/indikator. |
Ini juga mengembalikan SQL_NEED_DATA, yang merupakan indikator ke aplikasi yang harus dipanggil SQLPutData untuk mengirim data.
Aplikasi memanggil SQLPutData sebanyak yang diperlukan untuk mengirim data yang sedang dieksekusi untuk kolom atau parameter. Setelah semua data dikirim untuk kolom atau parameter, aplikasi memanggil SQLParamData lagi. Jika SQLParamData kembali menampilkan SQL_NEED_DATA, data harus dikirim untuk parameter atau kolom lain. Oleh karena itu, aplikasi kembali memanggil SQLPutData. Jika semua data yang dieksekusi telah dikirim untuk semua parameter atau kolom, maka SQLParamData mengembalikan SQL_SUCCESS atau SQL_SUCCESS_WITH_INFO, nilai dalam *ValuePtrPtr tidak ditentukan, dan pernyataan SQL dapat dijalankan atau panggilan SQLBulkOperations atau SQLSetPos dapat diproses.
Jika SQLParamData menyediakan data parameter untuk pernyataan pembaruan atau penghapusan yang dicari yang tidak memengaruhi baris apa pun di sumber data, panggilan ke SQLParamData mengembalikan SQL_NO_DATA.
Untuk informasi selengkapnya tentang bagaimana data parameter data-at-execution diteruskan pada waktu eksekusi pernyataan, lihat "Meneruskan Nilai Parameter" di SQLBindParameter dan Mengirim Data Panjang. Untuk informasi selengkapnya tentang bagaimana data kolom data-at-execution diperbarui atau ditambahkan, lihat bagian "Menggunakan SQLSetPos" di SQLSetPos, "Melakukan Pembaruan Massal Menggunakan Bookmark" di SQLBulkOperations, dan Long Data dan SQLSetPos dan SQLBulkOperations.
SQLParamData dapat dipanggil untuk mengambil parameter output yang dialirkan. Saat SQLMoreResults, SQLExecute, SQLGetData, atau SQLExecDirect mengembalikan SQL_PARAM_DATA_AVAILABLE, panggil SQLParamData untuk menentukan parameter mana yang memiliki nilai yang tersedia. Untuk informasi selengkapnya tentang parameter output SQL_PARAM_DATA_AVAILABLE dan streaming, lihat Mengambil Parameter Output Menggunakan SQLGetData.
Contoh Kode
Lihat SQLPutData.
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat buffer ke parameter | Fungsi SQLBindParameter |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCancel |
| Mengembalikan informasi tentang parameter dalam pernyataan | Fungsi SQLDescribeParam |
| Menjalankan pernyataan SQL | Fungsi SQLExecDirect |
| Menjalankan pernyataan SQL yang disiapkan | Fungsi SQLExecute |
| Mengirim data parameter pada waktu eksekusi | Fungsi SQLPutData |
Lihat Juga
Referensi API ODBC
File Header ODBC
Mengambil Parameter Output Menggunakan SQLGetData