bcp_moretext

Artikel
01/10/2024

Berlaku untuk: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)

Mengirim bagian dari nilai jenis data panjang dan panjang variabel ke SQL Server.

Sintaks

  
RETCODE bcp_moretext (  
        HDBC hdbc,  
        DBINT cbData,  
        LPCBYTE pData);

Argumen

hdbc
Adalah handel koneksi ODBC yang mendukung penyalinan massal.

cbData
Adalah jumlah byte data yang disalin ke SQL Server dari data yang direferensikan oleh pData. Nilai SQL_NULL_DATA menunjukkan NULL.

pData
Adalah penunjuk ke potongan data yang didukung, panjang, dan panjang variabel untuk dikirim ke SQL Server.

Mengembalikan

BERHASIL atau GAGAL.

Keterangan

Fungsi ini dapat digunakan bersama dengan bcp_bind dan bcp_sendrow untuk menyalin nilai data panjang dan panjang variabel ke SQL Server dalam sejumlah gugus yang lebih kecil. bcp_moretext dapat digunakan dengan kolom yang memiliki jenis data SQL Server berikut: teks, ntext, gambar, varchar(max), nvarchar(max), varbinary(max), jenis yang ditentukan pengguna (UDT), dan XML. bcp_moretext tidak mendukung konversi data, data yang disediakan harus cocok dengan jenis data kolom target.

Jika bcp_bind dipanggil dengan parameter pData non-NULL untuk jenis data yang didukung oleh bcp_moretext, bcp_sendrow mengirim seluruh nilai data, terlepas dari panjangnya. Namun, jika bcp_bind memiliki parameter pData NULL untuk jenis data yang didukung, bcp_moretext dapat digunakan untuk menyalin data segera setelah pengembalian berhasil dari bcp_sendrow menunjukkan bahwa kolom terikat dengan data yang ada telah diproses.

Jika Anda menggunakan bcp_moretext untuk mengirim satu kolom tipe data yang didukung secara berturut-turut, Anda juga harus menggunakannya untuk mengirim semua kolom tipe data lain yang didukung dalam baris. Tidak ada kolom yang dapat dilewati. Jenis data yang didukung adalah SQLTEXT, SQLNTEXT, SQLIMAGE, SQLUDT, dan SQLXML. SQLCHARACTER, SQLVARCHAR, SQNCHAR, SQLBINARY dan SQLVARBINARY juga termasuk dalam kategori ini jika kolom masing-masing adalah varchar(max), nvarchar(max) atau varbinary(max).

Memanggil bcp_bind atau bcp_collen mengatur panjang total semua bagian data yang akan disalin ke kolom SQL Server. Upaya untuk mengirim SQL Server lebih banyak byte daripada yang ditentukan dalam panggilan ke bcp_bind atau bcp_collen menghasilkan kesalahan. Kesalahan ini akan muncul, misalnya, dalam aplikasi yang digunakan bcp_collen untuk mengatur panjang data yang tersedia untuk kolom teks SQL Server menjadi 4500, lalu dipanggil bcp_moretext lima kali sambil menunjukkan pada setiap panggilan bahwa panjang buffer data panjangnya 1000 byte.

Jika baris yang disalin berisi lebih dari satu kolom panjang dan panjang variabel, bcp_moretext terlebih dahulu mengirimkan datanya ke kolom bernomor biasa terendah, diikuti oleh kolom bernomor biasa terendah berikutnya, dan sebagainya. Pengaturan yang benar dari total panjang data yang diharapkan penting. Tidak ada cara untuk memberi sinyal, di luar pengaturan panjang, bahwa semua data untuk kolom telah diterima oleh salinan massal.

Ketika nilai var(max) dikirim ke server menggunakan bcp_sendrow dan bcp_moretext, tidak perlu memanggil bcp_collen untuk mengatur panjang kolom. Sebaliknya, hanya untuk jenis ini, nilai dihentikan dengan memanggil bcp_sendrow dengan panjang nol.

Aplikasi biasanya memanggil bcp_sendrow dan bcp_moretext dalam perulangan untuk mengirim sejumlah baris data. Berikut adalah kerangka cara melakukan ini untuk tabel yang berisi dua kolom teks :

while (there are still rows to send)  
{  
bcp_sendrow(...);  
  
for (all the data in the first varbinary(max) column)  
bcp_moretext(...);  
bcp_moretext(hdbc, 0, NULL);  
  
for (all the data in the second varbinary(max) column)  
bcp_moretext(...);  
bcp_moretext(hdbc, 0, NULL);  
  
}

Contoh

Contoh ini menunjukkan cara menggunakan bcp_moretext dengan bcp_bind dan bcp_sendrow:

// Variables like henv not specified.  
HDBC      hdbc;  
DBINT      idRow = 5;  
char*      pPart1 = "This text value isn't very long,";  
char*      pPart2 = " but it's broken into three parts";  
char*      pPart3 = " anyhow.";  
DBINT      cbAllParts;  
DBINT      nRowsProcessed;  
  
// Application initiation, get an ODBC environment handle, allocate the  
// hdbc, and so on.  
...   
  
// Enable bulk copy prior to connecting on allocated hdbc.  
SQLSetConnectAttr(hdbc, SQL_COPT_SS_BCP, (SQLPOINTER) SQL_BCP_ON,  
   SQL_IS_INTEGER);  
  
// Connect to the data source, return on error.  
if (!SQL_SUCCEEDED(SQLConnect(hdbc, _T("myDSN"), SQL_NTS,  
   _T("myUser"), SQL_NTS, _T("myPwd"), SQL_NTS)))  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Initialize bulk copy.   
if (bcp_init(hdbc, "comdb..articles", NULL, NULL, DB_IN) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Bind program variables to table columns.   
if (bcp_bind(hdbc, (LPCBYTE) &idRow, 0, SQL_VARLEN_DATA, NULL, 0,  
   SQLINT4, 1)    == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
cbAllParts = (DBINT) (strnlen(pPart1, sizeof(pPart1) + 1) + strnlen(pPart2, sizeof(pPart2) + 1) + strnlen(pPart3, sizeof(pPart3) + 1));  
if (bcp_bind(hdbc, NULL, 0, cbAllParts, NULL, 0, SQLTEXT, 2) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// Send this row, with the text value broken into three chunks.   
if (bcp_sendrow(hdbc) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart1, sizeof(pPart1) + 1), pPart1) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart2, sizeof(pPart2) + 1), pPart2) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
if (bcp_moretext(hdbc, (DBINT) strnlen(pPart3, sizeof(pPart3) + 1), pPart3) == FAIL)  
   {  
   // Raise error and return.  
   return;  
   }  
  
// All done. Get the number of rows processed (should be one).  
nRowsProcessed = bcp_done(hdbc);  
  
// Carry on.

Lihat Juga

Fungsi Salin Massal

Bagikan melalui