INGEST コマンド

許可

• ターゲット表にトリガーがある場合は、 そのトリガーに指定されている操作の実行に必要な特権を、 許可 ID が持っていなければなりません。
• 保護列のある表を挿入または更新するには、許可 ID に、その表内のすべての保護列への書き込みアクセスを許可する LBAC 信用証明情報が必要です。 そうでない場合、コマンドは失敗し、エラーが戻されます。
• UPDATE または MERGE ステートメントで保護列を読み取る必要がある場合は、 その列への読み取りアクセスを可能にする LBAC 信用証明情報を、 許可 ID が持っていなければなりません。 そうでない場合、コマンドは失敗し、エラーが戻されます。
• 保護行を持つ表に対して挿入または更新を行うには、 以下の基準を満たす LBAC 信用証明情報を、許可 ID が持っていなければなりません。
  • LBAC 信用証明情報は表を保護しているセキュリティー・ポリシーの一部である
  • セキュリティー・ポリシーが RESTRICT NOT AUTHORIZED WRITE SECURITY LABEL として定義されている場合は、LBAC 資格情報が、書き込みアクセス用に許可 ID に付与されていなければなりません。
  挿入する行のセキュリティー・ラベル、許可 ID の LBAC 資格情報、セキュリティー・ポリシー定義、および LBAC 規則によって、行が保護されている表に対する挿入または更新を実行できるかどうかが決まります。
• INGEST コマンドに RESTART NEW オプション (デフォルト) または RESTART CONTINUE オプションを指定する場合は、再始動表に対する SELECT 特権、INSERT 特権、UPDATE 特権、および DELETE 特権。
• INGEST コマンドに RESTART TERMINATE オプションを指定する場合は、 再始動表に対する SELECT および DELETE 特権。
• INGEST コマンドに EXCEPTION TABLE オプションを指定する場合は、例外表に対する INSERT 特権。

さらに、INGESTコマンドのSQLステートメントは、取り込みユーティリティを実行しているユーザーが取り込みユーティリティの外部の表にアクセスした場合と同じきめ細かいアクセス制御（FGAC）の対象になります。

必要な接続

データベース

コマンド構文

from-clause

format-clause

options

error-handling options

SQL-statement

format-definition

field-list

field-definition

field-type

DELETE-statement

period-clause

INSERT-statement

MERGE-statement

matching-condition

modification-operation

period-clause

assignment-clause

insert-operation

REPLACE-statement

UPDATE-statement

assignment-clause

expression

operator

function-invocation

argument

case-expression

searched-when-clause

simple-when-clause

cast-specification

search-condition

predicate

basic-predicate

NULL-predicate

コマンド・パラメーター

FROM

入力データのソースを指定します。 INGEST ユーティリティーは、常に、 入力データをクライアントから読み取ります。

FILE file-name

指定されたファイルからデータを読み取るように指定します。 ファイル名の構文については、 ファイル名とパイプ名を参照してください。

FILE remote-file-name

IBM® Cloud Object Storage や Amazon Simple Storage Service (S3) などのリモート・ストレージからデータを読み取り、ストレージ・アクセス別名を使用してアクセスすることを指定します。 リモート・ストレージ・サーバーから転送されるファイルを一時的に保管するには、ローカル・ステージング・スペースが必要です。 リモート・ストレージ要件を参照してください。 リモート・ファイル名の構文は、次のとおりです。

DB2REMOTE://<alias>//<storage-path>/<file-name>

PIPE pipe-name

指定されたパイプからデータを読み取るように指定します。 パイプ名の構文については、 ファイル名とパイプ名を参照してください。

FORMAT format-definition

データは、指定されたフォーマット定義で規定されたフォーマットに従います。 フォーマット定義の構文は、前述の『format-definition』のセクションに示されています。

DUMPFILE or BADFILE file-name

フォーマッターから拒否された行を、指定のファイルに書き込むように 指定します。 次のタイプのエラーの場合に、 フォーマッターは行を拒否します。

• 無効な数値または範囲外の数値 (フィールド・タイプに基づく)
• 指定された書式と合わない日付、時刻、およびタイム・スタンプ
• フォーマッターによって検出されたその他のエラー

相対パスを指定する場合は、 現行のディレクトリーおよびデフォルト・ドライブが基準となります。 Linux® および UNIX プラットフォームでは、ファイルが存在しない場合、INGEST ユーティリティーは、ユーザーの umask 設定で指定された許可フラグを使用してファイルを作成します。 INGEST ユーティリティーは、Db2 CLP バックエンド・プロセス (db2bp) の開始時 (通常は最初の接続時) に有効であった umask 設定を使用します。 ファイルが既に存在する場合、 INGEST ユーティリティーは、そのファイルの最後にレコードを追加します。

INGEST ユーティリティーは、入力データの表記と同じフォーマットを使用して、 各レコードを書き込みます。 つまり、エラーを修正した後に、 ダンプ・ファイルを入力データとして使用して、INGEST コマンドを 再実行することができます。 ただし、INGEST ユーティリティーは、 複数の入力ファイルにおけるレコードの出現順序と同じ順序で、 レコードを書き込むとは限りません。また、各入力ファイル内においても同様です。 各入力ファイル内における出現順序と同じ順序で、 レコードがダンプ・ファイルに入るようにするには、 num_formatters 構成パラメーターを 1 に設定します。 このような場合には、次のような処理が行われます。

• 操作が INSERT または REPLACE である場合、 さまざまな入力ファイルに由来するレコードは、やはり順序どおりには出現しない可能性があります。 しかし、1 つの入力ファイルに由来するレコードは、すべてそのファイル内での順序と同じ 順序で出現します。
• 操作が UPDATE、DELETE、 または MERGE である場合、すべてのレコードは、 すべての入力ファイルにおける順序と同じ順序となり、また、各入力ファイル内においても同じ順序となります。

このファイルのオープンまたは書き込みでエラーが発生した場合、INGEST ユーティリティーは、入力ソースおよび行番号を含むエラー・メッセージを出し、コマンドを終了させます。 この場合、レコードはどこにも保存されません。 (入力データがファイルからのものである場合、ユーザーはそのファイルから元の入力レコードを取得できます。)

ダンプ・ファイルが完結していることを保証できるのは、 INGEST コマンドが 1 回の実行で正常に完了した場合のみです。 INGEST コマンドが失敗し、再開させたコマンドが成功した場合、 これら 2 回のコマンドで生成されたダンプ・ファイルの両方を合わせても、 レコードが欠落していたり、重複レコードが含まれていたりする可能性があります。

このパラメーターを指定しない場合、INGEST ユーティリティーは、 拒否された行ごとにエラー・メッセージを出しますが、その行をどこにも保存しません。

注: このパラメーターを指定し、拒否された入力レコードに機密データが含まれている場合、これらのレコードはダンプ・ファイルに表示されます。 必要に応じて、そのファイルへの無許可アクセスを防止してください。

EXCEPTION TABLE table-name

INGEST ユーティリティーによって挿入され、特定の SQLSTATE を持つ Db2 によってリジェクトされた行を、指定された表に書き込むことを指定します。 Db2 は、以下のタイプのエラーで行を拒否する可能性があります。 なお、これらのエラーの各々は、入力ファイル内の不良データを示しています。

• 文字データにおいて、右側が切り捨てられた。例えば、更新または挿入する値が、列に対して長すぎるストリングである、あるいは、日時値が小さすぎてホスト変数に割り当てられない、などが考えられます。
• バイナリー・データにおいて、右側が切り捨てられた。例えば、更新または挿入する値が、列に対して長すぎるストリングである、あるいは、日時値が小さすぎてホスト変数に割り当てられない、などが考えられます。
• 値が NULL、または標識パラメーターがないことが検出されました。 例えば、標識変数が指定されていないため、NULL 値がホスト変数に割り当てられない、などが考えられます。
• 数値が範囲を超えています。
• 無効な日時フォーマットが検出されました。つまり、無効なストリング表現または値が指定されました。
• CAST 指定またはキャスト・スカラー関数の文字値が無効です。
• 文字がコード化文字セットにありません。
• データ・パーティション・キーの値が無効である。
• 結果として得られた行が、行権限に適合しなかった。
• 挿入または更新の値が NULL ですが、列に NULL 値を入れることはできません。
• FOREIGN KEY の挿入値または更新値が、親表の親キーのいずれの値とも異なる。
• ユニーク索引またはユニーク制約で定められている制約に対する違反が発生しました。
• INSERT または UPDATE の結果の行が、チェック制約定義に合いません。
• その値は、表を保護しているセキュリティー・ポリシーの有効なセキュリティー・ラベルに変換できません。
• この許可 ID は、保護表に対して操作を実行することは許可されていません。
• セキュリティー・ラベル・コンポーネントにコンポーネント・エレメントが定義されていません。
• 指定されたセキュリティー・ラベル名が、指定されたセキュリティー・ポリシーで見つからない。
• ルーチンの引数のデータ・タイプ、長さ、または値が誤っている。

