• [アーティクル]

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 列のバインドを作成するために使用します。このメソッドは、列の長さ、型、ターミネータ、およびプレフィックス長をパラメータとして受け取り、個々のフィールドの対応するプロパティに設定します。

ユーザーが対話モードを選択すると、このメソッドが 2 回呼び出されます。1 回は既定値 (サーバーの列の型によって異なります) に応じて列形式を設定するために呼び出され、もう 1 回はクライアントが対話モードで選択した列の型に応じて各列の形式を設定するために呼び出されます。

対話モード以外の場合、このメソッドは列ごとに 1 回だけ呼び出され、各列の型を文字型またはネイティブ型に設定し、列ターミネータと行ターミネータを設定します。

BCPColFmt メソッドにより、一括コピーのユーザー ファイルのフォーマットを指定できます。次に、一括コピーに使用するフォーマットの内容を示します。

  • ユーザー ファイルのフィールドからデータベース列へのマッピング

  • ユーザー ファイルの各フィールドのデータ型

  • 各フィールドの省略可能なインジケータの長さ

  • ユーザー ファイルの各フィールドにおけるデータの最大長

  • 各フィールドの省略可能なターミネータ バイト シーケンス

  • 省略可能なターミネータ バイト シーケンスの長さ

BCPColFmt を呼び出すたびに、ユーザー ファイルの 1 つのフィールドの形式が指定されます。たとえば、5 つのフィールドから構成されるユーザー データ ファイルの 3 つのフィールドの既定の設定を変更するには、まず BCPColumns(5) を呼び出し、BCPColFmt を 5 回呼び出します。この 5 回の呼び出しのうち 3 回は独自の形式を設定して呼び出します。残りの 2 回は、eUserDataType を BCP_TYPE_DEFAULT に設定し、cbIndicator、cbUserData、cbUserDataTerm をそれぞれ 0、BCP_VARIABLE_LENGTH、0 に設定して呼び出します。このプロシージャでは、5 つの列すべてをコピーします。それらの列のうち 3 つはカスタマイズされた形式でコピーされ、2 つは既定の形式でコピーされます。

注意注意

BCPColFmt を呼び出す前に、IBCPSession::BCPColumns メソッドを呼び出す必要があります。また、BCPColFmt は、ユーザー ファイル内の列ごとに 1 回呼び出す必要があります。BCPColFmt をユーザー ファイルの 1 つの列に対して複数回呼び出すと、エラーが発生します。

ユーザー ファイル内のすべてのデータを 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 からファイルへの一括コピー操作を行う場合の動作を次に示します。

    • コピー元の列が decimal 型または numeric 型以外の場合は、既定の有効桁数と小数点以下桁数が使用されます。

    • コピー元の列が decimal 型または numeric 型の場合は、コピー元の列の有効桁数と小数点以下桁数が使用されます。

  • cbIndicator[in]
    フィールドのプレフィックス長。既定値は BCP_PREFIX_DEFAULT です。有効なプレフィックス長は、0、1、2、4、および 8 です。フィールドがチャンク分割される場合に頻繁に使用されるプレフィックスのサイズは 8 です。チャンク分割は、大きい値になっている列を効率的に一括コピーするために使用します。

  • cbUserData[in]
    ユーザー ファイル内にあるフィールド データの最大長 (バイト単位)。長さのインジケータやターミネータの長さは含まれません。

    cbUserData を BCP_LENGTH_NULL に設定すると、データ ファイルのフィールドに含まれているすべての値が NULL に設定されます。また、cbUserData を BCP_LENGTH_VARIABLE に設定すると、各フィールドのデータの長さがシステムによって決定されます。これは、フィールドによっては、SQL Server からコピーされるデータの前に長さのインジケータや NULL インジケータを生成したり、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)