bcp_setcolfmt
適用対象: 
SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)
bcp_setcolfmt関数は、bcp_colfmtよりも優先されます。 列の照合順序を指定する場合は、 bcp_setcolfmt 関数を使用する必要があります。 bcp_setbulkmode を使用して、複数の列形式を指定できます。
この関数では、一括コピー操作で列の形式を柔軟に指定できます。 個別の列形式属性を設定する場合に、この関数を使用します。 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 に設定します。 SQL Server からファイルに一括コピーする場合、BCP_FMT_TYPEが SQLDECIMAL または SQLNUMERIC の場合、ソース列が 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)を呼び出し、次に 5 回 bcp_setcolfmt 呼び出し、そのうちの 3 つの呼び出しでカスタム形式を設定します。 残りの 2 つの呼び出しでは、BCP_FMT_TYPEを 0 に設定し、それぞれ BCP_FMT_INDICATOR_LENGTH、BCP_FMT_DATA_LEN、および cbValue を 0、SQL_VARLEN_DATA、0 に設定します。 このプロシージャでは、5 つの列すべてをコピーします。それらの列のうち 3 つはカスタマイズされた形式でコピーされ、2 つは既定の形式でコピーされます。
bcp_columns関数は、bcp_setcolfmtを呼び出す前に呼び出す必要があります。
ユーザー ファイル内の各列のプロパティごとに、 bcp_setcolfmt を 1 回呼び出す必要があります。
ユーザー ファイル内のすべてのデータを SQL Server テーブルにコピーする必要はありません。 列をスキップするには、列のデータの形式を指定する際に BCP_FMT_SERVER_COL パラメーターを 0 に設定します。 列をスキップする場合でも、その列の型を指定する必要があります。
bcp_writefmt関数を使用して、書式指定を保持できます。
bcp_setcolfmt による機能強化された日付と時刻のサポート
日付/時刻型のBCP_FMT_TYPE プロパティで使用される型は、「拡張日付/時刻型の変更のコピー (OLE DB および ODBC)で指定されているとおりです。
詳細については、「 Date and Time Improvements (ODBC)」を参照してください。