IBCPSession::BCPColFmt (OLE DB)

Artikel
05/23/2023

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

Unduh driver OLE DB

Membuat pengikatan antara variabel program dan kolom SQL Server.

Sintaks

  
HRESULT BCPColFmt(   
      DBORDINAL idxUserDataCol,  
      int eUserDataType,  
      int cbIndicator,  
      int cbUserData,  
      BYTE *pbUserDataTerm,  
      int cbUserDataTerm,  
      DBORDINAL idxServerCol);

Keterangan

Metode BCPColFmt digunakan untuk membuat pengikatan antara bidang file data BCP dan kolom SQL Server. Dibutuhkan panjang, jenis, terminator, dan panjang awalan kolom sebagai parameter dan mengatur masing-masing properti ini untuk bidang individual.

Jika pengguna memilih mode interaktif, metode ini dipanggil dua kali; sekali untuk mengatur format kolom sesuai dengan nilai default (yang sesuai dengan jenis kolom server), dan sekali untuk mengatur format sesuai dengan jenis kolom pilihan klien yang dipilih selama mode interaktif, untuk setiap kolom.

Dalam mode non-interaktif, hanya dipanggil sekali per kolom untuk mengatur jenis setiap kolom ke karakter atau jenis asli, dan untuk mengatur terminator kolom dan baris.

Metode BCPColFmt memungkinkan Anda menentukan format file pengguna untuk salinan massal. Untuk penyalinan massal, format berisi bagian-bagian berikut:

Pemetaan dari bidang file pengguna ke kolom database.
Jenis data setiap bidang file pengguna.
Panjang indikator opsional untuk setiap bidang.
Panjang maksimum data per bidang file pengguna.
Urutan byte penghentian opsional untuk setiap bidang ¹.
Panjang urutan byte penghentian opsional ¹.

Penting

[1]: Menggunakan urutan terminator dalam skenario di mana halaman kode file data diatur ke UTF-8 tidak didukung. Dalam skenario seperti itu, pbUserDataTerm harus diatur ke nullptr dan cbUserDataTerm harus diatur ke 0.

Setiap panggilan ke BCPColFmt menentukan format untuk satu bidang file pengguna. Misalnya, untuk mengubah pengaturan default untuk tiga bidang dalam file data pengguna lima bidang, pertama-tama panggil BCPColumns(5), lalu panggil BCPColFmt lima kali, dengan tiga panggilan tersebut mengatur format kustom Anda. Untuk dua panggilan yang tersisa, atur eUserDataType ke BCP_TYPE_DEFAULT, dan atur cbIndicator, cbUserData, dan cbUserDataTerm masing-masing ke 0, BCP_VARIABLE_LENGTH, dan 0. Prosedur ini menyalin kelima kolom, tiga dengan format yang dikustomisasi dan dua dengan format default.

Catatan

Metode IBCPSession::BCPColumns harus dipanggil sebelum panggilan ke BCPColFmt. Anda harus memanggil BCPColFmt sekali untuk setiap kolom dalam file pengguna. Memanggil BCPColFmt lebih dari sekali untuk setiap kolom file pengguna menyebabkan kesalahan.

Anda tidak perlu menyalin semua data dalam file pengguna ke tabel SQL Server. Untuk melewati kolom, tentukan format data untuk kolom yang mengatur parameter idxServerCol ke 0. Untuk melewati bidang, Anda masih memerlukan semua informasi agar metode berfungsi dengan benar.

Fungsi IBCPSession::BCPWriteFmt dapat digunakan untuk mempertahankan spesifikasi format yang disediakan melalui BCPColFmt.

Argumen

idxUserDataCol[in]
Indeks bidang dalam file data pengguna.

eUserDataType[in]
Jenis data bidang dalam file data pengguna. Jenis data yang tersedia tercantum dalam Driver OLE DB untuk file header SQL Server (msoledbsql.h) dengan format BCP_TYPE_XXX, misalnya, BCP_TYPE_SQLINT4. Jika nilai BCP_TYPE_DEFAULT ditentukan, penyedia mencoba menggunakan jenis yang sama dengan jenis kolom tabel atau tampilan. Untuk operasi penyalinan massal dari SQL Server dan ke dalam file saat argumen eUserDataType BCP_TYPE_SQLDECIMAL atau BCP_TYPE_SQLNUMERIC:

Jika kolom sumber tidak desimal atau numerik, presisi dan skala default akan digunakan.
Jika kolom sumber desimal atau numerik, presisi dan skala kolom sumber akan digunakan.

