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 nilai data karakter atau 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 ValueTypedari SQLBindParameter (untuk data parameter) atau argumen TargetTypedari 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 SQL Jenis Data di Lampiran D: Jenis Data.

Mengembalikan

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_STILL_EXECUTING, SQL_ERROR, atau SQL_INVALID_HANDLE.

Diagnostik

Ketika 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, nilainya 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, yang 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 pada struktur tanggal, waktu, atau tanda waktu C, dan nilai dalam parameter yang dikembalikan masing-masing adalah tanggal, waktu, atau tanda waktu yang tidak valid. (Fungsi mengembalikan SQL_SUCCESS_WITH_INFO.)
22008 Bidang tanggalwaktu meluap Ekspresi tanggalwaktu yang dihitung untuk parameter input/output atau output menghasilkan struktur tanggal, waktu, atau tanda waktu C yang tidak valid.
22012 Pembagian dengan nol Ekspresi aritmatika yang dihitung untuk parameter input/output atau output menghasilkan pembagian dengan nol.
22015 Bidang interval meluap Data yang dikirim untuk kolom atau parameter numerik atau interval yang tepat ke interval SQL jenis data 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 interval SQL jenis, dan tidak ada representasi nilai jenis C dalam interval SQL jenis.

Data yang dikirim untuk kolom atau parameter C numerik atau interval yang tepat ke jenis interval C 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 transmisi 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 tepat atau perkiraan numerik, tanggalwaktu, atau jenis data interval; 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 dalam 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 penunjuk 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 karakter C 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 Panjang string atau 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 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 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 dieksekusi data 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 karakter C 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. 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);  
}  
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

Lihat juga

Referensi API ODBC
File Header ODBC