The IFormNG2 menu overview

The IformNG2 main menu (Spool2XML) is shown with this command:

IFORMNG2/IFORMNG2

This menu is shown:

IFORMNG2                      InterForm NG2 Main Menu                       

Select one of the following:                          System . . . :  PMK250
                                                      User . . . . :  KSE
                                                      Version  . . :  1.6.0b

   Administration
     1. Work with monitored output queues
     2. Work with XML definitions
     5. Work with IFORMNG2 output queue

    10. Start IFORMNG2 subsystem
    11. End IFORMNG2 subsystem
    12. Work with IFORMNG2 subsystem

    31. Display print service log
    51. Adjust CPI - *AFPDS configuration
    91. License
    92. Change NG2 installation

Selection or command
===> 

F3=Exit   F4=Prompt   F9=Retrieve   F12=Cancel
F13=Information Assistant   F16=System main menu

These are the menu options:

1. Work with monitored output queues
The output queues monitored by IFormNG400 for new XML spooled files.
2. Work with XML definitions
The XML definitions refer to a printer file, decides if the original output should be split up into several XML files, selects the InterFormNG template for the merge and an output queue for the final, merged output from InterFormNG.
5. Work with IFORMNG2 output queue
The merged result from InterFormNG2 are created as spooled files on output queues.
10. Start IFORMNG2 subsystem
Start the IFORMNG2 subsystem. This is where all IFormNG400 related jobs run.
12. Work with IFORMNG2 subsystem
Lists all jobs in the IFORMNG2 subsystem.
31. Display Print service log
Displays the service log file from InterFormNG2. The log can also directly in the IFS inside /iformng2/InterFormNG-shell/user/profiles/default/logs/interformng2.log and you can also see the same log as the system log of InterFormNG2.
51. Adjust CPI - *AFPDS configuration
If you process AFPDS spooled files in InterFormNG2, then you might need to expand the input spooled file, when the contents is mapped to lines and positions - especially if small fonts are used in the input spooled file. This section explains how you can set this up.
91. License
The InterFormNG2 and Spool2XML functions, that you can execute via an IBM i command line can only be executed, if a valid license code can be found. A valid license code can be registered in 3 places: As a system license code in InterFormNG2, a tenant license code in InterFormNG2 and also via this option.
92. Change NG2 installation
As default the service jobs for both Spool2XML as well as for InterFormNG2 (to run it natively) are started as a part of the subsystem, IFORMNG2/IFORMNG2. With this option you can decide to only start one or the other of these servers.

1. Work with monitored output queues

Select option 1. Work with monitored output queues on the IFORMNG2/IFORMNG menu to work with the output queues, that are monitored by IFormNG2 for new XML Spooled Files:

          Work with Monitored Output Queues                         NGQ300D

 Type options, press Enter.
   1=Start monitoring   2=Change   3=Copy   4=Delete   5=Display
   9=End monitoring     12=Work with output queue

 Opt  Queue       Library     Description
      IFORMNG2    QUSRSYS     Default output queue for InterForm NG
      MONITOR     QUSRSYS     

                                                                           End

 F3=Exit   F5=Refresh   F6=Create   F11=View 2   F12=Cancel

For each output queue listed you can enable or disable the monitor by selecting option ‘1=Start monitoring’ or ‘9=End monitoring’. This starts and stops a job in the IFORMNG2 subsystem.

If you want to add a new monitored output queue, you will first need to create the output queue yourself (CRTOUTQ) and then add it here with F6=Create. The create screen looks like this:

           Create Monitored Output Queue                              NGQ310D

 Monitored output queue  . . . :   INPUTQ
   Library  . . . . . . . . . . :   QUSRSYS

 Description  . . . . . . . . . :   My Monitored output queue

 Default output queue . . . . . :   OUT_OUTQ
   Library  . . . . . . . . . . :   QUSRSYS

 Create fragments  . . . . . . :   
                                    Blank = Use definition setting
                                    0 = Ignore fragment processing
                                    1 = Single fragments file
                                    2 = Multiple fragment files

 Code page  . . . . . . . . . . :   
                                    Blank = System value (QCHRID)

 Move, keep, hold or delete processed spooled files:
 Output queue . . . . . . . . . :   *KEEP        Name, *KEEP, *HOLD, *DELETE
   Library  . . . . . . . . . . :   
                                                                        More...
 F3=Exit   F12=Cancel

           Create Monitored Output Queue                              NGQ310D


 Auto start job . . . . . . :   Y              Y=Yes, N=No

 Exit program . . . . . . . :   XML_INBOX      Name, *NONE
   Library  . . . . . . . . :   IFORMNG

                                                                           End
 F3=Exit   F12=Cancel

The fields are these:

Monitored output queue

The output queue where the XML spooled file(s) are expected to arrive. You need to create the output queue yourself (CRTOUTQ) before you can add it here.

Description

Description of this output queue

Default output queue

The output queue where InterFormNG will print the merged result. You can use the exit program below to override this and let e.g. the workflow of InterFormNG decide what should happen.

This output queue is also inserted in the output XML file, so that the workflow in InterFormNG can react accordingly.

Create fragments

With this you decide if the single original spooled file should be split up into several XML files e.g. if several documents (e.g. invoices) are included. This can either refer to the XML definition for the specific spooled file or overrule this to let the output queue decide the output. By setting the field here you can let the output queue decide what to do. On runtime you can e.g. override (or temporarily change) the printer file depending on what should happen. Please notice, that there is an additional fragment value possible on the conversion definition (printer file).

Code page