指定表は、関連リンク・セクションの例外表トピック説明されたように定義しなければなりません。 そのセクションおよびメッセージ SQL3604N にリストされた制限も適用されますが、以下は例外です。

• ターゲット表に DB2SECURITYLABEL 列が含まれる場合、その DB2SECURITYLABEL 列に対応する例外表の列は、タイプが VARCHAR で、長さが 128 以上でなければなりません。 (LONG VARCHAR タイプも許容されますが、推奨されていません。)

INGEST ユーティリティーは、 操作が INSERT または REPLACE である場合に限り、 例外表を使用します。 操作が UPDATE、MERGE、または DELETE であり、EXCEPTION TABLE パラメーターが指定されている場合、このユーティリティーはエラーを発行します。

この表への挿入でエラーが発生した場合、 INGEST ユーティリティーは、入力ソースおよび行番号を含むエラー・メッセージを出し、処理を継続させます。 この場合、レコードはどこにも保存されません。 (入力データがファイルからのものである場合、ユーザーはそのファイルから元の入力レコードを取得できます。)

表名が完全修飾されていない場合、 INGEST ユーティリティーは、スキーマ名として CURRENT SCHEMA の値を 使用します。 EXCEPTION TABLE パラメーターを指定しない場合、INGEST ユーティリティーは、拒否された行ごとにエラー・メッセージを出しますが、その行をどこにも保存しません。

WARNINGCOUNT n

n 個の警告メッセージとエラー・メッセージが出された後、 INGEST コマンドが停止することを指定します。 このパラメーターの対象となるのは、特定のタイプのエラーのみです。 詳しくは、 エラーのカテゴリーを参照してください。 その数はすべての入力ソースの合計です。 トランザクションの途中でこの制限に達した場合、 そのトランザクションはロールバックされます。 ただし、制限に達する前に ターゲット表に対してコミットされた行は、表に残されます。 0 個の場合、INGEST コマンドは、 警告およびエラーの数にかかわらず処理を継続します。 範囲は、 0 から 2,147,483,647 (32 ビット符号付き整数の最大値) までです。 デフォルトは 0 です。

MESSAGES file-name

通知、警告、およびエラー・メッセージを受け取るファイルを指定します。

相対パスを指定する場合は、 現行のディレクトリーおよびデフォルト・ドライブが基準となります。 Linux および UNIX プラットフォームでは、ファイルが存在しない場合、INGEST ユーティリティーは、ユーザーの umask 設定で指定された許可フラグを使用してファイルを作成します。 INGEST ユーティリティーは、Db2 CLP バックエンド・プロセス (db2bp) の開始時 (通常は最初の接続時) に有効であった umask 設定を使用します。 ファイルが既に存在する場合、 INGEST ユーティリティーは、そのファイルの最後に追加します。 パラメーターが指定されていない場合、 INGEST ユーティリティーは、メッセージを標準出力に書き込みます。

パラメーターが指定されていても、 次の場合は、INGEST ユーティリティーはメッセージを標準出力に書き込みます。

• 構文エラー
• 入力ファイルが見つからない、または読み取り可能ではない
• ターゲット表または例外表が見つからない
• ダンプ・ファイルもメッセージ・ファイルも開けない
• 開始中に検出される他のエラー

また、最後に出力される要約メッセージ (読み取りや 挿入などを行った行数と、警告およびエラーの総数を表示) は、常に標準出力に 書き込まれます。

メッセージ・ファイルのオープン、またはそのファイルへの書き込みでエラーが発生した場合、INGEST ユーティリティーはエラー・メッセージを出してコマンドを終了します。

INGEST コマンドからのメッセージの例については、 INGEST コマンドからのメッセージを参照してください。

RESTART NEW job-ID

INGEST コマンドが完了前に失敗した場合に、後続の INGEST コマンドで RESTART CONTINUE オプションを指定することによって、最後のコミット点から再開できることを指定します。 job-ID は、最大 128 バイトのストリングであり、INGEST コマンドを一意的に識別します。 このジョブ ID は、 RESTART オプションを指定し、まだ完了していない、現行データベース内のすべての INGEST コマンドで固有でなければなりません。 (このようなコマンドは、まだ実行中のコマンドであったり、 完了せずに失敗したコマンドであったりする可能性があります)。 INGEST コマンドが完了すると、後続の INGEST コマンドの RESTART パラメーターでジョブ ID を再使用することができます。 job-ID を省略すると、 INGEST ユーティリティーによって job-ID が生成されます。 このオプションはデフォルトです。

このオプションを使用する前に、 再開ログ表を作成しておく必要があります。 詳しくは、下記の関連リンクのセクションにある 『INGEST コマンドが失敗した場合の再開方法』を参照してください。

RESTART OFF

再開に関する情報を保存しないように指定します。 INGEST コマンドが完了せずに失敗した場合、 RESTART CONTINUE オプションを使用して再開することができません。 このコマンドを再実行して完了させるには、ターゲット表を INGEST コマンドの実行前の状態にリストアし、 同じ入力データを使用して INGEST コマンドを再実行する必要があります。

RESTART CONTINUE job-ID

INGEST ユーティリティーが、 RESTART NEW オプションを指定し、完了前に失敗した、直前の INGEST コマンドを再始動することを指定します。 このオプションに指定する job-ID は、 その過去の INGEST コマンドに指定されていた job-ID と一致しなければなりません。 この再開コマンドもまた再開可能です。 再始動されたコマンドが完了すると、後続の INGEST コマンドの RESTART NEW パラメーターでジョブ ID を再利用できます。 詳しくは、以下の関連リンク・セクションの 失敗した INGEST コマンドの再始動 を参照してください。

RESTART TERMINATE job-ID

INGEST ユーティリティーが、 RESTART NEW オプションを指定し、完了前に失敗した直前の INGEST コマンドの再始動情報をクリーンアップすることを指定します。 このオプションに指定するストリングは、 その過去の INGEST コマンドに指定されていたストリングと一致しなければなりません。

このオプションは、 再開可能な INGEST コマンドが過去に失敗しているが、 そのジョブを再開する予定がない場合に使用します。 このオプションを指定すると、 前に失敗した INGEST コマンドを、 再開できなくなります。 ただし、後の INGEST コマンドの RESTART NEW パラメーターでこのストリングを再利用することはできます。

注: LOAD コマンドの TERMINATE パラメーターとは異なり、元の INGEST コマンドが失敗前にコミットしたデータは、ターゲット表に残ります。 詳しくは、以下の関連リンク・セクションの 失敗した INGEST コマンドの終了 を参照してください。

DELIMITED BY char

各入力レコードが、指定の文字で区切られたテキスト・フィールドの シーケンスであることを指定します。 区切り文字には、次の値を除く 任意の 1 バイト文字を使用できます。

