Troubleshooting AS400 specifics - InterFormNG2 Manual

Troubleshooting AS400 specifics

This section covers issues, that can be met in regards to the IBM i platform (AS400 iSeries). Non IBM i related troubleshooting is found in the section, Troubleshooting.

 

The issues covered are:

Problem when loading a spooled file
This section can help you if you see this error in the log while loading a spooled file:
com/ibm/as400/data/ProgramCallDocument.setTimeOut(I)V in file /QIBM/ProdData/OS400/jt400/lib/jt400Native.jar.

If you see this error message, then you are using an older AS400 with a jt400Native.jar file that should be updated. You can solve the problem in these ways:
  1. Recommended: You can upgrade your Java to the latest version by installing the latest OS400 PTFs (cumulative package).
  2. You can also remove the reference to the jt400Native.jar file in the stream file (in the IFS) as covered here.
The NG2SERVER job does not start in the IFORMNG2 subsystem
The NG2SERVER job needs to run in the IFORMNG2 subsystem if you want to run InterFormNG2 on the AS400/iSeries/IBM i platform. If this job does not start with the subsystem, then you should run the command:
IFORMNG2/IFORMNG2
and here select option 92: Change NG2 installation.
                     Configure IFORMNG2 Startup (NG2SETUP)                     

                                                                                
 Type choices, press Enter.                                                     
                                                                                
 IBM I Queue Monitor  . . . . . . > *ACTIVE       *ACTIVE, *INACTIVE, *SAME     
 NG2-Server (Output generator)  . > *ACTIVE       *ACTIVE, *INACTIVE, *SAME     
 CommandLine to NG2 . . . . . . . > *ACTIVE       *ACTIVE, *INACTIVE, *SAME     
 QIBM_QSH_CMD_OUTPUT - *JOB . . . > NONE                                        
                                                                                
 JAVA_HOME Blank=System default   > '/QOpenSys/QIBM/ProdData/JavaVM/jdk17/64bit'

On the screen above, you can verify two things:
  1. The value for the line:
    NG2-Server (Output generator) must be *ACTIVE.
    This indicates that the InterFormNG2 server will be started the next time the IFORMNG2 subsystem is started.
  2. The value for the line:
    JAVA_HOME
    This should contain the path to the 64-bit version of Java 17 . The recommended value is shown above.
Monitor an output queue: InterFormNG2 does not create a data queue
If you set up InterFormNG2 to monitor an output queue in a workflow via the input type: From IBM i output queue, then InterFormNG2 should do two things:
  1. A data queue is to be created in the same library as the monitored output queue.
  2. The data queue is to be assigned to the monitored output queue.
If the InterFormNG2 workflow does not start and the status is an error, then it may be that the data queue does not exist or is not assigned to the output queue.

You can verify from an IBM i command line if the data queue and output queue exist with the command:
WRKOBJ OBJ(<library>/<output queue>)
e.g.:
WRKOUTQ OBJ(QUSRSYS/PRT01)
This should result in a list of at least these two objects:
Opt  Object      Type      Library 
     PRT01       *DTAQ     QUSRSYS 
     PRT01       *OUTQ     QUSRSYS
 If the data queue does not exist, then you should verify:
  1. Do you have an active connection to the IBM i?
  2. Perhaps the user used for the connection does not have sufficient authority to create the data queue?
  3. Is there a reference to an error in the system log at the time the workflow was created/changed? Perhaps the user profile lacks authority?
You can verify the connection to the IBM i by signing on as a system administrator and selecting the system settings.

Under Other settings, you will find the setup of the connection to the IBM i machine, like below:

  

Here, you can consider connecting as another user instead of the iformng2 user profile, especially if you have a restricted environment. You can test if the user is able to sign on with the 'TEST CONNECTION' icon at the bottom and save any changes using the 'SAVE' icon in the bottom right.
Apart from normal authority restrictions, the option to create the data queue can also be locked down via an Exit Point in OS400. The exit points can be seen with the command:
WRKREGINF
The exit point relevant for the creation of the data queue is:
QIBM_QZHQ_DATA_QUEUE
The advice is NOT to change the settings of the exit point if this is preventing the creation, but instead to contact your system administrator. Perhaps a third-party tool is used for maintaining the exit points, or special company rules apply.

