Online documentation - Websydian v6.5

Deploying and operating iSeries Application Services

Introduction
Prerequisites
Starting the iSeries Application Services
Verifying that the iSeries Application Service is started
Stopping the iSeries Application Services
Restarting the iSeries Application Services
Troubleshooting the iSeries Application Service

Introduction

This document describes how to deploy, operate and troubleshoot the Application Service for iSeries.

It is required that the user deploying the iSeries Application Service has knowledge of the iSeries. Especially with reference to job management.

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

Please make sure the following prerequisites have been performed or verified.

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.

Websydian Server deployed and running

Make sure that the Websydian Server has been deployed and is running.

For further information on deployment of the Websydian Server go to the main page of the DWA Deployment Guides.

Check and set data areas

Before starting the iSeries Application Service a number of data areas need to be checked for the correct information. The data areas are supplied with the Websydian iSeries runtime objects with the default settings, it is recommended to copy these data areas to the library of the application.

The data areas and there content are:

Dataarea	Description	Default value
WSYDDATMSK	Date mask used when transferring date fields from input.	yyyy/mm/dd
WSYDDECSEP	Decimal separator used when transferring numeric fields from input.	. (dot)
WSYDPATH	Path identifying the location of the document templates.	/WSYD600/TEMPLATES/
WSYDTHUSEP	Thousand separator used when transferring numeric fields from input.	, (comma)
WSYDTMEMSK	Time mask used when transferring time fields from input.	hh:mm:ss
WSYDTMSMSK	Timestamp mask used when transferring timestamp fields from input.	yyyy/mm/dd hh:mm:ss

After changing the values in these data areas, you must restart the application services or any page that has already been shown will use the old formats.

Create or check the job description to be used

Make sure that a job description is available in order to start the Application Service. We recommend copying the job description WSYDJOBD located in the Websydian runtime library to the library of the application.

Make sure that the job description has the following libraries in the initial library list, adding all other libraries that the application may require.

QTEMP
[AppLibrary]
WSYD610PTF
WSYD610
[PlexLibrary]

Replacing the [AppLibrary] by the name of the library of the application and the [PlexLibrary] by the name of the library containing the iSeries Plex runtime objects.

Copy Document Templates to the iSeries

Create the directory specified in the data area WSYDPATH and copy all document templates used by the Application to this directory.

Starting the iSeries Application Service

The iSeries Application Service is started by issuing the command STRAS which is located in the Websydian runtime library.

Submit the iSeries Application Service using the STRAS command followed by F4.

===>WSYD610/STRAS [F4]

                        Start Application Service (STRAS)                       
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Application Service Listener . .   SVCAPP        Character value               
 Websydian Server IP Address  . .   *LOCALHOST                                  
                                                                                
                                                                                
 Websydian Server TCP Port  . . .   08189         Number                        
 Application Service IP Address     *LOCALHOST                                  
                                                                                
                                                                                
 Application Service TCP Port . .   03860         Number                        
 Number of Application Services     1             Number                        
 Service name . . . . . . . . . .   DWATUTOR                                    
 Job name . . . . . . . . . . . .   DWATUTOR      Character value               
 Job description  . . . . . . . .   WSYDJOBD      Name                          
   Library  . . . . . . . . . . .     WSYD610     Name                          
 Job queue  . . . . . . . . . . .   QINTER        Name                          
   Library  . . . . . . . . . . .     QGPL        Name                          
                                                                        Mere... 
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    
 F24=More keys

                        Start Application Service (STRAS)                       
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Init library list  . . . . . . .   *JOBD         Name, *CURRENT, *JOBD...      
 User . . . . . . . . . . . . . .   *CURRENT      Name, *CURRENT, *JOBD         
                                                                                
                                                                                
                                                                         Slut   
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    
 F24=More keys

