bcp_setcolfmt

Artikel
01/10/2024

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

Fungsi bcp_setcolfmt menggantikan bcp_colfmt. Dalam menentukan kolase kolom, fungsi bcp_setcolfmt harus digunakan. bcp_setbulkmode dapat digunakan untuk menentukan lebih dari satu format kolom.

Fungsi ini menyediakan pendekatan fleksibel untuk menentukan format kolom dalam operasi penyalinan massal. Ini digunakan untuk mengatur atribut format kolom individual. Setiap panggilan ke bcp_setcolfmt menetapkan satu atribut format kolom.

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

Sintaks

  
RETCODE bcp_setcolfmt (  
        HDBC hdbc,  
        INT field,  
        INT property,  
        void* pValue,  
        INT cbValue);

Argumen

hdbc
Adalah handel koneksi ODBC yang mendukung penyalinan massal.

Bidang
Adalah nomor kolom ordinal yang propertinya sedang diatur.

property
Adalah salah satu konstanta properti. Konstanta properti ditentukan dalam tabel ini.

Properti	Nilai	Deskripsi
BCP_FMT_TYPE	BYTE	Adalah tipe data kolom ini dalam file pengguna. Jika berbeda dari jenis data kolom terkait dalam tabel database, salinan massal mengonversi data jika memungkinkan. Parameter BCP_FMT_TYPE 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 SQLCHARACTER khusus untuk SQL Server. 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 BCP_FMT_TYPE adalah SQLDECIMAL atau SQLNUMERIC, jika kolom sumber tidak desimal atau numerik, presisi dan skala default digunakan. Jika tidak, jika kolom sumber desimal atau numerik, presisi dan skala kolom sumber digunakan.
BCP_FMT_INDICATOR_LEN	INT	Adalah panjang dalam byte indikator (awalan). Ini adalah panjang, dalam byte, dari indikator panjang/null dalam data kolom. Nilai panjang indikator yang valid adalah 0 (saat tidak menggunakan indikator), 1, 2, atau 4. 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 mereka terapkan. 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 salah satu yang menghasilkan jumlah data paling sedikit yang disalin. File data yang dihasilkan oleh salinan massal ketika tidak ada intervensi pengguna yang menyesuaikan format data berisi indikator ketika data kolom dapat bervariasi panjangnya atau kolom dapat menerima NULL sebagai nilai.
BCP_FMT_DATA_LEN	DBINT	Apakah panjang dalam byte data (panjang kolom) Ini adalah panjang maksimum, dalam byte, dari data kolom ini dalam file pengguna, tidak termasuk panjang indikator panjang atau terminator apa pun. Mengatur BCP_FMT_DATA_LEN ke SQL_NULL_DATA menunjukkan bahwa semua nilai dalam kolom file data adalah, atau harus diatur ke, NULL. Mengatur BCP_FMT_DATA_LEN 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 SQL Server karakter dan jenis data biner, BCP_FMT_DATA_LEN dapat SQL_VARLEN_DATA, SQL_NULL_DATA, 0, atau beberapa nilai positif. Jika BCP_FMT_DATA_LEN 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 BCP_FMT_DATA_LEN 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 BCP_FMT_DATA_LEN adalah 0 atau nilai positif, sistem menggunakan BCP_FMT_DATA_LEN sebagai panjang data maksimum. Namun, jika, selain BCP_FMT_DATA_LEN positif, indikator panjang atau urutan terminator disediakan, sistem menentukan panjang data dengan menggunakan metode yang menghasilkan jumlah data paling sedikit yang disalin. Nilai BCP_FMT_DATA_LEN mewakili jumlah byte data. Jika data karakter diwakili oleh karakter lebar Unicode, maka nilai parameter BCP_FMT_DATA_LEN positif mewakili jumlah karakter yang dikalikan dengan ukuran, dalam byte, dari setiap karakter.
BCP_FMT_TERMINATOR	LPCBYTE	Arahkan ke urutan terminator (baik ANSI atau Unicode yang sesuai) 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.
BCP_FMT_SERVER_COL	INT	Posisi ordinal kolom dalam database
BCP_FMT_COLLATION	LPCSTR	Nama kolab.

pValue
Adalah penunjuk ke nilai untuk dikaitkan dengan properti. Ini memungkinkan setiap properti format kolom diatur satu per satu.

cbvalue
Adalah panjang buffer properti dalam byte.

Mengembalikan

BERHASIL atau GAGAL.

Keterangan

Fungsi ini menggantikan fungsi bcp_colfmt . Semua fungsionalitas bcp_colfmt disediakan dalam fungsi bcp_setcolfmt . Selain itu, dukungan untuk kolase kolom juga disediakan. Disarankan agar atribut format kolom berikut diatur dalam urutan yang diberikan di bawah ini:

BCP_FMT_SERVER_COL

BCP_FMT_DATA_LEN

BCP_FMT_TYPE

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

Pemetaan dari kolom file pengguna ke kolom database.
Jenis data 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_setcolfmt 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_setcolfmt lima kali, dengan tiga panggilan tersebut mengatur format kustom Anda. Untuk dua panggilan yang tersisa, atur BCP_FMT_TYPE ke 0, dan atur masing-masing BCP_FMT_INDICATOR_LENGTH, BCP_FMT_DATA_LEN, dan cbValue ke 0, SQL_VARLEN_DATA, dan 0. Prosedur ini menyalin kelima kolom, tiga dengan format yang disesuaikan dan dua dengan format default.

Fungsi bcp_columns harus dipanggil sebelum memanggil bcp_setcolfmt.

Anda harus memanggil bcp_setcolfmt sekali untuk setiap properti setiap kolom dalam file pengguna.

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

Fungsi bcp_writefmt dapat digunakan untuk mempertahankan spesifikasi format.

Dukungan bcp_setcolfmt untuk Fitur Tanggal dan Waktu yang Ditingkatkan

Jenis yang digunakan dengan properti BCP_FMT_TYPE untuk jenis tanggal/waktu seperti yang ditentukan dalam Perubahan Salin Massal untuk Jenis Tanggal dan Waktu yang Ditingkatkan (OLE DB dan ODBC).

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

Lihat juga

Fungsi Salin Massal

Share via