bcp_colfmt
適用対象: 
SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW)
ユーザー ファイルのデータのコピー元またはコピー先の形式を指定します。 ソース形式として使用する場合、 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 (9.x) では、 eUserDataType パラメーターに SQLXML および SQLUDT データ型トークンのサポートが導入されました。
eUserDataType パラメーターは、ODBC C データ型列挙子ではなく、sqlncli.h の SQL Server データ型トークンによって列挙されます。 たとえば、SQL Server 固有の型 SQLCHARACTER を使用して、文字列 ODBC 型SQL_C_CHARを指定できます。
SQL Server データ型の既定のデータ表現を指定するには、このパラメーターを 0 に設定します。
SQL Server からファイルに一括コピーする場合、 eUserDataType が SQLDECIMAL または SQLNUMERIC の場合:
ソース列が decimal または numeric でない場合は、既定の有効桁数と小数点以下桁数が使用されます。
ソース列が decimal または numeric の場合、ソース列の有効桁数と小数点以下桁数が使用されます。
cbIndicator
列データ内にある長さのインジケーターや NULL インジケーターのバイト単位の長さです。 インジケーターの長さの有効値は、0 (インジケーターを使用しない場合)、1、2、4、または 8 です。
一括コピーのインジケーターの既定の使用方法を指定するには、このパラメーターに SQL_VARLEN_DATA を設定します。
インジケーターは、メモリ内ではすべてのデータの直前に、データ ファイル内ではインジケーターを適用するデータの直前に配置します。
複数の方法 (インジケーターと列の最大長、インジケーターとターミネータ シーケンスなど) を使用してデータ ファイルの列長を指定すると、一括コピーではコピーするデータの量が最も少なくなる方法が使用されます。
ユーザーの操作でデータの形式が調整されずに一括コピーで生成されたデータ ファイルには、列データの長さが異なる場合や、列の値に NULL が許容される場合にインジケーターが含まれます。
cbUserData
ユーザー ファイル内にある列データの最大長 (バイト単位)。長さのインジケーターやターミネータの長さは含まれません。
cbUserDataをSQL_NULL_DATAに設定すると、データ ファイル列のすべての値が NULL に設定されるか、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)を呼び出し、次に 5 回 bcp_colfmt 呼び出しを行い、そのうちの 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 による機能強化された日付と時刻のサポート
日付/時刻型の eUserDataType パラメーターで使用される型の詳細については、「 拡張日時型の変更のコピー (OLE DB および ODBC)」を参照してください。
詳細については、「 Date and Time Improvements (ODBC)」を参照してください。