Fungsi SQLPutData
Kesesuaian
Versi diperkenalkan: Kepatuhan Standar ODBC 1.0: ISO 92
Ringkasan
SQLPutData memungkinkan aplikasi mengirim data untuk parameter atau kolom ke driver pada waktu eksekusi pernyataan. Fungsi ini dapat digunakan untuk mengirim karakter atau nilai data biner dalam bagian ke kolom dengan tipe data khusus karakter, biner, atau sumber data (misalnya, parameter jenis SQL_LONGVARBINARY atau SQL_LONGVARCHAR). SQLPutData mendukung pengikatan ke jenis data Unicode C, bahkan jika driver yang mendasar tidak mendukung data Unicode.
Sintaks
SQLRETURN SQLPutData(
SQLHSTMT StatementHandle,
SQLPOINTER DataPtr,
SQLLEN StrLen_or_Ind);
Argumen
StatementHandle
[Input] Handel pernyataan.
DataPtr
[Input] Penunjuk ke buffer yang berisi data aktual untuk parameter atau kolom. Data harus dalam jenis data C yang ditentukan dalam argumen ValueType SQLBindParameter(untuk data parameter) atau argumen TargetType dari SQLBindCol (untuk data kolom).
StrLen_or_Ind
[Input] Panjang *DataPtr. Menentukan jumlah data yang dikirim dalam panggilan ke SQLPutData. Jumlah data dapat bervariasi dengan setiap panggilan untuk parameter atau kolom tertentu. StrLen_or_Ind diabaikan kecuali memenuhi salah satu kondisi berikut:
StrLen_or_Ind SQL_NTS, SQL_NULL_DATA, atau SQL_DEFAULT_PARAM.
Jenis data C yang ditentukan dalam SQLBindParameter atau SQLBindCol SQL_C_CHAR atau SQL_C_BINARY.
Jenis data C SQL_C_DEFAULT, dan jenis data C default untuk jenis data SQL yang ditentukan SQL_C_CHAR atau SQL_C_BINARY.
Untuk semua jenis data C lainnya, jika StrLen_or_Ind tidak SQL_NULL_DATA atau SQL_DEFAULT_PARAM, driver mengasumsikan bahwa ukuran buffer *DataPtr adalah ukuran tipe data C yang ditentukan dengan ValueType atau TargetType dan mengirim seluruh nilai data. Untuk informasi selengkapnya, lihat Mengonversi Data dari C ke Jenis Data SQL di Lampiran D: Jenis Data.
Kembali
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.
Diagnostik
Saat SQLPutData 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 umumnya dikembalikan oleh SQLPutData 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.) |
| 01004 | Data string, terpotong kanan | String atau data biner yang dikembalikan untuk parameter output menghasilkan pemotongan karakter nonblank atau data biner non-NULL. Jika itu adalah nilai string, nilai tersebut dipotong kanan. (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. |
| 07S01 | Penggunaan parameter default tidak valid | Nilai parameter, diatur dengan SQLBindParameter, SQL_DEFAULT_PARAM, dan parameter yang sesuai tidak memiliki nilai default. |
| 08S01 | Kegagalan tautan komunikasi | Tautan komunikasi antara driver dan sumber data tempat driver tersambung gagal sebelum fungsi selesai diproses. |
| 22001 | Data string, pemotongan kanan | Penetapan karakter atau nilai biner ke kolom menghasilkan pemotongan karakter atau byte nonblank (karakter) atau non-null (biner). Jenis informasi SQL_NEED_LONG_DATA_LEN di SQLGetInfo adalah "Y", dan lebih banyak data dikirim untuk parameter panjang (jenis data SQL_LONGVARCHAR, SQL_LONGVARBINARY, atau jenis data khusus sumber data panjang) daripada yang ditentukan dengan argumen StrLen_or_IndPtr di SQLBindParameter. Jenis informasi SQL_NEED_LONG_DATA_LEN di SQLGetInfo adalah "Y", dan lebih banyak 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. |
| 22003 | Nilai numerik di luar rentang | Data yang dikirim untuk parameter atau kolom numerik terikat menyebabkan seluruh (dibandingkan dengan pecahan) bagian dari angka yang akan dipotong saat ditetapkan ke kolom tabel terkait. Mengembalikan nilai numerik (sebagai numerik atau string) untuk satu atau beberapa parameter input/output atau output akan menyebabkan seluruh (dibandingkan dengan pecahan) bagian dari angka yang akan dipotong. |
| 22007 | Format tanggalwaktu tidak valid | Data yang dikirim untuk parameter atau kolom yang terikat ke struktur tanggal, waktu, atau tanda waktu, masing-masing, tanggal, waktu, atau tanda waktu yang tidak valid. Parameter input/output atau output terikat ke struktur C tanggal, waktu, atau tanda waktu, dan nilai dalam parameter yang dikembalikan masing-masing, tanggal, waktu, atau tanda waktu yang tidak valid. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.) |
| 22008 | Meluapnya bidang tanggalwaktu | Ekspresi tanggalwaktu yang dihitung untuk parameter input/output atau output menghasilkan struktur C tanggal, waktu, atau tanda waktu yang tidak valid. |
| 22012 | Pembagian dengan nol | Ekspresi aritmatika yang dihitung untuk parameter input/output atau output menghasilkan pembagian dengan nol. |
| 22015 | Meluapnya bidang interval | Data yang dikirim untuk kolom atau parameter numerik atau interval yang tepat ke jenis data SQL interval menyebabkan hilangnya digit signifikan. Data dikirim untuk kolom interval atau parameter dengan lebih dari satu bidang, dikonversi ke jenis data numerik, dan tidak memiliki representasi dalam jenis data numerik. Data yang dikirim untuk data kolom atau parameter ditetapkan ke jenis SQL interval, dan tidak ada representasi nilai jenis C dalam jenis SQL interval. Data yang dikirim untuk kolom atau parameter C numerik atau interval yang tepat ke jenis C interval menyebabkan hilangnya digit signifikan. Data yang dikirim untuk data kolom atau parameter ditetapkan ke struktur interval C, dan tidak ada representasi data dalam struktur data interval. |
| 22018 | Nilai karakter tidak valid untuk spesifikasi cast | Jenis C adalah jenis data numerik, tanggalwaktu, atau interval yang tepat atau perkiraan; jenis SQL kolom adalah jenis data karakter; dan nilai dalam kolom atau parameter bukan harfiah yang valid dari jenis C terikat. Jenis SQL adalah jenis data numerik, tanggalwaktu, atau interval yang tepat atau perkiraan; jenis C SQL_C_CHAR; dan nilai dalam kolom atau parameter bukan harfiah yang valid dari jenis SQL terikat. |
| 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. Kemudian fungsi dipanggil lagi pada StatementHandle. Fungsi ini dipanggil, dan sebelum selesai dieksekusi, SQLCancel atau SQLCancelHandle dipanggil pada StatementHandle dari utas yang berbeda dalam aplikasi multithread. |
| HY009 | Penggunaan pointer null tidak valid | (DM) Argumen DataPtr adalah pointer null, dan argumen StrLen_or_Ind bukan 0, SQL_DEFAULT_PARAM, atau SQL_NULL_DATA. |
| HY010 | Kesalahan urutan fungsi | (DM) Panggilan fungsi sebelumnya bukan panggilan ke SQLPutData atau SQLParamData. (DM) Fungsi eksekusi asinkron dipanggil untuk handel koneksi yang terkait dengan StatementHandle. Fungsi asinkron ini masih dijalankan ketika fungsi SQLPutData 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 (bukan yang ini) dipanggil untuk StatementHandle dan masih dijalankan ketika fungsi ini dipanggil. |
| HY013 | Kesalahan manajemen memori | Panggilan fungsi tidak dapat diproses karena objek memori yang mendasar tidak dapat diakses, mungkin karena kondisi memori yang rendah. |
| HY019 | Data non-karakter dan non-biner yang dikirim dalam potongan-potongan | SQLPutData dipanggil lebih dari sekali untuk parameter atau kolom, dan tidak digunakan untuk mengirim data C karakter ke kolom dengan tipe data khusus karakter, biner, atau sumber data atau untuk mengirim data C biner ke kolom dengan tipe data khusus karakter, biner, atau sumber data. |
| HY020 | Mencoba menggabungkan nilai null | SQLPutData dipanggil lebih dari sekali sejak panggilan yang mengembalikan SQL_NEED_DATA, dan dalam salah satu panggilan tersebut , argumen StrLen_or_Ind berisi SQL_NULL_DATA atau SQL_DEFAULT_PARAM. |
| HY090 | String atau panjang buffer tidak valid | Argumen DataPtr bukan penunjuk null, dan argumen StrLen_or_Ind kurang dari 0 tetapi tidak sama dengan SQL_NTS atau SQL_NULL_DATA. |
| 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 terkait 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 SQLPutData dipanggil saat mengirim data untuk parameter dalam pernyataan SQL, SQLSTATE dapat mengembalikan SQLSTATE apa pun yang dapat dikembalikan oleh fungsi yang dipanggil 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
SQLPutData 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.
Ketika aplikasi memanggil SQLParamData untuk menentukan data mana yang harus dikirimnya, driver mengembalikan indikator yang dapat digunakan aplikasi untuk menentukan data parameter mana yang akan dikirim atau di mana data kolom dapat ditemukan. Ini juga mengembalikan SQL_NEED_DATA, yang merupakan indikator ke aplikasi yang harus dipanggil SQLPutData untuk mengirim data. Dalam argumen DataPtr ke SQLPutData, aplikasi meneruskan penunjuk ke buffer yang berisi data aktual untuk parameter atau kolom.
Ketika driver mengembalikan SQL_SUCCESS untuk SQLPutData, aplikasi memanggil SQLParamData lagi. SQLParamData mengembalikan SQL_NEED_DATA jika lebih banyak data perlu dikirim, dalam hal ini aplikasi memanggil SQLPutData lagi. Ini mengembalikan SQL_SUCCESS jika semua data yang dieksekusi telah dikirim. Aplikasi kemudian memanggil SQLParamData lagi. Jika driver mengembalikan SQL_NEED_DATA dan indikator lain di *ValuePtrPtr, driver memerlukan data untuk parameter atau kolom lain dan SQLPutData dipanggil lagi. Jika driver mengembalikan SQL_SUCCESS, maka semua data yang dieksekusi telah dikirim dan pernyataan SQL dapat dijalankan atau panggilan SQLBulkOperations atau SQLSetPos dapat diproses.
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.
Catatan
Aplikasi dapat menggunakan SQLPutData untuk mengirim data dalam beberapa bagian hanya 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 tipe data khusus karakter, biner, atau sumber data. Jika SQLPutData dipanggil lebih dari sekali dalam kondisi lain, SQL_ERROR SQLSTATE HY019 (Data non-karakter dan non-biner dikirim dalam potongan-potongan).
Contoh
Sampel berikut mengasumsikan nama sumber data yang disebut Uji. Database terkait harus memiliki tabel yang bisa Anda buat, sebagai berikut:
CREATE TABLE emp4 (NAME char(30), AGE int, BIRTHDAY datetime, Memo1 text)
// SQLPutData.cpp
// compile with: odbc32.lib user32.lib
#include <stdio.h>
#include <windows.h>
#include <sqlext.h>
#include <odbcss.h>
#define TEXTSIZE 12000
#define MAXBUFLEN 256
SQLHENV henv = SQL_NULL_HENV;
SQLHDBC hdbc1 = SQL_NULL_HDBC;
SQLHSTMT hstmt1 = SQL_NULL_HSTMT;
void Cleanup() {
if (hstmt1 != SQL_NULL_HSTMT)
SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);
if (hdbc1 != SQL_NULL_HDBC) {
SQLDisconnect(hdbc1);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
}
if (henv != SQL_NULL_HENV)
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
int main() {
RETCODE retcode;
// SQLBindParameter variables.
SQLLEN cbTextSize, lbytes;
// SQLParamData variable.
PTR pParmID;
// SQLPutData variables.
UCHAR Data[] =
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz"
"abcdefghijklmnopqrstuvwxyz";
SDWORD cbBatch = (SDWORD)sizeof(Data) - 1;
// Allocate the ODBC environment and save handle.
retcode = SQLAllocHandle (SQL_HANDLE_ENV, NULL, &henv);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLAllocHandle(Env) Failed\n\n");
Cleanup();
return(9);
}
// Notify ODBC that this is an ODBC 3.0 app.
retcode = SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER) SQL_OV_ODBC3, SQL_IS_INTEGER);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLSetEnvAttr(ODBC version) Failed\n\n");
Cleanup();
return(9);
}
// Allocate ODBC connection handle and connect.
retcode = SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc1);
if ( (retcode != SQL_SUCCESS_WITH_INFO) && (retcode != SQL_SUCCESS)) {
printf("SQLAllocHandle(hdbc1) Failed\n\n");
Cleanup();
return(9);
}
// Sample uses Integrated Security, create SQL Server DSN using Windows NT authentication.
retcode = SQLConnect(hdbc1, (UCHAR*)"Test", SQL_NTS, (UCHAR*)"",SQL_NTS, (UCHAR*)"", SQL_NTS);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLConnect() Failed\n\n");
Cleanup();
return(9);
}
// Allocate statement handle.
retcode = SQLAllocHandle(SQL_HANDLE_STMT, hdbc1, &hstmt1);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLAllocHandle(hstmt1) Failed\n\n");
Cleanup();
return(9);
}
// Set parameters based on total data to send.
lbytes = (SDWORD)TEXTSIZE;
cbTextSize = SQL_LEN_DATA_AT_EXEC(lbytes);
// Bind the parameter marker.
retcode = SQLBindParameter (hstmt1, // hstmt
1, // ipar
SQL_PARAM_INPUT, // fParamType
SQL_C_CHAR, // fCType
SQL_LONGVARCHAR, // FSqlType
lbytes, // cbColDef
0, // ibScale
(VOID *)1, // rgbValue
0, // cbValueMax
&cbTextSize); // pcbValue
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLBindParameter Failed\n\n");
Cleanup();
return(9);
}
// Execute the command.
retcode =
SQLExecDirect(hstmt1, (UCHAR*)"INSERT INTO emp4 VALUES('Paul Borm', 46,'1950-11-12 00:00:00', ?)", SQL_NTS);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_NEED_DATA) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLExecDirect Failed\n\n");
Cleanup();
return(9);
}
// Check to see if NEED_DATA; if yes, use SQLPutData.
retcode = SQLParamData(hstmt1, &pParmID);
if (retcode == SQL_NEED_DATA) {
while (lbytes > cbBatch) {
SQLPutData(hstmt1, Data, cbBatch);
lbytes -= cbBatch;
}
// Put final batch.
retcode = SQLPutData(hstmt1, Data, lbytes);
}
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("SQLParamData Failed\n\n");
Cleanup();
return(9);
}
// Make final SQLParamData call.
retcode = SQLParamData(hstmt1, &pParmID);
if ( (retcode != SQL_SUCCESS) && (retcode != SQL_SUCCESS_WITH_INFO) ) {
printf("Final SQLParamData Failed\n\n");
Cleanup();
return(9);
}
// Clean up.
SQLFreeHandle(SQL_HANDLE_STMT, hstmt1);
SQLDisconnect(hdbc1);
SQLFreeHandle(SQL_HANDLE_DBC, hdbc1);
SQLFreeHandle(SQL_HANDLE_ENV, henv);
}
Fungsi Terkait
| Untuk informasi tentang | Lihat |
|---|---|
| Mengikat buffer ke parameter | Fungsi SQLBindParameter |
| Membatalkan pemrosesan pernyataan | Fungsi SQLCancel |
| Menjalankan pernyataan SQL | Fungsi SQLExecDirect |
| Menjalankan pernyataan SQL yang disiapkan | Fungsi SQLExecute |
| Mengembalikan parameter berikutnya untuk mengirim data | Fungsi SQLParamData |