共用方式為

IBCPSession::BCPColFmt (OLE DB)

  • 發行項

在程式變數與 SQL Server 資料行之間建立繫結。 

語法

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

備註

BCPColFmt 方法是用來建立 BCP 資料檔欄位與 SQL Server 資料行之間的繫結。 它會使用資料行的長度、類型、結束字元和前置長度當做參數，並為個別欄位設定每一個屬性。

如果使用者選擇互動模式，就會呼叫這個方法兩次；一次是根據預設值設定資料行格式 (預設值是根據伺服器資料行的類型)，另一次是根據互動模式期間選擇之用戶端的資料行類型，針對每一個資料行設定格式。

在非互動模式中，每一個資料行只會呼叫這個方法一次，以便將每一個資料行的類型設定為字元或原生類型，或是設定資料行和資料列結束字元。

BCPColFmt 方法可讓您指定大量複製的使用者檔案格式。 如果是大量複製，格式會包含以下部分：

  • 從使用者檔案欄位對應至資料庫資料行。

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

  • 每個欄位的選擇性指標長度。

  • 每個使用者檔案欄位的資料最大長度。

  • 每個欄位的選擇性結束位元組順序。

  • 選擇性結束位元組順序的長度。

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

[!附註]

在 BCPColFmt 的任何呼叫之前，都必須先呼叫 IBCPSession::BCPColumns 方法。 您必須在使用者檔案中，針對每個資料行呼叫 BCPColFmt 一次。 針對任何使用者檔案資料行多次呼叫 BCPColFmt 會產生錯誤。

您不必將使用者檔案中的所有資料複製到 SQL Server 資料表。 若要略過資料行，請指定資料行的資料格式，並將 idxServerCol 參數設定為 0。 為了略過欄位，您仍然需要所有資訊，才能讓此方法正確運作。

注意：可使用 IBCPSession::BCPWriteFmt 函數來保存透過 BCPColFmt 提供的格式規格。

引數

  • idxUserDataCol[in]
    使用者的資料檔案中的欄位索引。

  • eUserDataType[in]
    使用者的資料檔案中欄位的資料類型。 可用的資料類型會列在 SQL Server Native Client 標頭檔 (sqlncli.h)，且格式為 BCP_TYPE_XXX，例如 BCP_TYPE_SQLINT4。 如果指定了 BCP_TYPE_DEFAULT 值，提供者會嘗試使用與資料表或檢視表資料行類型相同的類型。 當 eUserDataType 引數為 BCP_TYPE_SQLDECIMAL 或 BCP_TYPE_SQLNUMERIC 時，要從 SQL Server 進行大量複製作業，並複製到檔案中：

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

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

  • cbIndicator[in]
    欄位的前置長度。 預設值為 BCP_PREFIX_DEFAULT。 此前置詞的有效長度為 0、1、2、4 和 8。 前置詞大小 8 最常用來指示此欄位已分成若干區塊。 這可用來有效率地大量複製大型值類型的資料行。

  • cbUserData[in]
    使用者檔案中此欄位之資料的最大長度 (以位元組為單位)，不包括任何長度指標或結束字元的長度。

    將 cbUserData 設定為 BCP_LENGTH_NULL 表示資料檔案欄位中的所有值都會 (或應該) 設定為 NULL。 將 cbUserData 設定為 BCP_LENGTH_VARIABLE 表示系統應該決定每個欄位的資料長度。 對於某些欄位而言，這可能表示長度/null 指標會在 SQL Server 複本之資料前產生，或者表示該指標應該會在複製到 SQL Server 的資料中出現。

    對於 SQL Server 字元和二進位資料類型而言，cbUserData 可以是 BCP_LENGTH_VARIABLE、BCP_LENGTH_NULL、0 或某個正數值。 如果 cbUserData 為 BCP_LENGTH_VARIABLE，系統會使用長度指標 (如果存在) 或結束字元順序來決定資料的長度。 如果同時提供長度指標與結束字元順序，大量複製會使用導致複製最少量資料者。 如果 cbUserData 為 BCP_LENGTH_VARIABLE、資料類型為 SQL Server 字元或二進位類型，而且長度指標和結束字元順序都未指定，系統會傳回錯誤訊息。

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

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

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

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

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

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

  • cbUserDataTerm[in]
    要用於此資料行的結束字元順序長度 (以位元組為單位)。 如果資料中沒有或不需要結束字元，請將此值設定為 0。

  • idxServerCol[in]
    此資料行在資料庫資料表中的序數位置。 第一個資料行編號為 1。 資料行的序數位置是由 IColumnsInfo::GetColumnInfo 或類似的方法所報告。 如果此值為 0，大量複製會在資料檔案中忽略此欄位。

傳回碼值

  • S_OK
    此方法已成功。

  • E_FAIL
    發生提供者特有的錯誤，如需詳細資訊，請使用 ISQLServerErrorInfo 介面。

  • E_UNEXPECTED
    此方法的呼叫是非預期的。 例如，在呼叫這個方法之前，不會呼叫 IBCPSession::BCPInit 方法。

  • E_INVALIDARG
    此引數無效。

  • E_OUTOFMEMORY
    記憶體不足的錯誤。

請參閱

概念

執行大量複製作業

其他資源

IBCPSession (OLE DB)