Deploying CWA applications on iSeries (Apache HTTP Server and IBM HTTP Server)

Contents

• Introduction

• Copy the document templates to the iSeries

• Setup the iSeries environment

• Setup correct character translation information

• Create Websydian data queues

• Configure the IBM HTTP Web Server

• Configure the iSeries Apache Web Server

• Further reading/information

• Troubleshooting

  • What is the correct method of ending and restarting the Websydian queues

Introduction

This white paper describes the basic steps to deploy a CWA Websydian application on the iSeries platform using either IBM HTTP Server or Apache HTTP Server.
Basic knowledge about the iSeries platform is required in order to successfully complete this white paper.

Prerequisites:

• A Websydian application generated and built using the variant "iSeries web server" ("AS/400 web server" for Websydian versions prior to v3.1) for the WSYBASE library model. The version/level should be set to the latest for all Websydian group models.
  If using v3.0 or later the version for WSYBASE should be set to "v.x.x RPG" where x.x is the Websydian version number.
• An iSeries installed with the Apache HTTP Server or IBM HTTP Server.
• The screenshots in this white paper is taken using Websydian 5.5. If using an earlier version of Websydian some screenshots may not apply, but the text covers all versions of Websydian back to 2.0.
• The Websydian iSeries run-time library should be installed on the iSeries machine. The Websydian run-time library is named WSYDxxx where xxx is the Websydian version number, e.g. WSYD600 for Websydian v6.0.

Copy the document templates to the iSeries

Copy the Document Templates to an iSeries folder in the IFS, e.g. /WEBTUTOR.

Setup the iSeries environment

1. Copy the job description WSYDJOBD from the Websydian library WSYDxxx to the library where the application resides. 
   Change the initial library list in the job description to hold the library where the Websydian application resides.
   Example of the initial library list:

   QTEMP
   WEBTUTOR
   WSYD600PTF
   WSYD600
   PLEX500
   QGPL

   If needed change the user profile for the job description. Default is YOBSYDIAN.
    

2. Check that the user profile used in the job description has the following authorities and settings:

• If using the HFS to store the folders, the user profile used in the job description must be created in the directory entry so the Websydian application has access to the templates in the folder system. Use the command DSPDIRE to verify this.
• The user has authority to use the folder where the templates reside. 
• The user has authority to use the library where the Websydian applications resides including the WSYDxxx library. 
• The user has authority to use the databases used by the Websydian application. 
• Make sure the user profile QTMHHTP1 has at least *USE authority to programs, and any files referenced by the Websydian application. 
• Make sure the user profile QTMHHTP1 is not disabled (*DISABLED). Use the command DSPUSRPRF to verify this.

3. Copy the data area WSYDPATH from the library WSYDxxx to the library of the Websydian application. Modify the data area to reflect the location of your document templates. e.g. /WEBTUTOR/ or /QDLS/WEBTUTOR/.
    

Setup correct character translation information

The iSeries uses the EBCDIC character set but document templates are stored in ASCII and the web server also sends and receives information from the browser using ASCII (or more correctly ISO-8859-1).

For this reason the Websydian application must be configured with relevant information about the character sets used so the correct character translation can take place.

For document templates

In Websydian 3.0 and later the character set identifier (CCSID) of the document templates should be stored in the data area IFSCCSID. Default is 01252 (Windows Latin-1).

In Websydian 2.5 and prior the character translation of the document templates are handled by the translation table ASCII2E. The default table complies with Windows Latin-1.

For input and output to the Web Server

In Websydian 3.1 the character translation of inbound and outbound URL encoded characters are handled by the data areas CGIICCSID and CGIOCCSID.

In Websydian 3.0x and prior the translation of inbound URL encoded characters are handled by the translation table WLATIN2E. The default supplied table complies with Western Latin-1.

n this white paper we will use the facility of the web server to translate all in and outbound characters and you should make sure the data areas are set to 65535 and if using Websydian 3.0 or prior use a dummy table for the WLATIN2E translation table.
The value 65535 indicates that no translation will be performed by the Websydian application.

For further information on CCSID's see the iSeries manual:
Title: AS/400 International Application Development V4R2
Document Number: SC41-5603-01
Build Date: 12/01/97 19:46:21 Build Version: 1.3.0
Book Path: /home/publib/epubs/book/qb3aq501.boo

Create Websydian data queues

This white paper assumes that the Web Server and the application resides on the same iSeries machine. It is possible to have the Web Server and the application on two different iSeries machines. For more information on how to do this please consult the Websydian documentation.

Run the command WSYDCRTQ found in the library WSYDxxx.

The WSYDCRTQ command starts the Websydian data queues and a listener job for these. The data queues are used to pass information from the Web Server to the Websydian application. More information can be found here. 

To ease any troubleshooting during development, only start one queue.

The parameters are described here. As all parameters are important it is essential that all the settings above are understood.

Configure the IBM HTTP Web Server

If using the Apache HTTP Web Server skip this section and proceed with the next.

To use the commands described in this section you must have QSECOFR rights.

