Rational Developer for System z
Enterprise COBOL for z/OS バージョン 4.1 言語解説書


XML GENERATE ステートメント

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
生成された XML 文書の受け取り領域。ID-1 は、以下のいずれかを参照する必要があります。
  • 英数字カテゴリーの基本データ項目
  • 英数字グループ項目
  • 国別カテゴリーの基本データ項目
  • 国別グループ項目

ID-1 が国別グループ項目を参照する場合は、ID-1 は 国別カテゴリーの基本データ項目として処理されます。 ID-1 が英数字グループ項目を参照する場合は、ID-1 は英数字カテゴリーの基本データ項目とし処理されます。

ID-1 は JUSTIFIED 節を使用して記述することはできません。また、関数 ID にすることはできません。ID-1 は、添え字または参照変更にすることができます。

ID-1ID-2ID-3codepage (ID の場合)、 ID-4、または ID-5 とオーバーラップすることはできません。

生成された XML 出力は、以下の ENCODING 句の説明に従ってエンコードされます。

ID-1 は、国別カテゴリーのデータ項目を参照する必要があります。あるいは次の条件が該当する場合、ENCODING 句に 1208 を指定する必要があります。

  • CODEPAGE コンパイラー・オプションが EBCDIC DBCS コード・ページを指定する。
  • ID-4 または ID-5 が国別カテゴリーのデータ項目を参照する。
  • リテラル-4 または リテラル-5 が国別カテゴリーである。
  • 生成された XML に次のものを指定する ID-2 からのデータが含まれる。
    • 国別クラスまたは DBCS クラスの任意のデータ項目
    • DBCS 名を持つ任意のデータ項目 (つまり、名前が DBCS 文字からなるデータ項目)
    • DBCS 文字を含む英数字クラスの任意のデータ項目

ID-1 には生成された XML 文書を入れるだけの大きさが必要です。通常は、ID-2 のサイズの 5 倍から 10 倍の大きさでなければなりません (ID-2 内の 1 つ以上のデータ名の長さによって異なります)。 ID-1 の大きさが十分でない場合は、XML GENERATE ステートメントの終わりにエラー条件が存在します。

ID-2
XML 形式に変換されるグループ・データ項目または基本データ項目。

ID-2 が国別グループ項目を参照する場合は、ID-2 はグループ項目として処理されます。ID-2 が従属国別グループ項目を含んでいるときには、その従属項目はグループ項目として処理されます。

ID-2 は関数 ID にすることや参照修飾することはできませんが、添え字を付けることはできます。

ID-2 は、ID-1 または ID-3 とオーバーラップすることはできません。

ID-2 には、RENAMES 節を指定してはなりません。

ID-2 によって指定された以下のデータ項目は、XML GENERATE ステートメントによって無視されます。

  • 任意の名前なし基本データ項目または基本 FILLER データ項目
  • SYNCHRONIZED 項目に挿入された任意の遊びバイト
  • REDEFINES 節を指定して記述されているか、またはそのような再定義項目に従属する ID-2 に従属する任意のデータ項目
  • RENAMES 節を指定して記述された ID-2 に従属する任意のデータ項目
  • すべての従属データ項目が無視される任意のグループ・データ項目

ID-2 によって指定され、上記の規則によって無視されないすべてのデータ項目は、以下の条件を満たす必要があります。

  • それぞれの基本データ項目は、英字、英数字、数字、または国別クラスを持つか、または指標データ項目である必要があります。(つまり、基本データ項目は USAGE POINTER、USAGE FUNCTION-POINTER、USAGE PROCEDURE-POINTER、または USAGE OBJECT REFERENCE 句を使用して記述することはできません。)
  • 上記のような基本データ項目が最低 1 つ必要です。
  • FILLER 以外のそれぞれのデータ名は、直接上位にあるグループ・データ項目内で固有である必要があります。
  • DBCS データ名は、Unicode に変換する場合、XML specification バージョン 1.0 で規定された正しい名前でなければなりません。
  • データ項目は DATE FORMAT 節を指定することはできません。また、DATEPROC コンパイラー・オプションが有効であってはなりません。

