bcp_colfmt

  • Artikel

Berlaku untuk:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse Analytics AnalyticsPlatform System (PDW)

Menentukan format sumber atau target data dalam file pengguna. Saat digunakan sebagai format sumber, bcp_colfmt menentukan format file data yang ada yang digunakan sebagai sumber data dalam salinan massal ke tabel SQL Server. Saat digunakan sebagai format target, file data dibuat menggunakan format kolom yang ditentukan dengan bcp_colfmt.

Sintaks

  
RETCODE bcp_colfmt (  
        HDBC hdbc,  
        INT idxUserDataCol,  
        BYTE eUserDataType,  
        INT cbIndicator,  
        DBINT cbUserData,  
        LPCBYTE pUserDataTerm,  
        INT cbUserDataTerm,  
        INT idxServerCol);

Argumen

hdbc
Adalah handel koneksi ODBC yang mendukung penyalinan massal.

idxUserDataCol
Adalah nomor kolom ordinal dalam file data pengguna yang formatnya ditentukan. Kolom pertama adalah 1.

eUserDataType
Adalah tipe data kolom ini dalam file pengguna. Jika berbeda dari jenis data kolom yang sesuai dalam tabel database (idxServerColumn), salinan massal mengonversi data jika memungkinkan.

SQL Server 2005 (9.x) memperkenalkan dukungan untuk token jenis data SQLXML dan SQLUDT dalam parameter eUserDataType .

Parameter eUserDataType dijumlahkan oleh token jenis data SQL Server di sqlncli.h, bukan enumerator tipe data ODBC C. Misalnya, Anda dapat menentukan string karakter, jenis ODBC SQL_C_CHAR, menggunakan jenis SQL Server khusus SQLCHARACTER.

Untuk menentukan representasi data default untuk jenis data SQL Server, atur parameter ini ke 0.

Untuk salinan massal dari SQL Server ke dalam file, ketika eUserDataType adalah SQLDECIMAL atau 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 digunakan.

cbIndicator
Apakah panjangnya, dalam byte, dari indikator panjang/null dalam data kolom. Nilai panjang indikator yang valid adalah 0 (saat tidak menggunakan indikator), 1, 2, 4, atau 8.

Untuk menentukan penggunaan indikator salin massal default, atur parameter ini ke SQL_VARLEN_DATA.

Indikator muncul dalam memori langsung sebelum data apa pun, dan dalam file data langsung sebelum data yang diterapkan.

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

File data yang dihasilkan oleh salinan massal ketika tidak ada intervensi pengguna yang menyesuaikan format data yang berisi indikator ketika data kolom dapat bervariasi panjangnya atau kolom dapat menerima NULL sebagai nilai.

cbUserData
Adalah panjang maksimum, dalam byte, dari data kolom ini dalam file pengguna, tidak termasuk panjang indikator panjang atau terminator apa pun.

Mengatur cbUserData ke SQL_NULL_DATA menunjukkan bahwa semua nilai dalam kolom file data adalah, atau harus diatur ke NULL.

Mengatur cbUserData ke SQL_VARLEN_DATA menunjukkan bahwa sistem harus menentukan panjang data di setiap kolom. Untuk beberapa kolom, 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 karakter SQL Server dan jenis data biner, cbUserData dapat SQL_VARLEN_DATA, SQL_NULL_DATA, 0, atau beberapa nilai positif. Jika cbUserData SQL_VARLEN_DATA, sistem menggunakan indikator panjang, jika ada, atau urutan terminator untuk menentukan panjang data. Jika indikator panjang dan urutan terminator disediakan, salinan massal menggunakan indikator panjang dan urutan terminator yang disalin. Jika cbUserData SQL_VARLEN_DATA, jenis data adalah karakter SQL Server atau jenis biner, dan tidak ada indikator panjang atau urutan terminator yang 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.

pUserDataTerm
Adalah urutan terminator yang akan digunakan untuk kolom ini. 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 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.

cbUserDataTerm
Apakah panjangnya, dalam byte, dari urutan terminator yang akan digunakan untuk kolom ini. Jika tidak ada terminator yang ada atau diinginkan dalam data, atur nilai ini ke 0.

idxServerCol
Adalah posisi ordinal kolom dalam tabel database. Nomor kolom pertama adalah 1. Posisi ordinal kolom dilaporkan oleh SQLColumns.

Jika nilai ini adalah 0, salinan massal mengabaikan kolom dalam file data.

Kembali

BERHASIL atau GAGAL.

Keterangan

Fungsi bcp_colfmt memungkinkan Anda menentukan format file pengguna untuk salinan massal. Untuk salinan massal, format berisi bagian-bagian berikut:

  • Pemetaan dari kolom file pengguna ke kolom database.

  • Jenis data dari setiap kolom file pengguna.

  • Panjang indikator opsional untuk setiap kolom.

  • Panjang maksimum data per kolom file pengguna.

  • Urutan byte penghentian opsional untuk setiap kolom.

  • Panjang urutan byte penghentian opsional.

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

Untuk cbIndicator, nilai 8 untuk menunjukkan jenis nilai besar sekarang valid. Jika awalan ditentukan untuk bidang yang kolom terkaitnya adalah jenis maks baru, itu hanya dapat diatur ke 8. Untuk detailnya, lihat bcp_bind.

Fungsi bcp_columns harus dipanggil sebelum panggilan ke bcp_colfmt.

Anda harus memanggil bcp_colfmt sekali untuk setiap kolom dalam file pengguna.

Memanggil bcp_colfmt lebih dari sekali untuk kolom file pengguna apa pun menyebabkan kesalahan.

Anda tidak perlu menyalin semua data dalam file pengguna ke tabel SQL Server. Untuk melewati kolom, tentukan format data untuk kolom , atur parameter idxServerCol ke 0. Jika Anda ingin melewati kolom, Anda harus menentukan jenisnya.

Fungsi bcp_writefmt dapat digunakan untuk mempertahankan spesifikasi format.

Dukungan bcp_colfmt untuk Fitur Tanggal dan Waktu yang Ditingkatkan

Untuk informasi tentang jenis yang digunakan dengan parameter eUserDataType untuk jenis tanggal/waktu, lihat Perubahan Salin Massal untuk Tipe Tanggal dan Waktu yang Ditingkatkan (OLE DB dan ODBC).

Untuk informasi selengkapnya, lihat Peningkatan Tanggal dan Waktu (ODBC).

Lihat Juga

Fungsi Salin Massal