• ヌル文字 (X'00')
• ブランク (X'20')
• 復帰または改行 (X'0D' または X'0A')
• ドット (X'2E')、RADIX POINT 節の指定とは無関係
• 小数点 (RADIX POINT 節に指定されます。デフォルトはドット.です)
• 文字列区切り文字 (別紙BY節で指定。デフォルトは二重引用符 "です)

入力データのコード・ページが DBCS または EUC コード・ページである場合、 この文字は X'01' から X'3F' までの範囲内 (境界値を含む) になければなりません。 垂直バー (| または X'7C') は含まれないことに注意してください。 入力データのコード・ページが 1 バイト・コード・ページではない場合、 この文字は X'01' から X'7F' までの範囲内 (境界値を含む) になければなりません。 入力データのコード・ページが 1 バイト・コード・ページである場合、この文字は X'01' から X'FF' までの範囲内にすることができます。

デフォルトはコンマ,です。

string

メタ変数 string は、以下を含む任意の文字列の定数を指定します。

• ストリング区切り文字で始まりストリング区切り文字で終わる文字のシーケンス。この場合のストリング区切り文字はアポストロフィ (') です。
• 16 進定数:Xの後に、アポストロフィで囲んだ 16 進文字のシーケンスが続きます。
• Unicode文字列定数：U&アポストロフィで開始および終了し、オプションでUESCAPE句が続く文字のシーケンスが続きます。
• GRAPHIC ストリング定数:GまたはNの後、アポストロフィに囲まれた2バイト文字のシーケンスが続きます。
• 16 進グラフィック・ストリング定数: GXの後、アポストロフィに囲まれた 16 進文字のシーケンスが続きます。
• UCS-2 GRAPHIC ストリング定数:UXの後、アポストロフィに囲まれた16進文字のシーケンスが続きます。
• バイナリ定数：BXアポストロフィで開始および終了する一連の16進文字が続きます。

ストリング内に囲み文字がある場合は、 そのストリング内で 2 回重ねて入力する必要があります。 たとえば、文字列が"don't know"であり、囲み文字が一重引用符である場合は、'don''t know'を指定します。 この例としては、'This is a string'、X'303132'とU&'Unicode chars'があります。

char

メタ変数char は、長さが 1 バイトの文字列の定数を指定します。 例えば、'A'とX'30'です。

POSITIONAL

各入力レコードが、入力レコード内の位置によって特定されるテキスト・フィールドまたは 2 進数フィールド、またはその両方のフィールドのシーケンスであることを指定します。 各フィールドの位置は、 フィールド定義内の POSITION 節で指定します。

RECORDLEN length

入力データが固定長レコードであり、各レコードが指定の長さ (バイト) であることを 指定します。 レコード内の復帰または改行文字 (X'0D' または X'0A') は、 データの一部と見なされます。 一部のエディターでは、これらの文字は表示に含まれないため、場合によって、エディターに表示されているレコード長に 1 または 2 を加算する必要が生じることに注意してください。 入力にバイナリー・データが含まれている場合、このパラメーターは必須です。

範囲は 1 から 32,767 です。 RECORDLEN に指定した長さが、 各フィールド定義に指定したフィールド長の合計より短い場合、 INGEST ユーティリティーは、エラー・メッセージを出して終了します。 RECORDLEN に指定した長さが、最長フィールドの終了位置を超えている場合、INGEST ユーティリティーは、最長終了位置のフィールドの最後より後ろのバイトを無視します。 最後のレコードが短すぎる場合、 INGEST ユーティリティーは、エラー・メッセージを出し、 そのレコードを拒否します。

このパラメーターを省略すると、 INGEST ユーティリティーは、プラットフォームにかかわらず、 次の両方をレコード (行) 区切り文字として認識します。

• 改行 (X'0A')
• 改行 (X'0D0A') が後に続く 1 つ以上の復帰

INPUT CODEPAGE integer

入力データのコード・ページを指定します。 取り込みユーティリティは、次の値を除いて、関連リンクセクションのサポート・テリトリーコードとコードページトピックにリストされるコードページをサポートします。

• 1200 (UTF-16)
• 「ホスト」のコード・ページとしてリストされているコード・ページ

デフォルトは Db2 アプリケーションの コード・ページです。

入力データが、このパラメーターに指定されたコード・ページのものではなくても、 INGEST ユーティリティーは、エラーを出しません。 ただし、INGEST ユーティリティーまたは Db2 によって入力データを別のコード・ページに変換する必要がある場合、一部の文字が、置換文字 (Unicode U+001A) または意図しない他の文字に変換される可能性があります。 詳しくは、INGEST ユーティリティーのコード・ページに関する注意点トピックを参照してください。

IMPLICITLYHIDDENINCLUDE

暗黙的な非表示列がデフォルトの列リストに含まれるように指定します。 クライアント・サイドで DB2_DMU_DEFAULT レジストリー変数も指定されている場合には、このキーワードが優先されます。 このキーワードは、表の名前の後に列リストが存在しない INSERT ステートメントに対してのみ許可されます。 SQL ステートメントが INSERT でない場合、または表名の後に列リストがある場合は、エラー (SQLCODE -2918) が戻されます。 このオプションは、生成別ランダム方式を使用するランダム分散表の非表示の RANDOM_DISTRIBUTION_KEY 列には適用されません。

IMPLICITLYHIDDENMISSING

暗黙的な非表示列がデフォルトの列リストから除外されるように指定します。 クライアント・サイドで DB2_DMU_DEFAULT レジストリー変数も指定されている場合には、このキーワードが優先されます。 このキーワードは、表の名前の後に列リストが存在しない INSERT ステートメントに対してのみ許可されます。 SQL ステートメントが INSERT でない場合、または表名の後に列リストがある場合は、エラー (SQLCODE -2918) が戻されます。 このオプションは、生成別ランダム方式を使用するランダム分散表の非表示の RANDOM_DISTRIBUTION_KEY 列には適用されません。

RADIX POINT IMPLIED

暗黙指定されている小数点の位置が列定義によって決定され、 値の終わりにあるとは見なされなくなります。 例えば、値 12345 は、DECIMAL(8,2) 列に 12345.00 ではなく 123.45 として取り込まれます (INGEST されます)。 PACKED 10 進数オプションと RADIX POINT オプションには互換性がありません (SQLCODE -3525)。

このパラメーターは、LOADとIMPORT コマンドのimplieddecimal修飾子と同等です。

DELIMITER PRIORITY CHAR

区切り文字の現在のデフォルト優先順位は、(1) レコード区切り文字、(2) 区切り文字、(3) 列区切り文字です。 この修飾子を使用すると、区切り文字の優先順位が (1) 区切り文字、(2) レコード区切り文字、(3) 列区切り文字に戻り、以前の優先順位に依存している既存のアプリケーションが保護されます。

例えば、区切り文字で区切られている以下のデータ・ファイルがあるとします。

"Smith, Joshua",4000,34.98<row delimiter>
"Vincent,<row delimiter>, is a manager", ...
... 4005,44.37<row delimiter>

DELIMITER PRIORITY CHAR が指定されている場合、このデータ・ファイルに含まれるのは 2 行のみです。 2番目の<row delimiter> は、2 番目の行の最初のデータ列の一部として解釈されます。 最初と3番目の<row delimiter>は、実際のレコード区切り文字として解釈されます。 DELIMITER PRIORITY CHARが指定されない場合、このデータ・ファイルには3つの行があり、それぞれが<row delimiter>に区切られます。

このパラメーターは、LOADとIMPORT コマンドのdelprioritychar修飾子と同等です。

POSITIONAL 入力は互換性がありません (SQLCODE -3525)。

NO CHAR DELIMITER

INGEST ユーティリティーを使用する場合、2 つの列区切り文字の間にあるすべてのバイト・データは、その列のデータの一部と見なされます。 文字区切り文字は、列データの一部として構文解析されます。 Db2 データベース・システムを使用してエクスポートされたデータの場合 (エクスポート時に nochardel 修飾子が指定された場合を除く)、このオプションは指定しないでください。 nochardel 修飾子は、区切り文字のないベンダー・データ・ファイルをサポートするために提供されています。 不適切に使用すると、データが損失または破壊される場合があります。 DELIMITER PRIORITY CHAR パラメーターと OPTIONALLY ENCLOSED BY パラメーターには互換性がありません (SQLCODE -3525)。

このパラメーターは、LOADとIMPORT コマンドのnochardel修飾子と同等です。

field-list

フィールド定義のリストを指定します。 リストを省略すると、 デフォルト・フィールド定義リストで説明されているように、デフォルトが使用されます。

$field-name

フィールド名の長さは、2 から 129 バイト (ドル記号を含む) であり、SQL 識別子と同じ規則に従います。 また、$"My Field Name" のように、 引用符で区切られている名前の前にドル記号を指定することによって、 引用符で区切られているフィールド名を指定できます。

SQL ステートメントでドル記号で始まる表名や列名を指定する場合、表名または列名を区切り文字で区切られた ID として指定してください。 例として、 次の各識別子を、INGEST ユーティリティーがどのように解釈するかを示します。

表 1. フィールド名 ID の意味

ID	意味
$name (名前)	field "$NAME"
$NAME (名前)	field "$NAME"
$"My Name"	フィールド「$My Name」
"$name"	列「$name」(小文字)
"$NAME"	列「$NAME」(大文字)
"$My Name"	列「$My Name」

UNIX のシステム・コマンド行で INGEST コマンドを指定する場合、フィールド名が環境変数と見なされないようにするには、コマンドを単一引用符で囲む必要があります。 詳しくは、 システム・コマンド行での INGEST の使用 (UNIX)を参照してください。

POSITION (start:end)

この節は、形式が POSITIONAL である場合に限り有効です。 これは、 レコード内のフィールドの開始位置および終了位置 (オプション) を指定します。 単位はバイトです。 レコードの最初のバイトは位置1にあります。 終了位置を指定する場合は、開始位置以上でなければなりません。

異なるフィールドに指定した位置が、 オーバーラップしていても構いません。 例えば、米国州の完全な名前が 1 から 10 までの位置にある場合、 次の 2 つのフィールドを定義できます。

• $state_full_name POSITION(1:10)
• $state_abbreviation POSITION(1:2)

指定のフィールド位置の外にデータが存在していても、 INGEST ユーティリティーは無視します。 例えば、フィールド定義リストに POSITION(1:10) および POSITION(21:30) の 2 つのフィールドを指定した場合、INGEST ユーティリティーは、位置 11:20 のデータと、位置 30 より後からレコードの終わりまでのデータを無視します。

POSITION 節を省略すると、 前のフィールドの次のバイトが、開始位置と見なされます。 最初のフィールドについては、位置 1 が開始位置と見なされます。 終了位置を省略すると、 フィールド長の規則とデフォルトで説明されているように、ユーティリティーはデフォルトを使用するか、エラーを出します。

フィールド定義に長さが指定されない場合、取り込みユーティリティはend_position --start_position+1の長さを使用します。 この長さには、次の制限が適用されます。

• EXTERNAL 修飾子を指定したタイプ SMALLINT、INTEGER、BIGINT、DECIMAL、REAL、FLOAT、および DECFLOAT のフィールドの最大長は 50 です。
• タイプが DATE、TIME、および TIMESTAMP(p) のフィールドにフォーマット・ストリングが指定されている場合、そのフィールドの長さはフォーマット・ストリングに一致する最小値の長さ以上である必要があります。
• 書式制御ストリングが指定されていない場合は、次のようになります。
  • DATE の場合、フィールド長は 8 以上 10 以下である必要があります。
  • TIME の場合、フィールド長は 4 以上 8 以下である必要があります。
  • TIMESTAMP の場合、フィールド長は 19 以上 32 以下である必要があります。

field-type

フィールドのデータ・タイプを指定します。

CHARACTER (長さ) /BINARY (長さ)

文字データまたはバイナリー・データ。

コード・ページは、 INPUT CODEPAGE パラメーターで指定されます。 デフォルトはアプリケーション・コード・ページです。

デフォルトの長さについては、 フィールド長の規則とデフォルトを参照してください。

NOTRIM, LTRIM, RTRIM, TRIM

ストリング区切り文字で囲まれていない、フィールド内の先行ブランク (LTRIM)、末尾ブランク (RTRIM)、 または先行ブランクと末尾ブランクの両方 (TRIM) を、 ストリングに含めないように指定します。 バイナリー・ストリングの場合、LTRIM、RTRIM、および TRIM は、16 進ゼロをストリングに含めないように指定します。 形式が DELIMITED の場合のデフォルトは TRIM です。 形式が POSITIONAL の場合のデフォルトは NOTRIM です。 このパラメーターを いずれかの文字フィールドに指定する場合は、 他のすべての文字フィールドにも同じ値がなければなりません。

OPTIONALLY ENCLOSED BY char

この節は、形式が DELIMITED である場合に限り有効です。

ストリングを、ここに指定した文字で囲むことができます。 制約事項は、フィールド区切り文字の場合と同じです。 また、この文字は、フィールド区切り文字または小数点と同じ文字には できません。 いずれかの文字、バイナリー、日付、時刻、またはタイム・スタンプのフィールドにこのパラメーターを指定した場合は、それ以外の文字、バイナリー、日付、時刻、またはタイム・スタンプのフィールドにも同じ値を指定する必要があります。

ユーティリティーでは、以下のアルゴリズムを使用して、値の先頭が区切り文字であるかどうかを判別します。

• TRIM または LTRIM オプションを指定した場合 (またはデフォルトで設定された場合)、ユーティリティーは先行ブランクをトリミングした後に、フィールド内の先頭文字 (文字ストリングの場合) または 16 進ゼロ (バイナリー・ストリングの場合) を検査します。
• RTRIM または NOTRIM オプションが指定されている場合、ユーティリティーはフィールド内の先頭文字を検査します。 (すなわち、RTRIM または NOTRIM が指定されている場合、ユーティリティーはストリング区切り文字を見つける際に先行ブランクを飛ばしません。)

ユーティリティーは、レコード区切り文字を除き、 囲み文字の間にあるすべての文字を、 ストリングの一部と見なします。 ストリング内に囲み文字がある場合は、 そのストリング内で 2 回重ねて入力する必要があります。 たとえば、文字列がdon't knowであり、囲み文字が一重引用符である場合は、'don''t know'を指定します。 ストリングの末尾が囲み文字でない場合、ユーティリティーは開始区切り文字をストリングの一部と見なします。

ユーティリティーは、以下の状況では警告 SQL3114W を出します。

• TRIM または RTRIM が指定されていて (またはデフォルト)、終了区切り文字と次のフィールド区切り文字 (またはレコードの終わり) との間に、余分な非ブランク文字がある。
• NOTRIM または LTRIM が指定されていて、終了区切り文字と次のフィールド区切り文字 (またはレコードの終わり) との間に、余分な文字 (ブランクを含む) がある。

このパラメーターを指定しない場合、デフォルトは OPTIONALLY ENCLOSED BY '"'です。 その場合、値の先頭が二重引用符でないのであれば、ユーティリティーは、ストリングの周囲にある (フィールド区切り文字以外の) すべての文字をストリングの一部と見なします。

FOR BIT DATA

注: このオプションは、CHARACTER データ・タイプにのみ適用されます。

フィールドにビット・データが入っていることを示し、また、 INGEST ユーティリティーで、そのデータを入力データ・コード・ページから INGEST ユーティリティー・アプリケーション・コード・ページに 変換しないように指定します。 このフィールドを使用して、 FOR BIT DATA 指定の列に割り当てる場合は、 フィールド定義にも FOR BIT DATA と指定することを強くお勧めします。 そうしないと、 INGEST ユーティリティーが時によって行うコード・ページ変換の最適化方法によって、 列に割り当てられる値が予測不能になります。

INTEGER/SMALLINT/BIGINT EXTERNAL (length)

数値を表す最大 length バイトの文字ストリング。 このストリングは、整数、10 進数、または浮動小数点定数にすることができます。 このストリングに 10 進数または浮動小数点の値が指定されていると、 INGEST ユーティリティーは、小数部分を切り捨てることによって、 指定された整数タイプに変換します。 ストリングが有効な数値ではない場合、 または数値が範囲外である場合、INGEST ユーティリティーは、エラー・メッセージを出し、 そのレコードを拒否します。 詳しくは、 無効な数値データの処理を参照してください。

数値フィールド・タイプに EXTERNAL を使用すると、フィールド値がバイナリーではなく ASCII 文字で指定されていることを示します。 いずれかの整数フィールドに EXTERNAL を指定する場合は、 他のすべての整数、10 進浮動小数点、または浮動小数点フィールドにも指定する必要があります。

デフォルトの長さについては、 フィールド長の規則とデフォルトを参照してください。

DECIMAL (precision, scale) EXTERNAL (length)

10 進数を表す最大 length バイトの文字ストリング。 このストリングは、整数、10 進数、または浮動小数点定数にすることができます。 INGEST ユーティリティーは、指定された精度および位取りを使用して、 ストリングを 10 進数値に変換します。 ストリングに、 フィールド・タイプに指定された位取りよりも大きい位取りの 10 進数値が指定されていると、 INGEST ユーティリティーは、警告もエラーも出さずに、その値の 小数部分を切り捨てます。 フィールド・タイプに指定した位取りよりも小さい位取りの 10 進数値がストリングに指定されていると、INGEST ユーティリティーは、その値の小数部分にゼロを埋め込みます。 ストリングが有効な数値ではない場合、 または数値が範囲外である場合 (位取りの範囲ではない)、INGEST ユーティリティーは、エラー・メッセージを出し、 そのレコードを拒否します。 詳しくは、 無効な数値データの処理を参照してください。

精度には、1 から 31 までを指定できます。 位取りには、0 から精度の値までを指定できます。 デフォルトは (5,0) です。 デフォルトの長さについて詳しくは、 フィールド長の規則とデフォルトを参照してください。

いずれかの 10 進フィールドに EXTERNAL を指定する場合は、 他のすべての 10 進フィールドにも指定する必要があります。

DECFLOAT (16|34) EXTERNAL (length)

10 進浮動小数点数を表す最大 length バイトの文字ストリング。 このストリングは、整数、10 進数、浮動小数点定数、 または 10 進浮動小数点特殊値にすることができます。 INGEST ユーティリティーは、このストリングを、指定された精度の 10 進浮動小数点値 に変換します。 ストリングが有効な数値または 10 進浮動小数点特殊値ではない場合、 あるいは数値が範囲外である場合、INGEST ユーティリティーは、エラー・メッセージを出し、 そのレコードを拒否します。 詳しくは、 無効な数値データの処理を参照してください。 精度は、16 または 34 (デフォルト) のいずれかにすることができます。

デフォルトの長さについて詳しくは、 フィールド長の規則とデフォルトを参照してください。

いずれかの 10 進浮動小数点フィールドに EXTERNAL を指定する場合は、 他のすべての整数、10 進浮動小数点、または浮動小数点フィールドにも指定する必要があります。

FLOAT(integer) EXTERNAL(length)

浮動小数点数を表す最大 length バイトの文字ストリング。 このストリングは、整数、10 進数、または浮動小数点定数にすることができます。 ストリングが有効な数値ではない場合、 または数値が範囲外である場合、INGEST ユーティリティーは、エラー・メッセージを出し、 そのレコードを拒否します。 詳しくは、 無効な数値データの処理を参照してください。

integer の値は、1 から 53 の範囲の整数でなければなりません。 1 から 24 の値は単精度、25 から 53 の値は倍精度を示します。 デフォルトは 53 です。 また、以下を指定することもできます。

REAL

単精度浮動小数点数。

DOUBLE, DOUBLE PRECISION, or FLOAT

倍精度浮動小数点数。

いずれかの浮動小数点フィールドに EXTERNAL を指定する場合は、 他のすべての整数、10 進浮動小数点、または浮動小数点フィールドにも指定する必要があります。

デフォルトの長さについては、 フィールド長の規則とデフォルトを参照してください。

RADIX POINT char

小数点として使用する文字。 制約事項は、フィールド区切り文字の場合と同じです。 また、この文字は、フィールド区切り文字またはストリング区切り文字と同じ文字には できません。 いずれかの整数、10 進数、10 進浮動小数点、または浮動小数点フィールドに、 このパラメーターを指定する場合は、 他のすべての整数、10 進数、10 進浮動小数点、または浮動小数点フィールドにも同じ値がなければなりません。 デフォルトはドット.です。

INTEGER, SMALLINT, or BIGINT

指定されたタイプのバイナリー整数。 これらのタイプを指定できるのは、 形式が POSITIONAL であり、RECORDLEN パラメーターを指定する場合のみです。 また、次を指定することもできます。

BIG | LITTLE ENDIAN

整数が、ビッグ・エンディアン形式 (アドレスが低い方が最上位バイト ) またはリトル・エンディアン形式 (アドレスが低い方が最下位バイト ) のどちらであるかを指定します。 このオプションは、整数、浮動小数点、および 10 進浮動小数点タイプに適用されますが、 10 進タイプには適用されません。 デフォルトは、INGEST ユーティリティーを実行中の現行ハードウェア・プラットフォームのデフォルト形式です。

DECIMAL (precision, scale) PACKED | ZONED

指定された精度および位取りの、パック形式またはゾーン形式の 10 進数。 これらのタイプを指定できるのは、 形式が POSITIONAL であり、RECORDLEN パラメーターを指定する場合のみです。 精度には、1 から 31 までを指定できます。 位取りには、0 から精度の値までを指定できます。 デフォルトは (5,0) です。 この PACKED/ZONED 設定は、他のすべての 10 進フィールドで同じでなければなりません。 デフォルトは PACKED です。

DECFLOAT(16|34)

指定された精度のバイナリー 10 進浮動小数点数。 精度は、16 または 34 (デフォルト) のいずれかにすることができます。 このタイプを指定できるのは、 形式が POSITIONAL であり、RECORDLEN パラメーターを指定する場合のみです。

FLOAT(integer)

指定されたサイズのバイナリーの単精度または倍精度浮動小数点数。 (IEEE 浮動小数点数形式)。 integer の値は、1 から 53 の範囲の整数でなければなりません。 1 から 24 の値は単精度、25 から 53 の値は倍精度を示します。 デフォルトは 53 です。 これらのタイプを指定できるのは、 形式が POSITIONAL であり、RECORDLEN パラメーターを指定する場合のみです。 また、以下を指定することもできます。

REAL

単精度浮動小数点数。

DOUBLE, DOUBLE PRECISION, or FLOAT

倍精度浮動小数点数。

DATE, TIME, TIMESTAMP

ストリングとして指定された日付、時刻、またはタイム・スタンプ。 データベースのdate_compat データベース構成パラメーターが ONに設定される場合、DATEはTIMESTAMP (0) に相当します。

デフォルトの長さについては、 フィールド長の規則とデフォルトを参照してください。

precision

タイム・スタンプの精度を指定します。 範囲は 0 から 12 です。 デフォルトは 6 です。 入力データがフィールドタイプに指定された精度よりも高い精度でタイムスタンプを指定した場合、取り込みユーティリティは警告やエラーなしでタイムスタンプの小数部分を切り捨てます（タイムスタンプがフォーマット文字列で指定されたフォーマットを持つ場合）。 入力データに、 フィールド・タイプに指定された精度よりも低い精度のタイム・スタンプが指定されていると、 INGEST ユーティリティーは、そのタイム・スタンプの小数部分に ゼロを埋め込みます。

string

日付、時刻、またはタイム・スタンプ値の書式を指定します。 この書式制御ストリングの要素は、 現在 IMPORT および LOAD コマンドでサポートされている要素と同じです。 詳しくは、IMPORT コマンドトピックの dateformat、 timeformat、timestampformat ファイル・タイプ修飾子の説明を参照してください。

形式が POSITIONAL であり、 POSITION パラメーターに指定された長さよりもストリングが長い場合、 INGEST ユーティリティーはエラーを出します。 例えば、ストリングが 'yyyy-mm-dd' (10 バイト) であるのに、位置が 1:6 である場合、INGEST ユーティリティーは、 エラーを出します。

入力データ内の日付、時刻、またはタイム・スタンプの値は、 この書式に一致していなければなりません。ただし、右側のサブフィールドは 省略することができます。 例えば、タイム・スタンプの書式が「yyyy/mm/dd hh:mm:ss.uuu」である場合、 次のタイム・スタンプは有効です。

2010/06/03 12:34  
2010/06/03 12:34:56  
2010/06/03 12:34:56.1  
2010/06/03 12:34:56.12  
2010/06/03 12:34:56.123 

しかし、「2010/06/03 12:34:56.1234」は 有効ではありません。 サブフィールドを省略すると、IMPORTコマンドトピックのdateformat、timeformat、timestampformatファイルタイプ修飾子の説明に説明されるようにデフォルトになります。

サブフィールドの省略に関する上記の説明には、例外が 1 つあります。形式が POSITIONAL で、フィールドがレコードの最後のフィールドである場合に、レコードがフィールドの終了位置より手前で終了していると、ユーティリティーは警告を出し、その値として NULL を使用します。

日付、時刻、タイム・スタンプの値が指定の書式ではない場合 (右側のサブフィールドの欠如は除く)、INGEST ユーティリティーは、エラー・メッセージを出し、 その行を拒否します。

また、以下の規則も適用されます。

• このパラメーターをいずれかの DATE フィールドに指定する場合は、他のすべての DATE フィールドについても同じ値を指定しなければなりません。 date_compatデータベースのデータベース構成パラメーターがオンになっている場合（この場合、フィールド・タイプDATEはTIMESTAMP（0）と同等です）、それも指定しなければならない他のすべてのTIMESTAMPフィールドで同じ値を持ちます。
• これをいずれかの TIME フィールドに指定する場合は、他のすべての TIME フィールドにも同じ値を指定しなければなりません。
• これをいずれかの TIMESTAMP フィールドに指定する場合は、他のすべての TIMESTAMP フィールドにも同じ値を指定しなければなりません。 date_compat データベースのデータベース構成パラメーターがオンになっている場合（この場合、フィールド・タイプDATEはTIMESTAMP（0）と同等です）、それも指定しなければならない他のすべてのDATEフィールドで同じ値を持ちます。

フォーマット・ストリングが指定されていない場合、INGEST ユーティリティーは、 表 2に示すように、さまざまなフォーマットを認識します。

表 2. DATE、TIME、および TIMESTAMP のデフォルト値

フィールド・タイプ	デフォルトの書式
日数	date_compat データベース構成パラメーターが OFFに設定される場合は、以下のようになります。 'yyyymmdd' (DELIMITED 形式のみ) 'YYYY-MM-DD' 「mm/dd/yyyy」 'dd.mm.yyyy' 注: 最初の形式以外では、月と日を 1 桁の数字で指定することもできます (例: 'yyyy-m-d')。 date_compatデータベース構成パラメーターがオンに設定される場合、TIMESTAMP (0) と同じデフォルトになります。
時刻	'hh.mm.ss' 「hh:mm tt」 'hh:mm:ss'
TIMESTAMP	'yyyy-mm-dd-hh.mm.ss.uuuuuuuuuuuu' または 'yyyy-mm-dd hh:mm:ss.uuuuuuuuuuuu' 'yyyy-mm-dd-hh.mm.ss.uuuuuuuuuuuu' 'yyyy-mm-dd hh:mm:ss.uuuuuuuuuuuu' 'YYYY-MM-DD' 「mm/dd/yyyy」 'dd.mm.yyyy' 'yyymmdd' (DELIMITED 形式のみ) 注: 最初の形式を除くすべての形式で、月と日を 1 桁として指定することもできます。例えば、 'yyyy-m-d-hh.mm.ss.uuuuuuuuuuuu''のように指定します。

OPTIONALLY ENCLOSED BY char

この節は、形式が DELIMITED である場合に限り有効です。

ストリングを、ここに指定した文字で囲むことができます。 制約事項は、フィールド区切り文字の場合と同じです。 また、この文字は、フィールド区切り文字または小数点と同じ文字には できません。 いずれかの文字、バイナリー、日付、時刻、またはタイム・スタンプのフィールドにこのパラメーターを指定した場合は、それ以外の文字、バイナリー、日付、時刻、またはタイム・スタンプのフィールドにも同じ値を指定する必要があります。

ユーティリティーでは、以下のアルゴリズムを使用して、値の先頭が区切り文字であるかどうかを判別します。

• TRIM または LTRIM オプションを指定した場合 (またはデフォルトで設定された場合)、ユーティリティーは先行ブランクをトリミングした後に、フィールド内の先頭文字 (文字ストリングの場合) または 16 進ゼロ (バイナリー・ストリングの場合) を検査します。
• RTRIM または NOTRIM オプションが指定されている場合、ユーティリティーはフィールド内の先頭文字を検査します。 (すなわち、RTRIM または NOTRIM が指定されている場合、ユーティリティーはストリング区切り文字を見つける際に先行ブランクを飛ばしません。)

ユーティリティーは、レコード区切り文字を除き、 囲み文字の間にあるすべての文字を、 ストリングの一部と見なします。 ストリング内に囲み文字がある場合は、 そのストリング内で 2 回重ねて入力する必要があります。 たとえば、文字列がdon't knowであり、囲み文字が一重引用符である場合は、'don''t know'を指定します。 ストリングの末尾が囲み文字でない場合、ユーティリティーは開始区切り文字をストリングの一部と見なします。

ユーティリティーは、以下の状況では警告 SQL3114W を出します。

• TRIM または RTRIM が指定されていて (またはデフォルト)、終了区切り文字と次のフィールド区切り文字 (またはレコードの終わり) との間に、余分な非ブランク文字がある。
• NOTRIM または LTRIM が指定されていて、終了区切り文字と次のフィールド区切り文字 (またはレコードの終わり) との間に、余分な文字 (ブランクを含む) がある。

このパラメーターを指定しない場合、デフォルトは OPTIONALLY ENCLOSED BY '"'です。 その場合、値の先頭が二重引用符でないのであれば、ユーティリティーは、ストリングの周囲にある (フィールド区切り文字以外の) すべての文字をストリングの一部と見なします。

BOOLEAN

ブール値。

ブール値の列の場合、データ取り込み (INGEST) 時にサポートされている値は 1 または 0 のみです。

DB2SECURITYLABEL (length)

Db2 セキュリティー・ラベルを指定します。 NAME または STRING のいずれも指定されておらず、形式が POSITIONAL である場合、デフォルトの形式はエンコードされた数値形式です。それ以外の場合は、エラーが戻されます。

デフォルトの長さについては、 フィールド長の規則とデフォルトを参照してください。

NAME

Db2 セキュリティー・ラベルは、その名前を使用して指定します。 形式が DELIMITED の場合は、NAME または STRING のいずれかを指定する必要があります。 このパラメーターを いずれかの DB2SECURITYLABEL フィールドに指定する場合は、他のすべての DB2SECURITYLABEL フィールドにも同じ値がなければなりません。 表を保護するセキュリティー・ポリシーで、指定された名前のセキュリティー・ラベルが存在しない場合、 行はロードされず、警告が戻されます。

STRING

Db2 セキュリティー・ラベルは、ストリング・フォーマットで指定します。 形式が DELIMITED の場合は、NAME または STRING のいずれかを指定する必要があります。 このパラメーターを いずれかの DB2SECURITYLABEL フィールドに指定する場合は、他のすべての DB2SECURITYLABEL フィールドにも同じ値がなければなりません。 ストリングが適切な形式ではない場合、行はロードされず、警告が戻されます。 ストリングが表を保護するセキュリティー・ポリシーの一部である有効なセキュリティー・ラベルを表していない場合、行はロードされず、警告が戻されます。

デフォルトは、エンコードされた数値形式であり、形式が POSITIONAL である場合に限り有効です。

DEFAULTIF = NULL

フィールドが空の場合に、ユーティリティーによりそのフィールドの値は、フィールド代入先の表列のデフォルト値となると見なされることを指定します。 DEFAULTIF キーワードと等号記号の間に、少なくとも 1 つのスペースを入れる必要があります。 フィールドが空と見なされるのは、以下のいずれかの条件が真の場合です。

• 入力形式が DELIMITED であり、かつ以下の条件のいずれかが真の場合。
  • 2 個の区切り文字が隣接している場合。
  • 間にはブランクのみが存在する 2 個の区切り文字があり、かつ NOTRIM オプションが指定されていない場合。
  • 前のフィールドの終了位置でレコードが終了している場合。
• 入力形式が POSITIONAL であり、かつ前のフィールドの終了位置でレコードが終了している場合。

このパラメーターは、LOADとIMPORT コマンドのusedefaults修飾子と同等です。

DEFAULTIF (position) = char

データベース表の列のデフォルト値に変換する、入力ファイル内の列の入力値を指定します。 位置 (position) はオプションであり、形式が POSITIONAL の場合にのみ指定できます。 位置が指定されている場合、ユーティリティーは、指定またはデフォルトのトリム・オプションを適用する前に、入力レコードから該当文字を読み取ります。 この位置は、 フィールド内でなくても構いません。 位置が省略されている場合、ユーティリティーは、指定またはデフォルトのトリム・オプションを適用した後に、フィールドの先頭文字を読み取ります。 いずれの場合も、 入力レコードから読み取った文字が指定の文字と一致していると、 ユーティリティーは、そのフィールドの値を、 フィールドの割り当て先の表の列のデフォルト値であると見なします。

DEFAULTIF パラメーターには、以下の制限があります。

• 位置を省略する場合は、 DEFAULTIF と等号記号との間に、少なくとも 1 つスペースを入れる必要があります。 そうでない場合は、構文エラーが発生します。
• DEFAULTIF の文字には、次の値を除く 任意の 1 バイト文字を使用できます。
  • ヌル文字 (X'00')
  • 復帰または改行 (X'0D' または X'0A')
  入力データのコード・ページが DBCS または EUC コード・ページである場合、 この文字は X'01' から X'3F' までの範囲内 (境界値を含む) になければなりません。 入力データのコード・ページが 1 バイト・コード・ページではない場合、 この文字は X'01' から X'7F' までの範囲内 (境界値を含む) になければなりません。 入力データのコード・ページが 1 バイト・コード・ページである場合、この文字は X'01' から X'FF' までの範囲内にすることができます。
• フィールドを割り当てる列は、1 つのみでなければならず、 また、フィールドを、列に割り当てる式の一部にすることはできません。 例えば、以下の INGEST コマンドについて考えてみます。

  INGEST FROM FILE ...     
      UPDATE my_table  
          SET (c1, c2, c3, c4, c5) =           
              ($field1, $field2, $field2, $field3, $field4+$field5)
          WHERE $field3 = 1;

  複数の列に割り当てられているため、DEFAULTIF. $field2 は指定できません。$field1 のみが指定できます。$field3 は、述部に使用されているため、使用できません。 $field4と$field5 は、式に使用されているため、使用できません。
• 表の列のデフォルト値は、定数または NULL でなければなりません。 特殊レジスターにすることはできません。
  注: 列が NULL 可能 (つまり、列定義で NOT NULL が指定されていない) で、列定義で WITH DEFAULT 節が指定されていない場合、列のデフォルト値は NULL のままです。
• 表の列のタイプが、フィールド・タイプと異なる場合、 INGEST ユーティリティーは、入力データをフィールド・タイプに変換するときと同じ規則を適用して、 デフォルト値をフィールド・タイプに変換します。 例えば、表列がFLOAT WITH DEFAULT 3.7として定義され、フィールドがINTEGER DEFAULTIF=...として定義される場合、INGEST ユーティリティーはデフォルト値3 を使います。 同様に、表列のデフォルト値の長さがフィールド長よりも大きい場合、ユーティリティはデフォルト値をフィールド長に切り捨てます。

これらの制約事項に違反している場合、 INGEST ユーティリティーはエラーを出し、その INGEST コマンドは終了します。

例

使用上の注意

システム・コマンド行での INGEST の使用 (UNIX)

UNIX コマンド・シェルのシステム・コマンド行で INGEST コマンドを指定する場合は、フィールド名を単一引用符で囲んで指定するか、フィールド名を開始する $ の前にエスケープ文字 (円記号) を付ける必要があります。 そうしないと、 コマンド・シェルがフィールド名を環境変数として解釈し、 対応する環境変数の値に置換します。

db2 INGEST ... FORMAT DELIMITED ($field1 INTEGER, $field2 CHAR) ...

INGEST ... FORMAT DELIMITED (abc INTEGER, CHAR) ...

db2 'INGEST ... FORMAT DELIMITED ($field1 INTEGER, $field2 CHAR) ...'

db2 "INGEST ... FORMAT DELIMITED BY X'7C' (\$field1 ...) ..."

上記の問題を すべて回避する最も簡単な方法は、コマンドをファイルに入力し、 db2 コマンドに -f オプションを指定することです。

コミット頻度

エラーの区分

INGEST コマンドからのメッセージ

INGEST FROM FILE my_table.del FORMAT DELIMITED
   ($field1 INTEGER EXTERNAL, $field2 CHAR(32))
   INSERT INTO my_table VALUES($field1, $field2)
Number of rows read         = 6
Number of rows inserted     = 6
Number of rows rejected     = 0
SQL2980I The ingest utility completed successfully at timestamp "11/02/2011 12:34:56.123456".

INGEST FROM FILE bad_file.del FORMAT DELIMITED     
    ($field1 INTEGER EXTERNAL, $field2 CHAR)     
    INSERT INTO my_table VALUES($field1, $field2)  

SQL2036N  The path for the file or device "bad_file.del" is not valid. 

INGEST FROM FILE my_table1.del, my_table2.del FORMAT DELIMITED
   ( $field1 integer external, $field2 char(32) )
   INSERT INTO my_table VALUES($field1, $field2)

SQL2905I  The following error occurred issuing the SQL "INSERT" 
statement on table "ALVEYWD.MY_TABLE" using data from line "6" of 
input file "my_table1.del".

SQL0803N  One or more values in the INSERT statement, UPDATE statement, 
or foreign key update caused by a DELETE statement are not valid 
because the primary key, unique constraint or unique index identified 
by "1" constrains table "ALVEYWD.MY_TABLE" from having duplicate values 
for the index key.  SQLSTATE=23505


SQL2905I  The following error occurred issuing the SQL "INSERT" statement 
on table "ALVEYWD.MY_TABLE" using data from line "9" of input file "my_table2.del".

SQL0803N  One or more values in the INSERT statement, UPDATE statement, 
or foreign key update caused by a DELETE statement are not valid because 
the primary key, unique constraint or unique index identified by "1" 
constrains table "ALVEYWD.MY_TABLE" from having duplicate values 
for the index key.  SQLSTATE=23505

Number of rows read         = 6
Number of rows inserted     = 4
Number of rows rejected     = 2
Number of rows committed    = 4

SQL2902I The ingest utility completed at timestamp "11/02/2011 12:34:56.123456". 
Number of errors: 2. Number of warnings: 0.  

MESSAGES パラメーターを指定すると、 このパラメーターの説明に明記されているものを除き、 ほとんどのメッセージがファイルに書き込まれます。

ファイル名およびパイプ名

'dir1/dir2/my=file'

dir1/dir2/'my=file'

デフォルトのフィールド定義リスト

フィールド長の規則およびデフォルト

フィールド・タイプに指定するフィールド長はバイト単位で、1 から 32 767 まで (両端を含む) でなければなりません。

INGEST ユーティリティーが フィールド長を決定する方法

無効な数値データの処理

FORMAT 節に関する注

INGEST コマンドの SQL ステートメント

• カラム・オーガナイズ 表での INGEST コマンドの使用に適用される制約事項は、 カラム・オーガナイズ 表での INSERT、UPDATE、または DELETE ステートメントの使用に適用される制約事項と同じです。
  • WITH isolation-level 節に RR または RS を指定することはできません。この節は、 INGEST コマンドの一部である UPDATE ステートメントおよび DELETE ステートメントに対して指定できます。
• INGEST ユーティリティーは、PERIOD 節で次の値をサポートします。
  • 固定情報
  • 特殊レジスター
    注: INGEST コマンドでの SQL ステートメントの実行に影響を与えるのは、以下の特殊レジスターのみです。

    • CURRENT SCHEMA
    • CURRENT TEMPORAL SYSTEM_TIME
    • CURRENT TEMPORAL BUSINESS_TIME
  • サポートされるオペランドが引数に指定されたスカラー関数 (ただし、ネストされた 関数呼び出しおよびユーザー定義関数は使用できません)。
  • キャストのオペランドが、算術演算子およびオペランドを使用する、 サポートされるオペランド式である CAST 指定
  • 算術演算子および算術オペランドを使用する式
  また、 フィールド名を指定することもできます (フィールド名は、ユーティリティーによってパラメーター・マーカーに変換されます)。
• テンポラル表への INGEST には、他にもいくつかの考慮事項があります。
  • 特殊レジスター CURRENT TEMPORAL SYSTEM_TIME が設定されている場合、 システム期間テンポラル表およびバイテンポラル表に INGEST することはできません。
  • 特殊レジスター CURRENT TEMPORAL BUSINESS_TIME が設定されている場合であっても、 ビジネス期間テンポラル表またはバイテンポラル表 (システム期間テンポラル表に関する他の制限は受けます) に INGEST することができます。
  • システム期間テンポラル表またはバイテンポラル表に REPLACE または DELETE 操作を使用することはできません。
  • INGEST ユーティリティーは、システム期間テンポラル表の SYSTEM_TIME 期間に値を挿入できません。
• SQL ステートメント内のストリングは、アプリケーション・コード・ページのものと 見なされます。
• 先頭がドル記号 ($) の列名は、 フィールド名と区別するために、 SQL 区切り ID (二重引用符で囲む) として指定する必要があります。
• ほとんどの場合、フィールド名をパラメーター・マーカーに変換し、フィールドの値をバインドした後、 INGEST ユーティリティーは、これらのステートメントをそのまま Db2 に渡します。 そのため、これらには 同じ制約事項が適用されます。 以下に例を示します。
  • フィールドは、そのフィールド・タイプとしてバインドされます。 このため、 指定されたタイプの値が許可されている場合にのみ使用できます。 例えば、 タイプ DB2SECURITYLABEL のフィールドを使用できるのは、 セキュリティー・ラベルが許可されている場合のみです。
  • INSERT ステートメントの列リストを省略し、 VALUES リストは指定する場合、その VALUES リストには、すべての列に対応する項目を含める必要があります。 表に暗黙的な非表示列が含まれる場合、暗黙的な非表示列を含めるかどうかを明示的に指定する必要があります。 DB2_DMU_DEFAULT レジストリー変数、または IMPLICITLYHIDDENINCLUDE キーワードか IMPLICITLYHIDDENMISSING キーワードを使用して、暗黙的な非表示列を含めるかどうかを指定します。
• 次の条件のいずれかが当てはまる場合、INGEST ユーティリティーはエラーを出し、その INGEST コマンドを 終了させます。
  • コマンドに指定されている SQL ステートメントがフィールドを参照していない。
  • SQL ステートメントが DELETE または UPDATE であり、WHERE 節がないか、 または WHERE 節がフィールドを参照していない。
  • SQL ステートメントが MERGE であり、ON 節がフィールドを参照していない。
• デフォルトの分離レベルはカーソル固定 (CS) です。 これは、SQLステートメントでWITH句を指定するか（INSERTを除く）、または DB2CLIINIPATH環境変数の指定ファイルにCLI IsolationLevelキーワードを設定することでオーバーライドできます（デフォルトsqllib/cfg/db2cli.ini）。 ただし、 IsolationLevel キーワードを設定すると、すべての CLI アプリケーションに影響します。

The MERGE statement

INGEST コマンドは、MERGE ステートメントを入力データ・レコードごとに発行し、 各レコードを 1 行表 (SQL MERGE ステートメントの USING table-reference パラメーターと同等) として処理します。 これは、時に同等の SQL MERGE ステートメントとは異なる結果を生成することがあります。 以下の例について考慮します。

• 表 SOURCE_TABLE には、次の 2 行が入っています。

  (1, 'source data 1')  
  (2, 'source data 2') 

• 入力ファイル source_table.del には、SOURCE_TABLE と同じ 2つのレコードが含まれています。
• 表 TARGET_TABLE には、次の 1 行が入っています。

  (NULL, 'target data 1')

SQL MERGE ステートメントは以下のとおりです。

MERGE INTO target_table
   USING (SELECT * FROM source_table) source_table
   ON target_table.c1 <> source_table.c1
   WHEN NOT MATCHED THEN
      INSERT VALUES(source_table.c1, source_table.c2);

INGEST コマンド (同等の MERGE ステートメントを使用するもの) は以下のとおりです。

INGEST FROM FILE source_table.del
     FORMAT DELIMITED
     (
        $c1 INTEGER EXTERNAL,
        $c2 CHAR(32)
     )
     MERGE INTO target_table
        ON c1 <> $c1
        WHEN NOT MATCHED THEN
           INSERT VALUES($c1, $c2); 

この SQL MERGE ステートメントの実行後は、TARGET_TABLE には以下の行が入ります。

(NULL, 'target data 1')
(1, 'source data 1')
(2, 'source data 2')

この INGEST コマンドの実行後は、TARGET_TABLE には以下の行が入ります。

(NULL, 'target data 1')
(1, 'source data 1')

INGEST コマンドの場合に行数が少なくなる理由は、INGEST コマンドが最初の入力データ・レコードを処理した後、ターゲット表には上記の 2 行が入るからです。 この時点以降、ON 節は一致する行を持つため、WHEN NOT MATCHED 節の INSERT ステートメントはもう処理されないことになります。

この例は、MERGE ステートメントの一般的な使用方法ではありません。 MERGE ステートメントのより一般的な形式として、突き合わせキーに基づいて行を更新または挿入する場合、SQL MERGE ステートメントと INGEST コマンドは、同じ結果を生成します。

The REPLACE statement

REPLACE は、 INGEST ユーティリティーが挿入を開始する前に DELETE ステートメントを実行して表の全行を削除する点を除き、 基本的には INSERT と同じです。 表が大きい場合、DELETE に時間がかかり、かなりのログ・スペースが使用される可能性があります。

Data type conversion

ユーティリティーが INGEST するフィールドごとに、 以下の 2 つの場所でデータ変換が発生する可能性があります。

• 入力データが文字フォーマットである場合 (ASCII で指定された数値を含む)、 ユーティリティーが、データを文字からフィールド・タイプに変換します。
• フィールドのタイプが、対応する列のタイプと異なっている場合、Db2 が、フィールド値をフィールド・タイプから列のタイプに変換します。

どちらの場合も、INGEST ユーティリティーと Db2 は、トピック「 割り当てと比較」で説明されている規則を使用します。 これは、 時に、文字から列タイプに直接変換する場合とは異なる結果を生成することがあります。 以下の例について考慮します。

• 入力ファイルに、有効な DECFLOAT(34) の数値ではあるが DECFLOAT(16) の範囲外である、 ストリング '9.99E6143' が指定されています。
• フィールド・タイプは DECFLOAT(34) です。
• 列タイプは DECFLOAT(16) です。

この例では、INGEST ユーティリティーが、 フィールド値を文字から DECFLOAT(34) に変換します。 次に、Db2 が、DECFLOAT(34) から DECFLOAT(16) に変換します。 この結果、警告が生成され、DECFLOAT(16) 列の値が DECFLOAT の無限大になります。

Casting a field to an SQL data type

INGEST コマンドに指定された SQL ステートメントを実行する前に、INGEST ユーティリティーは、フィールド名をパラメーター・マーカーに変換し、その後、SQL ステートメントを動的に実行します。 Db2 は、パラメーター・マーカーのデータ・タイプを判別するために、トピック「 型なし式のデータ・タイプの判別」で説明されている規則を使用します。 動的 SQL と同様、 フィールドのデータ・タイプを、使用されているコンテキストから判別できない場合は、 エラーを受け取る可能性があります。その場合は、以下のアクションのいずれかを実行する必要があります。

• DB2_DEFERRED_PREPARE_SEMANTICS レジストリー変数を YESに設定します。
• CAST 指定を使用して、フィールド名を SQL データ・タイプに キャストします。

例えば、以下の INGEST コマンドについて考えてみます。

INGEST FROM FILE my_file.txt  
   FORMAT DELIMITED ( $date_fld DATE )
   INSERT INTO my_table(int_col) VALUES(day($date_fld));

DB2_DEFERRED_PREPARE_SEMANTICS レジストリー変数が NO (デフォルト) に設定されている場合、INGEST ユーティリティーがステートメントを発行しようとすると、 Db2 が使用する DAY 関数のバージョンを判別できないため、エラーが返されることがあります。 (このフィールドを DATE として定義し、 INGEST ユーティリティーが DATE としてバインドした場合であっても同じです)。

この問題は、 以下のように、フィールド名を対応するフィールド・タイプにキャストすることで解決できます。

INSERT INTO my_table(int_col) VALUES( day(CAST($date_fld AS DATE)) );

場合によっては、 レジストリー変数 DB2_DEFERRED_PREPARE_SEMANTICS=YES を設定することにより、問題を解決することもできます。 ただし、これは常に有効とは限りません。

追加の例として、以下の INGEST コマンドについて考えてみましょう。

INGEST FROM FILE my_file.txt
   FORMAT DELIMITED ( $field1 DECIMAL(5,2) )
   INSERT INTO my_table(dec_col) VALUES($field1 + 1);

$field1 は整数に加算されているため、 Db2 は、このフィールドにタイプ INTEGER を割り当てます。 Db2 が DECIMAL(5,2) タイプを割り当てるようにするには、SQL ステートメントを以下のように変更する必要があります。

INSERT INTO my_table(dec_col) VALUES(CAST($field1 AS DECIMAL(5,2)) + 1);

または

INSERT INTO my_table(dec_col) VALUES($field1 + 001.00);