The EBCDIC code page used for the incoming spooled files.

Move, keep, hold or delete..

This tells Spool2XML what to do with the incoming XML files after they have been handled by the output queue monitor. If you want to move the spooled files, then you state the output queue here.

Auto start job

Tells if you want to start monitoring this output queue when then IFORMNG2 subsystem is started. Normally this should be ‘Y’.

It is recommended to ensure, that the IFORMNG2/IFORMNG2 subsystem is started automatically during IPL. Such an automatic start should be inserted as one of the last commands in the program referenced in the system value, QSTRUPPGM. At best a MONMSG CPF0000 should also be added after the start of this subsystem. Please refer to your system administrator or InterForm support for more details.

Exit program

Normally Spool2XML will create a merged spooled file on an output queue set above. You can however override this by stating an exit program. Demo sources for such programs are included in the source file, APISRC in the IFORMNG library. The related sources are these:

Source	Purpose
XML_INBOX	Moves the XML file into the XML_INBOX for automatic processing in InterFormNG2
XML_NG2CMD	Calls an AS400 command input workflow via the command, NG2CMD. This can be used in order to make sure, that spooled file as are processed in the right sequence. You need to compile this in your own library to use it. Please notice the prerequisites listed in the program source.
XMLEXIT	Demo source - use as inspiration but not for production.

So if you e.g. set the exit program to be XML_INBOX in library IFORMNG2, then you can define all processing in InterFormNG2 e.g. in the workflow. This makes it easier, if you e.g. want to email or create PDF files.

It is a very good idea to copy the demo source to another library (never place any additional objects in the IFORMNG2 library as they will stay in the old library after a future upgrade of InterFormNG2), make any necessary changes in the copy and compile it into your own library.

2. Work with XML definitions

The XML definitions can be created in two manners:

Via the command: IFORMNG/CVTPRTFXML. This command creates a new (XML) printer file on the basis of the original printer file and sets an output queue for the new printer file.
This output queue should be a monitored output queue. This command is described here:
Via F6=Create on the 2. Work with XML definitions menu as shown below. This is normally NOT how an XML definition should be created. In short an XML definition is the ‘recipe’ of how the XML spooled file is to be converted into real XML file(s) and which InterFormNG template, that is used for the final merge(s) as well as on which output queue the final, merged spooled file is to be created.

This section e,g, covers:

The record format fragment option.
The unique record format option to delete duplicate record formats.
The fields including key fields, Top fields, delete fields and key field error messages.
Configuration of parent/child relationships.
Overview of all parent/child relationships.

This menu option gets to this screen:

             Work with XML Definitions                                  XDF300D

 Position to . . . . . . . . . . . . . . . . :   Printer file

 Type options, press Enter.
   2=Change   3=Copy   4=Delete   5=Display   12=Record formats
   14=Parent child relationship   15=Display keys   17=Export

 Opt  File        Library       Description
 _    AM64MRP1    IFORMDEV      CVTPRTFXML
      NG401PR     EXPORTID:1    CVTPRTFXML
      NG401PR     EXPORTID:2    CVTPRTFXML
      NG401PR     EXPORT0001    CVTPRTFXML
      NG401PR     KSE_HIGH      CVTPRTFXML
      NG401PR     KSE_HIGH¤     CVTPRTFXML
      NG401PR     PRODNY        CVTPRTFXML
      NG401PR     VERSION 2.    CVTPRTFXML
                                                                           End
 F3=Exit   F5=Refresh   F6=Create   F8=Import   F11=View 2   F12=Cancel

When you create or edit a new XML definition this screen is shown:

               Change XML Definition                                  XDF310D

 Printer file . . . . . . . :   AM64MRP1
   Library  . . . . . . . . :   IFORMDEV          Name, *ALL

 Reference printer file . . :   AM64MRP1
   Reference library  . . . :   AMALIBB

 Description  . . . . . . . :   CVTPRTFXML

 Template . . . . . . . . . :   

 Create fragments . . . . . :   3              0 = Ignore fragment processing
                                               1 = Single fragments file
                                               2 = Multiple fragment files
                                               3 = Treebuilder
 Output queue . . . . . . . :   
   Library  . . . . . . . . :   

 Optimize xml-output  . . . :   0              0 = No   1 = Yes

 F3=Exit   F12=Cancel

The fields are these:

Printer File
The printer file, that this XML definition is linked to/used for.
Library
The library of the printer file. State *ALL if the XML definition should be used for all printer files with this name above - independent of the library in which it is placed. (It can be that you have multiple, identical printer files in various libraries).
Reference Printer file and library
The original printer file from which the printer file above was created (with the CVTPRTFXML command). This information can be used if you would want to disable IFormNG2/400 and use the original printer file again.
Description
A description of the XML definition. If the definition has been created by the CVTPRTFXML command, then the description will be set to CVTPRTFXML.
Template
The InterFormNG template (form) to be used when the XML file will merged (and printed) in InterFormNG2.
Optimize xml-output
If you set this to 1, then redundant information in the XML file (e.g. comments) will be remove and cause smaller XML files and improved performance.
Create fragments
Select if a level break of any defined key field(s) should trigger a new fragment or XML file as input for InterFormNG2. The possibles values are:
0=Ignore fragment processing
Any defined fragment setting are ignored. The complete XML file is generated.
1=Single fragments file
This option runs like 2 below except that contents of all the files are placed in a single xml file with a common header that specifies the identification of the job, spooled file etc. as IFormNG always generates. This value can e.g. be used to verify the structure of the output without the risk of generating a lot of (wrong?) XML files before changing into 2 as below.
2=Multiple fragment files
This splits up the result into multiple files depending on the level break (or change) of the key fields in the record format marked for fragmenting. Please notice, that any record formats, that are not marked as parent or child for the fragmented format will NOT be included in the result when using either 1=Single fragments file or 2=Multiple fragment files - which could e.g. be the case of a front page of the original spooled file. If you want such record formats to be included you will need to select 0=Ignore fragment processing above.
3=Treebuilder
With this option you can build the XML tree of the output XML file in a totally different manner than for the other options. With this you specify a tree structure with a special Top node with a Top key field. With this you can eliminate any duplicates in the XML files and build a more efficient and compact XML file. Some prerequisites does apply.
Output queue
The output queue (and library) where the final print out (generated from InterFormNG2) will be generated - unless it is overridden in the definition of the monitored output queue.