例えば、次のようなデータ宣言があると考えてください。

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 として指定できます。

  • STRUCT。その従属データ項目 STAT および IN-AREA は XML 形式に変換されます。(OK-AREANG-AREA1、および NG-AREA2 は、REDEFINES 節を指定するため、無視されます。)
  • OK-AREA。その従属データ項目 FLAGSCOUNTER、および UNREFERENCED は変換されます。(データ記述項目で 03 PIC X(3) を指定する項目は、基本 FILLER データ項目であるため無視されます。ASFNPTR は REDEFINES 節を指定するため、無視されます。)
  • STRUCT に従属する任意の基本データ項目。ただし、以下を除きます。
    • ASFNPTR または PTR (使用禁止)
    • UNREFERENCED OF NG-AREA2 (非固有なデータ項目名。固有であれば有効)
    • 任意の FILLER データ項目

以下のデータ項目は ID-2 として指定することはできません。

  • NG-AREA1。これは、従属データ項目 PTR が USAGE POINTER を指定するが、REDEFINES 節を指定しないためです。(PTR で REDEFINES 節を指定した場合は無視されます。)
  • NG-AREA2。これは、従属基本データ項目に非固有名 UNREFERENCED が指定されているためです。
COUNT IN 句
COUNT IN 句を指定すると、ID-3 には (XML GENERATE ステートメントの実行後に) 生成された XML 文字エンコード・ユニット数が含まれます。 ID-1 (受け取り側) が国別カテゴリーの場合、個数は UTF-16 文字エンコード・ユニット数になります。UTF-8 を含めそれ以外のエンコード方式の場合はすべて、個数はバイト単位です。
ID-3
データ個数フィールド。PICTURE ストリングの中で記号 P を使用しないで定義された整数データ項目でなければなりません。

ID-3ID-1ID-2codepage (ID の場合)、 ID-4、または ID-5 とオーバーラップすることはできません。

ENCODING 句
指定した ENCODING 句は、生成された XML 文書のエンコード方式を決定します。
codepage
符号なし整数データ項目または符号なし整数リテラル であり、有効なコード化文字セット ID (CCSID) を表わさなければなりません。 COBOL XML 処理にサポートされるコード・ページの 1 つを識別する必要があります。『XML 文書のコード化文字セット』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。

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 コンパイラー・オプションによって指定されたコード・ページを使用してエンコードされます。

XML-DECLARATION 句
XML-DECLARATION 句を指定した場合、生成された XML 文書は、XML バージョン情報およびエンコード宣言を含む XML 宣言で始まります。

ID-1 が国別カテゴリーである場合、エンコード宣言の値は UTF-16 (encoding="UTF-16") となります。

ID-1 が英数字カテゴリーである場合、エンコード宣言は、ENCODING 句が指定されていればそこから派生するか、ENCODING 句が指定されていなければプログラムに有効な CODEPAGE コンパイラー・オプションから派生します。

XML-DECLARATION 句をコーディングした場合の効果の例については、『XML 出力の生成』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。

XML-DECLARATION 句を省略した場合、生成された XML 文書には XML 宣言が含まれません。

ATTRIBUTES 句
ATTRIBUTES 句を指定した場合、生成された XML 文書に含まれる適格な各項目は、XML エレメントの子エレメントとしてではなく、適格なその項目の直接上位にあるデータ項目に対応する XML エレメントの属性として表現されます。 適格となるには、データ項目は、基本項目であり、FILLER 以外の名前を持つ必要がありますが、そのデータ記述項目に OCCURS 節が指定されていてはなりません。

ATTRIBUTES 句の効果の例については、『XML 出力の生成』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。

NAMESPACE および NAMESPACE-PREFIX 句
NAMESPACE 句を使用すると、生成された XML 文書のネーム・スペースを識別できます。 NAMESPACE 句を指定しなかった場合、または ID-4 が長さゼロであるか、全桁スペースである場合、XML GENERATE ステートメントによって作成された XML 文書のエレメント名はどのネーム・スペースにもありません。

NAMESPACE-PREFIX 句を使用すると、生成された XML 文書で各エレメントの開始タグと終了タグを接頭部で限定できます。

NAMESPACE-PREFIX 句を指定しなかった場合、または ID-5 が長さゼロであるか、全桁スペースを含む場合、NAMESPACE 句によって指定されたネーム・スペースは、文書にデフォルトのネーム・スペースを指定します。 この場合、ルート・エレメントで宣言されたネーム・スペースが、そのルート・エレメントも含め、文書内の各エレメント名にデフォルトで適用されます。 (デフォルトのネーム・スペース宣言は、直接には属性名に適用されません。)

