プログラム変数と SQL Server 列の間にバインドを作成します。
構文
HRESULT BCPColFmt(
DBORDINALidxUserDataCol,
inteUserDataType,
intcbIndicator,
intcbUserData,
BYTE *pbUserDataTerm,
intcbUserDataTerm,
DBORDINALidxServerCol);
注釈
BCPColFmt メソッドは、BCP データ ファイル フィールドと SQL Server 列の間にバインドを作成するために使用されます。 列の長さ、型、ターミネータ、プレフィックスの長さをパラメーターとして受け取り、個々のフィールドに対してこれらの各プロパティを設定します。
ユーザーが対話型モードを選択した場合、このメソッドは 2 回呼び出されます。を使用して、既定値に従って列の形式を設定し (サーバー列の種類に応じて) 1 回、対話モードで選択したクライアントの列の種類に応じて、各列の形式を設定します。
非対話型モードでは、各列の型を文字型またはネイティブ型に設定し、列と行ターミネータを設定するために、列ごとに 1 回だけ呼び出されます。
BCPColFmt メソッドを使用すると、一括コピーのユーザー ファイル形式を指定できます。 一括コピーの場合、形式には次の部分が含まれます。
ユーザー ファイル フィールドからデータベース列へのマッピング。
各ユーザー ファイル フィールドのデータ型。
各フィールドの省略可能なインジケーターの長さ。
ユーザー ファイル フィールドあたりのデータの最大長。
各フィールドの省略可能な終了バイト シーケンス。
省略可能な終了バイト シーケンスの長さ。
BCPColFmt を呼び出すたびに、1 つのユーザー ファイル フィールドの形式が指定されます。 たとえば、5 フィールドのユーザー データ ファイル内の 3 つのフィールドの既定の設定を変更するには、最初に BCPColumns(5)を呼び出してから BCPColFmt を 5 回呼び出し、そのうちの 3 つの呼び出しでカスタム形式を設定します。 残りの 2 つの呼び出しでは、 eUserDataType を BCP_TYPE_DEFAULT に設定し、 cbIndicator、 cbUserData、 cbUserDataTerm をそれぞれ 0、BCP_VARIABLE_LENGTH、および 0 に設定します。 この手順では、5 つの列をすべてコピーします。3 列はカスタマイズした形式で、2 列は既定の形式でコピーします。
注
BCPColFmt を呼び出す前に、IBCPSession::BCPColumns メソッドを呼び出す必要があります。 BCPColFmt は、ユーザー ファイル内の各列に対して 1 回呼び出す必要があります。 ユーザー ファイル列に対して BCPColFmt を複数回呼び出すと、エラーが発生します。
ユーザー ファイル内のすべてのデータを SQL Server テーブルにコピーする必要はありません。 列をスキップするには、idxServerCol パラメーターを 0 に設定する列のデータの形式を指定します。 フィールドをスキップするには、メソッドのすべての情報が正しく機能する必要があります。
手記IBCPSession::BCPWriteFmt 関数を使用して、BCPColFmt で提供される形式の仕様を保持できます。
論争
idxUserDataCol[in]
ユーザーのデータ ファイル内のフィールドのインデックス。
eUserDataType[in]
ユーザーのデータ ファイル内のフィールドのデータ型。 使用可能なデータ型は、BCP_TYPE_SQLINT4などのBCP_TYPE_XXX形式の SQL Server Native Client ヘッダー ファイル (sqlncli.h) に一覧表示されます。 BCP_TYPE_DEFAULT値が指定されている場合、プロバイダーはテーブルまたはビュー列の型と同じ型を使用しようとします。
eUserDataType引数がBCP_TYPE_SQLDECIMALまたはBCP_TYPE_SQLNUMERICされたときに、SQL Server からファイルに一括コピー操作を行う場合:
ソース列が 10 進数または数値でない場合は、既定の有効桁数と小数点以下桁数が使用されます。
ソース列が 10 進数または数値の場合は、ソース列の有効桁数と小数点以下桁数が使用されます。
cbIndicator[in]
フィールドのプレフィックスの長さ。 既定値は BCP_PREFIX_DEFAULT です。 プレフィックスの有効な長さは 0、1、2、4、8 です。 プレフィックス サイズ 8 は、フィールドがチャンクされていることを示すために最も一般的に使用されます。 これは、大きな値型の列を効率的に一括コピーするために使用されます。
cbUserData[in]
長さインジケーターまたはターミネータの長さを含まない、ユーザー ファイル内のこのフィールドのデータの最大長 (バイト単位)。
cbUserDataを BCP_LENGTH_NULL に設定すると、データ ファイル フィールド内のすべての値が 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 インターフェイスを使用してください。
予期しないエラー
メソッドの呼び出しは予期しないものでした。 たとえば、 IBCPSession::BCPInit メソッドは、このメソッドを呼び出す前に呼び出されませんでした。
無効な引数エラー (E_INVALIDARG)
引数が無効です。
E_OUTOFMEMORY
メモリ不足エラー。