bcp_colfmt

  • 發行項

適用於：SQL ServerAzure SQL DatabaseAzure SQL 受控執行個體Azure Synapse AnalyticsAnalytics Platform System (PDW)

指定使用者檔案中資料的來源或目標格式。 當做來源格式使用時， bcp_colfmt 會指定做為大量複製 SQL Server 資料表之資料來源的現有資料檔案格式。 當做目標格式使用時，會使用以 bcp_colfmt 指定的資料行格式來建立資料檔案。

語法

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

引數

hdbc
這是啟用大量複製的 ODBC 連接控制碼。

idxUserDataCol
這是指定格式之使用者資料檔案中的序數位。 第一個資料行是 1。

eUserDataType
這是使用者檔案中這個資料行的資料類型。 如果與資料庫資料表中對應資料行的資料類型不同（ idxServerColumn ），請盡可能大量複製轉換資料。

SQL Server 2005 （9.x） 引進了 eUserDataType 參數中 SQLXML 和 SQLUDT 資料類型權杖的支援。

eUserDataType 參數是由 sqlncli.h 中的 SQL Server 資料類型標記所列舉，而不是 ODBC C 資料類型列舉值。 例如，您可以使用 SQL Server 特定類型 SQLCHARACTER 來指定字元字串、ODBC 類型SQL_C_CHAR。

若要指定 SQL Server 資料類型的預設資料標記法，請將此參數設定為 0。

當 eUserDataType 是 SQLDECIMAL 或 SQLNUMERIC 時 ，將 SQL Server 大量複製到檔案中：

  • 如果來源資料行不是 十進位或 數值 ，則會使用預設有效位數和小 數位數。

  • 如果來源資料行是 十進位 或 數值 ，則會使用來源資料行的有效位數和小數位數。

cbIndicator
這是資料行資料中長度/Null 指標的長度，以位元組為單位。 有效的指標長度值為 0（不使用指標時）、1、2、4 或 8。

若要指定預設大量複製指標使用方式，請將此參數設定為SQL_VARLEN_DATA。

指標會在任何資料之前直接出現在記憶體中，並在資料檔中直接出現在它們套用的資料之前。

如果使用多個指定資料檔案資料行長度的方法（例如指標和資料行長度上限，或指標和結束字元序列），大量複製會選擇產生最少複製資料量的資料。

當使用者介入時，大量複製所產生的資料檔案會在資料行資料長度可能不同或資料行接受 Null 做為值時，調整資料包含指標的格式。

cbUserData
這是使用者檔案中此資料行資料的最大長度，以位元組為單位，不包括任何長度指標或結束字元的長度。

將 cbUserData 設定 為 SQL_Null_DATA表示資料檔案資料行中的所有值都是，或應該設定為 Null。

將 cbUserData 設定 為 SQL_VARLEN_DATA表示系統應該決定每個資料行中的資料長度。 對於某些資料行，這可能表示在從 SQL Server 複製的資料之前產生長度/Null 指標，或指標在複製到 SQL Server 的資料中預期。

針對 SQL Server 字元和二進位資料類型， cbUserData 可以是SQL_VARLEN_DATA、SQL_Null_DATA、0 或某些正值。 如果 cbUserData 是SQL_VARLEN_DATA，則系統會使用長度指標、如果有，或是結束字元序列來判斷資料的長度。 如果同時提供長度指標與結束字元順序，大量複製會使用導致複製最少量資料者。 如果 cbUserData 是SQL_VARLEN_DATA，則資料類型為 SQL Server 字元或二進位類型，而且未指定長度指標或結束字元序列，系統就會傳回錯誤訊息。

如果 cbUserData 為 0 或正值，則系統會使用 cbUserData 當作最大的資料長度。 不過，如果除了正的 cbUserData 之外，也提供長度指標或結束字元順序，系統會使用導致複製最少量資料的方式決定資料長度。

cbUserData 值表示資料的位元組計數。 如果字元資料是以 Unicode 寬字元表示，則 cbUserData 正參數值表示字元數乘以每個字元的大小 (以位元組為單位)。

pUserDataTerm
這是要用於此資料行的結束字元序列。 此參數主要用於字元資料類型，因為其他所有類型都屬固定長度；如果是二進位資料，則需要一個長度指標，才能正確記錄出現的位元組數目。

為避免結束已擷取的資料，或要指出使用者檔案中的資料未結束，將此參數設定為 NULL。

如果使用多種指定使用者檔案資料行長度的方式 (例如結束字元和長度指標，或結束字元和資料行長度最大值)，大量複製會選擇導致複製最少量資料的方式。

大量複製 API 會視需要執行 Unicode 到 MBCS 的字元轉換。 請務必確認結束字元位元組字串與位元組字串長度的設定正確。

cbUserDataTerm
這是要用於此資料行之結束字元序列的長度，以位元組為單位。 如果資料中沒有或不需要結束字元，將此值設定為 0。

idxServerCol
這是資料行在資料庫資料表中的序數位置。 第一個資料行編號為 1。 SQLColumns 會 報告資料行的序數位置。

如果此值為 0，大量複製會忽略資料檔案中的資料行。

傳回

SUCCEED 或 FAIL。

備註

bcp_colfmt 函式可讓您指定大量複製的使用者檔案格式。 針對大量複製，格式包含下列部分：

  • 從使用者檔案資料行到資料庫資料行的對應。

  • 每個使用者檔案資料行的資料類型。

  • 每個資料行的選擇性指標長度。

  • 每個使用者檔案資料行的資料長度上限。

  • 每個資料行的選擇性終止位元組序列。

  • 選擇性終止位元組序列的長度。

每次呼叫 bcp_colfmt 都會指定一個使用者檔案資料行的格式。 例如，若要變更五欄使用者資料檔案中三個數據行的預設設定，請先呼叫 bcp_columns （5） ，然後呼叫 bcp_colfmt 5 次，其中三個呼叫會設定您的自訂格式。 針對其餘兩個呼叫，將 eUserDataType 設定 為 0，並將 cbIndicator 、 cbUserData 和 cbUserDataTerm 分別設定 為 0、SQL_VARLEN_DATA和 0。 此程序會複製全部五個資料行，其中三個為您自訂的格式，而另兩個為預設格式。

針對 cbIndicator ，表示大型實值型別的值為 8，現在有效。 如果為對應資料行為新 max 類型的欄位指定前置詞，則只能設定為 8。 如需詳細資訊，請參閱 bcp_bind 。

在呼叫 bcp_colfmt 之前，必須先呼叫 bcp_columns 函式 。

您必須針對使用者檔案中的每個資料行呼叫 bcp_colfmt 一次。

針對任何使用者檔案資料行呼叫bcp_colfmt 多次會導致錯誤。

您不需要將使用者檔案中的所有資料複製到 SQL Server 資料表。 若要略過資料行，請指定資料行的資料格式，並將 idxServerCol 參數設定為 0。 如果您想要略過資料行，您必須指定其類型。

bcp_writefmt 函式可用來保存格式規格。

bcp_colfmt增強日期和時間功能的支援

如需與日期/時間類型 eUserDataType 參數搭配 使用的類型相關資訊，請參閱 增強型日期和時間類型的大量複製變更（OLE DB 和 ODBC）。

如需詳細資訊，請參閱 日期和時間改善 （ODBC） 。

另請參閱

大量複製函式