bcp_setcolfmt
適用於：
SQL Server Azure SQL 資料庫 Azure SQL 受控執行個體 Azure Synapse Analytics Analytics Platform System （PDW）
bcp_setcolfmt 函式會取代bcp_colfmt。 在指定數據行定序時， 必須使用bcp_setcolfmt 函式。 bcp_setbulkmode可用來指定多個數據行格式。
此函式提供彈性的方法，可在大量複製作業中指定數據行格式。 它用來設定個別的數據行格式屬性。 每次呼叫 bcp_setcolfmt 都會設定一個數據行格式屬性。
bcp_setcolfmt 函式會指定使用者檔案中數據的來源或目標格式。 當做來源格式使用時， bcp_setcolfmt 指定現有數據檔的格式，做為 SQL Server 中數據表的數據源。 當做目標格式使用時，會使用以 bcp_setcolfmt 指定的數據行格式來建立數據檔。
語法
RETCODE bcp_setcolfmt (
HDBC hdbc,
INT field,
INT property,
void* pValue,
INT cbValue);
引數
hdbc
這是啟用大量複製的 ODBC 連接句柄。
field
這是要設定屬性的序數數據行編號。
property
這是其中一個屬性常數。 屬性常數定義在此數據表中。
| 屬性 | 數值 | Description |
|---|---|---|
| BCP_FMT_TYPE | BYTE | 這是使用者檔案中這個數據行的數據類型。 如果與資料庫數據表中對應數據行的數據類型不同，請盡可能大量複製轉換數據。 BCP_FMT_TYPE參數是由 sqlncli.h 中的 SQL Server 數據類型標記所列舉，而不是 ODBC C 數據類型列舉值。 例如，您可以使用 SQL Server 特定的 SQLCHARACTER 類型，指定字元字串 ODBC 類型SQL_C_CHAR。 若要指定 SQL Server 數據類型的預設數據表示法，請將此參數設定為 0。 對於從 SQL Server 大量複製到檔案中，當BCP_FMT_TYPE為 SQLDECIMAL 或 SQLNUMERIC 時，如果源數據行不是十進位或數值，則會使用預設有效位數和小數位數。 否則，如果源數據行是 十進位 或 數值，則會使用源數據行的有效位數和小數字數。 |
| BCP_FMT_INDICATOR_LEN | INT | 這是指標的位元組長度（前置詞）。 它是數據行數據中長度/Null 指標的長度，以位元組為單位。 有效的指標長度值為 0（不使用指標時）、1、2 或 4。 若要指定預設大量複製指標使用方式，請將此參數設定為SQL_VARLEN_DATA。 指標會在任何數據之前直接出現在記憶體中，並在數據檔中直接出現在它們套用的數據之前。 如果使用多個指定數據檔數據行長度的方法（例如指標和數據行長度上限，或指標和終止符序列），大量複製會選擇產生最少複製數據量的數據。 當使用者介入時，大量複製所產生的數據檔會在數據行數據長度可能不同或數據行接受NULL 做為值時，調整數據報含指標的格式。 |
| BCP_FMT_DATA_LEN | DBINT | 這是以位元組為單位的數據長度（資料行長度） 這是使用者檔案中此數據行數據的最大長度，以位元組為單位，不包括任何長度指標或終止符的長度。 將BCP_FMT_DATA_LEN設定為 SQL_NULL_DATA表示數據文件數據行中的所有值都設定為 NULL，或應設定為 NULL。 將BCP_FMT_DATA_LEN設定為 SQL_VARLEN_DATA表示系統應該決定每個數據行中的數據長度。 對於某些數據行，這可能表示在從 SQL Server 複製的數據之前產生長度/Null 指標，或指標在複製到 SQL Server 的數據中預期。 針對 SQL Server 字元和二進位數據類型，BCP_FMT_DATA_LEN可以是SQL_VARLEN_DATA、SQL_NULL_DATA、0 或某些正值。 如果BCP_FMT_DATA_LEN是SQL_VARLEN_DATA，則系統會使用長度指標、如果有，或是終止符序列來判斷數據的長度。 如果同時提供長度指標與結束字元順序，大量複製會使用導致複製最少量資料者。 如果BCP_FMT_DATA_LEN是SQL_VARLEN_DATA，則數據類型是 SQL Server 字元或二進位類型，而且未指定長度指標或終止符序列，系統就會傳回錯誤訊息。 如果BCP_FMT_DATA_LEN為 0 或正值，則系統會使用 BCP_FMT_DATA_LEN 作為最大數據長度。 不過，如果除了正BCP_FMT_DATA_LEN之外，也會提供長度指標或終止符序列，系統會使用會導致複製的數據量最少的方法來判斷數據長度。 BCP_FMT_DATA_LEN值代表數據的位元組計數。 如果字元數據是以 Unicode 寬字元表示，則正BCP_FMT_DATA_LEN參數值代表每個字元的大小乘以位元組為單位的字元數。 |
| BCP_FMT_TERMINATOR | LGBTYTE | 要用於此數據行的終止符序列指標（ANSI 或 Unicode）。 此參數主要用於字元資料類型，因為其他所有類型都屬固定長度；如果是二進位資料，則需要一個長度指標，才能正確記錄出現的位元組數目。 為避免結束已擷取的資料，或要指出使用者檔案中的資料未結束，將此參數設定為 NULL。 如果使用多種指定使用者檔案資料行長度的方式 (例如結束字元和長度指標，或結束字元和資料行長度最大值)，大量複製會選擇導致複製最少量資料的方式。 大量複製 API 會視需要執行 Unicode 到 MBCS 的字元轉換。 請務必確認結束字元位元組字串與位元組字串長度的設定正確。 |
| BCP_FMT_SERVER_COL | INT | 資料庫中數據行的序數位置 |
| BCP_FMT_COLLATION | LPCSTR | 定序名稱。 |
pValue
這是要與 屬性產生關聯之值的指標。 它允許個別設定每個資料行格式屬性。
cbvalue
這是以位元組為單位的屬性緩衝區長度。
傳回
SUCCEED 或FAIL。
備註
此函式會取代 bcp_colfmt 函式 。 bcp_colfmt的所有功能都會在 bcp_setcolfmt 函式中提供。 此外，也提供數據行定序的支援。 建議以下欄順序設定下列資料行格式屬性：
BCP_FMT_SERVER_COL
BCP_FMT_DATA_LEN
BCP_FMT_TYPE
bcp_setcolfmt函式可讓您指定大量複製的使用者檔案格式。 針對大量複製，格式包含下列部分：
從使用者檔案數據行到資料庫數據行的對應。
每個使用者檔案數據行的數據類型。
每個數據行的選擇性指標長度。
每個使用者檔案數據行的數據長度上限。
每個數據行的選擇性終止位元組序列。
選擇性終止位元組序列的長度。
每次呼叫 bcp_setcolfmt 都會指定一個使用者檔案數據行的格式。 例如，若要變更五欄用戶數據檔中三個數據行的預設設定，請先呼叫 bcp_columns（5），然後呼叫 bcp_setcolfmt 五次，其中三個呼叫會設定自定義格式。 針對其餘兩個呼叫，將 BCP_FMT_TYPE 設定為0，並將BCP_FMT_INDICATOR_LENGTH、BCP_FMT_DATA_LEN和 cbValue 分別設定為0、SQL_VARLEN_DATA和0。 此程序會複製全部五個資料行，其中三個為您自訂的格式，而另兩個為預設格式。
呼叫 bcp_setcolfmt 之前，必須先呼叫bcp_columns函式。
您必須針對使用者檔案中每個資料行的每個屬性呼叫 bcp_setcolfmt 一次。
您不需要將使用者檔案中的所有資料複製到 SQL Server 資料表。 若要略過數據行，請指定數據行的數據格式，並將 BCP_FMT_SERVER_COL 參數設定為 0。 如果您想要略過資料行，您必須指定其類型。
bcp_setcolfmt增強日期和時間功能的支援
與日期/時間類型的BCP_FMT_TYPE屬性搭配使用的型別，如增強日期和時間類型的大量複製變更（OLE DB 和 ODBC）中所指定。
如需詳細資訊，請參閱 日期和時間改善 （ODBC）。