For the XML definitions these options are possible:

12=Record formats

With this option you can see a list of the formats defined in the specific printer file:

                Work with Record Formats                                 XDR300D

 Printer file  . . . . :   AM64MRP1
 Library . . . . . . . :   IFORMDEV

 Type options, press Enter.
   2=Change   5=Display   12=Fields   14=Children

 Opt   Seq  Format      Description                                Frg  Unq
       1    P64M1010
       2    P64M1035
       3    P64M1040
       4    P64M1120
       5    P64M1130
       6    P64M1140
       7    P64M1HD1
       8    P64M1HD2
       9    P64M1170
      10    P64M1180
      11    P64M1190
      12    P64M1200
                                                                        More...
 F3=Exit   F5=Refresh   F12=Cancel

Record format fragment option

Each record format can be set to be either fragmented - indicated with a 'Y' in the Frg column or to be Unique (Ung). The unique option means, that only the first occurrence of a record format should appear in the output XML file, so you can use this to eliminate duplicates.

This is set via 2=Change on a record format above:

                 Change Record Format                                 XDR310D

 Printer file . . . . . . :   AM64MRP1
 Library  . . . . . . . . :   IFORMDEV

 Sequence . . . . . . . . :       8
 Record format  . . . . . :   P64M1HD2

 Description  . . . . . . :   

 Fragment level . . . . . :   Y   Y=Yes, N=No

 Format is unique . . . . :   Y   Y=Yes, N=No

 F3=Exit   F12=Cancel

The fragment flag is used by the fragment options 0,1 and 2. It is ignored for fragment option 3.

It should normally be used with a key field.

Record format unique option

On the record formats inside the XML definitions you can with option 2=Change set a unique option on the record formats. This can be used for deleting duplicates of the record format in the XML. This option simply only keeps the first occurrence of the record format in the input spooled file, if activated. You activate it here:

                 Change Record Format                                 XDR310D

 Printer file . . . . . . :   AM64MRP1
 Library  . . . . . . . . :   IFORMDEV

 Sequence . . . . . . . . :       8
 Record format  . . . . . :   P64M1HD2

 Description  . . . . . . :   

 Fragment level . . . . . :   Y   Y=Yes, N=No

 Format is unique . . . . :   Y   Y=Yes, N=No

 F3=Exit   F12=Cancel

The unique option works for all fragment options.

12=Fields

For each format you can use option 12=Fields to view the list of fields for the specific format.

For each field you can even set these options:

                   Work with Fields                                    XDS300D

 Printer file  . . . . :   AM64MRP1
 Library . . . . . . . :   IFORMDEV
 Record format . . . . :   P64M1HD2

 Type options, press Enter.
   X=Key   D=Delete   T=Top   blank=Not a key field

 Key   Seq  Field name  Description
        1   *IN68
        2   *IN08
        3   *IN26
        4   *IN39
        5   *IN60
        6   *IN84
  T     7   ORDNO
        8   REVNB
        9   SCDE1R
       10   VNAME1
       11   MNAME
                                                                        More...
 F3=Exit   F5=Refresh   F12=Cancel

X=Key

For fragment 0,1 and 2 only. The field is set to be a key field for fragmentation (Fragment 1 or 2 only). If one of the key fields changes in the output, then this is considered a potential ‘level break’. So depending on the fragment setting of the XML definition, then a change of value for any of these fields may trigger a new XML file as output. If no keys are marked for a record format, which is set to trigger fragments, then a ‘level break’ will be triggered each time the format is written.

If you select field to be a key, then the record format must have the fragment option activate. If you do not activate the fragment option for the record format, then you will see this error in the joblog of the monitor job and as a message in the QSYSOPR message queue:

                 Additional Message Information                

 Message ID . . . . . . :   NGE5012       Severity . . . . . . . :   00
 Message type . . . . . :   Diagnostic
 Date sent  . . . . . . :   02/04/20      Time sent  . . . . . . :   16:25:18

 Message . . . . :   Key field ORDNO at format P64M1HD2 found outside fragment.
                    Value '' not allowed outside a fragment.

- followed by this message:

  Additional Message Information                

 Message ID . . . . . . :   NGE5005       Severity . . . . . . . :   00
 Message type . . . . . :   Diagnostic
 Date sent  . . . . . . :   02/04/20      Time sent  . . . . . . :   16:25:18

 Message . . . . :   Error converting spooled file AM64MRP1 to XML.
                    Error processing spooled file AM64MRP1 spooled file number 4
                    from job 220598/VICB/AMA0090864.
                    See previous message in the *QSYSOPR message queue
                    for more information.

In case of these errors no XML file will be generated and processing of the XML spooled file will stop i.e. any spooled file action setup on the monitor job is not executed.