User authority considerations for IBM i
When you run InterFormNG2 on the IBM i platform, the default setup is to run InterFormNG2 as the user profile:
IFORMNG2
which is created during the installation. This user profile is delivered with the special authority:
*SPLCTL (spool control)
which ensures that the user can access all spooled files on the IBM i.

The user profile used must at least have use authority to the objects in the IFORMNG2 library and write authority to the directory:
/IFORMNG2
in the IFS, where core InterFormNG2 is running.
User profile for connecting to the IBM i

If you connect to the IBM i machine via the global system settings, then you need to ensure that InterFormNG2 is always able to sign on with the registered user profile and password.

You should consider disabling password expiration for this user profile to avoid any issues when the password runs out. You can set that with this command:

CHGUSRPRF USRPRF(<user>) PWDEXPITV(*NOMAX)
where <user> is the used user profile.
User profile for connection to the IBM i needs netserver access
If you run InterFormNG2 on another server, then the user profile used for connecting to the IBM i needs Netserver access to the IBM i.
That not only require, that the Netserver of the IBM i is running, but it also requires, that the user profile is not disabled for Netserver access, which should not be confused with a normal disabled user profile, which you can see directly on the DSPUSRPRF command like below:
                         Display User Profile - Basic

User Profile . . . . . . . . . . . . . :  MYUSER

Previous Sign-On  . . . . . . . . . . . :  11/02/22  11:21:54
Password Verifications Not Valid  . . . :  0
Status  . . . . . . . . . . . . . . . . :  *DISABLED
If the user is disabled like above then it is probably also disabled for Netserver access, but not the other way around..
You can verify if a user profile is disabled for Netserver access  - and enable the user, but this is not at all as simple.

Enable a user profile for Netserver access
Here are the steps to go through:
First sign on to IBM i Navigator via your browser by specifying the ip-address or hostname of the IBM i followed by colon and port 2001 like e.g.: https://ip-address:2001 or http://ip-address:2001

Then you sign on and double click on the server:
  selectedImg
​
And now you see this view on the left:
  selectedImg

Now you need to click this icon and select Servers and TCP/IP Servers as highlighted above:
  selectedImg
The TOOLSHED2 jobs not start or ends immediately
Starting the IFORMNG2 Subsystem on IBM i
On the IBM i platform, you should normally start the IFORMNG2 subsystem. You can manually start this subsystem by running the following command: 
IFORMNG2/IFORMNG2

This will display the IFORMNG2 menu
  

where you can start the subsystem using:
Option 10: Start IFORMNG2 subsystem

Checking running jobs
When the subsystem is running, you will normally see these jobs (which can be viewed using):
Option 12: Work with IFORMNG2 subsystem

  
In this subsystem, you will see the TOOLSHED2 jobs.

If these jobs do not start (or if they start and end immediately), you can verify the following:

Verifying NG2 installation and configuration
If the jobs are not started at all, then you should check the settings in the IFORMNG2 menu by selecting:
Option 92: NG2 installation and configuration
 
The screen may look like this:
  

Make sure that the value for: 'CommandLine to NG2' is set to:
*ACTIVE
If it is not ACTIVE, then the TOOLSHED2 jobs will not start.

Checking job logs for stopped jobs
If the jobs start but immediately stop, you can check the job log for the jobs.
WRKJOB TOOLSHED2

This will list all jobs with that name. You might see something like this:
  

Now, select:
Option 1 = Select for a job
Then, choose:
Option 4: Work with spooled files

You might be able to find a job log that contains the reason why the job stopped.


Checking additional log files
If the job log does not provide enough information, you can check other log files. These can be found in the IFS directory:
/IFormNG2/Log
where the NG2Tools.* files contain the logs.
One example of an issue found in the log file could be that the used port number (5679) is already in use.

InterFormNG2 does not react to a spooled file
This section concerns the issue where you have set up a workflow in InterFormNG2, but the workflow does not react to a new spooled file.
Info
Prerequisite: spooled file status must be RDY
One important prerequisite is that the spooled file must arrive on the output queue in status:
*RDY (Ready)
or the spooled file must be released after being placed on the monitored output queue.
Held spooled files are ignored by InterFormNG2.
If you hold and release the spooled files on the monitored output queue, and InterFormNG2 does not react (and there is no trace of the spooled file in the job log), then follow the checklist below.
For this guide, we will use the output queue IFORMNG2 in the library QUSRSYS as an example.

