Starting Java Application Service on iSeries

Introduction

This document describes how to deploy, tune, and troubleshoot the Java based Application Service for iSeries.

The Application Service is the component of the Distributed Websydian Architecture that is created by the developer in the Plex development environment. Further information on the Application Service can be found in this document.

Prerequisites

OS/400 software

Make sure that the following software are available on the IBM i:

• OS/400 V5R3 or later
• OS/400 - QShell Interpreter
• Java Developer Kit 1.6 or later with latest group PTF package.
• Latest cumulative PTF

Plex runtime objects

Make sure the Plex runtime objects are installed on the iSeries. Consult the Plex manual on how to install the Plex runtime objects for iSeries.

Websydian runtime objects

Make sure the Websydian runtime objects are installed, including the latest PTFs on the IBM i including the java runtime files for the DWA environment which are to be placed in the integrated file system (IFS).

For further information on installing the Websydian runtime on the IBM i read this document.

Deploy the Java Application Service

Before deploying and starting the Java Application Service on the iSeries it is recommended to deploy it on a Windows based platform. If the application has been successfully deployed on the Windows platform it is most likely going to be successfully deployed on the iSeries as well. Note that application problems are also easier identified on the Windows platform.

Deploy the Java Application Service

Java applications are deployed on the iSeries in the Integrated File System (IFS) and it is recommended to package all class files into one jar file for better performance.

In order to deploy the Application Service do the following:

1. Create a directory structure in the IFS that will contain the Java objects

   • Create a directory to contain the Java application.
     E.g. /Websydian/JavaApps/AcmeJavaApp
   • Create a subdirectory called jars in the application directory, this directory will hold all jar files required by the application.
     E.g. /Websydian/JavaApps/AcmeJavaApp/jars
   • Create a subdirectory called resources in the application directory, this directory will hold the resource files required by the application.
     E.g. /Websydian/JavaApps/AcmeJavaApp/resources
   • Create a subdirectory called html in the application directory, this directory will hold all the html document templates used by the application.
     E.g. /Websydian/JavaApps/AcmeJavaApp/html
   • Create a subdirectory called temp in the application directory, this directory will hold any temporary files created by the application, used by WebService applications.
     E.g. /Websydian/JavaApps/AcmeJavaApp/temp

2. Copy all required files to iSeries

   • Copy jar files required by Websydian and Plex to the 'jars' directory.
     • activation*.jar, supplied with Websydian
     • log4j*.jar, supplied with Websydian
     • mail*.jar, supplied with Websydian
     • wsyddwa*.jar, supplied with Websydian
     • commons-httpclient.jar, supplied with Websydian
     • wsydutil.jar, supplied with Websydian
     • wsydxml11.jar, supplied with Websydian
     • ObRun.jar, supplied with Plex
   • Copy Plex generated class files to the 'jars' directory, for information on how to create a jar file read this
     • Copy the directories holding the class files generated by Plex to the 'jars' directory.
   • Copy Plex generated resource files to the 'resources' directory
   • Copy the obxxxclient.properties file to the application directory
   • Copy the HTML document templates to the 'html' directory

3. Verify the Websydian parameters of the obxxxclient.properties file.

   Make sure that the Websydian parameters required in the obxxxclient.properties file are correct.

   Parameter	Dscription	E.g.
   html.path	Path to document templates	/Websydian/JavaApps/AcmeJavaApp/html
   html.date	Date format	yyyy-mm-dd
   html.time	Time format	hh:mm:ss
   html.timestamp	Timestamp format	yyyy-mm-dd hh:mm:ss
   TransacXML.TEMPORARY_FILES	Location of temporary files created by TransacXML	/Websydian/JavaApps/AcmeJavaApp/temp
   TransacXML.MAX_CONTENT_LENGTH	Max length of XML documents received by TransacXML	10240

   Make sure that the following parameters in the obxxxclient.properties file are correct:

   Parameter	E.g.
   DefaultAS400.System	ISERIESHOSTNAME
   DefaultAS400.Port	40000
   DefaultAS400.Encoding	Cp037
   DefaultAS400.User
   DefaultAS400.Password	Enter password in clear text, Plex runtime will encrypt on first call
   Environment.Default.Resources	file:/Websydian/JavaApps/AcmeJavaApp/resources

   For further information on parameters supplied by Plex please consult the Plex manual.

Start the Java Application Service

The Java Application Service is started by issuing the command STRJVAAS located in the Websydian runtime library.

Add the Websydian runtime libraries to the library list, making sure that the library WSYD600PTF is located before the library WSYD600.

