XML GENERATE ステートメント
XML GENERATE ステートメントは、データを XML 形式に変換します。
形式 1 >>-XML GENERATE--ID-1--FROM--ID-2--+---------------------+---------------> '-COUNT--+----+--ID-3-' '-IN-' >--+-----------------------------------------+---------------------------> '-+----+--EXCEPTION--命令ステートメント-1-' '-ON-' >--+----------------------------------------------+--+---------+-------->< '-NOT--+----+--EXCEPTION--命令ステートメント-2-' '-END-XML-' '-ON-'
形式 2 >>-XML GENERATE--FILE-STREAM--+-----------+--ID-4--FROM--ID-2------------> +-APPEND----+ '-OVERWRITE-' >--+---------------------+-----------------------------------------------> '-COUNT--+----+--ID-3-' '-IN-' >--+-----------------------------------------+---------------------------> '-+----+--EXCEPTION--命令ステートメント-1-' '-ON-' >--+----------------------------------------------+--+---------+-------->< '-NOT--+----+--EXCEPTION--命令ステートメント-2-' '-END-XML-' '-ON-'
- ID-1
- 生成された XML 文書の受信領域。ID-1 は、以下のいずれかを参照する必要があります。
- カテゴリー英数字の基本データ項目
- 英数字グループ項目
- カテゴリー国別の基本データ項目
ID--1 が英数字グループ項目を参照する場合、ID-1 は、カテゴリー英数字の基本データ項目であるかのように取り扱われます。
ID-1 は、JUSTIFIED 文節で記述されてはなりません。また、関数 ID であってはなりません。ID-1 は、添え字を付けたり、参照変更できます。
ID-1 は、ID-2 または ID-3 とオーバーラップしないようにしてください。
ID-1 がカテゴリー英数字のデータ項目を参照する場合、生成された XML 文書は、PROCESS ステートメント CCSID オプション d で指定される CCSID でエンコードされます (ソース・コードのコンパイル時に有効な XML GENERATE 1 バイト・データ CCSID)。有効な CCSID が 65535 の場合、実行時のジョブのデフォルト CCSID が使用されます。
ID-1 がカテゴリー国別のデータ項目を参照する場合、生成された XML 文書は、UCS-2 でエンコードされます。PROCESS ステートメントの CCSID オプション d で国別 CCSID が指定されている場合、その CCSID が使用されます。
それ以外の場合には、NTLCCSID PROCESS オプションで指定されている CCSID が使用されます。
バイト・オーダー・マークは生成されません。ID-1 は、生成された XML が以下の ID-2 からのデータを含む場合、カテゴリー国別のデータ項目を参照する必要があります。
- クラス国別またはクラス DBCS のすべてのデータ項目
- DBCS 名を持つすべてのデータ項目 (つまり、名前に DBCS 文字が含まれるデータ項目)
ID-1 は、生成された XML 文書を十分に含むことができる大きさである必要があります。通常、これは ID-2 のサイズの 5 倍から 8 倍である必要があり、identifier-2 内の 1 つまたは複数のデータ名の長さによって異なります。 ID-1 の大きさが十分でない場合、XML GENERATE ステートメントの終了時にエラー状態が発生します。
- ID-2
- XML 形式に変換されるグループまたは基本データ項目。
- 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 PROCEDURE-POINTER 句を使用して記述することはできません。)
- そのような基本データ項目が少なくとも 1 つ存在する必要があります。
- FILLER 以外の各データ名は、隣接した上位のグループ・データ項目内で固有である必要があります。
- Unicode に変換される場合、すべての DBCS データ名は、XML 仕様、バージョン 1.0 で許可されている名前である必要があります。
例えば、次のようなデータ宣言を想定します。
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 PIC S9(9). 03 ASFNPTR REDEFINES COUNTER USAGE PROCEDURE-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 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-AREA、NG-AREA1、および NG-AREA2 は、REDEFINES 節を指定するため無視されます。)
- OK-AREA。従属データ項目 FLAGS、COUNTER、および 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 文字位置のカウント (XML GENERATE ステートメントの実行後) が含まれます。 ID-1 (受信側) がカテゴリー国別を持つ場合、 そのカウントは国別文字位置 (UCS-2 文字エンコード単位) でのものです。それ以外の場合、カウントは、バイト単位です。
- ID-3
- データ・カウント・フィールド。ピクチャー・ストリングに記号 P を指定せずに定義した整数データ項目でなければなりません。
ID-3 は、ID-1 または ID-2 とオーバーラップしてはいけません。
- FILE-STREAM 句
- FILE-STREAM 句が指定される場合、変換された XML データは、ID-4 で指定される IFS ファイルに保存されます。以下のように、CCSID を使用して、XML ファイルはエンコードされます。
- Unicode UCS-2。生成された XML が (「ID-1」で説明したように)
以下に対する ID-2 からのデータを含む場合。
- すべての国別データ項目または DBCS データ項目
- DBCS 名を持つすべてのデータ項目
- これ以外の場合、PROCESS ステートメント CCSID オプション d で指定された CCSID (XML GENERATE 1 バイト・データ出力 CCSID、デフォルトは JOBRUN)。使用される CCSID は、 XML 文書のためのコード化文字セットにリストされている 1 バイト文字セット CCSID のいずれかである必要があります。
APPEND 句も OVERWRITE 句も使用されない場合、XML ファイル・エンコード CCSID を使用して新規ファイルが作成され、変換された XML データはそのファイルに保管されます。プログラムの実行中に同じ名前を持つファイルが存在する場合、XML 生成は停止し、特殊レジスター XML-CODE にはこのエラーを表す例外コードが含まれます。
APPEND 句が使用されるとき、ファイルが XML ファイル・エンコード CCSID を持つ場合には、変換された XML データは既存のファイルに追加されます。これ以外の場合、XML 生成は停止し、特殊レジスター XML-CODE にはこのエラーを表す例外コードが含まれます。
ただし、PROCESS オプション XMLGEN(KEEPFILEOPEN) が指定されていて、IFS ファイルが現在開かれている場合、APPEND および OVERWRITE 句なしで XML GENERATE を指定することで、IFS ファイルを閉じることができます (エラーおよび例外コードは発行されません)。
OVERWRITE 句が使用される場合、XML ファイル・エンコード CCSID を使用して既存のファイルは新規ファイルで置換されます。変換された XML データは新規ファイルに保管されます。
上述したエラーを除く他のすべてのファイル操作エラーは、ファイル操作エラー・メッセージを含むランタイム照会メッセージをトリガーします。操作を継続するために "G" で応答された場合は、特殊レジスター XML-CODE に例外コードが設定されます。
- ID-4
- IFS ファイル名であり、英字または英数字データ項目でなければなりません。変換された XML コンテントを保持する IFS ファイルのパス名を含みます。
- Unicode UCS-2。生成された XML が (「ID-1」で説明したように)
以下に対する ID-2 からのデータを含む場合。
- 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 には、例外コードが含まれます (「IBM® Rational® Development Studio for i: ILE COBOL プログラマーの手引き」の説明を参照)。
- NOT ON EXCEPTION
- XML 文書の生成時に例外条件が発生しない場合、指定されていれば、制御は 命令ステートメント-2 に渡され、指定されていない場合には、XML GENERATE ステートメントの最後に渡されます。ON EXCEPTION 句は、指定されていても無視されます。
特殊レジスター XML-CODE は、XML GENERATE ステートメント
の実行後、ゼロを含みます。
- 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 ステートメントで使用することも可能です。