D=Delete

For fragmentation=3 only: This deletes/removes the field from the output XML file. Use this to reduce the size of the output XML e.g. for increased performance and to make the design process easier as the user will not need to scroll past a lot of fields, that really is not needed.

T=Top

For fragmentation=3 only: This indicates, that the record format should be used as the Top node i.e. that this should be used for collecting duplicates. Any record formats with the same value for the Top key is merged into one.

Setup parent/child relationships in XML

You can also use option 14=Children to set how the XML file is to be structured i.e. if one format should be a subtree (or child) to another in the output XML file. Use this option to set the child formats for this

record format:

In this case the P64M1200 format is set to be a child of the P64M1HD2 format:

  Work with Child Record Formats                          XDC300D

 Printer file  . . . . :   AM64MRP1
 Library . . . . . . . :   IFORMDEV
 Record format . . . . :   P64M1HD2

 Type options, press Enter.
   X=Child   1=Single child   blank=Not a child format

 Child  Seq  Format      Description
        1    P64M1010
        2    P64M1035
        3    P64M1040
        4    P64M1120
        5    P64M1130
        6    P64M1140
        7    P64M1HD1
        9    P64M1170
       10    P64M1180
       11    P64M1190
   X   12    P64M1200
                                                                        More...
 F3=Exit   F5=Refresh   F12=Cancel

X=Child

This indicates, that the selected record format is be inserted as a child of the current record format.

1=Single child

This option is only supported for the fragment option 3=Treebuilder. The selected record format can only appear as a single child of the current node. Any subsequent child record formats will cause a new instance of the parents in the output XML file for the subsequent children.

14=Display parent child relationship

This option displays the parent-child relationships in the XML definition, that have been setup via option 12=Record formats followed by option 14=Children.

Here is an example:

           Display Parent Child Relationship                          XDC360D

 Printer file  . . . . :   AM64MRP1
 Library . . . . . . . :   IFORMDEV

 Position to . . . . . . . . . . . . . . :   Record format

 Parent      Child       0903 Description
 P64M1HD1    P64M1HD2    X
 P64M1HD2    P64M1200    X
 P64M1200    P64M1210    X
 P64M1200    P64M1240    1
 P64M1200    P64M1340    X
 P64M1200    P64M1420    X
 P64M1210    P64M1220    X
 P64M1220    P64M1230    X
 P64M1240    P64M1420    X
 P64M1340    P64M1420    X
 P64M1420    P64M1430    X
                                                                           End
 F3=Exit   F5=Refresh   F8=Import   F12=Cancel

The third column indicates if the child record format is a potential multiple child (X) or a single child (1).

15=Display keys

With this option for an XML definition you can view which fields, that are selected to be a key (Selected with an X when working with fields on the XML definition).

5. Work with IFORMNG2 output queue

This option displays the contents of the QUSRSYS/IFORMNG2 output queue. The command WRKOUTQ QUSRSYS/IFORMNG2 is behind this option- unless InterForm400 is installed on the same machine, then the command APF3812/APFWRKOUTQ is used - with additional functionality compared to WRKOUTQ.

This can e.g. be used for verifying if InterFormNG has actually created a merged spooled file when testing.

10. Start IFORMNG2 subsystem

This options starts the IFORMNG2/IFORMNG2 subsystem - like the command STRSBS IFORMNG2/IFORMNG2. To be sure that the subsystem is started after an IPL i it may be a good idea to include a start of this subsystem as a part of the IPL startup program. If you do so it is (as normal) recommended to include a MONMSG CPF0000 immediately after this command.

12. Work with IFORMNG2 subsystem

Choose this option to work with the IFORMNG2 subsystem e.g. to check the status or joblog of the IFORMNG jobs:

                       Work with Active Jobs                              PMK250
                                                            30/03/20  22:52:06

 CPU %:     0.0     Elapsed time:   00:00:00     Active jobs:   260

                         Current

 Opt  Subsystem/Job  User        Type  CPU %  Function          Status
      IFORMNG2       QSYS        SBS     0.0                    DEQW
        IFORMNG2     IFORMNG2    BCH     0.0  PGM-NGQ500C       DEQW
        MONITOR      IFORMNG2    BCH     0.0  PGM-NGQ500C       DEQW
        QP0ZSPWP     IFORMNG2    BCI     0.0  PGM-QZSHCHLD      EVTW
        QP0ZSPWP     IFORMNG2    BCI     0.3  JVM-InterformN    THDW
        QZSHSH       IFORMNG2    BCI     0.0  PGM-QZSHSH        EVTW

                                                                         Bottom
 ===>
 F21=Display instructions/keys

Apart from other jobs there are one job for each monitored output queue. The output queues IFORMNG2 and MONITOR are monitored above.

31. Display print service log

Select this option to display the service log of InterFormNG2. Here you can see the log of the merges between the generated XML files and the templates and verify if any errors should have occurred during these merges.

The service log looks like this:

************ Beginning of data ************