NAMESPACE-PREFIX 句を指定し、ID-5が長さゼロでなく、全桁スペースを含まない場合、生成された文書で各エレメントの開始タグと終了タグが指定された接頭部で限定されます。 したがって、この接頭部はできれば短いものにしてください。 XML GENERATE ステートメントを実行するときには、接頭部は有効な XML 名でなければなりませんが、コロン (:) は使用しないでください。これについては、Namespaces in XML 1.0 で定義されています。 接頭部の末尾にスペースを含めることができますが、使用前に除去されます。

ID-4リテラル-4; ID-5リテラル-5
ID-4リテラル-4: ネーム・スペース ID。有効な URI でなければなりません。これについては、Uniform Resource Identifier (URI): Generic Syntax で定義されています。

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 句
XML 文書の生成中にエラーが発生した場合、例えば、ID-1 に生成された XML 文書を含めるだけの大きさがない場合は、例外条件が存在します。この場合、XML 生成は停止し、受け取り側である ID-1 の内容は未定義となります。COUNT IN 句を指定すると、ID-3 には生成された文字位置の数 (0 から ID-1 の長さまで) が含まれます。

ON EXCEPTION 句が指定されている場合は、制御は 命令ステートメント-1 に移ります。 ON EXCEPTION 句が指定されていない場合は、NOT ON EXCEPTION 句が指定されていても無視されます。 この場合、制御は、XML GENERATE ステートメントの終わりに移ります。特殊レジスター XML-CODE には例外コードが入ります。詳細については、『XML 文書の生成エラーの処理』 (Enterprise COBOL プログラミング・ガイド) を参照してください。

NOT ON EXCEPTION 句
XML 文書の生成中に例外条件が発生しない場合、制御は命令ステートメント-2 (指定されている場合) に渡されます。指定されていない場合は、XML GENERATE ステートメントの終わりに渡されます。 ON EXCEPTION 句は、指定されていても無視されます。 XML GENERATE ステートメントを実行すると、特殊レジスター XML-CODE にゼロが格納されます。
END-XML 句
この明示範囲終了符号は、XML GENERATE ステートメントまたは XML PARSE ステートメントの有効範囲を設定します。END-XML は条件 XML GENERATE ステートメントまたは XML PARSE ステートメント (つまり、ON EXCEPTION 句または NOT ON EXCEPTION 句を指定する XML GENERATE ステートメントまたは XML PARSE ステートメント) を別の条件ステートメントにネストすることを許可します。

条件 XML GENERATE または XML PARSE ステートメントの有効範囲は、次のいずれかによって終了します。

  • ネスト構造で同じレベルにある END-XML 句。
  • 分離文字ピリオド。

END-XML は、ON EXCEPTION 句または NOT ON EXCEPTION 句を指定しない XML GENERATE ステートメントまたは XML PARSE ステートメントと共に使用することもできます。

明示的範囲終了符号の詳細については、範囲区切りステートメントを参照してください。

ネストされた 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 ステートメントと一致します。

XML GENERATE の操作

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 ステートメントの終了後に保管しておいた値を復元してください。

基本データのフォーマット変換

基本データ項目は、データ項目のタイプに応じて文字フォーマットに変換されます。

  • カテゴリーが英字、英数字、英数字編集、DBCS、外部浮動小数点、国別、国別編集、および数字編集のデータ項目は変換されません。
  • COMPUTATIONAL-5 (COMP-5) バイナリー・データ項目以外の固定小数点数値データ項目、または TRUNC(BIN) コンパイラー・オプションを使用してコンパイルされたバイナリー・データ項目は、以下を持つ数字編集項目に移動されたものとして変換されます。
    • 数値項目と同じだけの整数桁。最低でも 1 つの整数桁
    • 数値項目に最低 1 つの小数点位がある場合は、明示小数点
    • 数値項目と同じ小数点位数
    • データ項目が符号付き (PICTURE 節に S がある場合) の場合は、先行する '-' ピクチャー記号
  • COMPUTATIONAL-5 (COMP-5) バイナリー・データ項目、または TRUNC(BIN) コンパイラー・オプションを使用してコンパイルされたバイナリー・データ項目は、整数桁数以外は他の固定小数点数値項目と同様に変換されます。 整数桁の数は、ピクチャー文字ストリング内の '9' 記号の数に応じて以下のように計算されます。
    • ピクチャー記号 '9' がデータ項目に 1 個から 4 個ある場合は、5 から小数点以下の桁数を減算して得られた値
    • ピクチャー記号 '9' がデータ項目に 5 個から 9 個ある場合は、10 から小数点以下の桁数を減算して得られた値
    • ピクチャー記号 '9' がデータ項目に 10 個から 18 個ある場合は、20 から小数点以下の桁数を減算して得られた値
  • 内部浮動小数点データ項目は、以下のようにデータ項目に移動されたものとして変換されます。
    • COMP-1 の場合: PICTURE -9.9(8)E+99 を持つ外部浮動小数点データ項目
    • COMP-2 の場合: PICTURE -9.9(17)E+99 を持つ外部浮動小数点データ項目 (桁位置の数が原因で不正となります)
  • 指標データ項目は、USAGE COMP-5 PICTURE S9(9) と宣言されたものとして変換されます。

