XML GENERATE ステートメントはデータを XML 形式に変換します。
ID-1 が国別グループ項目を参照する場合は、ID-1 は国別カテゴリーの基本データ項目として処理されます。 ID-1 が英数字グループ項目を参照する場合は、ID-1 は英数字カテゴリーの基本データ項目とし処理されます。
ID-1 は JUSTIFIED 文節を使用して記述することはできません。また、関数 ID にすることはできません。ID-1 は、添え字または参照変更にすることができます。
ID-1 は、ID-2 または ID-3 とオーバーラップしてはなりません。
ID-1 が英数字カテゴリーの データ項目を参照する場合、コンパイル時のロケールおよびランタイムのロケールによって 示されたコード・ページが同一でなければなりません。
ID-1 が英数字カテゴリーの データ項目を参照する場合、生成された XML 文書は以下のコード・ページでエンコードされます。
ID-1 が国別カテゴリーのデータ項目を参照する場合は、生成された XML 文書は UTF-16 でエンコードされます。 バイト・オーダー・マークは生成されません。
ID-1 に対して有効な コード・ページがマルチバイト・コード・ページである場合、または生成された XML に以下の ID-2 からのデータが含まれている場合、ID-1 は 国別カテゴリーのデータ項目を参照する必要があります。
ID-1 には生成された XML 文書を入れるだけの大きさが必要です。通常は、ID-2 サイズの 5 倍から 8 倍の大きさでなければなりません (ID-2 内のデータ名 (1 つまたは複数) の長さによって異なります)。ID-1 の大きさが十分でない場合は、XML GENERATE ステートメントの終わりにエラー条件が存在します。
ID-2 が国別グループ項目を参照する場合は、ID-2 はグループ項目として処理されます。 ID-2 が従属国別グループ項目を含んでいるときには、その従属項目はグループ項目として処理されます。
ID-2 は、ID-1 または ID-3 とオーバーラップしてはなりません。
ID-2 には、RENAMES 文節を指定してはなりません。
ID-2 によって指定された以下のデータ項目は、XML GENERATE ステートメントによって無視されます。
ID-2 によって指定され、上記の規則によって無視されないすべてのデータ項目は、以下の条件を満たす必要があります。
例えば、次のようなデータ宣言があるとします。
01 STRUCT.
02 STAT PIC X(4).
02 IN-AREA PIC X(100).
02 OK-AREA REDEFINES IN-AREA.
03 FLAGS PIC X.
03 PIC X(3).
03 COUNTER USAGE COMP-5 PIC S9(9).
03 ASFNPTR REDEFINES COUNTER USAGE FUNCTION-POINTER.
03 UNREFERENCED PIC X(92).
02 NG-AREA1 REDEFINES IN-AREA.
03 FLAGS PIC X.
03 PIC X(3).
03 PTR USAGE POINTER.
03 ASNUM REDEFINES PTR USAGE COMP-5 PIC S9(9).
03 PIC X(92).
02 NG-AREA2 REDEFINES IN-AREA.
03 FN-CODE PIC X.
03 UNREFERENCED PIC X(3).
03 QTYONHAND USAGE BINARY PIC 9(5).
03 DESC USAGE NATIONAL PIC N(40).
03 UNREFERENCED PIC X(12).
以下のデータ項目は ID-2 として指定できます。
以下のデータ項目は ID-2 として指定することはできません。
ON EXCEPTION 句が指定されている場合は、制御は命令ステートメント-1 に移ります。 ON EXCEPTION 句が指定されていない場合は、NOT ON EXCEPTION 句が指定されていても無視されます。この場合、制御は、XML GENERATE ステートメントの終わりに移ります。特殊レジスター XML-CODE には例外コードが含まれています。詳細については、「COBOL for Windows プログラミング・ガイド」を参照してください。
条件 XML GENERATE または XML PARSE ステートメントの有効範囲は、次のいずれかによって終了します。
END-XML は、ON EXCEPTION 句または NOT ON EXCEPTION 句を指定しない XML GENERATE ステートメントまたは XML PARSE ステートメントと共に使用することもできます。
明示的範囲終了符号の詳細については、範囲区切りステートメントを参照してください。
XML GENERATE ステートメントまたは XML PARSE ステートメントが 命令ステートメント-1 または命令ステートメント-2 として出現する場合、あるいは別の XML GENERATE ステートメントまたは XML PARSE ステートメントの命令ステートメント-1 または 命令ステートメント-2 の一部として出現する場合、その XML GENERATE ステートメントまたは XML PARSE ステートメントはネストされた XML GENERATE ステートメントまたは XML PARSE ステートメントになります。
ネストされた XML GENERATE ステートメントまたは XML PARSE ステートメントは、左から右に処理される、一致した XML GENERATE と END-XML、または XML PARSE と END-XML の組み合わせとみなされます。したがって、検出される END-XML 句はすべて、暗黙的または明示的に終了されていない、先行の最も近い場所にある XML GENERATE ステートメントまたは XML PARSE ステートメントと一致します。
ID-2 内の適格な各基本データ項目の内容は、基本データのフォーマット変換および 生成された XML データのトリミングに記載された文字フォーマットに変換されます。 それぞれのストレージ域の最初の定義のみが処理されます。データ項目の再定義は含まれません。また、RENAMES 文節によって有効に定義されたデータ項目も含まれません。
次に、変換された内容はエレメント文字内容として XML マークアップに挿入されます。XML エレメント名は ID-2 内のデータ名から派生します。詳細については、XML エレメント名の形成で解説しています。選択済み基本項目を含むグループ項目の名前は、親エレメントとして保持されます。生成された XML をより読みやすくするために追加の空白文字 (改行、字下げなど) が挿入されることはありません。XML 宣言は生成されません。
ID-1 によって指定された受け取り領域の長さが生成された XML 文書を格納するのに十分でない場合は、エラー条件が存在します。詳細については、上記の ON EXCEPTION 句の説明を参照してください。
ID-1 の長さが生成された XML 文書よりも長い場合は、ID-1 内の XML が生成された部分のみが変更されます。ID-1 の残りの部分には、XML GENERATE ステートメントの今回の実行以前に存在していたデータが入っています。そのデータを参照しないようにするには、 ID-1 を初期化して XML GENERATE ステートメントの前にスペースを入れるか、または COUNT IN 句を指定します。
COUNT IN 句を指定すると、ID-3 には (XML GENERATE ステートメントの実行後) 生成された文字位置の総数 (UTF-16 エンコード・ユニットまたはバイト) が含まれます。ID-3 を参照修飾子の長さフィールドとして使用して、生成された XML 文書を含む ID-2 の一部を参照することができます。
XML GENERATE ステートメントの実行後、特殊レジスター XML-CODE には正常に完了したことを示すゼロ、またはゼロ以外の例外コードが含まれます。(詳細は、「COBOL for Windows プログラミング・ガイド」を参照してください。)
また、XML PARSE ステートメントも特殊レジスター XML-CODE を使用します。したがって、XML PARSE ステートメントの処理プロシージャーで XML GENERATE ステートメントをコーディングするときは、XML GENERATE ステートメントを実行する前に XML-CODE の値を保管し、XML GENERATE ステートメントの終了後に保管しておいた値を復元してください。
基本データ項目は、データ項目のタイプに応じて文字フォーマットに変換されます。
ネイティブ (IEEE) 浮動小数点項目では、特殊値である正の無限大、負の無限大、および NaN (非数値) が、それぞれ「INF」、「-INF」、「NaN」と表されます。
文字フォーマットへの変換後は、先頭や末尾のスペースおよび先行ゼロは除去されます。詳細については、生成された XML データのトリミングで解説しています。
変換後のデータ項目に XML の内容では正しくない文字が含まれている場合は、関連する XML 指定で指定されているように、元のデータ値 (つまり、変換またはトリミング前のデータ項目の値) が 16 進数で表され、接頭部 'hex.' が付いたエレメント・タグ名が通常のタグ名を置換します。例えば、データ項目 Customer-Name が LOW-VALUES を含んでいることが実行時に検出された場合、通常の 'Customer-Name' の代わりに XML エレメント・タグ名 'hex.Customer-Name' が使用され、その内容はゼロ数字のペアからなるストリングとして表されます。
5 つの文字 & (アンパーサンド)、' (アポストロフィ)、> (より大符号)、< (より小符号)、および “ (引用符) の残りのインスタンスは、同等の XML 参照である '&'、'''、'>'、'<'、および '"' にそれぞれ変換されます。
次に、ID-1 が国別カテゴリーのデータ項目である場合は、国別以外の値は国別フォーマットに変換されます。
2 つの UTF-16 エンコード・ユニット (「サロゲート・ペア」) で表された残りの Unicode 文字は、XML 文字参照によって置換されます。例えば、サロゲート・ペア (NX'D802', NX'DC13') は参照 '𐠓' によって置換されます。
トリミングは、データ値を文字フォーマットに変換した後にそのデータ値に対して実行されます。 (変換については、基本データのフォーマット変換で解説しています。)
符号付き数値から変換された値の場合、値が正であれば先行スペースが除去されます。
数値項目から変換された値の場合、実際または暗黙の小数点の直前の桁まで (直前の桁は含まない) の先行ゼロ (冒頭の負符号の後) が除去されます。小数点の後ろの後続ゼロは保持されます。以下に例を示します。
英字、英数字、DBCS、および国別クラスのデータ項目の文字値は、対応するデータ項目に左方 (デフォルト) または右方への位置調整があるかどうかに応じて、それぞれ後続スペースまたは先行スペースが除去されます。つまり、値に対応するデータ項目で JUSTIFIED 文節が指定されていない場合、値から後続スペースが除去されます。値に対応するデータ項目で JUSTIFIED 文節が指定されている場合、値から先行スペースが除去されます。文字値がスペースのみで構成される場合は、トリミングの完了後に 1 つのスペースが値として残ります。
ID-2 から生成された XML 文書において、XML エレメント・タグ名は ID-2 によって指定されたデータ項目の名前、および ID-2 に従属する適格なデータ名から派生します。以下に例を示します。
マルチバイト・データ名は、Unicode に変換する場合、XML specification のバージョン 1.0 で規定された正しい名前でなければなりません。
XML GENERATE ステートメントの実行後、特殊レジスター XML-CODE に含まれる可能性のある例外コードについては、「COBOL for Windows プログラミング・ガイド」を参照してください。