cbIndicator[in]
Panjang awalan untuk bidang . Defaultnya adalah BCP_PREFIX_DEFAULT. Panjang yang valid untuk awalan adalah 0, 1, 2, 4 dan 8. Ukuran awalan 8 paling umum digunakan untuk menunjukkan bahwa bidang dipotong. Ini digunakan untuk menyalin kolom jenis nilai besar secara efisien secara massal.

cbUserData[in]
Panjang maksimum, dalam byte, dari data bidang ini dalam file pengguna, tidak termasuk panjang indikator panjang atau terminator apa pun.

Mengatur cbUserData ke BCP_LENGTH_NULL menunjukkan bahwa semua nilai dalam bidang file data adalah, atau harus diatur ke NULL. Mengatur cbUserData ke BCP_LENGTH_VARIABLE menunjukkan bahwa sistem harus menentukan panjang data untuk setiap bidang. Untuk beberapa bidang, ini bisa berarti bahwa indikator panjang/null dihasilkan untuk mendahului data pada salinan dari SQL Server, atau bahwa indikator diharapkan dalam data yang disalin ke SQL Server.

Untuk SQL Server karakter dan jenis data biner, cbUserData dapat BCP_LENGTH_VARIABLE, BCP_LENGTH_NULL, 0, atau beberapa nilai positif. Jika cbUserData BCP_LENGTH_VARIABLE, sistem menggunakan indikator panjang, jika ada, atau urutan terminator untuk menentukan panjang data. Jika indikator panjang dan urutan terminator disediakan, salinan massal menggunakan salah satu yang menghasilkan jumlah data paling sedikit yang disalin. Jika cbUserData BCP_LENGTH_VARIABLE, jenis data adalah karakter SQL Server atau jenis biner, dan jika indikator panjang atau urutan terminator tidak ditentukan, sistem mengembalikan pesan kesalahan.

Jika cbUserData adalah 0 atau nilai positif, sistem menggunakan cbUserData sebagai panjang data maksimum. Namun, jika, selain cbUserData positif, indikator panjang atau urutan terminator disediakan, sistem menentukan panjang data dengan menggunakan metode yang menghasilkan jumlah data paling sedikit yang disalin.

Nilai cbUserData mewakili jumlah byte data. Jika data karakter diwakili oleh karakter lebar Unicode, nilai parameter cbUserData positif mewakili jumlah karakter yang dikalikan dengan ukuran, dalam byte, dari setiap karakter.

pbUserDataTerm[size_is][in]
Urutan terminator yang akan digunakan untuk bidang . Parameter ini berguna terutama untuk jenis data karakter karena semua jenis lainnya memiliki panjang tetap atau, dalam kasus data biner, memerlukan indikator panjang untuk merekam jumlah byte yang ada secara akurat.

Untuk menghindari penghentian data yang diekstrak, atau untuk menunjukkan bahwa data dalam file pengguna tidak dihentikan, atur parameter ini ke NULL.

Jika lebih dari satu cara menentukan panjang kolom file pengguna digunakan (seperti terminator dan indikator panjang, atau terminator dan panjang kolom maksimum), salinan massal memilih salah satu yang menghasilkan jumlah data paling sedikit yang disalin.

API salinan massal melakukan konversi karakter Unicode-ke-MBCS sesuai kebutuhan. Perawatan harus dilakukan untuk memastikan bahwa string byte terminator dan panjang string byte diatur dengan benar. Lihat bagian Keterangan di atas untuk batasan pengodean UTF-8.

cbUserDataTerm[in]
Panjang, dalam byte, dari urutan terminator yang akan digunakan untuk kolom. Jika tidak ada terminator yang ada atau diinginkan dalam data, atur nilai ini ke 0. Lihat bagian Keterangan di atas untuk batasan pengodean UTF-8.

idxServerCol[in]
Posisi ordinal kolom dalam tabel database. Nomor kolom pertama adalah 1. Posisi ordinal kolom dilaporkan oleh IColumnsInfo::GetColumnInfo atau metode serupa. Jika nilai ini adalah 0, salinan massal mengabaikan bidang dalam file data.

Mengembalikan Nilai Kode

S_OK
Metode berhasil.

E_FAIL
Terjadi kesalahan khusus penyedia, untuk informasi terperinci, gunakan antarmuka ISQLServerErrorInfo .

E_UNEXPECTED
Panggilan ke metode tidak terduga. Misalnya, metode IBCPSession::BCPInit tidak dipanggil sebelum memanggil metode ini.

E_INVALIDARG
Argumen tidak valid.

E_OUTOFMEMORY
Kesalahan kehabisan memori.

Lihat juga

IBCPSession (OLE DB)
Melakukan Operasi Salin Massal