Submit the Java Application Service using the STRJVAAS command followed by F4.

                   Start Java Application Service (STRJVAAS)                   
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Websydian Server IP Address  . .  *LOCALHOST                                  
 Websydian Server TCP Port  . . .  08189         Number                        
 Application Service IP Address .  *LOCALHOST                                  
 Application Service TCP Port . .  11001         Number                        
 Number of services . . . . . . .  1             Number                        
 Service Name . . . . . . . . . .  SVCNAME                                     
 Application Service Listener . .  MISC.MyAppSvc                               
                                                                                
 Websydian home directory . . . .  '/websydian/WSYD600'                        
                                                                                
                                                                                
 Application Jars Directory . . .  '/websydian/JavaApps/AcmeJavaApp/Jars'      
                                                                                
                                                                                
                                                                                
                                                                                
                                                                        More... 
 F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel      
 F13=How to use this display        F24=More keys                               
                                                                                

Press PageDown

                   Start Java Application Service (STRJVAAS)                   
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Plex Property file path  . . . .  '/websydian/JavaApps/AcmeJavaApp'           
                                                                                
                                                                                
 Job name . . . . . . . . . . . .  WSYDAPP       Character value               
 Job description  . . . . . . . .  WSYDJOBD      Name                          
   Library  . . . . . . . . . . .     WSYD600     Name                          
 Job queue  . . . . . . . . . . .  QINTER        Name                          
   Library  . . . . . . . . . . .     QGPL        Name                          
 Init library list  . . . . . . .  *JOBD         Name, *CURRENT, *JOBD...      
 User . . . . . . . . . . . . . .  *CURRENT      Name, *CURRENT, *JOBD          
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                         Bottom 
 F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel      
 F13=How to use this display        F24=More keys                               
                                                                                

Verifying the Java Application Service

After starting the Application Services verify that they are started and have reported information to the Websydian Server.

Using the command WRKLNK you are able to view the log file of the Websydian Server.

Select option 5 in front of the wsydsrv.log file for view and press enter.

 Edit File: /websydian/WSYD610/logs/wsydsrv.log                                 
 Record :       1   of       3 by   8            Column :   30     99 by  74    
 Control :                                                                      
                                                                                
CMD 3....+....4....+....5....+....6....+....7....+....8....+....9....+....0.... 
    a**************                                                             
 ead-0:INFO] - License info: Websydian Server Unregistered Basic expires at 'Ne
ead-0:INFO] - DWA protocol: Version 2.1. 
ead-0:INFO] - Waiting for connection on 192.168.102.20:41130... 
ead-0:DEBUG] - Receiving... 
ead-2:DEBUG] - Got packet... 
ead-2:DEBUG] - Got PUTTOKEN... 
ead-2:DEBUG] - PUTTOKEN - svcname:EXPRESS timeout:30 sessname:WSYD_SID ipaddr:1
ead-2:INFO] - Token received. Service name: DWAWSYDAPP, IP Address: 192.168.102
    ***************                                                             
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
 F2=Save   F3=Save/Exit   F12=Exit   F15=Services   F16=Repeat find             
 F17=Repeat change  F19=Left  F20=Right                                          

Input 30 in column and press enter.

The log file shows all communication with the Websydian Server, note this is only the case when log level is set to TRACE. Make sure that the log holds information about the packages PUTTOKEN identifying all Application Services started. Please note that the log information above is an example.

If the information is not in the log file or the log file is not present please proceed to the Troubleshooting the Java Application Service section of this document.

Tuning the Java Application Service

There are some tuning possibilities available to get the Java Application Service to respond faster.

The tuning options are:

Package all custom class files into jar files

For optimizing the load of classes IBM recommends creating jar packages holding class files, do the following for each directory holding class files:

1. Run the command QSH on the iSeries to start the 'QSH Command Entry'
2. Change to the directory where the class files are located using the cd command
   cd /Websydian/JavaApps/jars/MyAppMisc
3. Run the packaging tool 'jar' supplied with Java
   jar cfM /Websydian/JavaApps/jars/MyAppMisc.jar
4. Press F3 to end the 'QSH Command Entry'
5. Delete the directory containing the class files

Optimize the Java programs

Run the command CRTJVAPGM on the iSeries to optimize the java code.

The command create java program makes a copy of the java program and places an optimized version of the java program on the disk. When referring the java program the iSeries will check if there is an optimized version of the program and if present use this instead.

                         Create Java Program (CRTJVAPGM)                        
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Class file or JAR file . . . . .  '/websydian/JavaApps/AcmeJavaApp/Jars/*.j  
ar'                                                                             
 Classpath  . . . . . . . . . . .   *NONE                                       
                                                                                
 Java developer kit version . . .   *NONE         Character value, *NONE        
 Optimization . . . . . . . . . . > 40            10, *INTERPRET, 20, 30, 40    
 User profile . . . . . . . . . .   *USER         *USER, *OWNER                 
 Use adopted authority  . . . . .   *NO           *NO, *YES                     
 Replace program  . . . . . . . .   *YES          *YES, *NO                     
 Enable performance collection  .   *NONE         *NONE, *ENTRYEXIT, *FULL      
 Profiling data . . . . . . . . .   *NOCOL        *NOCOL, *COL                  
                                                                                
                                                                                
                                                                                
                                                                                
                                                                                
                                                                         Bottom 
 F3=Exit   F4=Prompt   F5=Refresh   F10=Additional parameters   F12=Cancel      
 F13=How to use this display        F24=More keys                               