2021-04-22 12:21:10.056  INFO 237348 --- [http-nio-8086-exec-8] c.interform400.joblog.JobLoggerFactory   : New log child with id 1d8
2021-04-22 12:21:10.106  INFO 237348 --- [http-nio-8086-exec-8] c.interform400.joblog.JobLoggerFactory   : Workflow null used
2021-04-22 12:21:10.107  INFO 237348 --- [http-nio-8086-exec-8] c.interform400.commandLineTools.CallNG2  : Recieved data at EMAIL
2021-04-22 12:21:10.115  INFO 237348 --- [http-nio-8086-exec-8] c.interform400.commandLineTools.CallNG2  : Mime-type detected to :ap
2021-04-22 12:21:10.117  INFO 237348 --- [http-nio-8086-exec-8] c.interform400.commandLineTools.CallNG2  : Mime-type detected to :ap
2021-04-22 12:21:10.168  INFO 237348 --- [http-nio-8086-exec-8] c.interform400.commandLineTools.CallNG2  : Setting body 21411
2021-04-22 12:21:10.196  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : Debug message headers:
2021-04-22 12:21:10.196  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : interform.input.spooled.p
2021-04-22 12:21:10.196  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : email.subject==This is my
2021-04-22 12:21:10.196  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : interform.input.spooled.d
2021-04-22 12:21:10.196  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : interform.input.spooled.t
2021-04-22 12:21:10.196  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : interform.input.spooled.u
2021-04-22 12:21:10.196  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : interform.input.spooled.s
2021-04-22 12:21:10.197  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : interformng.internalxml==
2021-04-22 12:21:10.197  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : interform.input.spooled.c
2021-04-22 12:21:10.197  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : NG2.TENANTID==home
2021-04-22 12:21:10.197  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : email.to==customremail@gm
2021-04-22 12:21:10.197  INFO 237348 --- [http-nio-8086-exec-8] com.interform400.DebugProcessorNG        : interform.input.spooled.c

---------------------------------------------------------------

F3=Exit   F10=Display Hex   F12=Cancel   F15=Services   
F16=Repeat find   F19=Left   F20=Right

The log displayed is this stream file in the IFS: /iformng2/InterFormNG-shell/user/profiles/default/logs/interformng2.log

You can also see the same log as the system log file in InterFormNG2 via the web interface.

91. License

The Spool2XML and InterFormNG2 commands: CVTPRTFXML, NG2CMD and NG2CPDEML commands all require a valid license. The fastest way for these commands to check for a valid license is via a license code, that is registered via option 91. License on the IFORMNG2 menu, but if InterFormNG2 is also running on the same machine, then the commands can also use the InterFormNG2 license instead.

If you run Spool2XML on a separate machine than InterFormNG2, then you will actually need to register a license key via this option.

When you select this menu option you will see this:

               Work with InterFormNG License Code(s)

 License is validated on system with:

   Serial no . . . . . . . . . :   785F48X
   Processor feature . . . . . :   EPXK

 Primary License:

   Expiry date  . . . . . . . :   20300101
   License type . . . . . . . :   00 (00=*ALL , 01=*XML , 02=*SPLF)
   License code . . . . . . . :   35C27E9EE3CXX615B931861F890F921D
   License status . . . . . . :   License Valid

 Secondary License:

   Expiry date  . . . . . . . :   *BLANKS
   License type . . . . . . . :        (00=*ALL , 01=*XML , 02=*SPLF)
   License code . . . . . . . :
   License status . . . . . . :   License not found

 NG2 Hosted License Found:

   License for XML  . . . . . :   License Valid
   License for SPLF . . . . . :   License Valid

 F3=Exit         F12=Cancel

The license screen refers to 3 licenses, where the first two can be entered via the screen above.

Either of the primary and the secondary license can be used. There are two for those customers, that is running Spool2XML (and/or InterFormNG2) on a mirrored machine. So you can enter the license code to match both of the machines and in this way Spool2XML does not care (in regards to the license) on which of the mirrored machine that you are currently running.

The entry fields

The entry fields on the license menu are:

Expiry date

The date when the license key runs out. You need to type a date, that match the license code, that you have been given.

License type

What functionality, that is included in the license. You need to type the right value specified with the license code. The possible values are:

00=*ALL	You can use the product for both spooled file and XML files as created via Spool2XML.
01=*XML	Only the XML funtionality of Spool2XML can be used, but spooled file support in InterFormNG2 is not included.
02=*SPLF	Only the spooled file funtionality can be used, but XML support (Spool2XML) in InterFormNG2 is not included.

License code

The license code for the functionality above.

The output fields

The output fields on the license menu are:

Serial number

The serial number of the IBM i on which this menu is running.

Processor feature

The processor feature code (DSPSYSVAL QPRCFEAT) of the IBM i on which this menu is running.

License status

The validity of the license code.

NG2 hosted License found

This section shows if it has been possible to get a valid license from InterFormNG2 on the same machine.

The two fields are:

License for XML

Here you can see, if InterFormNG2 contains a valid license code, that allows XML support on the commands above. If a valid license has been found, then you will see the text as above: License Valid. If the IFORMNG2 subsystem is not running (so that InterFormNG2 cannot reply) then you will see the text: License check timeout. In case of a timeout you probably have not started the IFORMNG2 subsystem. If you start it, then this output field will show the result to indicate what license you have in InterFormNG2.

License for SPLF

Here you can see if InterFormNG2 has replied and confirmed, that you have a valid license to work with spooled files in InterFormNG2.Details are the same as for License for XML above.

92. Change NG2 installation