Parameter	Default Value	Description
Application Service Listener	MyAppSvc	The implementation name of the function inheriting from ApplicationServiceListener
Websydian Server IP Address	*LOCALHOST	The IP address of the machine where the Websydian Server is started. This address together with the TCP port is used by the Web Server Component to connect to the Websydian Server. Valid values are: The host name of the iSeries An IP Address located on the iSeries (IP/v4 or IP/v6) *LOCALHOST indicating local IP Address 127.0.0.1
Websydian Server TCP Port	08189	The TCP port of the Websydian Server. The port is used together with the IP address by the Web Server Component to connect to the Websydian Server.
Application Service IP Address	*LOCALHOST	The IP address of the machine where the Application Services are started. This address together with the TCP port is used by the Web Server Component to connect to the Application Services. Valid values are: The host name of the iSeries An IP Address located on the iSeries (IP/v4 or IP/v6) *LOCALHOST indicating local IP Address 127.0.0.1
Application Service TCP Port	11001	The TCP port of the first Application Service to be started. The port is used together with the IP address by the Web Server Component to connect to the Application Service.
Number of Application Services	1	The number of Application Services to start starting at the TCP port specified by 'Application Service TCP Port' and incrementing this by one for each additional Application Services started.
Service name	SVCNAME	The name used to uniquely identify the Application Services started by the Websydian Server and Web Server Component.
Job name	DWAAS	Job name to be used by the Application Services
Job description	WSYD610/WSYDJOBD	Job description used for submitting the Application Services to batch
Job queue	QGPL/QINTER	Job queue used for submitting the Application Services to batch
Init library list	*JOBD	Initial library list to be used
User	*CURRENT	The user to be used for submitting the Websydian Server to batch

Verifying that the iSeries Application Service is started

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

===>WRKLNK '/Websydian/WSYD610/logs/*' [Enter]

                             Work with Object Links

Directory . . . . :   /websydian/WSYD610/logs

Type options, press Enter.
2=Edit   3=Copy   4=Remove   5=Display   7=Rename   8=Display attributes
11=Change current directory ...

Opt Object link            Type     Attribute     Text
   wsydsrv.log             STMF

                                                                   Slut
Parameters or command
===>
F3=Exit   F4=Prompt   F5=Refresh   F9=Retrieve   F12=Cancel   F17=Position to
F22=Display entire field   F23=More options

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 iSeries Application Service section of this document.

Stopping the iSeries Application Services

The iSeries Application Service is stopped by issuing the command ENDAS which is located in the Websydian runtime library.

Stop the iSeries Application Service using the ENDAS command followed by F4.

===>WSYD610/ENDAS [F4]

                         End Application Service (ENDAS)                        
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Websydian home directory . . . .   '/websydian/wsyd610'                        
                                                                                
                                                                                
 Websydian Server IP Address  . .   *LOCALHOST                                  
                                                                                
                                                                                
 Websydian Server TCP Port  . . .   08189         Number                        
 Application Service IP Address     *ALL                                        
                                                                                
                                                                                
 Application Service TCP Port . .   *ALL          Number, *ALL                  
 Web Server Component IP Addr.  .   *LOCALHOST                                  
                                                                                
                                                                                
 Web Server Component TCP Port  .   12000         Number                        
 Service Name . . . . . . . . . .   DWATUTOR                                    
                                                                        Slut 
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    
 F24=More keys

Parameter	Default Value	Description
Websydian home directory	/websydian/wsyd610	Directory in the IFS where required Websydian runtime objects are located
Websydian Server IP Address	*LOCALHOST	The IP address of the machine where the Websydian Server is started. This address together with the TCP port is used by the Web Server Component to connect to the Websydian Server. Valid values are: The host name of the iSeries An IP Address located on the iSeries (IP/v4 or IP/v6) *LOCALHOST indicating local IP Address 127.0.0.1
Websydian Server TCP Port	08189	The TCP port of the Websydian Server. The port is used together with the IP address by the Web Server Component to connect to the Websydian Server.
Application Service IP Address	*ALL	The IP address of the machine where the Application Services are started, that you would like to end. Valid values are: The host name of the iSeries An IP Address located on the iSeries (IP/v4 or IP/v6) LOCALHOST indicating local IP Address 127.0.0.1 ALL indicates that all Application Services with specified service name will be ended.
Application Service TCP Port	*ALL	The TCP port of the Application Service you would like to end. Valid values are: A valid TCP Port number *ALL indicating that all Application Services will be ended.
Web Server Component IP Addr	*LOCALHOST	The IP address of the machine where the Websydian Web Server Component is located. Valid values are: A valid host name An IP Address located on the iSeries (IP/v4 or IP/v6) LOCALHOST indicating local IP Address 127.0.0.1 CGI Indicates that the Websydian Web Server Component used is an CGI based version why we will not try to communicate with it.
Web Server Component TCP Port	12009	The TCP Port of the command port used by the Websydian Web Server Component to accept command requests.
Service name	SVCNAME	The name used to uniquely identify the Application Services started by the Websydian Server and Web Server Component.

Restarting the Application Service

The iSeries Application Service can be restarted by issuing the command RSTAS which is located in the Websydian runtime library. The RSTAS will end and then start each of the Application Services one by one which will make the restart not visible to the users of the web site.

Submit the iSeries Application Service using the STRAS command followed by F4.