Change the "Class file of JAR file" to reflect the directory where the Websydian Java runtime objects are installed.

Change the "Optimization" to 40, which is the full optimization.

• A RedBook is available from IBM called "Java and WebSphere Performance on IBM eServer iSeries Servers", that in depth describes different tuning options for better performance of Java applications on the iSeries.
  
  IBM Form number: SG24-6256-00

Troubleshooting the Java Application Service

When troubleshooting the Java Application Service running on the iSeries check for the following problems.

1. Make sure that the job has been submitted and is not waiting in the job queue.
    
2. Check if the job has ended successfully or abnormally, this can be checked by viewing the messages of the user submitting the job.
   
   Use the command DSPMSG to view the messages of a particular user.
   

   ===>DSPMSG <username> [Enter]

3. If the job is not active, or has ended abnormally, or successfully check the output queue QEZJOBLOG for any spool files pertaining the job running the Java Application Service.

   Use the command WRKOUTQ to view the contents of the output queue QEZJOBLOG

   ===>WRKOUTQ QEZJOBLOG [Enter]

4. When running Java programs a number of errors may be displayed on the standard out device or standard error device. On the iSeries information from standard out and standard error are stored in a spool file called QPRINT under the user running the Java application.
   
   Use the command WRKSPLF to view the list of spool files generated for the user running the Java application.
   

   ===>WRKSPLF <username> [Enter]

The Java Application Service may display a number of error messages generated by the Websydian DWA layer. A complete list of possible errors are located here, for the most often seen errors see below:

• Error code 48 - Socket Bind Failed, indicates that the Application Service was unable to start listening to the TCP port or IP address specified. Correct the problem and try starting the Application Service again, see below how to check for valid TCP port and IP address.

  Using the iSeries NETSTAT command

  Use the command NETSTAT to view the list of used IP addresses on the iSeries and select the menu option 3 - Work with TCP/IP connection status

  ===>NETSTAT [Enter]

                         Work with TCP/IP Connection Status                       
                                                               System:   DKSOFT00 
   Type options, press Enter.                                                     
     3=Enable debug   4=End   5=Display details   6=Disable debug                 
     8=Display jobs                                                               
                                                                                  
        Remote           Remote     Local                                         
   Opt  Address          Port       Port       Idle Time  State                   
        *                *          ftp-con >  000:52:39  Listen                  
        *                *          telnet     000:29:57  Listen                  
        *                *          smtp       238:56:17  Listen                  
        *                *          www-http   002:36:49  Listen                  
        *                *          pop3       238:56:19  Listen                  
        *                *          netbios >  238:56:19  Listen                  
        *                *          netbios >  000:00:36  *UDP                    
        *                *          netbios >  000:00:21  *UDP                    
        *                *          netbios >  000:29:07  Listen                  
        *                *          cifs       001:27:59  Listen                  
        *                *          drda       238:57:26  Listen                  
        *                *          ddm        238:57:26  Listen                  
                                                                     Mere...      
   F3=Exit   F5=Refresh   F9=Command line   F11=Display byte counts   F12=Cancel  
   F15=Subset   F22=Display entire field    F24=More keys                         
  

   

  Using the iSeries CFGTCP command

  Use the command CFGTCP followed by selection of the menu option 1 - Work with TCP/IP interfaces to view a list of available IP addresses on the iSeries.

  ===>CFGTCP [Enter]

   

                            Work with TCP/IP Interfaces                           
                                                               System:   DKSOFT00 
   Type options, press Enter.                                                     
     1=Add   2=Change   4=Remove   5=Display   9=Start   10=End                   
                                                                                  
        Internet         Subnet              Line      Line                       
   Opt  Address          Mask             Description  Type                       
                                                                                  
        127.0.0.1        255.0.0.0        *LOOPBACK    *NONE                      
        192.168.1.1      255.255.255.0    ETHLAN1      *ELAN                      
        192.168.1.2      255.255.255.0    ETHLAN2      *ELAN                      
        192.168.100.1    255.255.255.0    ETHLAN3      *ELAN                      
                                                                                  
                                                                                  
   F3=Exit      F5=Refresh   F6=Print list   F11=Display interface status         
   F12=Cancel   F17=Top      F18=Bottom                                           
  

   

• Error code 35 - Connect failed, indicates that the Application Service were unable to connect to the Websydian Server. Check that the correct TCP port and IP address is specified for the Websydian Server and make sure that the Websydian Server is started, how to do this check the document Starting Websydian Server on iSeries.