• [アーティクル]

bcp_colfmt

ユーザー ファイルのデータのコピー元またはコピー先の形式を指定します。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 では、eUserDataType パラメータでの SQLXML データ型および SQLUDT データ型のトークンのサポートが導入されました。

    eUserDataType パラメータは、ODBC C データ型の列挙子ではなく、sqlncli.h 内の SQL Server データ型トークンで列挙されます。たとえば、SQL Server 固有の SQLCHARACTER 型を使用して、ODBC の SQL_C_CHAR 型の文字列を指定できます。

    SQL Server データ型に既定のデータ表現を指定するには、このパラメータに 0 を設定します。

    eUserDataType に SQLDECIMAL または SQLNUMERIC を指定し、SQL Server からファイルへの一括コピーを行う場合、次の操作が実行されます。

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

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

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

cbIndicator では、サイズの大きな値をとるデータ型を示す、値 8 を指定できるようになりました。フィールドにプレフィックスを指定し、そのフィールドに対応する列が新しい max 型である場合、この値は 8 にしか設定できません。詳細については、「bcp_bind」を参照してください。

bcp_colfmt を呼び出す前に、bcp_columns 関数を呼び出す必要があります。

また、bcp_colfmt は、ユーザー ファイル内の列ごとに 1 回呼び出す必要があります。

ユーザー ファイルの任意の列に対して bcp_colfmt を複数回呼び出すと、エラーが発生します。

ユーザー ファイル内のすべてのデータを SQL Server テーブルにコピーする必要はありません。列をスキップするには、列のデータの形式を指定する際に idxServerCol パラメータを 0 に設定します。列をスキップする場合でも、その列の型を指定する必要があります。

bcp_writefmt 関数を使用すると、形式指定を保存できます。

bcp_colfmt による機能強化された日付と時刻のサポート

date 型または time 型の eUserDataType パラメータと共に使用される型の詳細については、「機能強化された日付型と時刻型向けの一括コピーの変更 (OLE DB および ODBC)」を参照してください。

詳細については、「日付/時刻の強化 (ODBC)」を参照してください。

関連項目

参照

一括コピー関数