You can decide what service jobs to start when the IFORMNG2&IFORMNG2 subsystem is started, if you here select option 92. Change NG2 installation from the IFORMNG2 main menu:

              Configure IFORMNG2 Startup (NG2SETUP)

 Type choices, press Enter.

 IBM I Queue Monitor  . . . . . . :   *ACTIVE       *ACTIVE, *INACTIVE
 NG2-Server (Output generator)  . :   *ACTIVE       *ACTIVE, *INACTIVE
 CommandLine to NG2 . . . . . . . :   *ACTIVE       *ACTIVE, *INACTIVE, *SAME
 QIBM_QSH_CMD_OUTPUT - *JOB . . . :   NONE

 JAVA_HOME (Blank = System default) :   '/QOpenSys/QIBM/ProdData/JavaVM/jdk17/64bit'

 JVM_MEMORY . . . . . . . . . . . :   '-Xms2g -Xmn1g -Xmx3g'

 Use jt400Native.jar  . . . . . . :   '-Dloader.path=/QIBM/ProdData/OS400/jt400/lib/jt400Native.jar'

 JVM custom options . . . . . . . :   ' '

                                                                         Bottom

 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display
 F24=More keys

If you want to use the Spool2XML module to convert spooled files into XML via converted printer files, then you should keep the first option, IBM I Queue Monitor active, but if you simply want InterFormNG2 to monitor output queues itself, then you should set this to *INACTIVE.

In the described setup you want to run the NG2 Server on another platform, so here you would probably set the second option, NG2-Server (Output generator) to *INACTIVE.

If you want to execute the IFORMNG2/NG2CMD command in your CL-programs, then you need to set the option CommandLine to NG2 to *ACTIVE.

The active/inactive settings really does not matter, if you do not start the IFORMNG2/IFORMNG2 subsystem at all, as no services can start unless the subsystem is running.

With QIBM_QSH_CMD_OUTPUT - *JOB you can set an output stream file for the java log if needed.

The rest of the options are related to the Java settings:

Java_Home

This sets the path to the JVM, that InterFormNG2 is to use. Please notice, that Java 8 64bit is required.

JVM_MEMORY

Memory settings for the Java part of InterFormNG2.

Use jt400Native.jar

Identifies which jar file to use.

JVM custom options

Here you can setup various JVM options for InterFormNG2. One example is the default file encoding, which with V7R4 has changed from Latin 1 into UTF8 as described here: https://www.ibm.com/docs/en/i/7.4?topic=jc-default-java-fileencoding-default-charset-changed-utf-8. InterFormNG2 is default using UTF-8, so normal InterFormNG2 customers will not be affected by this. With this option you can however e.g. overrule the UTF-8 encoding into e.g. Latin 1, if you set this option to -Dfile.encoding=ISO8859_1.

The CVTPRTFXML Command

The IFORMNG/CVTPRTFXML command is essential in Spool2XML as this command is able to generate an new printer file (that generates a special XML spooled file) based on a normal printer file.

The XML spooled file will contain a subtree for each record format and each field inside the record format will be represented by a node in this subtree. Any constants in the printer file will be ignored.

The new XML printer file will for the printing program look EXACTLY as the original so no level check error will be issued when putting this into production.

The command looks like this:

             Convert Printer File to XML (CVTPRTFXML)

 Type choices, press Enter.

 From file  . . . . . . . . . . . FROMFILE     > NG402PR         Name
   Library  . . . . . . . . . . .              > KSE             Name, *LIBL

 To file  . . . . . . . . . . . . TOFILE       > NG402PR         Name, *FROMFILE
   Library  . . . . . . . . . . .              > KSE_HIGH        Name

 Printer file output queue  . . . OUTQ           *JOB            Name, *JOB
   Library  . . . . . . . . . . .                               Name, *LIBL

 Include comments . . . . . . . . INCCOMMENT     *YES            *YES, *NO

 New page format(s) . . . . . . . NEWPAGFMT      *AUTO           Name, *AUTO, *FIRST, *ALL
                                             + for more values

 Reuse XML-definition file  . . . REFFILE       
   Library  . . . . . . . . . . .               

                                                                         Bottom
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display
 F24=More keys

The fields are these:

FROMFILE

The original printer file, that should be converted.

TOFILE

The name (and library) of the new XML printer file, that is the result of the conversion. You should specify the same name for the printer as the from file above - but use a different library. It is recommended to place the new printer file in another library than the original, so that you can later select between the original and the converted printer file by changing the library list for the relevant job.

OUTQ

The output queue of the new XML printer file. As default this will be *JOB. After the conversion the new XML printer file has been created and a new XML definition is

also added. You can now edit the preferences for the conversion into XML in the XML definition.

INCOMMENT

Here you can state if the comments from the printer file should also be included in the output XML spooled file.

REFFILE

If you are going to convert a printer file, that is very similar to a printer file, that has previously been converted (and has been setup with e.g. parent/child definitions), then you can here refer to the existing, converted printer file, that is registered as an XML definition in option 2 of the IFORMNG2/IFORMNG2 menu. If you refer to such a printer file, then all definitions are copied for the matching printer file formats and fields. In this way you can reuse as much of the old definitions as possible.

The fragment options

The fragment option in Spool2XML defines how the XML spooled file is to be converted into an XML file.

With the fragment options you can remove and/or merge multiple nodes and you can also split up the XML spooled file into multiple output XML files.

In Spool2XML you have these fragment options:

0=Ignore fragment processing
1=Single fragments file
2=Multiple fragment files
3=Treebuilder

The fragment can be activated/set on both the XML definitions and on the monitored output queues.

The options above can be set on the XML definition and on the monitored output queues you can choose these fragment options:

Blank=Use definition setting

0=Ignore fragment processing

1=Single fragments file

2=Multiple fragment files

So it means, that with the first (default), blank setting the setting on the XML definition will be used. For the other options you can overrule the settings of the XML definition. In this way you can make Spool2XML behave differently (when it comes to fragmentation) depending on the monitored output queue in which the spooled file is found.

You can only activate the 3=Treebuilder option on the XML definition.