文字フォーマットへの変換後は、先頭や末尾のスペースおよび先行ゼロは除去されます。詳細については、生成された XML データのトリミングで解説しています。

変換後のデータ項目に XML の内容では正しくない文字が含まれている場合は、関連する XML 仕様で指定されているように、 例外が生成されます。 詳細については、『XML 文書の生成エラーの処理』 (「Enterprise COBOL プログラミング・ガイド」) を参照してください。

5 つの文字 & (アンパーサンド)、' (アポストロフィ)、> (より大符号)、< (より小符号)、および (引用符) の残りのインスタンスは、同等の XML 参照である '&amp;'、'&apos;'、'&gt;'、'&lt;'、および '&quot;' にそれぞれ変換されます。

次に、ID-1国別カテゴリーのデータ項目である場合は、国別以外の値は国別フォーマットに変換されます。

2 つの UTF-16 エンコード・ユニット (サロゲート・ペア) で表された残りの Unicode 文字は、XML 文字参照によって置換されます。 例えば、サロゲート・ペア (NX'D802', NX'DC13') は参照 '&#x10813;' によって置換されます。

生成された XML データのトリミング

トリミングは、データ値を文字フォーマットに変換した後にそのデータ値に対して実行されます。(変換については、基本データのフォーマット変換で解説しています。)

符号付き数値から変換された値の場合、値が正であれば先行スペースが除去されます。

数値項目から変換された値の場合、実際または暗黙の小数点の直前の桁まで (直前の桁は含まない) の先行ゼロ (冒頭の負符号の後) が除去されます。小数点の後ろの後続ゼロは保持されます。以下に例を示します。

  • -012.340 は -12.340 になります。
  • 0000.45 は 0.45 になります。
  • 0013 は 13 になります。
  • 0000 は 0 になります。

英字、英数字、DBCS、および国別クラスのデータ項目の文字値は、対応するデータ項目に左方 (デフォルト) または右方への位置調整があるかどうかに応じて、それぞれ後続スペースまたは先行スペースが除去されます。つまり、値に対応するデータ項目で JUSTIFIED 節が指定されていない場合、値から後続スペースが除去されます。値に対応するデータ項目で JUSTIFIED 節が指定されている場合、値から先行スペースが除去されます。 文字値がスペースのみで構成される場合は、トリミングの完了後に 1 つのスペースが値として残ります。

XML エレメント名および属性名の形成

ID-2 から生成された XML 文書において、XML エレメント名および属性名は、以下のように ID-2 によって指定されたデータ項目の名前および ID-2 に従属する適格なデータ名から派生します。

  • データ記述項目で指定されたデータ名の英大/小文字混合の正確なスペルは維持されます。データ項目への任意の参照からのスペル (例えば、OCCURS DEPENDING ON 節で指定されているもの) は使用されません。
  • 数字で始まるデータ名には接頭部として下線が付けられます。例えば、データ名「3D」は XML タグまたは属性名「_3D」になります。
  • 大文字と小文字を任意に組み合わせた文字 'xml' で始まるデータ名には、接頭部として下線が付けられます。例えば、データ名「Xml」は XML タグまたは属性名「_Xml」になります。

DBCS データ名は、Unicode に変換する場合、XML specification のバージョン 1.0 で規定された正しい名前でなければなりません。


ご利用条件 | フィードバック

このインフォメーション・センターでは Eclipse テクノロジーが採用されています。(http://www.eclipse.org)