===>WSYD610/RSTAS [F4]

                      Restart Application Services (RSTAS)                      
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Websydian home directory . . . .   '/websydian/wsyd610'                        
                                                                                
                                                                                
 Application Service Listener . .   SVCAPP        Character value               
 Websydian Server IP Address  . .   *LOCALHOST                                  
                                                                                
                                                                                
 Websydian Server TCP Port  . . .   08189         Number                        
 Web Server Component IP Addr . .   *LOCALHOST                                  
                                                                                
                                                                                
 Web Server Component TCP Port  .   08189         Number                        
 Application Service IP Address     *LOCALHOST                                  
                                                                                
                                                                                
 Application Service TCP Port . .   03860         Number                        
                                                                        Mere... 
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    
 F24=More keys

                      Restart Application Services (RSTAS)                      
                                                                                
 Type choices, press Enter.                                                     
                                                                                
 Number of services . . . . . . .   1             Number                        
 Service name . . . . . . . . . .   DWATUTOR                                    
 Job name . . . . . . . . . . . .   DWATUTOR      Character value               
 Job description  . . . . . . . .   WSYDJOBD      Name                          
   Library  . . . . . . . . . . .     WSYD610     Name                          
 Job queue  . . . . . . . . . . .   QINTER        Name                          
   Library  . . . . . . . . . . .     QGPL        Name                          
 Init library list  . . . . . . .   *JOBD         Name, *CURRENT, *JOBD...      
 User . . . . . . . . . . . . . .   *CURRENT      Name, *CURRENT, *JOBD         
                                                                                
                                                                               
                                                                        Slut 
 F3=Exit   F4=Prompt   F5=Refresh   F12=Cancel   F13=How to use this display    
 F24=More keys

Parameter	Default Value	Description
Websydian home directory	/websydian/wsyd610	Directory in the IFS where required Websydian runtime objects are located
Application Service Listener	MyAppSvc	The implementation name of the function inheriting from ApplicationServiceListener
Websydian Server IP Address	*LOCALHOST	The IP address of the machine where the Websydian Server is started. This address together with the TCP port is used by the Web Server Component to connect to the Websydian Server. Valid values are: The host name of the iSeries An IP Address located on the iSeries (IP/v4 or IP/v6) *LOCALHOST indicating local IP Address 127.0.0.1
Websydian Server TCP Port	08189	The TCP port of the Websydian Server. The port is used together with the IP address by the Web Server Component to connect to the Websydian Server.
Web Server Component IP Addr	*LOCALHOST	The IP address of the machine where the Websydian Web Server Component is located. Valid values are: A valid host name An IP Address located on the iSeries (IP/v4 or IP/v6) LOCALHOST indicating local IP Address 127.0.0.1 CGI Indicates that the Websydian Web Server Component used is an CGI based version why we will not try to communicate with it.
Web Server Component TCP Port	12009	The TCP Port of the command port used by the Websydian Web Server Component to accept command requests.
Application Service IP Address	*LOCALHOST	The IP address of the machine where the Application Services are started. This address together with the TCP port is used by the Web Server Component to connect to the Application Services. Valid values are: The host name of the iSeries An IP Address located on the iSeries (IP/v4 or IP/v6) *LOCALHOST indicating local IP Address 127.0.0.1
Application Service TCP Port	11001	The TCP port of the first Application Service to be started. The port is used together with the IP address by the Web Server Component to connect to the Application Service.
Number of Application Services	1	The number of Application Services to start starting at the TCP port specified by 'Application Service TCP Port' and incrementing this by one for each additional Application Services started.
Service name	SVCNAME	The name used to uniquely identify the Application Services started by the Websydian Server and Web Server Component.
Job name	DWAAS	Job name to be used by the Application Services
Job description	WSYD610/WSYDJOBD	Job description used for submitting the Application Services to batch
Job queue	QGPL/QINTER	Job queue used for submitting the Application Services to batch
Init library list	*JOBD	Initial library list to be used
User	*CURRENT	The user to be used for submitting the Websydian Server to batch

Troubleshooting the iSeries Application Service

When troubleshooting the iSeries Application Service check for the following:

Make sure that the job has been submitted and is not waiting in the job queue.
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]
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 iSeries Application Service.
Use the command WRKOUTQ to view the contents of the output queue QEZJOBLOG

===>WRKOUTQ QEZJOBLOG [Enter]

The joblog created by the iSeries often shows the reason for the end of the iSeries Application Service. This is a list of the most common errors:

Job Description error, user not correct, library list incorrect etc.

Change the job description used and start the iSeries Application Service again.

The iSeries Application Service reports a Websydian error message

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 was 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. Check the document Starting Websydian Server on iSeries for information on how to do this.