Setting up eFORMz on iSeries
This post describes setting up eFORMz on iSeries, including licensing eFORMz and setting up the Director to run as an automated process.
Licensing eFORMz on iSeries
For additional details, consult the following post on creating an unsigned license file: License eFORMz on an AS/400 (iSeries) system
Connect to the iSeries using a tn5250 terminal emulator, such as the “Minisoft IBM Emulation” application. At the login prompt, enter your user name and password and press Enter to log in:
The Main Menu will now be displayed:
Before licensing eFORMz on the iSeries, we need to know what Java version is installed.
Finding the Java Version Installed on iSeries
To find the installed Java version, launch a command shell by typing the command “call qp2term” and pressing Enter:
We need to be in the minisoft directory a few steps below, so change to this directory by typing the following command:
cd /minisoft
Then at the command prompt, type “java -version” to see the default Java version installed on the iSeries.
In the example shown in the screen shot, the default Java version is 8, but it is a 32-bit version, indicated by “ppc -32” on the line showing the Java build. We want to find a 64-bit Java version if one exists. Go to the following IBM website to see the Java versions that can be present on various iSeries operating systems (you can find this website by typing “iSeries java version” into a search engine, and look for a link with the text “IBM Supported Java Development Kit (JDK) Versions…”
http://www-01.ibm.com/support/docview.wss?uid=nas8N1011999
Scroll down the page to the table showing the operating system version (in the leftmost column), the JDK version and Bit Level and the JAVA_HOME value (in the rightmost column). The latter is the directory where that version of Java is installed. For example, I am looking for operating system version 7.3, and I want to find the most recent 64-bit Java version that is supported:
The last row shows the JAVA_HOME value for JDK 8.0. To test whether this version is indeed installed on the iSeries, I paste this directory into the shell prompt, then append “/bin/java -version” to run the following command:
/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/bin/java -version
If I get back something like the following response, this is a valid Java version:
If a “not found” error is returned, I know this is not an installed Java version on this iSeries:
Create the eFORMz License File
To create the eFORMz license file (eFORMz.xml), run the following command from a shell (be sure there is a space between the last minus sign and “com.minisoft.Check”, and also be sure to capitalize everything exactly as written:
/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/bin/java -jar Run.jar – com.minisoft.Check
Success is indicated by the following output:
This command creates the unlicensed eFORMz.xml file, which can be copied from the iSeries, licensed, and copied back. After copying the eFORMz.xml file back, you can verify that it was licensed correctly by re-entering the command above. You should see output like the following:
Configure eFORMz as an Automated Process on iSeries
Following is the default “Start Director Command” for iSeries:
SBMJOB CMD(QSH CMD('cd /minisoft ; /QOpenSys/QIBM/ProdData/JavaVM/jdk80/32bit/bin/java -Djava.awt.headless=true -Duser.dir=/minisoft -jar /minisoft/Run.jar /minisoft com.minisoft.Director.Director')) JOB(DIRECTOR) JOBD(*USRPRF)
Reformatting this command makes it easier to figure out what is going on:
SBMJOB CMD(
QSH CMD('cd /minisoft ;
/QOpenSys/QIBM/ProdData/JavaVM/jdk80/32bit/bin/java
-Djava.awt.headless=true
-Duser.dir=/minisoft
-jar /minisoft/Run.jar
/minisoft com.minisoft.Director.Director'
)
)
JOB(DIRECTOR)
JOBD(*USRPRF)
This creates a job with the name “DIRECTOR” that runs the QSH command shown. We need to replace the path to the Java command with the correct one for the iSeries operating system and installed Java version. Refer to the above section “Finding the Java Version Installed on iSeries” to learn how to do that.
Example with 64-Bit Java
Let’s say that you research which Java versions are installed, and you find a 64-bit Java version installed in the following path:
/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/bin/java
Putting this into the SBMJOB string above gives us the following string that will start Director as a 64-bit process:
SBMJOB CMD(
QSH CMD('cd /minisoft ;
/QOpenSys/QIBM/ProdData/JavaVM/jdk80/64bit/bin/java
-Djava.awt.headless=true
-Duser.dir=/minisoft
-jar /minisoft/Run.jar
/minisoft com.minisoft.Director.Director'
)
)
JOB(DIRECTOR)
JOBD(*USRPRF)
Copy this string into the “Start Director Command”:
Then click Start. If there are no errors and the Director starts successfully, you will see the running configuration files and tasks, as shown in the example below:
If an error occurs on starting the Director, that error will be displayed as shown below. To simulate an error, I change the path to the java command to an invalid path (note the “jdk90” in the path):
/QOpenSys/QIBM/ProdData/JavaVM/jdk90/64bit/bin/java
When I click Start, I now see the following error:
Click the Cancel button. Now we need to figure out why the Director failed to launch.
Troubleshooting Start Director as an Automated Process
For some reason, the Director does not start successfully when you pressed Start on the Director tab of the Director Toolkit for iSeries. How do you figure out what went wrong? To find the answer, you need to first launch a terminal session with the iSeries. Pick your favorite tn5250 terminal emulator (Minisoft has one!), and connect to the iSeries and login. When you are at the main menu, your screen should look like this:
Type “wrkjob director” at the prompt, then press Enter:
A list of jobs named “DIRECTOR” is shown. You probably want the one with the most recent date (12/21/17 in the screen shot below), so type a “1” in the Option column for the one you want:
When you press Enter, you are given a list of tasks you can perform with the job:
A record of what happened when the job was run is kept in a spool file, so you want to select the option “4. Work with spooled files”, by typing a 4 and pressing Enter, to show the following screen with the contents of the spool file:
The error message in the spool file indicates that the command “QOpenSys/QIBM/ProdData/JavaVM/jdk90/64bit/bin/java” could not be found. That is because “jdk90” was entered instead of “jdk80”. I can now go back and correct the command and start the Director again.
Related posts