The reason for this is, that the Treebuilder option is incompatible with the other fragment options, so on the XML definition you need to decide, if it is to be used with the treebuilder option or not.

The fragment options are covered in the sections below.

0=Ignore fragment processing

This one of the 4 options, that you can set for fragment processing in Spool2XML.The value selected affects the output XML file generated from the standard XML spooled file.

With the value 0=Ignore fragment processing the output XML file is the the same as the input XML file with these things in mind:

Even though fragment is not activated you should still take care not to define a field to be key-field unless fragment is activated om the record format containing the field. If you do, then you will see an error.
As you notice some header record formats of the printer file may be repeated a lot of times, and that is also the case in the output XML file.
The key options D=Delete and T=Top are only supported for 3=Treebuilder - it is ignored for 0=Ignore fragment processing.
The parent/child option on record formats: 1=Single child is only supported for 3=Treeebuilder, and is ignored for 0=Ignore fragment processing.
If you want to reduce the size of the output XML file you can either activate the unique option on some record formats or consider even the fragment option 3=Treebuilder.
You can also consider to move to 1=Single fragments file to reduce the size of the XML file a bit.
It is possible to split up the output XML file into multiple XML files with 2=Multiple fragment files.

1=Single fragments file

This one of the 4 options, that you can set for fragment processing in Spool2XML.The value selected affects the output XML file generated from the standard XML spooled file.

With the value 1=Single fragments file the output XML file is the the same as the input XML file with these things in mind:

You should take care not to define a field to be key-field unless fragment is activated om the record format containing the field. If you do, then you will see an error.
You need to define a record format to have the fragment option activated, and inside of that record format a field must be selected as a key field, if that is not defined, then only the jobinformation XML subtree is included in the output XML file.
The size of the output XML file is reduced in size compared to 0=Ignore fragment processing.
There is only one XML node for the fragment record format with each unique value of the key field. The other fields (for all duplicates of the fragment record format), and other record formats are inserted inside the fragment node in the XML file. If a record format is defined as being parent, then it will however be a parent of the fragment record format.
The key options D=Delete and T=Top are only supported for 3=Treebuilder - it is ignored for 1=Single fragments file.
The parent/child option on record formats: 1=Single child is only supported for 3=Treeebuilder, and is ignored for1=Single fragments file.
If you want to reduce the size of the output XML file you can either activate the unique option on some record formats or consider even the fragment option 3=Treebuilder.
It is possible to split up the output XML file into multiple XML files with 2=Multiple fragment files.

2=Multiple fragment files

This one of the 4 options, that you can set for fragment processing in Spool2XML.The value selected affects the output XML file generated from the standard XML spooled file.

With the value 2=Multiple fragment files the output XML file can be split up into multiple XML files each contain a fragment of the output:

You should take care not to define a field to be key-field unless fragment is activated om the record format containing the field. If you do, then you will see an error.
You need to define a record format to have the fragment option activated, and inside of that record format a field must be selected as a key field, if that is not defined, then no XML output is generated.
Multiple output XML files may be created: One for each unique value of the key field.
There is only one XML node for the fragment record format with each unique value of the key field. The other fields (for all duplicates of the fragment record format), and other record formats are inserted inside the fragment node in the XML file. If a record format is defined as being parent, then it will however be a parent of the fragment record format. The other record formats are included based on how they appear in the XML spooled file: Any record format after the fragment record is included in the current file until the next unique key field is found.
The key options D=Delete and T=Top are only supported for 3=Treebuilder - it is ignored for 1=Single fragments file and 2=Multiple fragment files.
The parent/child option on record formats: 1=Single child is only supported for 3=Treeebuilder, and is ignored for 1=Single fragments file and 2=Multiple fragment files.
If you want to reduce the size of the output XML file you can either activate the unique option on some record formats or consider even the fragment option 3=Treebuilder.

3=Treebuilder

This one of the 4 options, that you can set for fragment processing in Spool2XML.The value selected affects the output XML file generated from the standard XML spooled file.

With the value 3=Treebuilder the output XML file can be created as the most compact output XML file:

The fragment option on record formats is ignored. The key-field option (value X) is ignored. A fragment/Tree record format and Tree key is defined by setting a field to be T=Top.
Only record formats, that are related (as either parent or child) to the Top-tree record format are included in the final XML file.
Children, that are listed prior to the first occurrence of the Top-record format are not included in the final output.
Children are always matched with the previous parent(s). The last found parent in the spooled file will be used.
Top nodes/record formats are only included as one for each unique value of the Top-key field.
The key options D=Delete and T=Top are only supported for 3=Treebuilder. Use D=Delete to delete a field from the output XML file.
he parent/child option on record formats: 1=Single child is only supported for 3=Treeebuilder, which will cause an extra set of parents for each instance of the child - to keep it a single child.

The IFORMNG2 objects

Apart from the IFORMNG library the application also use these objects:

The IFORMNG2 user profile

An IFORMNG2 Printer device in QUSRSYS.

The IFORMNG2 directory in the IFS containing the directories below:

The directory /IFORMNG2/InterFormNG-shell. This contains the InterFormNG2 installation.

The directory /IFORMNG2/temp. This contains all XML files, that have been created by IFORMNG.

Putting Spool2XML into Production

Before you put IFormNG/400 into production you should verify that the your application is using external printer files and that is it possible to force the application to print to another printer file (the special XML printer file created by the CVTPRTFXML command).

Forcing the application to print to another printer file can be done in these ways:

If the application is selecting the printer file via the library list you could name the XML printer file the same as the original and place it a library, that is higher in the library list of the printing job.
If possible you can change an override in the application to point to the new XML printer file.
You can move or rename the original printer file and let the new XML file be named exact the same as the original and be placed in the same library.

In the example below we will use the first option with these steps:

Setting up a monitored output queue in IFORMNG2
Starting an output queue monitor
Converting the printer file into a new ‘XML’ printer file
Remove old spooled files and XML files

Setting up a monitored output queue in IFormNG2

If you not already are monitoring an output queue in IFormNG/400 you should add one. You first need to create it (via CRTOUTQ) and then you can add it via option ‘1. Work with monitored output queues’.

On the output queue definition in IFORMNG it is a good idea to define, that the XML files are to be moved to a directory, that is monitored by InterFormNG. As default InterFormNG2 on the IBM i will monitor the IFS directory: /iformng/InterFormNG-shell/user/xml_inbox.

It is very easy to setup the monitored output queue to move the XML files to this directory by editing the output queue definition in IFORMNG2, press <Page> <Down> and set the exit program to be XML_INBOX in the library, IFORMNG2:

               Change Monitored Output Queue                              NGQ310D


 Auto start job . . . . . . :   Y              Y=Yes, N=No

 Exit program . . . . . . . :   XML_INBOX      Name, *NONE
   Library  . . . . . . . . :   IFORMNG2

                                                                           End
 F3=Exit   F12=Cancel

Starting an output queue monitor

To enable automatic merges into XML and print the monitor for this output queue must be started. First make sure that the IFORMNG2 subsystem is started e.g. with option ‘10. Start IFORMNG2 subsystem’.

Now you can verify that a job is monitoring the output queue via option ‘12. Work with IFORMNG2 subsystem’. If a job named the same as the output queue is not running, then you can start the monitor via option ‘1. Work with monitored output queues’ followed by option ‘1=Start monitoring’.

Converting the printer file into a new ‘XML’ printer file

In this case we want to create a new ‘XML’ printer file with the same name as the original and then place it higher in the library list of the printing application to make it use the new printer file.

The conversion is done with the CVTPRTFXML command:

IFORMNG/CVTPRTFXML FROMFILE(KSE/NG402PR) TOFILE(KSE_HIGH/NG402PR) OUTQ(QUSRSYS/IFORMNG2)

The original printer file KSE/NG402PR is converted into KSE_HIGH/NG402PR and the new printer file will print to the monitored output queue, QUSRSYS/IFORMNG2.

In order to use the output queue monitor you need to set this up on the jobs, that creates the spooled files:

Change the library list of the job, so that the converted (XML) printer file is higher in the library list, so that this printer file will be used instead of the normal printer file. You can ensure, that the right printer file is used by looking at the contents of the spooled file. You should be able to see the normal XML tags <> inside.
The spooled files must be moved to or created on the monitored output queue. The spooled files also need to have status *RDY in order to be seen by the monitor, that is monitoring the output queue. The monitor will then convert the XML spooled file into an XML file.

If you want to process a spooled file twice, then you can hold and release the spooled file to add a data queue entry and make the monitor job react again.

Remove old spooled files and XML files

All merges result in new ‘XML’ spooled files on the monitored output queues and XML files in the IFS. Currently no purge/automatic clean up is included in the product, so it is the responsibility of the user to make sure that old spooled files and XML files are deleted when they are no longer needed.

The XML files are placed in the IFS in /IFORMNG2/temp - unless you have moved them by calling a exit program e.g. XML _INBOX,

The files processed in InterFormNG2 from XML_INBOX are either moved to the processed folder, in which they are deleted after 24 hours as default or the error folder in which they will remain until deleted.

Related Articles
Designer Overview
This section covers the use of the InterFormNG2 designer. For installation you should refer to Installation and upgrade. These sections cover the use of the designer: Starting the designer. Create a new template. Open an existing template in the ...
Spool2XML setup and settings on IBM i
This section covers setup and settings for Spool2XML only. For normal implementation of InterFormNG2 on the IBM i platform (without Spool2XML) you can refer to e.g. these sections: Installing InterFormNG2 on IBM i and Start/stop InterFormNG2 on the ...
Spool2XML
One of the InterFormNG2 modules is spool2XML. When it comes to spooled file support in InterFormNG2 you have two options: You can use the spool2XML module to convert input spooled files into XML files, that are placed in the IFS, where InterFormNG2 ...
Spool2XML troubleshooting
This section covers some of the issues, that you might see when you start to use the Spool2XML module. InterFormNG2 does not react to a ready spooled file. The monitor job stops with the error message: LIC0001 License code issue. The output queue ...
Workflow groups
It is possible to assign a group name to a workflow. You can do that either when you create a new workflow, or by editing the header of an existing workflow. You see the group name of the workflows in the workflow overview: Here you can click the ...

The IFormNG2 menu overview

The IFormNG2 menu overview

12=Record formats

Record format fragment option

Record format unique option

12=Fields

Setup parent/child relationships in XML

14=Display parent child relationship

15=Display keys

The entry fields

The output fields

The CVTPRTFXML Command

The fragment options

0=Ignore fragment processing

1=Single fragments file

2=Multiple fragment files

3=Treebuilder

The IFORMNG2 objects

Putting Spool2XML into Production

Setting up a monitored output queue in IFormNG2

Starting an output queue monitor

Converting the printer file into a new ‘XML’ printer file

Remove old spooled files and XML files

Related Articles

Designer Overview

Spool2XML setup and settings on IBM i

Spool2XML

Spool2XML troubleshooting

Workflow groups