Integrating iSeries Host Applications into Portals

by Marc Logemann

Portals are on the way to becoming mainstream in enterprise software environments. Companies like BEA Systems, IBM, and Plumtree are pushing this product segment hard. Before I look into the details of a successful integration, I will outline the basic definition and working of a portal. This article will not cover every piece of the implementation, but will give you an idea how to start. Some aspects of the integration, especially the retrieval of current logged in user and its password, are portal specific and cannot be outlined here.

How Portals Work

Like application servers, portals provide an environment for Web-based applications. However, portals provide additional functionality like single sign on and the ability to run applications called portlets. Internally, many portal products are based on a standard J2EE application server. From a developer perspective, you have the choice to use proprietary vendor interfaces or the portlet interface JSR-168, which is specified by Sun Microsystems, the creator and steward of Java. The portlet interface allows for migration to another portal server and is the preferred way of doing portlet development. However, as stated before, portals live in the domain of the intranet or extranet, thus all their applications are completely http based. On the other hand, you have the host application world, where 5250 terminal emulation supplies the user interface for a host program. Next, I will show you how to run a 5250 terminal emulation application inside the portal with automated authentication.

Choosing the Terminal Emulation

To use terminal emulation in a portal, you need three characteristics. First, the terminal emulator must support 5250 emulation. Second, there has to be a way to start it using Java Web Start. And finally, the emulator has to be open source in order to modify it in a way that it supports automatic authentication and triggering of the host application. The emulator has to support Java Web Start in order to launch a desktop application such as TN5250j from the Web. Java Web Start is the bridge between the Web world and the desktop world. In order to use Java Web Start, all workstations must have the Java plug-in installed. You can download it on the official Java Web site.

TN5250j is the ultimate choice for our needs. It is widely used for iSeries 5250 terminal emulation. In addition, it is open source and since it's written in Java it works with Java Web Start. Most Java applications have to be reworked to support Java Web Start, but the developers of TN5250j have already done this. The most interesting feature of TN5250j is the ability to add Python-based scripting to iSeries sessions. TN5250j uses Jython in order to execute Python scripts within a Java application. This makes it possible to capture and replay current terminal sessions while adding content. Its intention was to give users the ability to write macros. I use this feature to automatically fill out host masks on connection. Be aware that all modifications, even if they are customer oriented, must be made public, because TN5250j is under the GNU General Public License (GPL). For more information on the restrictions of the GPL license, check the Free Software Foundation (FSF) Web site. You can download TN5250j on the SourceForge site.

Adding Custom Code for Automation

Before you can start modifying the code, be sure that you have downloaded the source distribution of TN5250j. From an object-oriented perspective, the TN5250j code base is not the best, but the application itself is really stable. A good place to insert our own code is inside the Gui5250.java file located in the package org.tn5250j. The method you are interested in is onSessionChanged(). This method is called as soon as the application connects to a host. See the creation of a StringBuffer with some Python commands.

public void onSessionChanged(SessionChangeEvent changeEvent) {

   switch (changeEvent.getState()) {
       case STATE_CONNECTED:

      //todo Hook for custom implementation
           StringBuffer pythonScript = new StringBuffer();
           pythonScript.append("screen = _session.getScreen()\n");
           pythonScript.append("screen.sendKeys(\"User\")\n");
           pythonScript.append("screen.sendKeys(\"[tab]\")\n");
           pythonScript.append("screen.sendKeys(\"Password\")\n");
	  pythonScript.append("screen.sendKeys(\"[tab]\")\n");
           pythonScript.append("screen.sendKeys(\"PRG001\")\n");
           pythonScript.append("screen.sendKeys(\"[enter]\")\n");

           try {
               InterpreterDriverManager.executeScript((Session)this,
 pythonScript.toString(), "Python");
           } catch (InterpreterDriver.InterpreterException e) {
               e.printStackTrace();
           }

           String mac = sesConfig.getStringProperty("connectMacro");
           if (mac.length() > 0)
               executeMeMacro(mac);
           break;
   }
 }

