bcp_bind
Berlaku untuk:
SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)
Mengikat data dari variabel program ke kolom tabel untuk salinan massal ke SQL Server.
Sintaks
RETCODE bcp_bind (
HDBC hdbc,
LPCBYTE pData,
INT cbIndicator,
DBINT cbData,
LPCBYTE pTerm,
INT cbTerm,
INT eDataType,
INT idxServerCol);
Argumen
hdbc
Adalah handel koneksi ODBC yang mendukung penyalinan massal.
pData
Adalah penunjuk ke data yang disalin. Jika eDataType adalah SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR, atau SQLIMAGE, pData dapat berupa NULL. PData NULL menunjukkan bahwa nilai data panjang akan dikirim ke SQL Server dalam gugus menggunakan bcp_moretext. Pengguna hanya boleh mengatur pData ke NULL jika kolom yang sesuai dengan bidang terikat pengguna adalah kolom BLOB jika tidak bcp_bind akan gagal.
Jika indikator ada dalam data, indikator muncul dalam memori langsung sebelum data. Parameter pData menunjuk ke variabel indikator dalam hal ini, dan lebar indikator, parameter cbIndicator , digunakan oleh salinan massal untuk mengatasi data pengguna dengan benar.
cbIndicator
Apakah panjangnya, dalam byte, dengan indikator panjang atau null untuk data kolom. Nilai panjang indikator yang valid adalah 0 (saat tidak menggunakan indikator), 1, 2, 4, atau 8. Indikator muncul dalam memori langsung sebelum data apa pun. Misalnya, definisi jenis struktur berikut dapat digunakan untuk menyisipkan nilai bilangan bulat ke dalam tabel SQL Server menggunakan salinan massal:
typedef struct tagBCPBOUNDINT
{
int iIndicator;
int Value;
} BCPBOUNDINT;
Dalam contoh kasus, parameter pData akan diatur ke alamat instans struktur yang dideklarasikan, alamat anggota struktur BCPBOUNDINT iIndicator . Parameter cbIndicator akan diatur ke ukuran bilangan bulat (sizeof(int)), dan parameter cbData akan kembali diatur ke ukuran bilangan bulat (sizeof(int)). Untuk menyalin baris secara massal ke server yang berisi nilai NULL untuk kolom terikat, nilai anggota iIndicator instans harus diatur ke SQL_NULL_DATA.
cbData
Adalah hitungan byte data dalam variabel program, tidak termasuk panjang panjang atau indikator null atau terminator apa pun.
Mengatur cbData ke SQL_NULL_DATA menandakan bahwa semua baris yang disalin ke server berisi nilai NULL untuk kolom.
Mengatur cbData ke SQL_VARLEN_DATA menunjukkan bahwa sistem akan menggunakan terminator string, atau metode lain, untuk menentukan panjang data yang disalin.
Untuk jenis data dengan panjang tetap, seperti bilangan bulat, jenis data menunjukkan panjang data ke sistem. Oleh karena itu, untuk jenis data dengan panjang tetap, cbData dapat dengan aman SQL_VARLEN_DATA atau panjang data.
Untuk karakter SQL Server dan jenis data biner, cbData dapat SQL_VARLEN_DATA, SQL_NULL_DATA, beberapa nilai positif, atau 0. Jika cbData SQL_VARLEN_DATA, sistem menggunakan indikator panjang/null (jika ada) atau urutan terminator untuk menentukan panjang data. Jika keduanya disediakan, sistem menggunakan yang menghasilkan jumlah data paling sedikit yang disalin. Jika cbData SQL_VARLEN_DATA, jenis data kolom adalah karakter SQL Server atau jenis biner, dan tidak ada indikator panjang atau urutan terminator yang ditentukan, sistem mengembalikan pesan kesalahan.
Jika cbData adalah 0 atau nilai positif, sistem menggunakan cbData sebagai panjang data. Namun, jika, selain nilai cbData positif, indikator panjang atau urutan terminator disediakan, sistem menentukan panjang data dengan menggunakan metode yang menghasilkan jumlah data paling sedikit yang disalin.
Nilai parameter cbData mewakili jumlah byte data. Jika data karakter diwakili oleh karakter lebar Unicode, maka nilai parameter cbData positif mewakili jumlah karakter yang dikalikan dengan ukuran dalam byte setiap karakter.
pTerm
Adalah penunjuk ke pola byte, jika ada, yang menandai akhir variabel program ini. Misalnya, string ANSI dan MBCS C biasanya memiliki terminator 1 byte (\0).
Jika tidak ada terminator untuk variabel, atur pTerm ke NULL.
Anda dapat menggunakan string kosong ("") untuk menunjuk terminator null C sebagai terminator variabel program. Karena string kosong yang dihentikan null merupakan byte tunggal (byte terminator itu sendiri), atur cbTerm ke 1. Misalnya, untuk menunjukkan bahwa string dalam szName dihentikan null dan bahwa terminator harus digunakan untuk menunjukkan panjangnya:
bcp_bind(hdbc, szName, 0,
SQL_VARLEN_DATA, "", 1,
SQLCHARACTER, 2)
Bentuk yang tidak ditentukan dari contoh ini dapat menunjukkan bahwa 15 karakter disalin dari variabel szName ke kolom kedua tabel terikat:
bcp_bind(hdbc, szName, 0, 15,
NULL, 0, SQLCHARACTER, 2)
API salinan massal melakukan konversi karakter Unicode-ke-MBCS sesuai kebutuhan. Pastikan string byte terminator dan panjang string byte diatur dengan benar. Misalnya, untuk menunjukkan bahwa string dalam szName adalah string karakter lebar Unicode, dihentikan oleh nilai terminator null Unicode:
bcp_bind(hdbc, szName, 0,
SQL_VARLEN_DATA, L"",
sizeof(WCHAR), SQLNCHAR, 2)
Jika kolom SQL Server terikat berkarakter lebar, tidak ada konversi yang dilakukan pada bcp_sendrow. Jika kolom SQL Server adalah jenis karakter MBCS, karakter lebar ke konversi karakter multibyte dilakukan saat data dikirim ke SQL Server.
cbTerm
Adalah jumlah byte yang ada dalam terminator untuk variabel program, jika ada. Jika tidak ada terminator untuk variabel, atur cbTerm ke 0.
eDataType Adalah jenis data C dari variabel program. Data dalam variabel program dikonversi ke jenis kolom database. Jika parameter ini adalah 0, tidak ada konversi yang dilakukan.
Parameter eDataType dijumlahkan oleh token jenis data SQL Server di sqlncli.h, bukan enumerator tipe data ODBC C. Misalnya, Anda dapat menentukan bilangan bulat dua byte, jenis ODBC SQL_C_SHORT, menggunakan jenis khusus SQL Server SQLINT2.
SQL Server 2005 (9.x) memperkenalkan dukungan untuk token jenis data SQLXML dan SQLUDT dalam parameter eDataType.
Tabel berikut ini mencantumkan tipe data enumerasi yang valid dan jenis data ODBC C terkait.
| eDataType | Tipe C |
|---|---|
| SQLTEXT | Char* |
| SQLNTEXT | wchar_t * |
| SQLCHARACTER | Char* |
| SQLBIGCHAR | Char* |
| SQLVARCHAR | Char* |
| SQLBIGVARCHAR | Char* |
| SQLNCHAR | wchar_t * |
| SQLNVARCHAR | wchar_t * |
| SQLBINARY | karakter yang tidak ditandatangani * |
| SQLBIGBINARY | karakter yang tidak ditandatangani * |
| SQLVARBINARY | karakter yang tidak ditandatangani * |
| SQLBIGVARBINARY | karakter yang tidak ditandatangani * |
| SQLBIT | char |
| SQLBITN | char |
| SQLINT1 | char |
| SQLINT2 | int pendek |
| SQLINT4 | int |
| SQLINT8 | _int64 |
| SQLINTN | cbIndicator 1: SQLINT1 2: SQLINT2 4: SQLINT4 8: SQLINT8 |
| SQLFLT4 | float |
| SQLFLT8 | float |
| SQLFLTN | cbIndicator 4: SQLFLT4 8: SQLFLT8 |
| SQLDECIMALN | SQL_NUMERIC_STRUCT |
| SQLNUMERICN | SQL_NUMERIC_STRUCT |
| SQLMONEY | DBMONEY |
| SQLMONEY4 | DBMONEY4 |
| SQLMONEYN | cbIndicator 4: SQLMONEY4 8: SQLMONEY |
| SQLTIMEN | SQL_SS_TIME2_STRUCT |
| SQLDATEN | SQL_DATE_STRUCT |
| SQLDATETIM4 | DBDATETIM4 |
| SQLDATETIME | DBDATETIME |
| SQLDATETIMN | cbIndicator 4: SQLDATETIM4 8: SQLDATETIME |
| SQLDATETIME2N | SQL_TIMESTAMP_STRUCT |
| SQLDATETIMEOFFSETN | SQL_SS_TIMESTAMPOFFSET_STRUCT |
| SQLIMAGE | karakter yang tidak ditandatangani * |
| SQLUDT | karakter yang tidak ditandatangani * |
| SQLUNIQUEID | SQLGUID |
| SQLVARIANT | Jenis data apa pun kecuali: -Teks - ntext -Gambar - varchar(maks) - varbinary(max) - nvarchar(maks) -Xml -Timestamp |
| SQLXML | Jenis data C yang didukung: -Char* - wchar_t * - karakter yang tidak ditandatangani * |
idxServerCol Adalah posisi ordinal kolom dalam tabel database tempat data disalin. Kolom pertama dalam tabel adalah kolom 1. Posisi ordinal kolom dilaporkan oleh SQLColumns.
Kembali
BERHASIL atau GAGAL.
Keterangan
Gunakan bcp_bind untuk cara yang cepat dan efisien untuk menyalin data dari variabel program ke dalam tabel di SQL Server.
Panggil bcp_init sebelum memanggil ini atau fungsi salinan massal lainnya. Memanggil bcp_init mengatur tabel target SQL Server untuk salinan massal. Saat memanggil bcp_init untuk digunakan dengan bcp_bind dan bcp_sendrow, parameter bcp_initszDataFile, menunjukkan file data, diatur ke NULL; parameter bcp_initeDirection diatur ke DB_IN.
Buat panggilan bcp_bind terpisah untuk setiap kolom dalam tabel SQL Server tempat Anda ingin menyalin. Setelah panggilan bcp_bind yang diperlukan dilakukan, panggil bcp_sendrow untuk mengirim baris data dari variabel program Anda ke SQL Server. Pengikatan ulang kolom tidak didukung.
Setiap kali Anda ingin SQL Server menerapkan baris yang sudah diterima, panggil bcp_batch. Misalnya, panggil bcp_batch sekali untuk setiap 1000 baris yang disisipkan atau pada interval lainnya.
Ketika tidak ada lagi baris yang akan disisipkan, panggil bcp_done. Kegagalan untuk melakukannya menghasilkan kesalahan.
Pengaturan parameter kontrol, yang ditentukan dengan bcp_control, tidak berpengaruh pada transfer baris bcp_bind .
Jika pData untuk kolom diatur ke NULL karena nilainya akan disediakan oleh panggilan ke bcp_moretext, kolom berikutnya dengan eDataType diatur ke SQLTEXT, SQLNTEXT, SQLXML, SQLUDT, SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, SQLNCHAR, atau SQLIMAGE juga harus terikat dengan pData yang diatur ke NULL, dan nilainya juga harus disediakan oleh panggilan ke bcp_moretext.
Untuk jenis nilai besar baru, seperti varchar(max), varbinary(max), atau nvarchar(max), Anda dapat menggunakan SQLCHARACTER, SQLVARCHAR, SQLVARBINARY, SQLBINARY, dan SQLNCHAR sebagai indikator jenis dalam parameter eDataType .
Jika cbTerm bukan 0, nilai apa pun (1, 2, 4, atau 8) berlaku untuk awalan (cbIndicator). Dalam situasi ini, SQL Server Native Client akan mencari terminator, menghitung panjang data sehubungan dengan terminator (i), dan mengatur cbData ke nilai i yang lebih kecil dan nilai awalan.
Jika cbTerm adalah 0 dan cbIndicator (awalan) bukan 0, cbIndicator harus 8. Awalan 8 byte dapat mengambil nilai berikut:
0xFFFFFFFFFFFFFFFF berarti nilai null untuk bidang
0xFFFFFFFFFFFFFFFE diperlakukan sebagai nilai awalan khusus, yang digunakan untuk mengirim data secara efisien dalam gugus ke server. Format data dengan awalan khusus ini adalah:
<><SPECIAL_PREFIX 0 atau lebih ZERO_CHUNK> DATA CHUNKS><di mana:
SPECIAL_PREFIX 0xFFFFFFFFFFFFFFFE
DATA_CHUNK adalah awalan 4 byte yang berisi panjang gugus, diikuti oleh data aktual yang panjangnya ditentukan dalam awalan 4 byte.
ZERO_CHUNK adalah nilai 4 byte yang berisi semua nol (00000000) yang menunjukkan akhir data.
Panjang 8 byte lain yang valid diperlakukan sebagai panjang data reguler.
Memanggil bcp_columns saat menggunakan bcp_bind menghasilkan kesalahan.
Dukungan bcp_bind untuk Fitur Tanggal dan Waktu yang Ditingkatkan
Untuk informasi tentang jenis yang digunakan dengan parameter eDataType untuk jenis tanggal/waktu, lihat Menyalin Perubahan Massal untuk Tipe Tanggal dan Waktu yang Ditingkatkan (OLE DB dan ODBC).
Untuk informasi selengkapnya, lihat Peningkatan Tanggal dan Waktu (ODBC).
Contoh
#include sql.h
#include sqlext.h
#include odbcss.h
// Variables like henv not specified.
HDBC hdbc;
char szCompanyName[MAXNAME];
DBINT idCompany;
DBINT nRowsProcessed;
DBBOOL bMoreData;
char* pTerm = "\t\t";
// 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 bcp.
if (bcp_init(hdbc, "comdb..accounts_info", NULL, NULL
DB_IN) == FAIL)
{
// Raise error and return.
return;
}
// Bind program variables to table columns.
if (bcp_bind(hdbc, (LPCBYTE) &idCompany, 0, sizeof(DBINT), NULL, 0,
SQLINT4, 1) == FAIL)
{
// Raise error and return.
return;
}
if (bcp_bind(hdbc, (LPCBYTE) szCompanyName, 0, SQL_VARLEN_DATA,
(LPCBYTE) pTerm, strnlen(pTerm, sizeof(pTerm)), SQLCHARACTER, 2) == FAIL)
{
// Raise error and return.
return;
}
while (TRUE)
{
// Retrieve and process program data.
if ((bMoreData = getdata(&idCompany, szCompanyName)) == TRUE)
{
// Send the data.
if (bcp_sendrow(hdbc) == FAIL)
{
// Raise error and return.
return;
}
}
else
{
// Break out of loop.
break;
}
}
// Terminate the bulk copy operation.
if ((nRowsProcessed = bcp_done(hdbc)) == -1)
{
printf_s("Bulk-copy unsuccessful.\n");
return;
}
printf_s("%ld rows copied.\n", nRowsProcessed);
Lihat Juga
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