bcp_setcolfmt

  • [アーティクル]

bcp_setcolfmt 関数は、bcp_colfmt に代わる関数です。列の照合順序を指定する際は、bcp_setcolfmt 関数を使用する必要があります。

この関数では、一括コピー操作で列の形式を柔軟に指定できます。個別の列形式属性を設定する場合に、この関数を使用します。bcp_setcolfmt を呼び出すたびに、1 つの列形式属性が設定されます。

bcp_setcolfmt では、ユーザー ファイルのデータのコピー元またはコピー先の形式を指定します。bcp_setcolfmt をコピー元の形式として使用するときは、既存のデータ ファイルの形式を指定します。このデータ ファイルがデータのコピー元として使用され、SQL Server テーブルにデータが一括コピーされます。bcp_setcolfmt をコピー先の形式として使用するときは、指定した列形式でデータ ファイルが作成されます。

構文

RETCODE bcp_setcolfmt (
        HDBC hdbc,
        INT field,
        INT property,
        void* pValue,
        INT cbValue);

引数

  • hdbc
    一括コピーが有効な ODBC 接続ハンドルです。
  • field
    プロパティを設定する列の序数です。

  • property
    プロパティ定数のいずれかを指定します。次の表に、プロパティ定数を示します。

    プロパティ 値 説明

    BCP_FMT_TYPE

    BYTE

    ユーザー ファイル内にある列のデータ型です。データベース テーブル内の対応する列のデータ型と異なる場合は、一括コピーでは可能な限りデータを変換します。

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

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

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

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

    BCP_FMT_INDICATOR_LEN

    INT

    インジケータ (プレフィックス) のバイト単位の長さです。

    これは、列データ内にある長さのインジケータや NULL インジケータのバイト単位の長さです。インジケータの長さの有効値は、0 (インジケータを使用しない)、1、2、または 4 です。

    一括コピーのインジケータの既定の使用方法を指定するには、このパラメータに SQL_VARLEN_DATA を設定します。

    インジケータは、メモリ内ではすべてのデータの直前に、データ ファイル内ではインジケータを適用するデータの直前に配置します。

    複数の方法 (インジケータと列の最大長、インジケータとターミネータ シーケンスなど) を使用してデータ ファイルの列長を指定すると、一括コピーではコピーするデータの量が最も少なくなる方法が使用されます。

    ユーザーの操作でデータの形式が調整されずに一括コピーで生成されたデータファイルには、列データの長さが異なる場合や、列の値に NULL が許容される場合にインジケータが含まれます。

    BCP_FMT_DATA_LEN

    DBINT

    データ (列長) のバイト単位の長さです。

    これは、ユーザー ファイル内にある列データのバイト単位の最大長です。長さのインジケータやターミネータの長さは含まれません。

    BCP_FMT_DATA_LEN を SQL_NULL_DATA に設定すると、データ ファイルの列に含まれるすべての値が NULL に設定されます。

    また、BCP_FMT_DATA_LEN を SQL_VARLEN_DATA に設定すると、各列のデータの長さがシステムによって決定されます。これは、列によっては、SQL Server からコピーされるデータの前に長さのインジケータや NULL インジケータを生成したり、SQL Server にコピーするデータにインジケータが必要になる場合があることを意味します。

    SQL Server の文字データ型やバイナリ データ型の場合は、BCP_FMT_DATA_LEN に SQL_VARLEN_DATA、SQL_NULL_DATA、0、正の値のいずれかを指定できます。BCP_FMT_DATA_LEN が SQL_VARLEN_DATA の場合、システムは、長さのインジケータ (存在する場合) またはターミネータ シーケンスを使用してデータの長さを決定します。長さのインジケータとターミネータ シーケンスの両方を指定した場合、一括コピーはコピーするデータ量が少なくなる方法を使用します。BCP_FMT_DATA_LEN が SQL_VARLEN_DATA の場合、データ型は SQL Server 文字型またはバイナリ型になります。長さのインジケータとターミネータ シーケンスをどちらも指定しなかった場合は、システムからエラー メッセージが返されます。

    BCP_FMT_DATA_LEN が 0 または正の値の場合、システムは最大データ長として BCP_FMT_DATA_LEN を使用します。ただし、BCP_FMT_DATA_LEN に正の値を指定し、長さのインジケータとターミネータ シーケンスを指定した場合、システムはコピーするデータ量が少なくなる方法を使用してデータ長を決定します。

    BCP_FMT_DATA_LEN の値はデータのバイト数を表します。文字データが Unicode ワイド文字で表されている場合、BCP_FMT_DATA_LEN パラメータ値が正の値のときは、各文字のサイズ (バイト数) に文字数を掛けた数を表します。

    BCP_FMT_TERMINATOR

    LPCBYTE

    この列で使用されるターミネータ シーケンス (ANSI または Unicode) を指すポインタです。このパラメータは主に文字データ型に対して有効です。これは、他のすべての型は固定長であったり、バイト数を正確に記録するために長さのインジケータが必要になる (バイナリ データの場合) ためです。

    抽出されるデータが途中で終了されないようにしたり、ユーザー ファイル内のデータが途中で終了していないことを示すには、このパラメータに NULL を設定します。

    複数の方法 (ターミネータと長さのインジケータ、ターミネータと列の最大長など) を使用してユーザー ファイルの列長を指定すると、一括コピーはコピーするデータの量が最も少なくなる方法を使用します。

    一括コピー API では、必要に応じて Unicode から MBCS への文字変換が実行されます。このため、ターミネータのバイト文字列とそのバイト文字列の長さの両方を正しく設定するように注意する必要があります。

    BCP_FMT_SERVER_COL

    INT

    データベース内での列の序数位置。

    BCP_FMT_COLLATION

    LPCSTR

    照合順序名。
  • pValue
    property に関連付ける値を指すポインタです。このポインタにより、列形式のプロパティを個別に設定できます。
  • cbvalue
    プロパティ バッファのバイト単位の長さです。

戻り値

SUCCEED または FAIL を返します。

解説

この関数は、bcp_colfmt 関数に代わるものです。bcp_colfmt のすべての機能が bcp_setcolfmt 関数にも用意されています。さらに、列の照合順序もサポートされます。列形式属性は、次に示した順番で設定することをお勧めします。

BCP_FMT_SERVER_COL

BCP_FMT_DATA_LEN

BCP_FMT_TYPE

bcp_setcolfmt 関数では、一括コピーのユーザー ファイルのフォーマットを指定できます。次に、一括コピーに使用するフォーマットの内容を示します。

  • ユーザー ファイルの列からデータベース列へのマッピング
  • ユーザー ファイルの各列のデータ型
  • 各列の省略可能なインジケータの長さ
  • ユーザー ファイルの各列におけるデータの最大長
  • 各列の省略可能なターミネータ バイト シーケンス
  • 省略可能なターミネータ バイト シーケンスの長さ

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

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

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

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

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

参照

関連項目

一括コピー関数

ヘルプおよび情報

SQL Server 2005 の参考資料の入手