As you can see, I am grabbing the host sign on screen and send the literal "User," followed by a [Tab] and the literal "Password," after another [Tab], I am supplying the program to call (PRG001) and at the end I am submitting the screen by sending [Enter]. When starting TN5250j after compilation, the terminal emulation will automatically try to login to the host with the credentials supplied. Of course, this is only an example, because I don't want to authenticate with "User" and "Password" and I also don't want to call PRG001.

Building the modified TN5250j application is simple because an ANT build.xml file is provided with the source distribution. Assuming you already have ANT installed or you are running an ANT capable IDE, you only need to execute the "dist-bin" target. Check the Building with Ant documentation on TN5250j Web site. For more general information on Ant see Building Applications with Ant or the Ant Web site.

To use the modified terminal emulation, unpack the newly created tn5250j-x-bin.zip in the dist directory archive and execute the tn5250j.jar file.

What to Do in the Portal Environment

Our modified terminal emulation program is called via Java Web Start. You must generate two things within your portal:

• An HTML page with links that start your emulation program. You will need one link for each host program you want to start
• The Java Web Start deployment descriptor (JNLP) must be generated dynamically by clicking on the various links from above

A Servlet can call TN5250j but a Portlet will integrate better in your portal. The exact implementation is out of the scope of this article but here are a few guidelines of what to consider.

• Generate HTML links like: http://myserver/CallApplication?name=PRG001 (where PRG001 should be replaced by other program names for other links)
• Create a Servlet acting on CallApplication
• Let the Servlet find out who is actually authenticated in the portal and read parameter "name"
• Let the Servlet create the Java Network Launching protocol (JNLP) stream and send it to the users workstation
• Return the correct Content-Type: application/x-java-jnlp-file

A dynamically created JNLP could look like this:

<?xml version="1.0" encoding="utf-8"?>
<jnlp spec="0.2 1.0"  codebase="http://MyServer/javawebstart">
<information>
<title>tn5250j</title>
<vendor>Yourname</vendor>
<homepage href="http://sourceforge.net/tn5250j"/>
<description>tn5250j - 5250 emulator written in java</description>
<description kind="short">tn5250j - 5250 emulator</description>
<icon href="tnicon.jpg"/>
<offline-allowed/>
</information>
<security>
<all-permissions/>
</security>
<resources>
<j2se version="1.3+" inital-heap-size="64m" max-heap-size="256m"/>
<jar href="tn5250j.jar" main="true" download="eager"/>
<jar href="activation.jar"/>
<jar href="mail.jar"/>
<jar href="mailapi.jar"/>
<jar href="smtp.jar"/>
</resources>
<application-desc main-class="org.tn5250j.My5250">
<argument>USERNAME</argument>
<argument>PASSWORD</argument>
<argument>PRG01</argument>
</application-desc>
</jnlp>

The important part is the <arguments > section. Replace the literals USERNAME, PASSWORD and PRG01 with values passed from the Servlet. The PRG01 variable is easy, because in the request parameter, you are getting the program to call. Just read out the parameter "name" and place the value right in the place where actually PRG01 is written. Retrieving and setting USERNAME and PASSWORD are a little bit trickier because each portal handles presents these values differently. Consult your portal documentation for details on this.

The last thing you need to consider is how to receive the command line argument in My5250.class and store it somewhere so that Gui5250.java and the presented method onSessionChanged() can retrieve these values. Of course, you have to modify the method and replace the hard-coded Strings like "User" and "Password" with the appropriate command line arguments. This is all straightforward Java programming and shouldn't be a problem.

Summary

With TN5250j, it is possible to easily integrate your host applications into your portal with full single sign-on capabilities. You have to tweak two Java files within this application (Gui5250.java and My5250.java) and you need to create two components on the server side to handle the Java Web Start launching and display a menu to the user. The only advanced issue here is to retrieve the actual credentials from the portal server and to pass them to the modified terminal application TN5250j.

Marc Logemann is founder of Logentis, a German consulting company that focuses on iSeries and Java services and development. Click here to contact Marc by e-mail.