Run the command WRKHTTPCFG CFG(x) to configure the Web Server where x is the name of the server configuration. Default is CONFIG.

With reference to the tutorial the lines inserted into the configuration file would be. 

Fail /tutorial.dum/*
Map /websydian/tutorial.exe /tutorial.dum/cgidtaq.pgm
Exec /tutorial.dum/* /QSYS.LIB/YTUTORIAL.LIB/* %%EBCDIC/EBCDIC%%

When the web server process a request it is done sequentially through the configuration file.

• The Map directive maps the request /websydian/tutorial.exe to the program the Web Server should start (CGIDTAQ.PGM).
• The Exec directive gives execute permissions to all programs in the /tutorial.dum/ folder and at the same time specifies that the folder maps to the YTUTORIAL library.
  The last option specifies that the Web Server should translate all requests/responses for the Websydian application between EBCDIC and ASCII. Alternatively the directive CgiConvMode can be used to specify the translation mode, but then it will apply to all applications on the Web Server, e.g. CgiConvMode %%EBCDIC/EBCDIC%%.
• The Fail directive prohibits the user from requesting the site /tutorial.dum/* and thereby executing any program in that folder.

With the directives above a user would reference the Websydian application as http://www.mywebserver.com/websydian/tutorial.exe.

Configure the iSeries Apache Web Server

If using the IBM HTTP Web Server skip this section and read the previous section instead.

To use the commands described in this section you must have QSECOFR rights.

The examples in this section uses the default Apache configuration called APACHEDFT that is installed by default when installing OS/400 on the iSeries.

There are two ways to configure the Apache Web Server: Using the web administration interface or altering the configuration files manually (used in this white paper).

Use the command WRKLNK to find the file /www/apachedft/conf/httpd.conf and select option 2 (edit).

Add a script alias and directory section for servicing the Websydian application.

1. Add a ScriptAlias statement to the configuration file:
   
   ScriptAlias /Webtutor/Webtutor.exe /qsys.lib/webtutor.lib/cgidtaq.pgm
   
   "/Webtutor/Webtutor.exe" is the URL used to access the Websydian application from a browser.
   "/qsys.lib/webtutor.lib/cgidtaq.pgm" is the program executed by the Web Server.
    
2. Add a directory section for the library where the program resides
   
   <Directory /qsys.lib/webtutor.lib>
       AllowOverride None
       UseCanonicalName Off
       HostNameLookups Off
       Options +ExecCGI
       Order allow,deny
       Allow from all
       CGIConvMode %%EBCDIC/EBCDIC%%
   </Directory>
   
   "Options +ExecCGI" indicates that the Apache server may execute programs from this directory.
   "CGIConvMode %%EBCDIC/EBCDIC%%" indicates that the Apache server is to perform all translation of in- and outbound characters from ASCII to EBCDIC and vice versa.
    

Add an alias and directory section for servicing images, static HTML pages, Style Sheets, etc.

1. Add an Alias statement to the configuration file:
   
   Alias /Webtutor /myfiles/Webtutor
   
   "/Webtutor" is the alias to use e.g. /Webtutor/myimage.gif.
   "/myfiles/webtutor" is the directory where to find the files.
    
2. Add a directory section for the directory where the files reside
   
   <Directory /myfiles/Webtutor>
       AllowOverride None
       UseCanonicalName Off
       HostNameLookups Off
       Options -ExecCGI
       Order allow,deny
       Allow from all
   </Directory>
   
   "Option -ExecCGI" makes sure that no execution of files are performed.
    

Restart the Web Server using the command STRTCPSVR. Always remember to restart the Web Server when configuration files have been changed.

STRTCPSVR SERVER(*HTTP) RESTART(*HTTP) HTTPSVR(APACHEDFT)

Further Reading / Information

For information on iSeries and Websydian go to the site http://doc.websydian.com/Websydian/Installing/as400help/Default.htm

For further information about the Apache Web Server go the to following sites

• Ignite/400 - iSeries E-Business User Group (http://www.ignite400.org)

  • Getting Started with Apache - Part I,  by Bob Cancilla
  • IBM's Apache Based HTTP Server - Part II, By Bob Cancilla
  • IBM’s Apache Based HTTP Server - Part III Virtually Enabled, By Bob Cancilla

• IBM HTTP Server Home (http://www1.ibm.com/servers/eserver/iseries/software/http/)
   
• The Apache Software Foundation (http://www.apache.org/)
   
• iSeries Magazine (http://eservercomputing.com/iseries/)
   
  • Installing Apache - A step-by-step configuration of the IBM HTTP Server (powered by Apache)

    By Michael Ryan

For additional information on the IBM HTTP Web Server please refer to the IBM manual:

Title: HTTP Server for AS/400 Webmaster's Guide V4R4
Document Number: GC41-5434-04.

Troubleshooting

• What is the correct method of ending and restarting the Websydian queues?

  In order to end the Websydian data queues use the command WSYDDLTQ. For starting the Webydian queues again call the WSYDCRTQ.