XML GENERATE ステートメントはデータを XML 形式に変換します。
フォーマット >>-XML GENERATE--ID-1--FROM--ID-2--+---------------------+------> '-COUNT--+----+--ID-3-' '-IN-' >--+----------------------------------+-----------------------> '-+------+--ENCODING--コード・ページ-' '-WITH-' >--+---------------------------+--+----------------------+------> '-+------+--XML-DECLARATION-' '-+------+--ATTRIBUTES-' '-WITH-' '-WITH-' >--+---------------------------------------------------------------------------------+--> '-NAMESPACE--+----+--+-ID-4-------+--+------------------------------------------+-' '-IS-' '-リテラル-4--' '-NAMESPACE-PREFIX--+----+--+--リテラル-5-+-' '-IS-' '--リテラル-5-' >--+---------------------------------------+------------------> '-+----+--EXCEPTION--命令ステートメント-1-' '-ON-' >--+--------------------------------------------+-------------> '-NOT--+----+--EXCEPTION--命令ステートメント-2-' '-ON-' >--+---------+------------------------------------------------->< '-END-XML-'
ID-1 が国別グループ項目を参照する場合は、ID-1 は 国別カテゴリーの基本データ項目として処理されます。 ID-1 が英数字グループ項目を参照する場合は、ID-1 は英数字カテゴリーの基本データ項目とし処理されます。
ID-1 は JUSTIFIED 節を使用して記述することはできません。また、関数 ID にすることはできません。ID-1 は、添え字または参照変更にすることができます。
ID-1 は ID-2、ID-3、 codepage (ID の場合)、 ID-4、または ID-5 とオーバーラップすることはできません。
生成された XML 出力は、以下の ENCODING 句の説明に従ってエンコードされます。
ID-1 は、国別カテゴリーのデータ項目を参照する必要があります。あるいは次の条件が該当する場合、ENCODING 句に 1208 を指定する必要があります。
ID-1 には生成された XML 文書を入れるだけの大きさが必要です。通常は、ID-2 のサイズの 5 倍から 10 倍の大きさでなければなりません (ID-2 内の 1 つ以上のデータ名の長さによって異なります)。 ID-1 の大きさが十分でない場合は、XML GENERATE ステートメントの終わりにエラー条件が存在します。
ID-2 が国別グループ項目を参照する場合は、ID-2 はグループ項目として処理されます。ID-2 が従属国別グループ項目を含んでいるときには、その従属項目はグループ項目として処理されます。
ID-2 は関数 ID にすることや参照修飾することはできませんが、添え字を付けることはできます。
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 として指定することはできません。
ID-3 は ID-1、ID-2、 codepage (ID の場合)、 ID-4、または ID-5 とオーバーラップすることはできません。
ID の場合、codepage は、ID-1 または ID-3 とオーバーラップすることはできません。
ID-1 が国別カテゴリーのデータ項目を参照する場合、codepage は 1200 (Unicode UTF-16 用 CCSID) を指定しなければなりません。
ID-1 が英数字カテゴリーのデータ項目を参照する場合、codepage は、1208 または EBCDIC コード・ページでサポートした CCSID (『XML 文書のコード化文字セット』 (「Enterprise COBOL プログラミング・ガイド」) にリストされているような) を指定する必要があります。
ENCODING 句が省略されて、ID-1 が国別カテゴリーである場合、文書エンコード方式は Unicode UTF-16 (CCSID 1200) です。
Unicode エンコードの XML 文書の場合、バイト・オーダー・マークは生成されません。
ENCODING 句が省略されて、ID-1 が英数字カテゴリーである場合、XML 文書は、ソース・コードのコンパイル時に有効であった CODEPAGE コンパイラー・オプションによって指定されたコード・ページを使用してエンコードされます。
ID-1 が国別カテゴリーである場合、エンコード宣言の値は UTF-16 (encoding="UTF-16") となります。
ID-1 が英数字カテゴリーである場合、エンコード宣言は、ENCODING 句が指定されていればそこから派生するか、ENCODING 句が指定されていなければプログラムに有効な CODEPAGE コンパイラー・オプションから派生します。
XML-DECLARATION 句をコーディングした場合の効果の例については、『XML 出力の生成』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。
XML-DECLARATION 句を省略した場合、生成された XML 文書には XML 宣言が含まれません。
ATTRIBUTES 句の効果の例については、『XML 出力の生成』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。
NAMESPACE-PREFIX 句を使用すると、生成された XML 文書で各エレメントの開始タグと終了タグを接頭部で限定できます。
NAMESPACE-PREFIX 句を指定しなかった場合、または ID-5 が長さゼロであるか、全桁スペースを含む場合、NAMESPACE 句によって指定されたネーム・スペースは、文書にデフォルトのネーム・スペースを指定します。 この場合、ルート・エレメントで宣言されたネーム・スペースが、そのルート・エレメントも含め、文書内の各エレメント名にデフォルトで適用されます。 (デフォルトのネーム・スペース宣言は、直接には属性名に適用されません。)
NAMESPACE-PREFIX 句を指定し、ID-5が長さゼロでなく、全桁スペースを含まない場合、生成された文書で各エレメントの開始タグと終了タグが指定された接頭部で限定されます。 したがって、この接頭部はできれば短いものにしてください。 XML GENERATE ステートメントを実行するときには、接頭部は有効な XML 名でなければなりませんが、コロン (:) は使用しないでください。これについては、Namespaces in XML 1.0 で定義されています。 接頭部の末尾にスペースを含めることができますが、使用前に除去されます。
ID-5、リテラル-5: ネーム・スペース接頭部。ネーム・スペース ID の別名として働きます。
ID-4 および ID-5 は、英数字または国別のカテゴリーのデータ項目を参照する必要があります。
ID-4 および ID-5 は、ID-1 または ID-3 とオーバーラップすることはできません。
リテラル-4 および リテラル-5 は、英数字または国別のカテゴリーでなければなりませんが、形象定数とすることはできません。
ネームスペースの詳細については、Namespaces in XML 1.0 を参照してください。
NAMESPACE および NAMESPACE-PREFIX 句の使用例については、『XML 出力の生成』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。
ON EXCEPTION 句が指定されている場合は、制御は 命令ステートメント-1 に移ります。 ON EXCEPTION 句が指定されていない場合は、NOT ON EXCEPTION 句が指定されていても無視されます。 この場合、制御は、XML GENERATE ステートメントの終わりに移ります。特殊レジスター XML-CODE には例外コードが入ります。詳細については、『XML 文書の生成エラーの処理』 (Enterprise COBOL プログラミング・ガイド) を参照してください。
条件 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 文書にエレメントの文字内容として、あるいは ATTRIBUTES 句が指定され、データ項目が属性として表現されるのに適格な場合は、属性の値として挿入されることになります。
XML エレメント名および属性名は、ID-2 内のデータ名から派生します。詳細については、XML エレメント名および属性名の形成で解説しています。 選択済み基本項目を含むグループ項目の名前は、親エレメントとして保持されます。NAMESPACE-PREFIX 句を指定した場合、末尾スペースを取り去った接頭部値は、各エレメントの開始タグと終了タグを限定するのに使用されます。
生成された XML をより読みやすくするために追加の空白文字 (改行、 字下げなど) が挿入されることはありません。XML 宣言は、XML-DECLARATION 句を指定した場合にのみ生成されます。
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 には正常に完了したことを示すゼロ、またはゼロ以外の例外コードが含まれます。詳細については、『XML 文書の生成エラーの処理』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。
また、XML PARSE ステートメントも特殊レジスター XML-CODE を使用します。したがって、XML PARSE ステートメントの処理プロシージャーで XML GENERATE ステートメントをコーディングするときは、XML GENERATE ステートメントを実行する前に XML-CODE の値を保管し、XML GENERATE ステートメントの終了後に保管しておいた値を復元してください。
基本データ項目は、データ項目のタイプに応じて文字フォーマットに変換されます。
文字フォーマットへの変換後は、先頭や末尾のスペースおよび先行ゼロは除去されます。詳細については、生成された XML データのトリミングで解説しています。
変換後のデータ項目に XML の内容では正しくない文字が含まれている場合は、関連する XML 仕様で指定されているように、 例外が生成されます。 詳細については、『XML 文書の生成エラーの処理』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。
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 に従属する適格なデータ名から派生します。
DBCS データ名は、Unicode に変換する場合、XML specification のバージョン 1.0 で規定された正しい名前でなければなりません。