1) Check for a printer writer connected to the output queue

Ensure that no printer writer is connected to the same output queue.
If a printer writer is connected, the spooled file might be printed and deleted before InterFormNG2 has processed it.

2) Verify the output queue settings

Run the following command:
WRKOUTQD OUTQ(QUSRSYS/IFORMNG2)
When you run this command, you should see:
Data queue . . . . . . . . . . . . . . : IFORMNG2
Library . . . . . . . . . . . . . . : QUSRSYS
This confirms that InterFormNG2 has attached a data queue to this output queue.
If the value is:
*NONE
then no data queue is connected, and you need to resolve this using:
CHGOUTQ OUTQ(QUSRSYS/IFORMNG2) DTAQ(QUSRSYS/IFORMNG2)
Notes
The data queue has the same name as the output queue and is placed in the same library.

3) Verify that the data queue exists

InterFormNG2 can only react to spooled files if the output queue is linked to a data queue, and that data queue must exist.
Verify this with:
WRKOBJ OBJ(QUSRSYS/IFORMNG2) OBJTYPE(*DTAQ)
The data queue is expected in the same library as the output queue, and it should have the same name.
InterFormNG2 should have both created the data queue and added the reference to the data queue in the output queue.

4) If the data queue is missing, recreate it

If the data queue and/or reference is missing, you can:

  • Delete the workflow and create it again.

  • Manually create the data queue using:

CRTDTAQ DTAQ(QUSRSYS/IFORMNG2) MAXLEN(160)
Then, link the data queue to the output queue with:
CHGOUTQ OUTQ(QUSRSYS/IFORMNG2) DTAQ(QUSRSYS/IFORMNG2)

5) Check for another application monitoring the data queue

If InterFormNG2 still does not react to input spooled files, another application might be monitoring the same data queue and taking the entries before InterFormNG2 processes them.
Verify Monitoring in the InterFormNG2 Subsystem
Run:
IFORMNG2/IFORMNG2
Then, select:
Option 12: Work with IFORMNG2 subsystem
If you see a job named IFORMNG2 (same as the output queue name) running in this subsystem, this means another job is monitoring the same output queue. This will block InterFormNG2 from monitoring it.

Temporarily stop the monitoring job
Go to:
Option 1: Work with monitored output queues
Then, select:
Option 9: End monitoring
for the output queue:
QUSRSYS/IFORMNG2

Prevent automatic restart of the monitoring job
To ensure the monitoring job does not start again automatically, change the settings for this output queue.

  1. In "1. Work with monitored output queues", select:
    Option 2: Change
  2. Press <Page Down>.
  3. Ensure that "Auto start job" is set to: N (No)
If you are also running InterForm400, ensure that the same output queue is not monitored by Auto Forms Control in InterForm400.

6) Check the data queue for missing entries

If none of the above steps resolve the issue, suspend the InterFormNG2 workflow and inspect the data queue contents.
Dump the data queue contents
Run the command:
DMPOBJ OBJ(QUSRSYS/IFORMNG2) OBJTYPE(*DTAQ)
This will create a spooled file containing the contents of the data queue.
The spooled file is normally created in the QEZDEBUG output queue.
To locate it, run:
WRKJOB
Then, select:
Option 4: Work with spooled files
Inside this spooled file you can see the contents e.g. like below:
selectedImg

Check If the data queue is empty
Inside the spooled file, you might see:
NG2NoQueueMessages
If you see:
No Queue messages
it means the data queue is empty, and no spooled files are waiting to be processed.
Now, try releasing spooled files on the monitored output queue while the workflow is suspended.

  • If the entries build up, then no other job is taking them.

  • If the data queue keeps getting emptied, then another job is taking the entries.

You can see the entries on the spooled file generated by the data queue dump as sections like these:
      selectedImg

In the screenshot above you can see two full entries referring to an input spooled file and the top of a third one.

Final steps

If you determine that another job is removing the data queue entries, try to:
  1. Find and stop the job that is taking the entries.
  2. Use a different output queue linked to another data queue.
If the issue persists, consider using a different monitoring approach in InterFormNG2.
Install fails with error: CPF2260 User profile IFORMNG2 was not created or changed.

First time install fails with CPF2260: User profile IFORMNG2 was not created or changed

A first-time install of InterFormNG2 may rarely stop with the following error message:

selectedImg

This error occurs at the stage where InterFormNG2 attempts to create the user profile, IFORMNG2.

User profile creation command

During installation, the user profile is created using the following command:
CRTUSRPRF USRPRF(IFORMNG2) PASSWORD()
INLMNU(*SIGNOFF) LMTCPB(*NO) TEXT('InterForm NG2 user profile')
SPCAUT(*SPLCTL) PWDEXPITV(*NOMAX) JOBD(IFORMNG2/IFORMNG2) 
GRPPRF(QPGMR) OWNER(*GRPPRF) MSGQ(*USRPRF)

Cause of the problem

The issue arises because InterFormNG2 refers to QPGMR as the group profile  and if someone has setup a group profile for the QPGMR user profile, then this is not possible.

Workaround: manually create the IFORMNG2 user profile before installation

To bypass this issue, you can create the IFORMNG2 user profile manually before starting the installation.
Instead of referring to QPGMR, you can assign a different group profile using the command:
CRTUSRPRF USRPRF(IFORMNG2) PASSWORD()
INLMNU(*SIGNOFF) LMTCPB(*NO) TEXT('InterForm NG2 user profile')
SPCAUT(*SPLCTL) PWDEXPITV(*NOMAX) JOBD(IFORMNG2/IFORMNG2) 
GRPPRF(<MYGRPPRF>) OWNER(*GRPPRF) MSGQ(*USRPRF)
Replace: <MYGRPPRF> → with the group profile of your choice.
Additionally, you must set a known password for the IFORMNG2 user profile if you want to use it for connecting to the IBM i system.

Alternative solution: avoid using a group profile

Instead of assigning a group profile, you can choose not to refer to one and set the OWNER
parameter to a value of your choice.
Error message: No physical fonts found.
The error "No physical fonts found" is a common issue related to the Java configuration on IBM i. To resolve this problem effectively and gain complete insights, please follow the link provided: Java configuration on the IBM i.

The NG2SERVER job fails with an error QSH0005 or similar
If the NG2 environment fails to start, stops or dumps after a while, you'll may have to redirect the internal system output to a file for further examining or analysis.

In order to save the system output from QIBM_QSH_CMD_OUTPUT to a file, you'll have to do the following:

1. End the IFORMNG2 subsystem in option 11
2. Enter configuration page in option 92



3. Change QIBM_QSH_CMD_OUTPUT from *NONE to 'FILEAPPEND=/tmp/stdout_from_ng2.txt'
Notes
  Change the path and filename /tmp/stdout_from_ng2.txt, if required






4. Start the IFORMNG2 subsystem in option 10

5. When ready to examine the resulting output file, you can issue DSPF STMF('/tmp/stdout_from_ng2.txt') on a commandline 
Notes
Change the path and filename /tmp/stdout_from_ng2.txt, if required



6. Examine the file content



7. Remember to change the QIBM_QSH_CMD_OUTPUT back to *NONE and restart IFORMNG2, in order to stop the redirection.



  

Problem when loading a spooled file

The NG2SERVER job does not start in the IFORMNG2 subsystem

Monitor an output queue: InterFormNG2 does not create a data queue

User authority considerations for IBM i

User profile for connecting to the IBM i

User profile for netserver access

The TOOLSHED2 jobs not not start or ends immediately

InterFormNG2 does not react to a spooled file

Install fails with error: CPF2260 User profile IFORMNG2 was not created or changed.

Error message: No physical fonts found.







    • Related Articles

    • Troubleshooting

      This section contains solutions to specific problems: Issues related to namespaces in input XML files Error during rendering: Message: org.apache.fontbox.ttf.TrueTypeFont.getAdvanceWidth(I) PKIX path building failed: XXXX: unable to find valid ...

    • 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 ...

    • Release log Version 3.x.x

      This is the list of the InterFormNG2 releases versions 3.x.x and the major new features in each release: Version 3.5.1 Version 3.5.0 Version 3.4.3 Version 3.4.2 Version 3.4.1 Version 3.4.0 Version 3.3.2 Version 3.3.1 Version 3.3.0 Version 3.2.0 ...

    • Datamatrix

      If you want to insert a datamatrix barcode in a template, then you need to insert a barcode element. If you want to insert a Datamatrix GS1 barcode, then you need to setup the data for the barcode accordingly. You need to select datamatrix as 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 ...