Installing LANSA on IBM i

Installing LANSA on IBM i

· About This Guide

· Start Here

· Planning a new Installation on IBM i

· Install LANSA on IBM i

· Upgrade LANSA on IBM i

· LANSA System i License

· LANSA for the Web Configuration and Set Up on IBM i

· LANSA Integrator Configuration and Set Up on IBM i

· Other Configuration and Setup Tasks on IBM i

· Troubleshooting

· Using Independent Auxiliary Storage Pool (IASP)

· Appendix A. System i Objects & Parameters

· Appendix B. IBM i Operator Procedures

· Appendix C. What is LANSA?

· Appendix D. LANSA Listener Configuration on IBM i

· Appendix E. Change the HTTP Install Instance

Edition Date August 7, 2012

© LANSA

Contents

About this Guide

Who should use this Guide

How to use this Guide

Additional Information

1. Start Here

1.1 Overview of Install Process

1.1.1 Upgrade LANSA on iSeries

1.1.2 Upgrade Web Server Only

1.1.3 Typical LANSA for iSeries Installation

1.1.4 LANSA for iSeries Only Installation

1.1.5 Single-tier LANSA for the Web Installation

1.1.6 Single-tier LANSA for the Web Installation (LANSA for iSeries Installed)

1.1.7 Multi-tier LANSA for the Web Installation

1.1.8 Multi-tier LANSA for the Web Installation (LANSA for iSeries Installed)

1.1.9 LANSA Integrator Installation

1.1.10 Open System Utilities Installation

1.1.11 Set up LANSA Open on IBM i

1.1.12 Set up LANSA Client on IBM i

2. Planning A New Installation on IBM i

2.1 Summary of LANSA IBM i Software Options

2.1.1 Typical LANSA for iSeries Installation

2.1.2 Custom LANSA for iSeries Installations

2.1.3 LANSA Integrator Installation

2.1.4 Upgrade LANSA for iSeries Installations

2.1.5 LANSA IBM i Software DVD or CD-ROM

2.2 Planning Considerations

2.2.1 Planning LANSA for the Web on IBM i Installations

2.3 Requirements Checklist

2.3.1 Skills Requirements

2.3.2 IBM i System Requirements

2.3.3 General Installation/Upgrade Requirements Checklist

2.3.4 LANSA for the Web Requirements

2.3.5 LANSA Integrator IBM i Requirements

2.3.6 Open System Utilities IBM i Requirements

2.4 Frequently Asked Questions

2.4.1 General Questions

2.4.2 LANSA for iSeries Questions

2.4.3 LANSA for the Web Questions

2.4.4 LANSA Integrator Questions

2.4.5 Open System Utilities Questions

3. Install LANSA on iSeries

3.1 Task: Typical Installation

3.1.1 Before You Begin Checklist

3.1.2 Call the Installation Program

3.1.3 Typical Installation Summary

3.1.4 Verify Typical Installation

3.2 Task: Custom Installation

3.2.1 Before You Begin Checklist

3.2.2 Call the Installation Program

3.2.3 Earlier Versions of LANSA

3.2.4 Select Software Components

3.2.5 Check the Custom Installation Summary

3.2.6 Verify the Custom Installation

4. Upgrade LANSA on IBM i

4.1 Task: Upgrade an Existing LANSA for iSeries System

4.1.1 Before You Begin Checklist

4.1.2 Special Warnings

4.1.3 LANSA Integrator Special Warnings

4.1.4 Start the Upgrade process

4.1.5 Select the LANSA system to be upgraded

4.1.6 Partition Initialization

4.1.7 Start the Upgrade Process

4.1.8 Verify the Upgrade

4.2 Task: Upgrade an Existing LANSA for the Web - Web Server ONLY on IBM i

4.2.1 Before You Begin Checklist

4.2.2 Start the Web Server upgrade

4.2.3 Select the Web Server to be upgraded

4.2.4 Start the Upgrade Process

4.2.5 Verify the Upgrade

4.3 Upgrade LANSA Windows Software

4.4 LANSA Communications Library

4.4.1 Change from QGPL to a LANSA Communications Library

4.4.2 Remove old Loader Objects from QGPL

4.5 Initialization Imports

4.5.1 Manual Import

4.5.2 Imports on the LANSA IBM i Software DVD or CD-ROM

5. LANSA IBM i License

5.1 Task: Enter the LANSA License Code

5.1.1 Before You Begin Checklist

5.1.2 Step 1. Sign on and Execute LANSA License Program

5.1.3 Step 2. Insert a Permanent License Code

5.1.4 Step 3. Display the License Status

5.2 Battery License

5.2.1 Using up Some Battery License Time

5.2.2 Requesting a Battery License Recharge or Replacement

5.2.3 Inserting a Battery License Recharge or Replacement

5.3 LANSA License Codes

5.3.1 LANSA License Categories

5.3.2 List of License Codes

5.3.3 General Licensing Considerations

5.4 Maintenance Contract

6. LANSA for the Web Configuration and Set Up on IBM i

6.1 Task: Install LANSA for the Web Administrator and Function Editor

6.2 Task: Configure IBM i Web Server (powered by Apache)

6.3 Task: Configure Multi-tier IBM i LANSA for the Web Installation

6.3.1 Configure LANSA for the Web on a Multi-tier IBM i Web Server

6.3.2 Configure IBM i Web Server for Communications with IBM i Data/Application Server

6.4 Task: Upgrade from a Single-tier to a Multi-tier IBM i Web Model

6.4.1 Before You Begin Checklist

6.4.2 Steps for Installing Programs on the IBM i Web Server

6.4.3 Other Considerations When Changing to Multi-tier

6.5 Task: Install the e-Business Framework Wizard on IBM i

6.5.1 Before You Begin Checklist

6.5.2 IBM i Import of LWEBWIZ2 Option

6.5.3 Test the Wizard Installation

6.5.4 Wizard Security Configuration

6.6 Task: Configure LANSA for the Web Security

6.6.1 Introduction to LANSA for the Web Security

6.6.2 No User Authentication - Anonymous User Access

6.6.3 Full User Authentication

6.6.4 Partial User Authentication - Process Level Security

6.6.5 Modifying Multi-tier IBM i LANSA for the Web User Information

6.6.6 Modifying IBM i Validation Lists

6.7 Task: Set up IBM i Partition for Web Development

6.7.1 Before You Begin Checklist

6.7.2 IBM i Import of LWEBSF & WEBLETS

6.7.3 Web Enable IBM i Partition using LANSA for the Web Administrator

6.7.4 Optional: Default User for the IBM i Partition

6.8 Task: LANSA for the Web Housekeeping

6.8.1 IBM i Clean Up System

6.8.2 Hold/Release LANSA for the WEB Systems

6.8.3 Pre-Start the IBM i Web Jobs

6.8.4 Pre-start the IBM i Transaction Monitor

6.8.5 HTTP Header Variables Support

6.8.6 Web and IBM i User Profiles

6.8.7 Considerations When Exporting LANSA for the Web Applications

6.8.8 Considerations When Importing LANSA for the Web Applications

6.8.9 Storing Application Images

6.8.10 Program Summary for LANSA for the Web on IBM ii

7. LANSA Integrator Configuration and Set Up on IBM i

7.1 Task: Configure the Java Service Manager on IBM i

7.2 Task: Configure JSMDirect on an IBM i

7.3 Task: Install LANSA Integrator Software on Windows PC

8. Other Configuration and Setup Tasks on IBM i

8.1 Task: LANSA Open Setup on IBM i

8.1.1 Preparing LANSA for iSeries for LANSA Open

8.1.2 Adjusting the DC@A1O Buffer/Data Area

8.1.3 TCP/IP and LANSA Listeners

8.2 Task: LANSA Client Setup on IBM i

8.3 Task: LANSA Email Setup on IBM i

8.3.1 Step 1. Configure TCP/IP

8.3.2 Step 2. Configure Simple Mail Transfer Protocol (SMTP)

8.3.3 Step 3. Setup the Mail Server Framework (MSF)

8.3.4 Step 4. Set System Value QUTCOFFSET

8.3.5 Step 5. Grant object authorities to the LANSA Product Owner

8.3.6 Step 6. Test your Configuration

8.3.7 Sample LANSA Email Function

8.4 Task: Test LANSA for iSeries on IBM i

8.4.1 Before You Begin Checklist

8.4.2 Step 1. Log on to LANSA

8.4.3 Step 2. Create a Test Process and Function

8.4.4 Step 3. Compile the Test Function

8.4.5 Step 4. Execute the Test Function

8.5 Task: Test LANSA for the Web

8.6 Testing using the DEM Partition

8.6.1 Personnel System Demonstration Files

8.7 LANSA for iSeries - What's Next?

8.7.1 Learning About LANSA

8.7.2 Getting Started with LANSA for iSeries

8.7.3 System Settings

8.7.4 Installing Other Products and IBM i Tasks

9. Troubleshooting

9.1 Troubleshooting Checklist

9.2 Troubleshooting LANSA Listener on IBM i

9.2.1 What should I see if the i5/OS Listener is running?

9.2.2 How do I know if the i5/OS Listener port is active?

9.2.3 How do I know if the port is accessible from the Internet?

9.2.4 The Listener i5/OS sub-system starts but there are no jobs

9.2.5 The Listener i5/OS sub-system starts and a job starts and then stops. There are no jobs running.

9.3 Troubleshooting Email Setup

9.3.1 Finding the Email Problem

9.3.2 LANSA Email Tracing

9.4 Web Troubleshooting

9.4.1 How can I test if I have a problem with my Web Server configuration?

9.4.2 Where do I look for details about problems using i5/OS?

9.4.3 What if my functions are not responding on the IBM i?

9.4.4 Is there a simple WebEvent test function I can use to test my web configuration?

9.4.5 Is there a simple WAM I can use to test my web configuration?

9.4.6 Is there a simple way to review my system and web configuration settings?

9.4.7 How do I restart the LANSA for the Web monitors?

9.4.8 What if my buttons do not work properly in my applications?

9.4.9 What if my graphic variables do not work properly in my applications?

9.4.10 What if my images do not appear in my applications?

Appendix A. IBM i Objects & Parameters

Summary of Installed Objects

Objects Created but not Deleted by LANSA_CLN

LANSA IBM i Install/Upgrade Data Areas

DCXLOADA01

DCXLOADA02

DCXLOADA04

DCXLOADA05

Appendix B. IBM i Operator Procedures

How to check for Active Users

Back up your Libraries

If not using QOTHPDOWN as the Product Owner

Identify your IBM i Details

Check LANSA_CLN

Appendix C. What is LANSA?

What is LANSA for iSeries?

What is Visual LANSA?

What is Visual LANSA Framework?

What is LANSA for the Web?

What is the e-Business Framework Wizard?

Web Application Modules (WAMs)

What is Commerce Edition?

What is the LANSA Integrator?

LANSA Composer

What is LANSA Open?

What are the Open System Utilities for IBM i?

What is LANSA Client?

Appendix D. LANSA Listener Configuration on IBM i

Configure LANSA Listener on the IBM i Data/Application Server

What is a Listener?

Before You Begin Checklist

Step 1. Sign On to IBM i

Step 2. Create Listener Job Queue

Step 3. Create Listener Job Description

Step 4. Create Listener Subsystem Description

Step 5. Add Listener Job Queue Entry

Step 6. Add a Listener Auto Start Job Entry

Step 7. Add a Listener Routing Entry

Step 8. Add a Second Listener Routing Entry

Step 9. Start the Listener Subsystem

Step 10. Verify Listener is Active

Configure LANSA Communications Extensions on the IBM i

Before You Begin Checklist

Step 1. Work with Configuration Items

Step 2. Review Communication Definition

Step 3. Work with Listener Records

Appendix E. Change the HTTP Install Instance

TOC \n \h \z \t "Heading 2,2,Heading 3,3,Heading 4,3"


About this Guide

This guide has been created for LANSA Version 12 SP1.

Before you use this guide, you should review the following:

Who Should Use This Guide

How To Use This Guide

Additional Information.

For the latest product information and updates, please refer to the technical information section of the LANSA Web site at www.LANSA.com/support

Note: The information in this guide is specific to the LANSA Version 12 SP1 software and cannot be used with earlier versions. If you are installing an earlier version, please be sure to use the related version's guides and installation media.


Who should use this Guide

This guide has been written for IBM i system administrators or developers who are responsible for installing and maintaining the LANSA development and execution environments.

It describes the installation of LANSA software components on an IBM i Server.

The LANSA software installation may include the following:

· LANSA for iSeries

· LANSA for the Web

· LANSA Integrator

· Open Systems Utilities.

It is assumed that the installer has some knowledge of the I5/OS operating system.


How to use this Guide

The Installing LANSA on IBM i guide has been designed for online access. Information has been cross-referenced to help you understand how the installation parameters from one step relate to the next step. If you are using a printed version of this guide, you will not have the hyperlinks available. It will be helpful to have access to the online version of this guide during the installation.

This guide contains detailed instructions for the installation and upgrade of LANSA software products on the IBM i platform.

The Start Here section provides a high level roadmap of the LANSA software installation on Windows. Whether you are new to LANSA or are familiar with the installation/upgrade process, it is strongly recommended that you begin with Start Here. This section provides a summary of the tasks that you will need to complete.

If you are not familiar with the LANSA family of products, review What is LANSA? This section describes the software products and their basic architecture.

If this is your first time installing a LANSA system, review the Planning a New Installation before you begin the installation process.

It is recommended that you review the IBM i Requirements Checklist before you begin the software installation. This section provides general guidelines, and the hardware and software requirements for the LANSA software.

The remainder of the guide is divided into specific product installation tasks.

If you encounter any problems during the installation, please refer to Troubleshooting.

You will require the Installing LANSA on Windows Guide in order to complete the installation or upgrade of any LANSA products on Windows. For example, LANSA for the Web and LANSA Integrator have Windows-based development utilities.


Additional Information

For more details about installing, configuring or troubleshooting LANSA software, you may need to refer to these guides:

· Installing LANSA on Windows

· Introduction to LANSA for iSeries

· LANSA Communications Set Up

· LANSA Integrator

· LANSA Open.

For the latest product information, refer to the LANSA product Web site at www.LANSA.com/support

Before you contact your local vendor for technical support, please review the Troubleshooting information. In particular, be sure to review the Troubleshooting Checklist. If your problem involves LANSA for the Web, be sure to review the Troubleshooting information in the Installing LANSA on Windows Guide.

For additional information about Web serving using the IBM IBM i, refer to these guides:

· SC41-5430 - TCP/IP Fastpath Setup

· SC41-5420 - TCP/IP Configuration and Reference

· SG24-4815 - Cool Title about the AS/400 & Internet (You can see more IBM Red Books at http://www.redbooks.ibm.com/redbooks.nsf/redbooks/ )

Your feedback will help us improve the overall quality of the LANSA documentation and training. Please email your comments to lansatraining@LANSA.com.au

You will require the Installing LANSA on Windows Guide in order to complete the installation and configuration of LANSA for the Web.


1. Start Here

The i5/OS program LODRUN performs the LANSA install/upgrade process. The program has four options. You will use one or more of these options, depending on your requirements, to install or upgrade your LANSA software.

The options are:

· Typical Installation

· Custom Installation

· LANSA Integrator Installation

· Upgrade LANSA on iSeries

This software will only install on i5/OS V5R4 or higher.

Note: The Upgrade option is only available if the program finds a LANSA component.

If you know the type of LANSA installation required, go to Overview of Install Process. If unsure, refer to Planning a New Installation on IBM i.

The LANSA IBM i Software DVD or CD-ROM contains the guided install menu.


1.1 Overview of Install Process

The table guides you through the steps required for a particular installation or upgrade. Select either the appropriate heading to jump to a list of the steps you need to perform, or select the steps from the table.
If you're unsure which installation you require, refer to Planning a New Installation on IBM i for guidance.

Upgrade LANSA on IBM i

Install Tasks:
1. Upgrade an Existing LANSA for iSeries System.

2. Upgrade LANSA Windows Software.

License Tasks:

Web Tasks:

Integrator Tasks:

Other Tasks:

Review:
LANSA on IBM i - What's Next?

Upgrade Web Server Only

Install Tasks:

1. Task: Upgrade an Existing LANSA for the Web - Web Server ONLY on IBM i.

License Tasks:

Web Tasks:

Integrator Tasks:

Other Tasks:

Review:

LANSA on IBM i - What's Next?

Typical LANSA for iSeries Installation

Install Tasks:

1. Typical Installation.

License Tasks:

2. Enter the LANSA License Code

Web Tasks:

3. Install LANSA for the Web Administrator and Function Editor.

Integrator Tasks:

Other Tasks:

4. Test LANSA on IBM i and do the Simple LANSA for the Web's WebEvent's test on IBM iOptional:

5. LANSA Email Setup on System i.

6. Configure Web Security.

Review:

LANSA on IBM i - What's Next?

LANSA for iSeries Only Installation

Install Tasks:
1. Custom Installation (Component LANSA for iSeries).

License Tasks:
2. Enter the LANSA License Code

Web Tasks:

Integrator Tasks:

Other Tasks:

3. Test LANSA on IBM i.

Review:

LANSA on IBM i - What's Next?

Single-tier LANSA for the Web Installation

Install Tasks:
1. Custom Installation - (Components LANSA for iSeries and LANSA for the Web).

License Tasks:
2. Enter the LANSA License Code

Web Tasks:
3. Install LANSA for the Web Administrator and Function Editor.

4. Configure IBM i Web Server.

Integrator Tasks:

Other Tasks:
5. Test LANSA on System i & Test LANSA for the Web.

Optional:
6. LANSA Email Setup on System i.

7. Configure Web Security.

Review:
LANSA on IBM i - What's Next?

Single-tier LANSA for the Web Installation (LANSA for iSeries Installed)

Install Tasks:
1. Custom Installation- (Component: LANSA for the Web ).

License Tasks:
2. Enter the LANSA License Code

Web Tasks:
3. Install LANSA for the Web Administrator and Function Editor.

4. Configure IBM i Web Server.

Integrator Tasks:

Other Tasks:
5. Test LANSA for the Web.

Optional:
6. LANSA Email Setup on System i.

7. Configure Web Security.

Review:
LANSA on IBM i - What's Next?

Multi-tier LANSA for the Web Installation

On the Data/Application Server:

Install Tasks:
1. Custom Installation (Components LANSA for iSeries and LANSA for the Web )

License Tasks:
2. Enter the LANSA License Code

Web Tasks:
3. Install LANSA for the Web Administrator and Function Editor.

Integrator Tasks:

Other Tasks:

4. Optional:
LANSA Email Setup on IBM i.

Review:

On the Web Server:

Install Tasks:
1. Custom Installation - (LANSA for the Web - Web Server Only )

License Tasks:

Web Tasks:
2. Configure Multi-tier LANSA for the Web Installation.

3. Configure Web Server on System i.

Integrator Tasks:

Other Tasks:

Review:

On the Data/Application Server:

Install Tasks:

License Tasks:

Web Tasks:

Integrator Tasks:

Other Tasks:

1. Test LANSA on IBM i and Test LANSA for the Web.

Review:
LANSA on IBM i - What's Next?

Multi-tier LANSA for the Web Installation (LANSA for iSeries Installed)

On the Data/Application Server:

Install Tasks:
1. Custom Installation - (Component: LANSA for the Web )

License Tasks:
2. Enter the LANSA License Code

Web Tasks:
3. Install LANSA for the Web Administrator and Function Editor.

Integrator Tasks:

Other Tasks:

4. Optional:
LANSA Email Setup.

Review:

On the Web Server:

Install Tasks:
1. Custom Installation - (LANSA for the Web - Web Server Only ).

License Tasks:

Web Tasks:
2. Configure Multi-tier LANSA for the Web Installation.

3. Configure IBM i Web Server.

Integrator Tasks:

Other Tasks:

Review:

On the Data/Application Server:

Install Tasks:

License Tasks:

Web Tasks:

Integrator Tasks:

Other Tasks:

1. Test LANSA for the Web.

Review:
LANSA on IBM i - What's Next?

LANSA Integrator Installation

Install Tasks:
1. LANSA Integrator Installation if installing LANSA Integrator alone
or

Custom Installation (select component LANSA Integrator )

License Tasks:
Your LANSA Integrator license is recorded during the Configure the Java Service Manager on IBM i
in the Integrator Tasks.

Web Tasks:

Integrator Tasks:
2. Configure the Java Service Manager on IBM i.

3. Configure JSMDirect on System i.

4. Install LANSA Integrator Software on Windows PC.

5. Test the Java Service Manager on IBM i.

Other Tasks:

Review:
LANSA on IBM i - What's Next?

Open System Utilities Installation

Install Tasks:
1. Custom Installation (Component Open System Utilities )

License Tasks:

Web Tasks:

Integrator Tasks:

Other Tasks:

Review:
LANSA on IBM i - What's Next?

Set up LANSA/Server (LANSA Open) on IBM i

Install Tasks:

License Tasks:

Web Tasks:

Integrator Tasks:

Other Tasks:

1. LANSA Open (LANSA/Server) Setup on IBM i.

Review:
LANSA on IBM i - What's Next?

Set up LANSA Client on IBM i

Install Tasks:

License Tasks:

Web Tasks:

Integrator Tasks:

Other Tasks:

1. LANSA Client Setup on System i.

Review:
LANSA on IBM i - What's Next?


1.1.1 Upgrade LANSA on iSeries

If you are upgrading existing LANSA iSeries Software, then you should complete these tasks:

1. If your LANSA version is Version 11.3 or higher, go straight to the Task: Upgrade an Existing LANSA iSeries System to upgrade to Version 12 SP1.

2. If you have a LANSA system earlier than Version 11.3, you must update your system to Version 11.3 or higher before continuing with this upgrade. Please contact your LANSA vendor for the software required to update to Version 12.

3. When your IBM i is updated to this current version, go to Upgrade LANSA for Windows Software to consider the Windows software that needs to be upgraded to match your IBM i software.

4. If you have a Multi-tier LANSA for the Web Installation, you must also complete the Upgrade Web Server Only on IBM i.

If you encounter problems, refer to Troubleshooting.

After completing these steps, review the LANSA for iSeries - What's Next?


1.1.2 Upgrade Web Server Only

If you are using a Multi-tier LANSA for the Web Installation, you will have LANSA for the Web software installed on a separate IBM i machine acting as the Web Server. This IBM i machine may not have a LANSA for iSeries system installed. Only the Web Server software for LANSA for the Web needs to be installed on the machine.

1. On the Web Server, complete the Task: Upgrade an Existing LANSA for the Web - Web Server Only on IBM i.

If you encounter problems, refer to Troubleshooting.

After completing these steps, review the LANSA for iSeries - What's Next?


1.1.3 Typical LANSA for iSeries Installation

If you are using the Typical Installation, then complete these tasks:

1. Complete the Task: Typical Installation.

2. Task: Enter the LANSA License Code.

3. Task: Install LANSA for the Web Administrator & Editor.

4. Task: Test LANSA for iSeries and carry out the Simple WebEvent Test for LANSA for the Web on IBM i Data/Application Server.

5. Task: LANSA Email Setup on IBM i if you are planning to use email with LANSA.

Before you begin development with LANSA for the Web, you may wish to review the Task: Configure LANSA for the Web Security.

If you encounter problems, refer to Troubleshooting.

After completing these steps, review LANSA for iSeries - What's Next?


1.1.4 LANSA for iSeries Only Installation

If you are only installing a new LANSA for iSeries system (and LANSA for the Web is NOT to be installed), complete the following tasks:

1. Task: Custom Installation and select the Component: LANSA iSeries.

2. Task: Enter the LANSA License Code.

3. Task: Test LANSA for iSeries.

If you encounter problems, refer to Troubleshooting.

After completing these steps, review LANSA for iSeries - What's Next?


1.1.5 Single-tier LANSA for the Web Installation

If you are installing a new LANSA for iSeries system that includes LANSA for the Web on a single IBM i Server (and you have decided not to use the Typical installation), then complete these tasks:

1. Task: Custom Installation and select the LANSA iSeries and LANSA for Web - Complete Web Install components.

2. Task: Enter the LANSA License Code.

3. Task: Install LANSA for the Web Administrator & Editor.

4. Task: Configure IBM i Web Server.

5. Task: Test LANSA for iSeries and carry out the Simple WebEvent Test for LANSA for the Web on IBM i Data/Application Server.

6. Task: LANSA Email Setup on IBM i if you are planning to use email with LANSA.

Before you begin development with LANSA for the Web, you may wish to review the Task: Configure LANSA for the Web Security.

If you encounter problems, refer to Troubleshooting.

After completing these steps, review LANSA for iSeries - What's Next?


1.1.6 Single-tier LANSA for the Web Installation (LANSA for iSeries Installed)

If you already have a LANSA for iSeries system installed, and you wish to install LANSA for the Web for the first time, then follow these steps.

Your LANSA for iSeries system must be at Version 12 SP1. If not, go to 1.1.1 Upgrade LANSA on iSeries before starting these steps.

1. Install the Web components using Custom Installation and select the LANSA for Web - Complete Web Install component.

2. Task: Enter the LANSA License Code.

3. Task: Install LANSA for the Web Administrator & Editor.

4. Task: Configure IBM i Web Server.

5. Simple WebEvent Test for LANSA for the Web on IBM i Data/Application Server.

6. Task: LANSA Email Setup on IBM i if you are planning to use email with LANSA.

Before you begin development with LANSA for the Web, you may wish to review the Task: Configure LANSA for the Web Security.

If you encounter problems, refer to Troubleshooting.

After completing these steps, review LANSA for iSeries - What's Next?


1.1.7 Multi-tier LANSA for the Web Installation

If you are installing LANSA for the Web using two IBM i servers, it is recommended that you start with a Single-tier LANSA for the Web Installation. Once you have LANSA for the Web working in a Single-tier environment, you can convert to a Multi-tier installation as described in the Task: Upgrade from a Single-tier to a Multi-tier IBM i Web Model.

A Multi-tier installation involves the installation of LANSA software on both the Data/Application Server and the Web Server.

If you are installing a new LANSA for iSeries system that includes LANSA for the Web in a Multi-tier configuration, then you should follow these steps:

On the Data/Application Server:

To install a new LANSA for the Web system on the Data/Application Server, complete the following tasks:

1. Task: Custom Installation and select the LANSA iSeries and LANSA for Web - Complete Web Install components.

2. Task: Enter the LANSA License Code.

3. Task: Install LANSA for the Web Administrator & Editor.

4. Task: LANSA Email Setup on IBM i if you are planning to use email with LANSA.

See a further step for the Data/Application Server below.

On the Web Server:

To install the LANSA for the Web software components on the Web Server, complete the following tasks:

1. Task: Custom Installation and select the LANSA for the Web - Web Server ONLY Installation component.

2. Task: Configure Multi-tier IBM i LANSA for the Web Installation.

3. Task: Configure IBM i Web Server.

On the Data/Application Server:

Complete the following tasks:

1. Task: Test LANSA for iSeries and do the Simple WebEvent Test for LANSA for the Web on IBM i Data/Application Server.

If you encounter problems, refer to Troubleshooting.

Before you begin development with LANSA for the Web, you may wish to review the Task: Configure LANSA for the Web Security.

After completing these steps, review LANSA for iSeries - What's Next?


1.1.8 Multi-tier LANSA for the Web Installation (LANSA for iSeries Installed)

A Multi-tier installation involves the installation of LANSA software on both the Data/Application Server and the Web Server.

If you already have a LANSA for iSeries system installed, and you wish to install a Multi-tier LANSA for the Web for the first time, then follow these steps:

On the Data/Application Server:

Your LANSA for iSeries system must be at Version 12 SP1. If not, go to Upgrade LANSA on iSeries before starting these steps.

To install a new LANSA for the Web system on the Data/Application Server, complete the following tasks:

1. Install the Web components using the Custom Installation and selecting the LANSA for Web - Complete Web Install component.

2. Task: Enter the LANSA License Code.

3. Task: Install LANSA for the Web Administrator & Editor.

4. Task: LANSA Email Setup on IBM i if you are planning to use email with LANSA.

See a further step for the Data/Application Server below.

On the Web Server:

To install the LANSA for the Web software components on the Web Server, complete the following tasks:

1. Task: Custom Installation and select the LANSA for the Web - Web Server ONLY Installation component.

2. Task: Configure Multi-tier IBM i LANSA for the Web Installation.

3. Task: Configure IBM i Web Server.

On the Data/Application Server:

1. Complete the Simple WebEvent Test for LANSA for the Web on IBM i Data/Application Server .

If you encounter problems, refer to Troubleshooting.

Before you begin development with LANSA for the Web, you may wish to review the Task: Configure LANSA for the Web Security.

After completing these steps, review LANSA for iSeries - What's Next?


1.1.9 LANSA Integrator Installation

Complete the following tasks:

1. Complete the Task: Custom Installation, selecting the LANSA Integrator Installation component
or
Select the LANSA Integrator Install option from the main window. The Integrator options will then be pre-selected for you and will be installed as a separate process.

2. Task: Configure the Java Service Manager on IBM i.

3. Configure JSMDirect on IBM i.

4. Task: Install LANSA Integrator Software on Windows.

5. Task: Test the Java Service Manager on IBM i.

If you encounter problems, refer to Troubleshooting.

After completing these steps, review LANSA for iSeries - What's Next?


1.1.10 Open System Utilities Installation

Complete the following task:

1. Task: Custom Installation, selecting the Open System Utilities component.

If you encounter problems, refer to Troubleshooting.

After completing this step, review LANSA for iSeries - What's Next?


1.1.11 Set up LANSA Open on IBM i

If you are using LANSA Open (previously called LANSA/Server) with your LANSA for iSeries system, you must complete the following task:

1. Task: LANSA Open Setup on IBM i.

After completing this task, review LANSA for iSeries - What's Next?


1.1.12 Set up LANSA Client on IBM i

If you are using the LANSA Client with your LANSA for iSeries system, you must complete the following task:

1. Task: LANSA Client Setup on IBM i.

After completing this task, review LANSA for iSeries - What's Next?.


2. Planning A New Installation on IBM i

Before you begin installing a new LANSA system, you should carefully plan your installation. Review the following sections:

Summary of LANSA IBM i Software Options

Planning Considerations

Requirements Checklist

Frequently Asked Questions.

The information in this guide is specific to the LANSA Version 12 SP1 software. It cannot be used with earlier versions of the software. If you are attempting to install an earlier version, please be sure to use the guides corresponding to the installation media.


2.1 Summary of LANSA IBM i Software Options

This section provides a high level description of the LANSA IBM i Software installation program options to assist you in determining the option that best meets your requirements.

The LANSA IBM i software installation offers you these options:

· Typical LANSA for iSeries Installation

· Custom LANSA for iSeries Installations

· LANSA Integrator Installation

· Upgrade LANSA for iSeries Installations

If you insert the LANSA IBM i Software DVD or the first CD-ROM into a Windows PC, an autorun program will open an HTML browser window displaying the LANSA for iSeries software Installation Main Menu. This menu simply describes the steps to execute the Installation Program. You cannot install the LANSA IBM i software from this interface. For more details, refer to LANSA IBM i Software DVD or CD-ROM.


2.1.1 Typical LANSA for iSeries Installation

The Typical Install is the quickest and easiest way to install a new LANSA for iSeries and LANSA for the Web system on an IBM i Server.

Use this option ONLY if you are:

· Installing a brand new LANSA system

· Installing both LANSA for iSeries and LANSA for the Web

· Using the IBM HTTP Server with CGI to access data

· Satisfied with the system configuration as described in Summary of Installed Objects. Please check that these objects will suit your site.

Single-Tier LANSA for the Web Installations

The Typical Install loads LANSA for iSeries and LANSA for the Web in a Single-tier LANSA for the Web configuration. The Web Server and the Data/Application Server are installed on a single IBM i machine. For descriptions of the available Web models, refer to Planning LANSA for the Web on IBM i Installations.

Multi-tier LANSA for the Web Installations

For multi-tier configuration, use the Typical Install to load the required LANSA for iSeries and LANSA for the Web software on the Data/Application Server. You must also use the Custom Install - Web Server Only option to install the necessary components on the Web Server. For descriptions of the available Web models, refer to Planning LANSA for the Web on IBM i Installations.


2.1.2 Custom LANSA for iSeries Installations

The Custom Install allows you to select the specific LANSA software components to be installed.

You may select from the following:

· LANSA for iSeries

· LANSA for the Web

· LANSA Integrator

· Open System Utilities

· LANSA for the Web - Web Server Only.

More than one software component may be installed at the same time. For a list of recommended combinations, see below.

Recommended installation combinations are:

· LANSA for iSeries and LANSA for the Web at the same time, if you are using LANSA for the Web.

· LANSA Integrator as a separate install.

· Open System Utilities as a separate install.

· If you perform a Web Server Only install, do not install other components at the same time. A Web Server Only is installed on a Web Server used in a multi-tier installation.

Be aware that:

· If LANSA for iSeries is already installed, you can install LANSA for the Web.
You can also install LANSA Integrator or the Open System Utilities after LANSA for iSeries has been installed.

· You can install just LANSA Integrator on a server with or without LANSA for iSeries installed.

· You would only install the Open System Utilities on an IBM i that has a LANSA for iSeries system installed.


2.1.3 LANSA Integrator Installation

If you select LANSA Integrator installation option, you will immediately be taken to the Component selection screen. LANSA Integrator component will be selected for you. Press Enter to continue to install just LANSA Integrator or F12 to return to the previous screen to change your options.


2.1.4 Upgrade LANSA for iSeries Installations

When executing the LANSA IBM i software installation, the upgrade option will automatically appear on the installation program menu if any LANSA software components are detected on the IBM i.

This easy to use upgrade facility will list all LANSA Systems and LANSA Software Components detected. You may select a single system or component for upgrade.

If your LANSA for iSeries includes LANSA for the Web software, the LANSA for the Web software is automatically updated.

Once you have upgraded the LANSA IBM i software, you should upgrade any associated LANSA Windows software.

If you wish to add new software components (refer to Custom LANSA for iSeries Installations), it is recommended that you upgrade your existing system before you install the new components.


2.1.5 LANSA IBM i Software DVD or CD-ROM

If the LANSA IBM i Software DVD or first CD-ROM is inserted into a Windows PC, an auto run program will open an HTML browser window displaying the LANSA for iSeries Software Installation Main Window. (If this screen does not appear automatically, use Windows Explorer to open the index.htm file.)

This screen lists, in the left hand menu, the various items you might wish to review. Press menu item: Installation to open the next window which shows you the steps you will take to run the install process. This is the same information as you will see in the Installing LANSA on iSeries Guide.

Remove the DVD or CD from the PC's drive and place it in an IBM i drive to continue with the install or upgrade, as required. You cannot install the LANSA IBM i software from a PC.


2.2 Planning Considerations

This section provides a description of the different LANSA installations to assist you in selecting the type of installation that best meets your requirements.

If you are installing LANSA for the Web on IBM i, you must also decide between single-tier and multi-tier models. Review the following:

Planning LANSA for the Web on IBM i Installations

If you are using an Independent Auxiliary Storage Pool then please refer to Using Independent Auxiliary Storage Pool (IASP) for further information before you begin the installation.


2.2.1 Planning LANSA for the Web on IBM i Installations

The LANSA for the Web IBM i Architecture supports both single-tier and multi-tier installations.

A single-tier installation includes the Web Server and Data/Application Server on a single IBM i server.

A multi-tier installation uses two IBM i servers. The Web Server is located on one IBM i server and the Data/Application Server is located on a second IBM i Server. The LANSA for iSeries software and the LANSA for the Web software are always installed on the Data/Application Server. For a multi-tier installation, additional Web components must be installed on the Web Server. LANSA for the Web supports CGI for communication.

Using a multi-tier model can provide an additional level of security by limiting the exposure of your Data/Application Server directly to the Internet.

You may use an IBM i to act as both your Web Server and Data/Application Server for your Internet applications. If this server is separate from your other internal production systems, a single-tier model is appropriate. If your Web site is used for an Intranet (which is not connected to the Internet), the single-tier model may be sufficient.

When using an IBM i, you may wish to start with a single-tier model. For example, you may use a single-tier model when you first install, develop and test your applications. Once you are ready to deploy your applications to the Internet, you may wish to use the multi-tier model.

Some considerations when using a Single-tier model:

· In a single-tier model, you are using a single IBM i for your Web Server and Data/Application Server. All of the LANSA software is installed on a single Server. Only a single IP address is required to identify the Server as the Web Server and the Data/Application Server are on the same machine.

· This model is the simplest to install and configure. You may wish to begin with this model and move to a multi-tier application model where the Web Server is located on another Server. (Refer to the Task: Upgrading from a Single-tier to a Multi-tier IBM i Web Model). The single-tier model is useful for testing your LANSA applications before deploying the applications on the Internet.

· You will not have to configure the Web Server to Data/Application Server communications since you are using just one machine.

· This model may be sufficient if you are intending to deploy your applications in an Intranet. An Intranet limits the number of people who can access your IBM i so your security considerations do not need to be as strict as for an Internet application.

· If you are deploying your application on the Internet, a single-tier model has security risks because your IBM i will be on the Internet. You should consider using a firewall and other security precautions to protect your IBM i.

· It is strongly recommended that you use the Typical install for a new single-tier installation.

Some considerations when using a Multi-tier model:

· In a multi-tier deployment model, you are using two separate machines for your Web Server and Data/Application Server. Two IP addresses are required: one to identify the Web Server and one to identify the Data/Application Server.

· Only the Data/Application Server requires a full LANSA development environment installed. The LANSA Repository (including the generated HTML) and your application data are installed on this machine. The LANSA for the Web software is also installed on the Data/Application Server.

· The Web Server will have a small component of LANSA for the Web installed. Its main task is to act as the interface between the Web serving software and LANSA for the Web. The Web Server does not require a LANSA system to be installed on it.

· The Web Server can be an IBM i or a Windows server.

· In an IBM i multi-tier deployment, you will be using IBM i servers for both the Web Server and Data/Application Server. The LANSA for the Web PC-based Administrator will only need to connect to the IBM i Data/Application Server.

· You must configure Web Server to Data/Application Server communications using TCP/IP and a Listener.

· Although the multi-tier model is a secure model for deploying your applications on the Web, there is a small performance overhead because of the link between the two machines as well as extra processing that has to be done by LANSA for the Web. This performance overhead may have an impact on the overall performance of your application.

· As a variation to this model, you can use a firewall that is attached to the Web serving machine. The machine with the attached firewall will be connected to the Internet.

· If you are installing LANSA for the Web using two IBM i servers, it is strongly recommended that you start with a single-tier installation. Once you have LANSA for the Web working in a single-tier environment, you can convert to a multi-tier installation. Refer to Task: Upgrade from a Single-tier to a Multi-tier IBM i Web Model.


2.3 Requirements Checklist

The requirements checklists for LANSA IBM i Software have been grouped by the software product being installed:

Skills Requirements

IBM i System Requirements

General Installation/Upgrade Requirements Checklist

LANSA for the Web Requirements

LANSA Integrator IBM i Requirements

Open System Utilities IBM i Requirements


2.3.1 Skills Requirements

Skills recommended for completing the LANSA software installation on IBM i:

· Working knowledge of i5/OS.

· Experience with LANSA environments. This is an asset but not essential.

No LANSA programming experience is required to perform the installation.

If you are installing LANSA for the Web, the following skills are recommended:

· Familiarity with IBM HTTP Web Server powered by Apache or access to staff with these skills.

· Familiarity with TCP/IP (if used) or access to staff with these skills.


2.3.2 IBM i System Requirements

Following is a summary of the IBM i specific requirements:

· An IBM actively supported version of the i5/OS Operating System. Refer to the Supported Platforms and Versions document, for supported platforms/software compatibility.

· Minimum disk space of 500 megabytes.

· RPG and/or C/C++ compilers.

· SEU Editor.
Note: The SEU (Source Edit Utility) is recommended for editing templates and help text. Edit File command (EDTF) will be used if SEU is unavailable.
SEU is required if you wish to use the optional features of editing virtual RPG code.

· TCP/IP correctly configured.

· If using SELECT_SQL, then DB2 Query Manager and SQL Development Kit is required for compiling functions.

· If using spool file Built-In Functions, a supported Web server must be installed.

· For details of the Web Server requirements, refer to the LANSA for the Web Requirements.

· For details of the Java requirements, refer to LANSA Integrator IBM i Requirements.


2.3.3 General Installation/Upgrade Requirements Checklist

Before starting the LANSA for iSeries installation/upgrade, complete this checklist. Do you have:

· The correct version of the LANSA IBM i Product software?

· A RISC IBM i at an IBM supported i5/OS operating system release level?

· The device name of the IBM i DVD/CD-ROM drive? (Default is often OPT01)

· The appropriate LANSA licenses for components and options being installed?

· Have you selected a library name prefix if the default library name prefix (DCX) is already in use?

· Access to the QSECOFR user id? (This is the recommended identifier to be used when installing or upgrading the LANSA software.) The use of other profiles or the removal of the special authorities will cause security and integrity alterations to the installed system.
If you do not have access to QSECOFR for the installation, you will need to create one with the same permission as QSECOFR.

· Reviewed the topic Summary of Installed Objects?

· If you are using a Custom Install, have you reviewed the Software Installation Combinations in the Custom LANSA for iSeries Installations?

· If you are installing LANSA for the Web, have you decided on a single-tier or multi-tier installation?

· If you are not using the default IFS directories, have you created the directories that you want to use? (They must exist before you can use them in the install.)

· Have you reviewed the topic LANSA for the Web Requirements?

· If you are installing LANSA Integrator, have you reviewed the topic LANSA Integrator IBM i Requirements?

· Have you reviewed the IBM i Requirements Checklist?

· Have you reviewed the LANSA for the Web IBM i Requirements?

· Does the IBM supplied default job description QDFTJOBD exist? The install/upgrade will end if it does not exist.

Installation Notes

Following are some tips, techniques and considerations for new installations:

· The install/upgrade will use the following commands from the QSYS library regardless of any other libraries you may have created:

· CRTLIB - Create Library

· MD - Create IFS directory

· CRTJOBQ - Create job queue

· CRTJOBD - Create job description

· CRTSBSD - Create subsystem

· CRTUSRPRF - Create user profile

· The LANSA installation will create a user profile named QOTHPRDOWN. This profile owns the LANSA system. Do not modify the authority rights of QOTHPRDOWN until you have completed the installation. Refer to If QOTHPRDOWN Profile is not used as your Product Owner for actions you must take after the installation is completed.

· It is strongly recommended that you retain the DEM partition which is automatically installed with a new LANSA for iSeries installation. The DEM partition contains the Personnel Demonstration system which is used to test your installation.

· Do not install LANSA for iSeries into libraries already containing user objects.

· Do not create objects of your own in the main LANSA for iSeries program or data libraries. (That is: DCXPGMLIB, DCXDTALIB or their equivalents.)

· Arrange and test your back up procedures before making any use of a LANSA for iSeries system.


2.3.4 LANSA for the Web Requirements

Following is a summary of the software requirements for using LANSA for the Web:

· The correct version of the LANSA IBM i Product software.

· Licenses for the components and options being installed.

· IBM actively supported version of the i5/OS Operating System. Refer to the Supported Platforms and Versions document, for supported platforms/software compatibility.

· Minimum disk space of 35 megabytes. (Web Server only requirement is 10 megabytes.)

· TCP/IP correctly configured.

· Internet browser capable of supporting frames as well as JavaScript. Microsoft's Internet Explorer Version 6.0 or later is recommended.

Web Server Software Requirements

IBM HTTP Server powered by APACHE for CGI.

The Web serving software must be configured and running before attempting to use LANSA for the Web. A quick test is to attempt to load the home page, using http://<as400address>/.


2.3.5 LANSA Integrator IBM i Requirements

· The correct version of the LANSA IBM i Product software.

· Licenses for the components and options being installed.

Integrator Installation Notes

Following are some general tips & techniques for assisting in the Java Service Manager installation:

· A library (default JSMLIB) will be created on the IBM i to store objects used by the Java Service Manager. This includes a number of work management objects such as job descriptions and sub-system descriptions.

· Add the JSMLIB library to your library list for job descriptions and user profiles using the Java Service Manager.

· Java Service Manager IFS objects are restored to an instance directory (default /jsm/instance). This includes .jar files and property files.

· The content of data area JSMMGRDTA is the Java Service Manager instance directory.

· The content of data area JSMCLTDTA is used to determine the host server.

· RPG program examples are located in source file QRPGSRC in the JSMLIB library.


2.3.6 Open System Utilities IBM i Requirements

Following is a summary of the software requirements for using the Open System Utilities:

· The correct version of the LANSA IBM i Product software.

· Licenses for the components and options being installed.

· Minimum disk space of 5 megabytes.

· IBM actively supported version of the i5/OS Operating System. Refer to the Supported Platforms and Versions document, for supported platforms/software compatibility.

· Access to the QSECOFR user profile (recommended profile to be used during an installation).


2.4 Frequently Asked Questions

Frequently asked questions about installing and configuring LANSA software have been grouped by the software product being installed:

General Questions

LANSA for iSeries Questions

LANSA for the Web Questions

LANSA Integrator Questions

Open System Utilities Questions


2.4.1 General Questions

Following are some frequently asked questions about LANSA IBM i Software installation/upgrades:

Should I Use the Typical or Custom Installation?

Do I have to install all products at the same time?

Do I have to use Partition Initialization?

How long will the installation or upgrade take?

When is a good time to install LANSA software?

Can developers or users be using the system during the upgrade?

Where can I find more information about installation and configuration?

Is this version compatible with previous versions?


Should I Use the Typical or Custom Installation?

The LANSA software installation program provides two types of installations: Typical and Custom.

Note: You CANNOT use these install options to upgrade existing LANSA components.

Typical Installation

This option will install, with the minimum of intervention:

· A brand new LANSA system

· Both LANSA for iSeries and LANSA for the Web

· The IBM HTTP Server powered by Apache with CGI to access data

· Satisfied with the system configuration as described in Summary of Installed Objects.

You can use the Typical Install with both single-tier and multi-tier LANSA for the Web deployment models. (For multi-tier, you must follow the Typical Install with a Custom Install to install the Web Server Only components on the Web Server.)

Custom Installation

The Custom install allows you to select the installation components, parameters and options, rather than using the default settings selected for you in the Typical install.

You will use this option if you meet ANY of the following criteria:

· Installing a brand new LANSA for iSeries system

· Installing LANSA for the Web for the first time

· Installing the Web Server Only components in a multi-tier LANSA for the Web installation

· Installing the LANSA Open System Utilities

· Installing LANSA Integrator.

The Custom option allows you to install more than one software component at a time. Refer to the Software Installation Combinations in the Custom LANSA for iSeries Installations.


Do I have to install all products at the same time?

When you perform a Custom install, you can install a single product or multiple products. Sometimes there are advantages of installing a single product in terms of testing, job logs, etc. Following are some general recommendations:

· LANSA for iSeries and LANSA for the Web should be installed together. Where possible, use the Typical Install to install these products.

· LANSA Integrator can be installed separately, after you have completed the LANSA for iSeries installation.

· The Open System Utilities can be installed separately, after you have completed the LANSA for iSeries installation.


Do I have to use Partition Initialization?

Partition Initialization provides a quick and easy way to install optional products and objects at the same time as installing/upgrading your LANSA system.

You do not have to use the Partition Initialization. All of the imports can be performed manually at a later time. Refer to Initialization Imports for notes on manually importing these options.

Notes:

· The Partition Initialization screen is displayed during the Custom Install or Upgrade. It allows you to select, for each partition, from the standard imports shipped with a new LANSA system.

· The list of Partition Initialization options displayed will depend upon the component being installed.

· If you are installing LANSA for iSeries, you will see a complete list of Options. If you are only installing LANSA for the Web, a limited number of Web specific Options will be displayed.


How long will the installation or upgrade take?

The time for the installation and upgrade will vary depending upon the number of software components installed. If installing LANSA for the Web, it will also vary depending upon the type of Web Server and installation model.

As a general rule:

· A LANSA for iSeries system can be installed in less than one hour.

· Allow at least 2-3 hours for the installation and configuration of LANSA for the Web.

If you are not familiar with the HTTP Web Serving software and its configuration, allow more time.

Developers and end users cannot be using the LANSA system during the installation/upgrade.


When is a good time to install LANSA software?

Developers and end users cannot use the LANSA system during the installation/upgrade. You may want to schedule the upgrade at a time which will not disrupt your development efforts.

If you are installing a new LANSA system, LANSA for the Web can be installed at the same time as the LANSA for iSeries.


Can developers or users be using the system during the upgrade?

No. Developers and end users cannot use the LANSA for iSeries or LANSA for the Web applications during the installation/upgrade. There must be no LANSA jobs running during the upgrade and no other LANSA jobs running on other LANSA systems on the same machine.

Note: "Developers" and "end users" also include the LANSA Listener and Java Service Manager.


Where can I find more information about installation and configuration?

You should check the LANSA Web site at www.lansa.com/support for the latest product, configuration and installation updates. Refer to Additional Information.


Is this version compatible with previous versions?

Is this LANSA version compatible with previous versions?

RDMLX objects compiled on this version of LANSA cannot be ported in compiled form backwards to any previous LANSA version.

RDML objects compiled on this version of LANSA may be ported backwards to the immediately preceding LANSA version provided that:

· They can be successfully re-encapsulated by the target IBM i operating system as required.

· No new version facilities have been directly or indirectly used in the RDML objects or database file definitions involved.

· All required LANSA run time routines are present and correct on the target system. Run time routines that may not be present and have to be individually installed from the later version system are normally prefixed DC@P8*, DC@P9*, BI@*, M@*, F@*, DC@S*, DCXS*.

· This facility is used only for very short term stop gap or emergency situations.


2.4.2 LANSA for iSeries Questions

Following are some frequently asked questions about LANSA for iSeries installation/upgrade:

Must I have a DEM partition?

How can I determine the name of the IBM i LANSA program library?

Can I install more than one LANSA System on the same IBM i?


Must I have a DEM partition?

The DEM partition is automatically created during the install process. You will need it for testing your new LANSA for iSeries system.

The online LANSA tutorials require the DEM partition, based on the default Partition Initialization settings. The Personnel System, used for the Task Test LANSA for iSeries Installation, is automatically installed in the DEM partition.


How can I determine the name of the IBM i LANSA program library?

You can determine the LANSA program library name by displaying the data area DC@A01 for this LANSA system and checking the entry in positions 1-10.


Can I install more than one LANSA System on the same IBM i?

You may install more than one LANSA system on the same IBM i.

Some common reasons for running more than one LANSA system on the same IBM i server include:

· You require different versions of LANSA systems. For example, you require a LANSA system at Version 11 and another system at Version 12.0.

· For security, deployment, or other reasons, your development and production systems require completely separate LANSA systems, that is, you cannot use the partition approach.

· You require LANSA systems installed in different Auxiliary Storage Pools.

· If you are installing for a trial or evaluation you would normally install only one system. Additional systems may be installed at a later stage, or you may just choose to partition one system into separate environments.

Following are some considerations for installing multiple LANSA systems:

· Determine if you will need more than one LANSA for iSeries system installed before you begin your installation.

· If you are installing for a trial or evaluation you would normally install only one system. Additional systems may be installed at a later stage, or you may just choose to partition one system into separate environments.

· Do not share libraries between your LANSA systems. Each system should have its own unique set of libraries especially for such items as the LANSA communications library.

· Always install a LANSA for iSeries system into four separate and unique i5/OS libraries. For example, if you wish to install two completely separate LANSA for iSeries systems, (e.g. a production system and a development system), you might choose this configuration:

 | LANSA for iSeries System 1 | LANSA for iSeries System 2
Use for: | Production: | Development:
Program library | PRLANSAPGM | DVLANSAPGM
Data library | PRLANSADTA | DVLANSADTA
SYS Partition | PRLANSASYS | DVLANSASYS
DEM Partition | PRLANSADEM | DVLANSADEM


2.4.3 LANSA for the Web Questions

Following are some frequently asked questions about LANSA for the Web installation/upgrade:

What IBM i Web Server should I use?

How much Web security do I need?


What IBM i Web Server should I use?

IBM Apache HTTP Server and CGI.

The IBM HTTP Web Server powered by Apache, is shipped as a standard feature of the i5/OS operating system.


How much Web security do I need?

The level of security required will be determined by the type of Web site you are creating. Internet, Intranet and Extranet applications require different levels of security.

Security can be defined at the network, Web Server, Data/Application Server and LANSA levels. For example, you can use firewalls on the network along with user profile and object level security on the IBM i. LANSA for the Web provides an additional three levels of security.

During the initial installation and configuration of LANSA for the Web, you may wish to begin with very basic security requirements. The anonymous user access to LANSA for the Web is recommended when you first install and test LANSA for the Web. Once your system is operating properly, you can enhance the security features used.

Following are some considerations for LANSA for the Web security:

· LANSA for the Web provides additional security features, on top of the security features provided by the Web serving products.

· LANSA for the Web allows for anonymous user access. Anonymous access allows a casual visitor to use your Web applications without a user profile. There is a Data/Application Server user profile assigned to this anonymous user. This profile should only have minimal access rights on your Server.

· By default, LANSA for the Web will install a system for anonymous user access.

· It is recommended that you start with anonymous user access when you first install, configure and test the LANSA for the Web software. Once you have this level of authentication working properly, you can easily implement partial or full user authentication.

· If you intend to allow for anonymous user access to your applications, you can also configure LANSA for the Web to enforce user authentication to specific Web applications. Partial or process level authentication allows you to restrict access to a specific set of Web enabled applications while still allowing the anonymous user access to the rest of your Web enabled applications. The casual visitor to your Web site can access the applications which are intended for public access.

· You may choose to implement the full user authentication model. In this case, a user must enter a valid user profile and password to access any part of your application. Public access will not be allowed to any part of your application.

· LANSA for the Web supports the use of Secure Socket Layers.

· A multi-tier LANSA for the Web installation can also increase your site security so that your Data/Application Server is not directly connected to the Internet.

For more details about LANSA for the Web security, refer to the Task: Configuring LANSA for the Web Security.


2.4.4 LANSA Integrator Questions

Following are some frequently asked questions about LANSA Integrator installation/upgrade:

Can I have multiple LANSA Integrator systems installed?

What license do I need?

Do I need LANSA for iSeries installed to use LANSA Integrator?


Can I have multiple LANSA Integrator systems installed?

You can have more than one instance of the LANSA Integrator Java Service Manager executing on a single IBM i Server. Multiple JSM Servers are configured using multiple instances. You do not have to install LANSA Integrator more than once. For more details, refer to the LANSA Integrator Guide.


What license do I need?

Many of the LANSA Integrator services and tools are individually licensed or licensed as collections or bundles. You may not be licensed to use all the services and tools available.

When you first purchase LANSA Integrator, your supplier will provide the license keys for the services and tools you have licensed, along with instructions to apply them.

To request a LANSA Integrator license, you will need to provide information about your IBM i including processor, serial and model numbers as well as the i5/OS version to your LANSA Distributor. Refer to your LANSA product distributor for further information.


Do I need LANSA for iSeries installed to use LANSA Integrator?

If you are using the 3GL interface for LANSA Integrator, you do not require a LANSA for iSeries system installed. You can call LANSA Integrator from RPG or COBOL applications.

If you are using the LANSA Built-In Functions to integrate with your existing LANSA applications and databases, then you must have LANSA for iSeries installed on the IBM i Server.


2.4.5 Open System Utilities Questions

Following are some frequently asked questions about Open System Utilities installation/upgrade:

Should I install the Open System Utilities?

Do I need a license for Open System Utilities?


Should I install the Open System Utilities?

Following are some considerations for using the Open System Utilities with your LANSA development environment:

· Refer to What are the Open System Utilities? if you are not familiar with them.

· The utilities are provided on an "as is" basis with complete documentation. Refer to the LANSA Open System Utilities Guide for information.

· The nature of the manipulations they perform require that skill and care be exercised by the user.
No warranty is expressed or implied in the provision of these utilities.

· The utilities provide you with extensive knowledge of the internals of your LANSA for iSeries environment, allowing you to extend the shipped utilities, or to develop new ones.

· Source code and documentation for each utility is provided.


Do I need a license for Open System Utilities?

You do not require a license to use the Open System Utilities.


3. Install LANSA on iSeries

The following choices are available using the LANSA IBM i software installation:

· Task: Typical Installation

· Task: Custom Installation

· LANSA Integrator Installation

· Task: Upgrade LANSA on iSeries.

Note: The Upgrade option is only available if the program finds a LANSA component.

After the installation tasks, review LANSA on iSeries - What's Next?

Refer to the Supported Platforms and Versions document, for supported platforms/software compatibility.


3.1 Task: Typical Installation

The Typical Installation is the quickest and easiest way to install a new LANSA system on an IBM i.

When you use the Typical Installation:

· LANSA for iSeries is installed

· A complete single tier LANSA for the Web is installed

· A system and development partition will be installed with library and partition names commencing with DCX but if you need to, you can change the Library prefix to some other three characters, as described in Call the Installation Program.

· The LANSA Communication Extensions are automatically configured and ready to use

· IBM HTTP Server Instance (Original or APACHE) is fully initialized and ready to use.

The default options selected for you result in a number of objects being loaded onto your IBM i. You will find a list of these objects in the topic Summary of Installed Objects. Please check that they suit your site.

If you would prefer not to accept the Typical Installation default options, then you can use the Custom Installation which allows you to customize the install options to suit your requirements.

The Typical Installation task includes the following steps:

Before You Begin Checklist

Call the Installation Program

Typical Installation Summary

Verify Typical Installation

Note that you cannot run a Typical install twice nor can you create new partitions. If either is required, you would use a Custom install.

Once you have completed the installation, go to LANSA License Codes.


3.1.1 Before You Begin Checklist

If you answer Yes to all the questions in the General Installation/Upgrade Requirements Checklist go to Call the Installation Program.


3.1.2 Call the Installation Program

1. Sign on to the IBM i as either QSECOFR or a profile within the QSECOFR group.

2. Insert the LANSA IBM i Software DVD or the first CD-ROM into the IBM i drive.

3. From an i5/OS command line (CALL QCMD), enter the following command to restore the software from the input medium:

LODRUN DEV(*OPT)

The LANSA Installation/Upgrade Program screen will be displayed.

4. Specify the name of the job queue and library to which the actual installation job is to be submitted. The default value is job queue QBATCH in library QGPL. If this is not valid at your installation, change it to the name required.

Enter 1 to select the Typical Install. Press Enter.

A pop-up box will be displayed with the defaults that will be used.

5. Either confirm or change the defaults:

a. New Library Prefix. If DCX (the default) already exists, then enter a different library prefix. If the prefix you enter already exists, an error message will be displayed.

b. Listener - connection identifier

c. Web Instance Port - the port number used by web jobs.

Note that you cannot select a second Typical Install as the libraries will have already been created. If you do select this option again, as soon as you press Enter, an error message will be displayed to inform you.

6. Press Enter to confirm your choices and continue.

7. Once the in use indicator has gone out, unload the first CD and load the second CD. Reply G to continue or C to Cancel.

If you Cancel the install, the job will end without doing any Imports but will leave a basic LANSA System. If you wish to use this LANSA system, you will need to import the Imports using the Housekeeping menu or the Initialize Partition option from the Word with Administration Task.

8. You will be asked if you have any earlier versions of LANSA-developed applications.

If you are a new LANSA user, you should reply NO to this question.

Go to Typical Installation Summary.


3.1.3 Typical Installation Summary

Installation Summary screens are displayed for you to check that the default parameters that have been made suit your site standards.

· If you wish to change any of the parameters on the Summary screens, you must cancel the Typical installation and choose the Custom installation. The Custom installation will allow you to change the default installation parameters.

· If you are satisfied with the installation summary, on the final Summary page, press F8 to submit the batch job.
A list of the options chosen is displayed.

· If you do not wish to submit the installation job, press F3 to exit.

· If you wish to change the default options, press F12 return to the starting screen and choose option 2, Task: Custom Installation.

For a list of the objects installed, refer to Summary of Installed Objects.

Go to Verify Typical Installation.


3.1.4 Verify Typical Installation

When you see the message indicating that the batch job has finished, examine the resulting job log QPJOBLOG before attempting to use the LANSA system.

If there are any EPCs with the Install, they will be applied and the EPC log updated accordingly.

Once the LANSA update job has completed, check the job's spooled file for the following:

Check messages

· Filename: QPDSPMSG

· User Data: SUMMARYMSG and DETALMSG

and check for any errors.

Check for required IBM i software

· Filename: QSYSPRT

· User Data: DC@LOAD20

The final message after a successful install is:

****All selected LANSA components have successfully installed****

Regardless of whether the successful install message appears or not, retain the job log that results from the install for future reference.

The typical installation process will have installed some Initialization imports. To do this successfully, partitions need to be set to multilingual and this is done automatically during the install process. The LANSA_CLN job returns the partitions to a non-multilingual status. You must check that LANSA_CLN has been run successfully. For further details refer to Check LANSA_CLN.

If the Installation of LANSA for iSeries completed successfully, go to LANSA License Codes.

As LANSA for the Web is installed as part of the Typical Install, you must also install the LANSA for the Editor and Administrator as applicable.

QOTHPRDOWN User Profile

If you had used QOTHPRDOWN instead QSECOFR to do the install, the QOTHPRDOWN profile might not have authority to use the command STRSBS. Because of this, the following sub systems might not start automatically:

· LISTENER

· LANSA for Integrator (if installed).

You must use a User Profile that has appropriate authority to start sub systems (STRSBS).

If you did use QOTHPRDOWN as the product owner, you must perform the steps in QOTHPRDOWN Profile not used.

Typical Installation failed

If you did not see this message:

All selected LANSA components have successfully installed

read the other messages sent to the workstation and in the job log and perform any suggested actions in full.

When reading the job log, always read it backwards, starting from the last page. If you read it from the beginning, you cannot assume that the first error you see is the cause of the problem.

For instance, most job logs will contain escape messages reporting "Object xxxxxxxxxx in lllllllll type tttttttttt not found". If you read the job log forwards and stop at this apparently fatal/severe message you will miss the actual error that caused the install to fail. In this case, this error occurs when the install software tests if an object already exists. It is not fatal and does not indicate any problem with the install.

Do not restart the installation without first checking the job log produced for messages that clearly indicate the source of the problem.


3.2 Task: Custom Installation

The Custom Installation allows you to select the LANSA software components to be installed as well as to create new Partitions.

If you have selected the Integrator Install, then you will follow the Custom installation steps but with Integrator defaults already selected for you.

The steps performed during the installation will depend on the software components being installed. Every custom install includes these steps:

Before You Begin Checklist

Call the Installation Program

Earlier Versions of LANSA

Select Software Components

Check the Custom Installation Summary

Verify the Custom Installation

Note that the new partitions option is not available independently of a Custom Install. Use LANSA's Housekeeping facility if you wish to create a new partition after you have completed a Custom install.

Once you have completed the Custom Installation, go to LANSA License Codes.


3.2.1 Before You Begin Checklist

Before you begin the Custom Installation task, check the following:

· If you are using an Independent Auxiliary Storage Pool please refer to Using Independent Auxiliary Storage Pool (IASP) for further information.

· Have you answered Yes to all the questions in the General Installation/Upgrade Requirements Checklist ?

· If you are adding software to an existing LANSA system, are they at the same version?

· Have you read the Software Installation Combinations in the Custom LANSA for iSeries Installations to help plan your installation?

· Have you checked the prefixes that you must supply and the parameters that you must confirm when performing the install?
If not, you will find them at the beginning of each section for the installation options you select. For example, if you are creating a new partition, you will need to know the Identifier you wish to assign to the partition, the Partition you may wish to use as a base, and the names to be assigned to the Module and Default libraries. These are described in Create New Partition.

· Do you know which partition options you will be installing? For selections, refer to Partition Initialization.

· If you are not using the default IFS directories, have you created the directories that you want to use? (They must exist before you can use them in the install.)

· If you are installing LANSA for the Web, have you decided on a single-tier or multi-tier installation?

If you answer Yes to all these questions, go to Call the Installation Program.


3.2.2 Call the Installation Program

1. Sign on to the IBM i as either QSECOFR or a profile in the QSECOFR group. The QSECOFR profile is recommended.

2. Insert the LANSA IBM i Software DVD or the first CD-ROM into the IBM i drive.

3. From an i5/OS command line (CALL QCMD), execute the following command:

LODRUN DEV(*OPT)

The LANSA Installation/Upgrade Program screen will be displayed.

4. Specify the name of the job queue and library to which the actual installation job is to be submitted. The default value is job queue QBATCH in library QGPL. If this is not valid at your installation, change it to the name required.

5. Enter 2 to select Custom Install and press Enter.

6. If you are loading from a CD-ROM, at the appropriate time, you will be asked to load the second the IBM i software CD-ROM. Before you remove the first CD, you will be asked if you wish to continue.

Reply G to continue or C to Cancel.

If you Cancel the install, the job will end without doing any Imports but will leave a basic LANSA System. If you wish to use this LANSA system, you will need to import the Imports using the Housekeeping menu or the Initialize Partition option from the Word with Administration Task.


3.2.3 Earlier Versions of LANSA

Do you have or plan to install applications that were developed using earlier versions of LANSA?

If you are a new LANSA user, you should reply NO to this question.

If you reply NO

LANSA will be installed with default attributes for new partitions that take maximum advantage of new features in this version.

If you are an existing LANSA customer, you should reply YES, unless specifically instructed otherwise by your software provider.

If you reply YES

LANSA will be installed with default attributes for new partitions that will provide full compatibility with your existing applications and your existing development activity.

In either case, when creating new partitions in LANSA, you can override the default partition settings that LANSA suggests.

Go to Select Software Components.


3.2.4 Select Software Components

From the list, choose the software components that you wish to install.

If you have selected the Integrator Install, then the LANSA Integrator component will be pre-selected. Press Enter to open the pop-up window to enter the LANSA Integrator Parameters. Be sure you know the Integrator TCP port and Integrator AdminTCP port before you begin.

Enter "Y" to select the component(s) you wish to install and press Enter to continue. For a list of valid combinations, refer to the Software Installation Combinations in the Custom LANSA for iSeries Installations.

When you have selected your required option(s) and pressed Enter, a pop-up window will open for you to enter some details required for the installation.

The path you take through the install process will depend on the components you select.

LANSA IBM i

Enter "Y" to install the LANSA Application Development Environment which is described in What is LANSA for iSeries?

A pop-up window will open for you to specify the Current & New Library Prefix to be used for the installation. If you make no change, the shipped default of DCX will be used.

LANSA for the Web - Complete Web Install

Enter "Y" to install the components that are used to build LANSA for the Web applications. These components integrate seamlessly with the LANSA Application Development Environment.

If you are using a single-tier installation, you need only install LANSA for the Web using this option.

If you select this option alone, you must already have a LANSA system installed. A pop-up window will open for you to specify the LANSA Program Library name.

For a multi-tier installation, you will also need to request the LANSA for the Web - Web Server ONLY Install. The Web Server ONLY install must be run on the IBM i machine acting as the Web Server. For more information, refer to What is LANSA for the Web?

Go to LANSA for the Web - Parameters.

LANSA Integrator

Enter "Y" to install the components of a Java service framework that allows you to integrate Java Services with LANSA and 3GL applications. For more information, refer to What is the LANSA Integrator?

If LANSA Integrator is selected by itself, a pop-up window will open for you to specify the LANSA Program Library name.

Go to LANSA Integrator Parameters.

Open System Utilities

Enter "Y" to install a library of utilities for experienced developers to manipulate the LANSA environment. These utilities enable global or system level manipulations of a LANSA for iSeries environment. For more information, refer to


The IBM i Parameters (1)

Except for your Company Name, the defaults are formatted according to the options that you have previously specified when selecting the components to install.

LANSA Program Library

The name of the library into which the program component of LANSA for iSeries software will be installed. This library must not exist. It will be created by the installation.

LANSA Data Library

The name of the library into which the data component of LANSA for iSeries software will be installed. This library must not exist. It will be created by the installation.

LANSA Communications Library

The name of the library into which the LANSA communications software components will be installed. This library must not exist. It will be created by the installation.

Company Name/Title

The name or title to appear at the top of all screens displayed by the LANSA for iSeries system. It is recommended that you center the name/title in the 30 characters available.

SYS Partition Library

The library into which objects associated with the SYS partition will be installed. This library must not exist. It will be created by the installation.

DEM Partition Library

The name of the library into which objects associated with the DEM partition will be installed. This library must not exist. It will be created by the installation.

Enable for full RDMLX

Enter YES if full RDMLX is required for this partition.

Enter NO if RDMLX is not required for this partition.

If you are unsure of the implications of this option, refer to RDML and RDMLX Partitions Concepts.

If you enable this partition for RDMLX objects:

· it cannot be returned to a non-RDMLX state

· all development must be done in Visual LANSA

· development in LANSA for iSeries is NOT permitted.

If you select YES to enable the partition for full RDMLX, you will need to specify further options, as described in If you Enable a Partition for Full RDMLX in the iSeries User Guide.

The default value is NO.

Auxiliary Storage Pool (ASP)

If you are using ASP, then the value for this parameter must be in the range 1 to 32.

If you are using IASP, then the value for this parameter must be *ASPDEV. In this case, you must specify the next two parameters.

Default is 1.

ASP device

If you are using IASP, then the value for this parameter must be a valid IASP device name and the device must be online.

If you are using ASP, then the value for this parameter must be *ASP. This is the default.

ASP Group

If you are using IASP, then the value for this parameter must be a valid IASP group name.

If you are using ASP, then the value for this parameter must be *NONE. This is the default.

Press Enter once you have specified the required information.

Go to The IBM i Parameters (2).


The IBM i Parameters (2)

Except for the Listener - Connection Id, the defaults are formatted according to the options that you specified when selecting the components to install.

LANSA Root Directory

The LANSA directory used by all the LANSA objects that require the IFS. It is recommended that you do not change the default path. This directory will be created during Install process.

Development Language

The development language to be used with the LANSA for iSeries system.

Product Owner

Specify the name of an existing i5/OS user profile that will be the owner of this LANSA for iSeries system. Objects subsequently created by LANSA for iSeries on behalf of its users will also be owned by this Product Owner.

If a Product Owner is not specified, the default value, QOTHPRDOWN will be used. This profile will be automatically created if it does not already exist. Other profiles can only be nominated if you are signed on as QSECOFR or a QSECOFR group profile. QSECOFR should not be used. Refer to If not using QOTHPDOWN as the Product Owner for extra tasks after the install process is finished.

Partition Security Officer

Specify the name of an existing i5/OS user who is to be the LANSA for iSeries Partition Security Officer.

The default value is a user profile with the same name as the LANSA Program Library, for example DCXPGMLIB. If this default profile does not exist it will be automatically created.

The LANSA for iSeries Partition Security Officer does not have to be the same as the i5/OS Security Officer (QSECOFR). A user nominated as the LANSA for iSeries Partition Security Officer has no special authority outside the LANSA system.

If using an existing profile, the library list must be changed to reflect the new libraries.

Job Description

This is the job description used by LANSA.

Auxiliary Storage Pool

If you wish to install into an auxiliary storage pool other than 1, change this value to a valid number supported by your operating system.

Listener - Subsystem

This is the sub-system where the Listener jobs run. This name is stored in the LANSA program library.

Listener - Job Description

The job description used by LANSA. Job descriptions are a native part of the i5/OS operating system and are required whenever a batch job is submitted. Refer to the IBM manuals for more details. This job description is placed in the program library.

Listener - Job Queue

Job queues are a native part of the i5/OS operating system and all batch jobs are to be submitted onto a job queue. Refer to the IBM manuals for more details. This job queue is placed in the program library.

Listener - Connection Id

The port number that will be used to connect the Listener.

Press Enter to confirm the information.

If you have selected The Complete Web component, go to LANSA for the Web - Parameters.

If you have also selected other software components, then return to Select Software Components
otherwise go to Partition Initialization.


Partition Initialization

Material that supports LANSA development and applications is supplied with the LANSA install software. This material can be in several forms including LANSA standard definitions, LANSA applications or tools. For the purposes of the Install process, these definitions and applications are generically referred to as Options. When you select an option, objects are imported into the selected partition. Some options must be installed and these have been set to "Y".

The Partition Initialization step is performed as part of a LANSA Custom installation.

From this screen you can:

· create a new partition

· vary some of the default LANSA options to be imported into each partition.

Note that the SYS and DEM partitions are created with a new LANSA system regardless of the Options you select during the Partition Initialization.

A "Y" in the Status column indicates options that have already been selected or pre-selected for you.

If you wish to create a new partition press F6. Refer to Create New Partition for details. When you have created the new partition, you will be returned to this window.

If you wish to delete new partitions, press F5.

Enter "Y" to select a partition and then press Enter to display the Options & Applications that you can install for the selected partition(s). If you select more than one partition, the options selected will apply to each partition selected.

Note: If you choose not to install an Option at this time, you can do so later using a LANSA Import. For more information, refer to Initialization Imports.

To import an object or application into your LANSA system, enter Y. The recommended options have already been selected for you.

System Variables

Mandatory. The system variables are system wide; that is, they are used in all partitions. You only need to install system variables once per system.

LANSA Templates

Mandatory. The LANSA templates are system wide; that is, they are used in all partitions. You only need to install templates once per system.

System Fields

Mandatory. The system fields include the standard field definitions used in the LANSA development environment. System fields are required in all development partitions.

Web enable

Select this option to use the partition to develop LANSA for the Web applications. If you are installing LANSA for the Web (that is, you have selected the LANSA for the Web - Complete Web Install component), this indicator will be selected. It is strongly recommended that you Web enable the DEM partition for training and testing purposes.

e-Business Framework Wizard

Optional. Select this option to use the e-Business Framework Wizard when building LANSA for the Web applications. If you are using LANSA for the Web, it is strongly recommended that you load the e-Business Framework Wizard into the DEM partition for training and testing purposes. For further information, refer to What is the e-Business Framework Wizard?

LANSA Client enable

Optional. If you are using the LANSA Client software, you must select this option for each partition to be used by LANSA Client.

Multilingual Help or Non-Multilingual Help

Optional. The option displayed will reflect whether the partition is defined as multilingual or not. It imports the standard LANSA help text form for multilingual or non-multilingual help as applicable.

Personnel System

Optional. This is a demonstration application that is used by the online tutorials and during the steps that test the install of LANSA for iSeries. It is strongly recommended that you import the Personnel System into the DEM partition.

Press Enter once you have selected the desired options.

If you have not selected all the required options, you can import them manually at any time after the installation is complete.

If you have also selected other software components, return to Select Software Components
otherwise, go to Check the Custom Installation Summary.


Create New Partition

If you press F6 on the Partition Initialization screen the Create Partitions window will open.

A system partition is a means of 'dividing up' or 'partitioning' one LANSA system. Each partition is completely separate from other partitions. Once a new partition is created, specific compulsory options are imported into the new partition. The compulsory options are System Fields, Help and Web enable. You can select more options from the Partition Initialize screen if required.

Before you create your new partition, you will need to know the names of the Module and Default libraries you will use with the new partition.

Note that you cannot change any of the partition options via the Create Partition window's entries. If you make a mistake, you can either delete the new partition (function key F5 on the Partition Initialization window) and create another new partition or change them using the LANSA Housekeeping facility when you have completed the installation.

Partition Identifier

Specify the identifier/mnemonic to be assigned to the new partition. Must be three characters long and consist of characters in the range A to Z, 0 to 9, @ (at sign), # (hash sign), and/or $ (dollar). No two partitions can have the same identifier.

Partition Description

The description of the new partition. Must not be left blank.

Module Library

The name of the library in which the compiled RDML programs associated with this new partition are to be kept. This library must not be the same as the module library used by other partitions. It must not exist as it will be created by the initialization process. Once specified, this name can only be changed using LANSA's Housekeeping facility.

Default File Library

The name of the library for the files in this partition. The library must not exist as it will be created during the initialization process. Once specified, this name can only be changed using LANSA's Housekeeping facility. If left blank, the default will be the Module Library.

From Partition

Copy details for the new partition from this partition. If the partition is multilingual, the multilingual details will be copied to the new partition. This partition must already exist.

Press Enter once you have entered the required details. Your new partition will immediately be included in the Partition list in the Partition Initialization window.

Enable for full RDMLX

Allowable values are:

YES full RDMLX is required for this partition.

NO full RDMLX is not required for this partition.

The default value is NO.

If you specify YES, you will be asked to confirm your selection. Once a partition is enabled for full RDMLX:

· it cannot be returned to a non-RDMLX state

· all development must be done on a workstation in Visual LANSA

· development in LANSA for System i is NOT permitted.

If you select YES to enable the partition for full RDMLX, you will need to specify further options, as described in If you enable a Partition for full RDMLX in the LANSA for iSeries User Guide.

If you Press Enter, you will be presented with the Create Partition screen again to enter another partition. Press F12 or F3 to continue.


LANSA for the Web - Parameters

If you have selected the LANSA for the Web - Complete Web Install, the Parameter screen will be displayed. Check that the installation parameters, especially the Web Instance Port, Web Image Path and HTTP Server, that will be used during the installation are correct.

If you are also installing LANSA for iSeries, then the parameters that have already been specified for LANSA for iSeries (LANSA Program Library, Development Language & Web Interface Used) will not be displayed.

LANSA Program Library

If this field is displayed, the name of the LANSA program library used when LANSA for iSeries was installed. This library must already exist.

Web Interface

The default value is 1 (for CGI).

HTTP Server

The default is 1 (IBM HTTP server powered by APACHE) and it cannot be changed.

HTTP Instance Name

The name that is used by the HTTP instance. This name should be unique amongst all HTTP instances. If you need to change this name, refer to Appendix E. Change the HTTP Install Instance .

Web Instance Port

The port number used by the Web jobs. The default is 80.

Web Monitor Job Queue

The job queue that is used by Web Monitor job. The default is [your specified library prefix]WEBJQ.

Web Jobs Job Queue

The job queue that is used by Web jobs. [your specified library prefix]WEBJQ.

Web Work Library

The name of the library into which the working objects used by LANSA for the Web will be stored. The Web Work Library will be used at run time by LANSA for the Web applications. The default is [your specified library prefix]WRKLIB. The library will be created by the installation.

Development Language

The development language to be used with this LANSA for iSeries system.

Web Image Path

The full path and name for the Image Directory. The Image Directory is used to store the image files used by the LANSA for the Web applications. This default directory will be created if it does not exist. If you do not use the default, the directories in the path name must already exist.

Press Enter if the information is correct.

Go to The Web - CGI, Host & Client CCSID library parameters.


The Web - CGI, Host & Client CCSID library parameters

For CGI as your Web interface, the CGI, Host & Client CCSID library parameters are displayed.

Press Enter to confirm that the following information is correct:

CGI Library

The library name where the CGI program for the IBM Apache HTTP Web server should be installed. The CGI library will default to the LANSA Communications Library.

Host CCSID

The Host CCSID used for data translation purposes. The default is 00037.

Client CCSID

The Client CCSID used for data translation purposes. The default is 00819.

ServerRoot

If you are using APACHE as the HTTP Server, this is IFS name that will be used by the APACHE configuration file. It is httpd.conf

Press Enter to continue.

If you have also selected the LANSA iSeries install, go to Partition Initialization; or
if you have selected other software components, return to Select Software Components;
otherwise
go to Check the Custom Installation Summary.


LANSA Integrator Parameters

If you have elected to install the LANSA Integrator either with LANSA for iSeries, or as a separate install, these screens will be presented requesting the Integrator Parameters:

followed by

Be sure you know the Integrator TCP port and Integrator AdminTCP port before you begin this installation.

Press Enter to display the default Integrator Parameters that will be used for the installation. Check that the parameters displayed are correct.

Associated LANSA Program Library

The Associated LANSA program library identifies the LANSA system that you wish to use with this instance of LANSA Integrator. If you do not intend to use LANSA Integrator with LANSA, you may leave this field blank.
If entered, it must be a valid LANSA program library. The LANSA to be associated with LANSA Integrator must be at the same version.

Leave blank.

Java Service Manager Library

The name of the library where the LANSA Integrator objects should be installed. The default is The default is xxxjsmlib, where xxx is the library prefix that you entered. If it does not exist, this library will be created. If the library already exists it will be cleared before objects are installed.

Java Service Manager Path

The full path name for the directory where the LANSA Integrator files should be installed. The default is /jsm/instance. This directory will be created if it does not exist. If you do not use the default, the directories in the path name must already exist.

Auxiliary Storage Pool

If you select LANSA and the Integrator together in the same installation process, the Auxiliary Storage Pool used will be the one you have already selected for LANSA.

If you wish to install into an auxiliary storage pool other than 1, change this value to a valid number supported by your operating system.

Integrator Owner

QOTHPRDOWN will be used.

Integrator Subsystem name

The sub-system used to run Java Service Manager jobs. Do not change the default.

Integrator User Id

The profile for running Java Service Manager jobs.

Do not use QSECOFR. If you do, the installation will fail.

If install is with LANSA:

The User Id that is used with the LANSA install will be used.

Install without LANSA

If the displayed default is not used, the profile must exist. Do not use QSECOFR.

Integrator TCP port

Every Java Service Manager instance has a TCP/IP server listener that accepts JSM client connections. This entry contains the value of this TCP/IP port.

Integrator AdminTCP port

Each Java Service Manager instance can have a HTTP web console interface that allows a remote browser to perform administration tasks on the currently active service manager. This entry contains the value of this TCP/IP port.

LANSA Integrator Studio also uses this console TCP/IP port.

HTTP Server Port Number

If installed with LANSA for the Web, the LANSA Web Port Number will be used. This cannot be changed.

If not installed with LANSA for the Web, you can change the default Port Number and this number will be used to configure an HTTP instance for Integrator. The instance name will be the Integrator Program Library.

Optimize Java Service Manager

Once the install process is completed, a separate job to optimize the Integrator files can be run. This job may take a few hours to complete.

Select 1 to start this long running job.

Select 2 to not submit the optimize job. '2' is the default. If you select option 2 and do not run this job now, you will be reminded to run it when you reach the Task: Configure the Java Service Manager on IBM i.

Press Enter once you have specified the required information.

If you have also selected the LANSA iSeries install, go to Partition Initialization; or
if you have selected other software components, return to Select Software Components;
otherwise
go to Check the Custom Installation Summary.


Open System Utilities Installation Library

You may install the Open System Utilities at the same time as the LANSA iSeries install or at any time afterwards. For more information about these utilities refer to What are the Open System Utilities?

When you install the Open System Utilities you must enter the Library into which they are to be installed, or accept the default that is displayed.

Open System Utilities Library

The name of the library where the Open System Utilities are to be installed. If this library does not exist, it will be created. If this library does exist, any existing objects in the library with the same name as the new objects will be replaced during the installation.

Press Enter to continue.

Note: If the Open System Utilities are installed by themselves, then the owner will be the current shipped owner (QOTHPRDOWN) and if this profile is not found on the system, the IBM default owner (QDFTOWN) will be the owner.

If the Open System Utilities are installed with LANSA, then the owner will be the LANSA Product Owner.

If you have selected other software components, return to Select Software Components; otherwise go to Check the Custom Installation Summary.


The Web Server Only - Parameters

If you have selected the LANSA for the Web - Web Server Only Install, please check the default Web Server Parameters that have been inserted for you.

LANSA Administration Library

The name of the library into which the LANSA for the Web software components should be installed. This library must not already exist as it will be created.

LANSA Communications Library

The name of the library into which the LANSA communications software components should be installed. This library must not exist for an install as it will be created.

Web Work Library

The name of the library into which the working objects used by LANSA for the Web will be stored. The Web Work Library will be used at run time by LANSA for the Web applications. The default is [your specified library prefix]WRKLIB. The library will be created by the installation.

LANSA object owner

Specify the name of an existing i5/OS user profile that will be the owner of this LANSA for iSeries system. Objects subsequently created by LANSA for iSeries on behalf of its users will also be owned by this Product Owner.

If a Product Owner is not specificied, the default value, QOTHPRDOWN will be used. This profile will be automatically created if it does not already exist. Other profiles can only be nominated if you are signed on as QSECOFR or a QSECOFR group profile. QSECOFR is not recommended.

HTTP Instance Name

The name that is used by HTTP instance. This name should be unique amongst all HTTP instances. If you need to change this name, refer to Appendix E. Change the HTTP Install Instance .

Web Instance Port

The port number used by the Web jobs. The default is 80.

Web Interface

The value is 1 for CGI.

HTTP Server

The IBM Web Server types are:

1. IBM HTTP server powered by APACHE.

Development Language

The development language to be used with the LANSA for iSeries system.

Press Enter to continue, once you have verified the required information.

LANSA Root Directory

The LANSA directory path used by all the LANSA objects that require the IFS. It is recommended that you use the default path. This directory will be created during the Install process.

Web Image Path

The full path and name for the Image Directory. The Image Directory is used to store the image files used by the LANSA for the Web applications. This default directory will be created if it does not exist. If you do not use the default, the directories in the path name must already exist.

Go to CGI, Host & Client CCSID parameters - Web Server Only.


CGI, Host & Client CCSID parameters - Web Server Only

With CGI as the Web interface, you must enter the Host & Client CCSID parameters.

CGI Library

The library name where the CGI program for the IBM HTTP Web server should be installed. The CGI library will default to the LANSA Communications Library.

Host CCSID

The Host CCSID used for data translation purposes. The default is 00037.

Client CCSID

The Client CCSID used for data translation purposes. The default is 00819.

Press Enter once you have specified the required information.

Go to Check the Custom Installation Summary.


3.2.5 Check the Custom Installation Summary

The installation iSeries Summary screens display the choices you have made on the preceding screens. Press Enter to page through these summary screens.

The information presented will depend on the components and options being installed.

Before you start the Install process, check that the choices that you have made are correct.

If you wish to change any of the details on the summary screens:

Press F21 to return to the beginning of the install process and change the selected parameters or Options.

Press F12 to return to a previous screen.

If you wish to cancel the install job, press F3 to exit.

If you are satisfied with the installation summary, press F8 to submit the batch job.

Go to Verify the Installation.

A list of the options chosen is displayed.

For a Web Server install, once the install process is completed, a clean up job called LANSA_CLN is submitted to delete the LANSA install work library.

Go to Verify the Custom Installation.


3.2.6 Verify the Custom Installation

When you see the message indicating that the batch job has finished, examine the resulting job log QPJOBLOG before attempting to use the LANSA system.

If there are any EPCs with the Install, they will be applied and the EPC log updated accordingly.

Once the LANSA update job has completed, check the job's spool files for the following:

Check Spool Files

· Filename: QPDSPMSG

· User Data: SUMMARYMSG and DETALMSG

Check the job log for any errors.

Check for required IBM i software

· Filename: QSYSPRT

· User Data: DC@LOAD20

The final message after a successful install is:

****All selected LANSA components have successfully installed****

Retain the job log that results from the install for future reference regardless of whether the install message appears or not.

If you have selected some Initialization imports, the partitions will have been set to multilingual automatically during the custom install process. The partitions are returned to a non-multilingual status by the job LANSA_CLN. You must check that LANSA_CLN has been run successfully. For further details refer to Check LANSA_CLN.

Return to the relevant Installation Process that you are following to check the next step, if any, to be performed.

If the Installation of LANSA for iSeries completed successfully, go to LANSA License Codes.

QOTHPRDOWN User Profile

If you had used QOTHPRDOWN instead QSECOFR to do the install, the QOTHPRDOWN profile might not have authority to use the command STRSBS. Because of this, the following sub systems might not start automatically:

· LISTENER

· LANSA for Integrator (if installed).

You can use a User Profile that has appropriate authority to start sub systems (STRSBS).

If you did not not use QOTHPRDOWN as the product owner, you must perform the steps in QOTHPRDOWN Profile not used.

Custom Installation Failed

If you do not see this message:

****All selected LANSA components have successfully installed****

read the other messages sent to the workstation and in the job log and perform any suggested actions in full.

When reading the job log, always read it backwards, starting from the last page. If you read it from the beginning, you cannot assume that the first error you see is the cause of the problem.

For instance, most job logs will contain a very early escape message reporting "Program message queue QCL not found". If you read the job log forwards and stop at this apparently fatal/severe message you will miss the actual error that caused the upgrade to fail. In this case, this error occurs when the upgrade software tests which IBM command requester program is controlling it, (QCL or QCMD). It is not fatal and does not indicate any problem with the upgrade.

Do not restart the installation without first checking the job log produced for messages that clearly indicate the source of the problem.


4. Upgrade LANSA on IBM i

Optional step: If you have an existing LANSA system that uses the QGPL library for many LANSA objects, you may wish to upgrade your system configuration to use a communication library other than QGPL. Refer to LANSA Communications Library for more details.

If you are upgrading an existing LANSA system (including any of LANSA for iSeries, LANSA for the Web, LANSA Integrator, and Open System Utilities), complete the following task:

Task: Upgrade an Existing LANSA for iSeries System

If you are upgrading a Multi-tier LANSA for the Web system, you must also complete the following task on the IBM i Web Server:

Task: Upgrade an Existing LANSA for the Web - Web Server ONLY on IBM i

Once you have completed the upgrade of LANSA for iSeries software, you should complete the following:

Upgrade LANSA Windows Software

Refer to the Supported Platforms and Versions document, for supported platforms/software compatability.


4.1 Task: Upgrade an Existing LANSA for iSeries System

Check your current lansa versions

If the version of the LANSA system that you are upgrading is:

· at Version 11.3 or later, continue with the upgrade

otherwise

· you must first upgrade your system to Version 11.3.

If you are unsure what you need to do, contact your local LANSA vendor for the update steps you will need to take.

Are you planning to create more partitions? If yes, save time by creating them during the upgrade.

You will perform the following steps to upgrade your LANSA for iSeries:

· Before You Begin Checklist

· Special Warnings

· Start the Upgrade process

· Select the LANSA system to be upgraded

· Partition Initialization

· Confirm your Selected Options

Note: If you have been evaluating LANSA and do not need to keep anything produced so far, you may wish to delete the existing system and simply re-install a brand new LANSA system.


4.1.1 Before You Begin Checklist

Before you begin the Upgrade LANSA for iSeries task, check the following:

· Have you reviewed the General Install/Update Checklist? This list has items that are pertinent to the upgrade.

· Is the version of the LANSA system that you are upgrading at the required version level? Refer to Upgrade an Existing LANSA for iSeries System if necessary.

· Do you know which software Components, Partitions and Options you will be upgrading?
If you do not know the answer to this question, stop now and recommence after you have obtained this information.

· Have you scheduled the upgrade at a time when no developers, users, or jobs will be using the LANSA system?

· Have you checked that there are no jobs/users accessing LANSA? Check as described in How to check for Active Users.
Note: "users" includes the Listener and JSM. Make sure both are closed. (If not closed, an error message will be displayed indicating that there are still users accessing the system.)

· Have you backed up the libraries and any IFS directories required by the LANSA system you will be upgrading?

· If you are upgrading LANSA Integrator:

· Have you backed up all the Integrator directories from the IFS and the objects library?

· Have you changed any sample source code, job description or sub-system objects? If yes, refer to LANSA Integrator Special Warnings.

· Have you verified that there are no existing installer/loader objects in QGPL? Refer to Remove old Loader Objects from QGPL for details.

· Have you a plan to move your communication objects from QGPL? Refer to LANSA Communications Library for further information.
Note: During earlier versions of LANSA, the LANSA install and upgrade objects were placed in QGPL. Now, the LANSA upgrade creates its own work library. For further information, refer to Back up your Libraries.

· Have you reviewed the Special Warnings?


4.1.2 Special Warnings

User Objects in the Program Library

The upgrade process deletes all objects from the program library before starting the upgrade. Any user defined (i.e. non-LANSA) objects should be moved to another library (or backed up) before commencing the upgrade procedures.

These objects can be moved back again after the upgrade has been completed however, the storage of user defined objects in the LANSA program library is not recommended.

Multilingual Users

If you have special versions of the DC@M01 message file in your national language (e.g.: DC@M01ITL or DC@M01JPN) then they should be moved or saved before the upgrade is started. After the upgrade has been completed they should be moved or restored to the program library.

Japanese Language Developers

If you have additional help text members in files DC@F01 or DC@F41 (e.g.: DC@F01JPN or DC@F41JPN) then these members should be moved or saved before the upgrade is started. After the upgrade have been completed, they should be copied back into new members in the newly installed DC@F01/DC@F41 files.

$$* files in LANSA database library

The upgrade process creates its own database files as $$* files. These $$* files are deleted after a successful upgrade.

Note that if you have renamed any files in the LANSA database library as $$*, they will also be deleted. You should save and move these files before you start the upgrade progress.


4.1.3 LANSA Integrator Special Warnings

If you are upgrading LANSA Integrator, please note that new source, job descriptions and sub-system description files are shipped as examples. For example, source files QRPGLESRC, QCLSRC are provided by LANSA and every upgrade replaces these files. If you have customized any source file, you are advised to keep these customized files with another name. You can then check if there have been changes to the new source members and reflect these changes in your customized files. The same applies to all objects created for those source members.

If you have previously configured JSM to run values other than the default ones (i.e. JSMLIB, JSM jobd, etc), then after the upgrade you won't be able to start JSM using the option 1 in the JSM menu. You will need to re-run the CL programs that you have previously modified.


4.1.4 Start the Upgrade process

You must use the QSECOFR or a profile in the QSECOFR group. The use of other profiles or the removal of the special authorities will cause security and integrity alterations to the upgraded system.

1. Immediately before you start, sign off the IBM i. Sign on again but do not evoke LANSA from this session.

2. Insert the LANSA IBM i Software DVD or the first CD-ROM into the IBM i drive.

3. If you are using an Independent Auxiliary Storage Pool (IASP) then you must set the IASP group by calling the SETASPGRP command. (Refer to Using Independent Auxiliary Storage Pool (IASP) for information.)

4. From an i5/OS command line (CALL QCMD), enter the following command to restore the software:

LODRUN DEV(*OPT)

The LANSA Installation Program screen will be displayed.

The Upgrade option is only available if the program finds a LANSA component.

5. Specify the name of the Job Queue and library to which the actual upgrade job is to be submitted. The default value is job queue QBATCH in library QGPL. If this is not valid at your installation, change it to the name required.

Note: The upgrade will create a new LANSA Root Directory. It is recommended that you use the default directory.

6. Enter 4 to select the Upgrade and press Enter.

7. If you are loading from a CD-ROM as opposed to a DVD, at the appropriate time, you will be asked to load the second the LANSA IBM i Software CD-ROM. Before you remove the first CD, you will be asked if you wish to continue.

Reply G to continue or C to Cancel.

If you Cancel the install, the job will end without doing any Imports but will leave a basic LANSA System. If you wish to use this LANSA system, you will need to import the Imports using the Housekeeping menu or the Initialize Partition option from the Word with Administration Task.

Go to Select the LANSA system to be upgraded.

You must use the QSECOFR or a profile in the QSECOFR group during the upgrade. The use of other profiles or the removal of the special authorities will cause security and integrity alterations to the upgraded system.


4.1.5 Select the LANSA system to be upgraded

1. After you have selected the upgrade option, the Select the required Components screen will appear.

A list of all the LANSA Components, their versions, Libraries and System Owners that you currently have installed on your IBM i is displayed.

2. Press Page Down to view a second page, if applicable.

3. Enter "2" to select the LANSA Component(s) that you wish to upgrade.

Components

You may select only one LANSA for iSeries system to upgrade. To upgrade another LANSA for iSeries system, you must execute the upgrade again.

If the LANSA for iSeries system includes LANSA for the Web components, the LANSA for the Web components are automatically upgraded. (The LANSA for the Web components are not listed separately on the Select the required Components screen.)

When upgrading a LANSA for iSeries system, you may also upgrade any combination of LANSA for iSeries, LANSA Integrator and Open System Utilities - provided they are listed.

If you are using a Multi-tier LANSA for the Web installation, you must only upgrade the LANSA for the Web Server by itself. Updating a Web server is described in Task: Upgrade an Existing LANSA for the Web - Web Server ONLY on IBM i.

If LANSA Integrator was originally installed at the same time as LANSA was installed, LANSA integrator will be automatically selected for upgrade.

A LANSA root directory will be created and the upgrade will move existing LANSA Communication objects to the new directory.

Note: When LANSA Integrator or a Web Server are selected alone, Partition Initialization will be bypassed as it is not required.

After completing your selections, press Enter to continue.

Error messages will be displayed if:

· Anyone is still using the LANSA system

· An error is found with the parameters the upgrade will use.


4.1.6 Partition Initialization

1. The LANSA components are supplied with LANSA standard definitions, applications or tools. You use the partition Initialization process to select the items to be updated for each of the partitions you are updating.

The Partition Initialization screen displays a list of the partitions containing a LANSA system on your IBM i.

2. Enter "Y" to select the Partition(s) that you wish to upgrade. You can upgrade the options in more than one partition during the upgrade process.

3. If you wish to create a new partition press F6. Refer to Create New Partition for details.

4. If you wish to delete new partitions, press F5.

5. Press Enter to go to Select Options to be upgraded.

If you do not choose any options to upgrade at this time, you can do so later. For further information, refer to Manual Import.

Note that a "Y" in the Status column indicates that options have already been selected for the partition.

6. When you have made your selections, or if you choose not to select any options to upgrade during this process, press Enter to go to the Start the Upgrade Process.


Select Options to be upgraded

Enter "Y" for each option you wish to have upgraded for the partition you have selected.

Note: If you select Web Enable, make sure that LANSA for the Web has, or is being, installed. If it hasn't, install it using the Custom Install process. Refer to the Task: Custom Installation

Press Enter after you have made your selection(s). You will be returned to Partition Initialization.


4.1.7 Start the Upgrade Process

4.1.7 Confirm your Selected Options

The Upgrade Summary screens show you the parameters that will be used in the upgrade. These parameters are based on the current LANSA system that you are updating as well as options you have selected during this upgrade process.

The number of Summary screens and the information presented on them will depend on the options you have selected to be upgraded.

Check these summary screens carefully. If you do not wish to proceed with the parameters that will be used in this upgrade, you can change them by returning to either to the beginning or to Partition Initialization or you can cancel the upgrade process.

Use the Page Down and Page Up keys to scroll through the summary screens to view the parameters, options and components you have selected.

If you do not wish to submit the upgrade job, press F3 to exit.

To return to a previous screen to make a change, press F11.

When you are satisfied that the parameters displayed on the update Summary screens are correct on the final summary screen, press F8 to submit the batch job.
A list of software that has been updated is produced.

Leave the LANSA DVD or CD-ROM loaded until the batch job completes execution.

If there are any EPCs with the Install, they will be applied and the EPC log updated accordingly.

Go to Verify the Upgrade.


4.1.8 Verify the Upgrade

During the upgrade, any EPCs supplied with the install will be automatically applied.

You may wish to use the i5/OS command CHGMSGQ to change the nominated <message queue> to DLVRY(*BREAK) to receive any messages from the submitted job. For example:

CHGMSGQ DSP02 DLVRY(*BREAK)

Once the LANSA update job has completed, check the job's spooled file for the following:

Check messages

· Filename: QPDSPMSG

· User Data: SUMMARYMSG and DETALMSG

and check for any errors.

Check for required IBM i software

· Filename: QSYSPRT

· User Data: DC@LOAD25

The final message after a successful install is:

****All selected LANSA components have successfully installed****

Retain the job log that results from the install for future reference regardless of whether the install message appears or not.

Refer also to Verify Integrator Upgrade if appropriate.

Once the LANSA upgrade batch job has been completed and if Initialization options have been selected, make sure the job LANSA_CLN is released. For further details of LANSA_CLN, refer to Check LANSA_CLN.

QOTHPRDOWN User Profile

If you had used QOTHPRDOWN instead QSECOFR to do the install, the QOTHPRDOWN profile might not have authority to use the command STRSBS. Because of this, the following sub systems might not start automatically:

· LISTENER

· LANSA for Integrator (if installed).

You can use a User Profile that has appropriate authority to start sub systems (STRSBS).

If you did not not use QOTHPRDOWN as the product owner, you must perform the steps in QOTHPRDOWN Profile not used.

Upgrade failure

If you do not see the message:

All selected LANSA components have successfully installed****

Read the job log that results from the upgrade to determine the reason for the upgrade's failure. When reading the job log, always read it backwards from the end. If you read it from the beginning, you cannot assume that the first error you see is the cause of the problem.

For instance, most job logs will contain a very early escape message reporting PROGRAM MESSAGE QUEUE QCL NOT FOUND. If you read the job log forwards and stop at this apparently fatal/severe message you will miss the actual error that caused the upgrade to fail. In this case, this error occurs on the job log when the upgrade software tests which IBM command requester program is controlling it, QCL or QCMD. It is not fatal and does not indicate any type of problem with the upgrade.

Restarting an upgrade

Under no circumstances should you restart the upgrade without first checking the job log produced for messages that clearly indicate whether you can restart it or not. You must follow the recovery/restart procedures that are printed at the end of the upgrade job log.


Verify Integrator Upgrade

Check for the completion message:
UPGRADE OF LANSA INTEGRATOR COMPLETED, PLEASE CHECK THE JOB LOG.

If you do not see this message:

****All selected LANSA components have been successfully installed/upgraded**

read the other messages in the job log and perform any suggested actions.

The Integrator upgrade program restores the JSM properties and JAR files and only partially upgrades the Java Service Manager.

The first time you start the Java Service Manager after an upgrade, it will run for a short while and, if the upgrade has been successful, it will restart itself, ready for you to use. If the upgrade has not been successful, the Java Service Manager will not start.

You can check the Java Service Manager upgrade's progress by viewing the UPGRADE-LOG.TXT file (example below) in the JSM instance directory. Always check this file for completion messages, to be sure that the upgrade has been completed successfully.

Upgrade JSM instance : /jsm/instance -

Upgrade properties file : manager.properties

Properties file upgraded

-

Upgrade properties file : service.properties

Properties file upgraded

-

-

Upgrade properties file : XMLQueueService.properties

Properties file upgraded

-

Upgrade completed

Remove upgrade files

-

Delete file : /devjsm/instance/upgrade/mailcap.txt

-

Delete file : /devjsm/instance/upgrade/integrator-feature.txt

-

-

Delete upgrade directory

-

Removal completed

User Exit programs

If User Exit programs JSMADMEXT, JSMDRTEXT, JSMLSAEXT and JSMPXYEXT are used they should be checked and recompiled. Samples are provided in file QCLSRC. For information, refer to Exit Programs (IBM i).

Review files and manually adjust

After the upgrade has completed it is important to review the files and make some manual adjustments.

All the properties files will contain Integrator Studio sections and an "unassigned" section. This section contains lines that did not belong to a section.

Review the unassigned section for possible configuration entries. Normally this section just contains # comments and the whole section can be deleted.

#!<studio-project id="00000000-000000" name="unassigned">

#

# Move these entries to a new or existing studio-project section.

# Delete this unassigned section.

#

#

#!</studio-project>

After reviewing the files, start the JSM instance again and the instance will be ready.

PKI Editor

The PKI Editor is available for use when using the secure mime feature to send and receive e-mails using the SMTP mail, POP3 mail and EDI-INT (AS2) services. This is only available if the secure mime jar files are installed. These jar files are not shipped with LANSA Integrator as these files relate to Public Key encryption which must be purchased separately from Phaos Technology Corporation to support secure mime (SMIME). In particular, the software that needs to be purchased is:

· Phaos Security Engine

· Phaos CMS

· Phaos S/MIME

Please refer to the Phaos Technology Corporation web site for more information.


4.2 Task: Upgrade an Existing LANSA for the Web - Web Server ONLY on IBM i

If you are using a multi-tier LANSA for the Web installation, you will have LANSA for the Web software installed on a separate IBM i machine acting as the Web Server. This IBM i machine may not have a LANSA for iSeries system installed. Only the Web Server software for LANSA for the Web may need to be installed on the machine.

In order to update this IBM i Web Server, you will perform the following steps:

Before You Begin Checklist

Start the Web Server Upgrade

Select the Web Server to be upgraded

Confirm your Selected Options

Verify the Upgrade

Note: If you are using a single-tier installation, there is no need to perform a separate upgrade of the Web Server. The LANSA for the Web software is automatically updated with the LANSA for iSeries software.


4.2.1 Before You Begin Checklist

Before you begin the Upgrade of the LANSA for the Web Server ONLY task, check the following:

· Have you reviewed the General Install/Upgrade Checklist?

· Have you scheduled the upgrade at a time when no developers, users, or jobs will be using the LANSA system?

· Have you checked that there are no jobs/users accessing LANSA? Check as described in How to check for Active Users.

· Have you backed up the libraries that you will be updating?

· Have you verified that there are no existing installer/loader objects in QGPL? Refer to Remove old Loader Objects from QGPL for details.

Note: During earlier versions of LANSA, the LANSA install and upgrade objects were placed in QGPL. Now, the LANSA upgrade creates its own work library. For further information, refer to Back up your Libraries.

If you answer Yes to all these questions, go to Start the Web Server upgrade.


4.2.2 Start the Web Server upgrade

Insert the LANSA IBM i Software DVD or first CD-ROM into the relevant drive of the IBM i Web Server.

From an i5/OS command line (CALL QCMD), enter the following command to restore the software:

LODRUN DEV(*OPT)

The LANSA Installation Program screen will appear.

The Upgrade option is only available if the program finds a LANSA component.

Specify the name of the Job Queue and library to which the actual upgrade job is to be submitted. The default value is job queue QBATCH in library QGPL. If this is not valid at your installation, change it to the name required.

Note: The upgrade will create a new LANSA Root Directory. It is recommended that you use the default directory.

Enter 4 to select the Upgrade and press Enter.

If you are loading from a CD-COM, the appropriate time you will be asked to load the second LANSA IBM i Software CD-ROM. Before you remove the first CD, you will be asked if you wish to continue.

· Reply G to continue or C to Cancel.

· If you Cancel the install, the job will end without doing any Imports or EPC updates but will leave a basic LANSA System. If you wish to use this LANSA system, you will need to import the Imports using the Housekeeping menu or the Initialize Partition option from the Word with Administration Task.

Go to Select the Web Server to be upgraded.


4.2.3 Select the Web Server to be upgraded

After you have selected the upgrade option, the Select the required Components screen will appear.

A list of all the LANSA Components, their versions, Libraries and System Owners that you currently have installed on your IBM i is displayed.

Enter "2" to select the LANSA for the Web Server that you wish to upgrade and press Enter to continue to Start the Upgrade Process.

If any errors are found, error messages will be displayed and you will need to take action on them before the upgrade can continue.

Note: When you upgrade a Web Server, you cannot upgrade any other components at the same time.


4.2.4 Start the Upgrade Process

4.2.4 Confirm your Selected Options

The Upgrade Summary screens show you the parameters that will be used in the Web Server upgrade.

Use the Page Down key to scroll through the summary screens to verify that the parameters to be used in the upgrade process are correct.

If you do not wish to proceed with the parameters that will be used in this upgrade, you can press F3 to cancel the upgrade process and return to it later.

If you do not wish to submit the upgrade job, press F3 to exit.

To return to a previous screen to make a change, press F11.

If you are satisfied with the upgrade summary, when you reach the final page, press F8 to submit the batch upgrade job.
A job submitted message will be displayed followed by a list of the options that you selected.

For a Web Server upgrade, once the install process is completed, a clean up job called LANSA_CLN is submitted to delete the LANSA install work library.

Go to Verify the Upgrade.


4.2.5 Verify the Upgrade

Leave the LANSA DVD or CD-ROM loaded until the batch job completes execution.

If any EPCs are included with the install, they will be applied and the EPC log will be updated accordingly.

You may wish to use the i5/OS command CHGMSGQ to change the nominated <message queue> to DLVRY(*BREAK) to receive any messages from the submitted job. For example:

CHGMSGQ DSP02 DLVRY(*BREAK)

Once the LANSA update job has completed, check the job's spooled file for the following:

· File: QPDSPMSG

· User Data: SUMMARYMSG and DETALMSG

and check for any errors.

The final message after a successful upgrade is:

****All selected LANSA components have successfully installed****

Retain the job log that results from the install for future reference regardless of whether the install message appears or not.

Once the LANSA upgrade batch job has been completed and if Initialization options have been selected, make sure the job LANSA_CLN is released. For further details of LANSA_CLN, refer to Check LANSA_CLN.

Note: Regardless of whether the upgrade message appears or not, retain the job log that results from the upgrade for future reference.

Refer also to Verify Integrator Upgrade if appropriate.

If you did not not use QOTHPRDOWN as the product owner, you must perform the steps in QOTHPRDOWN Profile not used.

Upgrade failure

If you do not see the message:

****All selected LANSA components have successfully installed****

Read the job log that results from the upgrade to determine the reason for the upgrade's failure. When reading the job log, always read it backwards from the end. If you read it from the beginning, you cannot assume that the first error you see is the cause of the problem.

Restarting an upgrade

Under no circumstances should you restart the upgrade without first checking the job log produced for messages that clearly indicate whether you can restart it or not. You must follow the recovery/restart procedures that are printed at the end of the upgrade job log.


4.3 Upgrade LANSA Windows Software

Once you have completed the upgrade of LANSA software on IBM i, you must remember to upgrade any associated LANSA Windows software products.

For example, if you have LANSA for the Web installed on IBM i, and you are using WebEvents, you should upgrade the Web Function Editor on both the IBM i and your Windows PC.

Your LANSA software on IBM i and LANSA software on Windows should always be maintained at the same level. For example, if you are using LANSA for iSeries at V11 SP5, then your Visual LANSA Systems should also be at V11 SP5.

LANSA Windows software includes the following components:

· Visual LANSA

· LANSA for the Web

· LANSA Integrator

· LANSA Open (previously LANSA/Server)

· LANSA Client.

For details about upgrading the LANSA Windows Software, refer to the Installing LANSA on Windows Guide.


4.4 LANSA Communications Library

The objects in the Communications Library are specific to a version of a LANSA system. Hence, if you have more than one LANSA system installed, it is recommended that you have multiple Communication Libraries. If you have customized your LANSA system installation or if you have multiple LANSA systems installed on a single IBM i, you may have created your own version of a Communications Library. For example, a QGPL2 library for a second LANSA system.

QGPL as the Communication Library

You must use a different library. To create the new library, use the steps in Change from QGPL to a LANSA Communications Library prior to upgrading your LANSA system.


4.4.1 Change from QGPL to a LANSA Communications Library

To use a separate Communications Library instead of QGPL, use the following procedure to update your LANSA library structure:

Note: You should be an experienced LANSA user if you are performing these steps. They should NOT be carried out immediately before running a LANSA upgrade as you will need to test your changes thoroughly before running the upgrade as described in Step 7.

1. BEFORE you upgrade your LANSA system, create the new LANSA Communications Library. You might name this library DCXCOMLIB (or use whatever name meets your site standards).

2. Back up the DC*, LC*, LX*, W3*, GU*, JSM*, LWEB.DAT and LANSA* objects in the QGPL library.

3. Restore these backed up objects to your new DCXCOMLIB.

4. Remove the DC*, LC*, LX*, W3*, GU*, JSM*, LWEB.DAT and LANSA* objects from the QGPL library.

5. Remove loader objects (if there are any) left from a previous installation or upgrade. Refer to Remove old Loader Objects from QGPL for details.

6. Modify all LANSA related job descriptions, user profiles, sub-system descriptions, etc. so that the new DCXCOMLIB is included in the library list before QGPL. (You should leave QGPL in your library list in case there are other non-LANSA objects required by your jobs.)

7. Change the Communications Library name in data area DCXLOADA01, position 21 using this command:

CHGDTAARA dtaara(<pgmlib>/DCXLOADA01 (21 10)) VALUE(<comlib>)

8. Change the CGI Library name in data area DCXLOADA02, position 12 using this command

CHGDTAARA dtaara(<pgmlib>/DCXLOADA02 (12 10)) VALUE(<cgilib>)

If the CGI Library is the same as the COMLIB then use the COMLIB for the <cgilib> value.

Note: Some times the CGI LIB is not the same as COMLIB.

9. Test your LANSA system to ensure that it works with the new library. Be sure to check your developer and user profiles. Check all batch and interactive jobs. Remember to check any client/server jobs, including LANSA Client, LANSA SuperServer and Host Monitors for Visual LANSA. Test your LANSA for the Web applications. Check your LANSA for the Web Administrator and Editor. Please allow several days or weeks to ensure that you have not missed any library list updates.

10. Once you have completed testing your LANSA systems using the new library structure, (and changed the library name in data area DCXLOADA01) you are ready to perform the upgrade.

11. If you are using LANSA for the Web, change your configuration to reference the new Communications Library (for example, DCXCOMLIB) instead of QGPL.


4.4.2 Remove old Loader Objects from QGPL

If the following objects exist in QGPL they should be removed:

DCXLOAD* Type *DTAARA

DC@LOADERI Type *DTAARA

DC@LOAD* Type *FILE

DCXLOAD* Type *FILE

DCXLOAD* Type *MSGF

PC@LOAD* Type *PGM

DC@PC* Type *PGM

DC@LOAD* Type *PGM

DC@LOAD* TYPE *SRVPGM

That is, the following commands could be used

DLTDTAARA QGPL/DCXLOAD*

DLTDTAARA QGPL/DC@LOADERI

DLTF QGPL/DC@LOAD*

DLTF QGPL/DCXLOAD*

DLTMSGF QGPL/DCXLOAD*

DLTPGM QGPL/PC@LOAD*

DLTPGM QGPL/DC@PC*

DLTPGM QGPL/DC@LOAD*

DLTSRVPGM QGPL/DC@LOAD*


4.5 Initialization Imports

The LANSA components are supplied with LANSA standard objects, applications and tools. In this section, these objects and applications are generically referred to as imports.

These imports can be installed in one of these ways:

· During an install/upgrade by Partition Initialization.

· At any time using Partition Initialization available from the Administration Menu and described in the iSeries User Guide.

· Manually, as described in The Steps Involved in Importing in the iSeries User Guide.

WARNING: The System Variables contain the Web graphic variables and these are reset when you import the System Variables.
It is strongly recommended that you back up your System Variables (by exporting them to a Save file) before you do the Import.

For information about importing IFS Objects, refer to IFS Objects in Importing Objects - Tips and Techniques in the iSeries User Guide.


4.5.1 Manual Import

For a newly installed system or an upgraded system, import requirements should be satisfied by the Partition Initialization. However, you may need to manually import the supplied objects when you create a new partition or if a set of standard definitions are corrupted and you wish to reset them.

To install the shipped objects, use the LANSA Housekeeping Menu and select the option to Import Objects into this Partition. For the optical path of the import you require, concatenate /AS400 with the directory name of the import supplied (refer to Imports on the LANSA IBM i Software DVD or CD_ROM). For example, to import the full set of templates, specify the drive's name (e.g. OPT01) and /AS400/TEMPLATE for the file name.

When a set of fields are imported, all fields that refer to the imported fields are updated. The action of making the referred changes to fields on import can be deferred by use of the keyword *IMPREFFLDNOPROP in DC@OSVEROP.

For full help on importing, go to the Housekeeping Menu and choose the option Import objects into this partition, then use F1 to invoke the help.

To import in multilingual format, before starting the import, the partition into which you are importing must be set to multilingual. Refer to Change Partition to Multilingual and Change Partition to non-Multilingual. You can import a non-multilingual application into a multilingual partition.

Templates and System Variables are defined at the system level. They are imported once per system. They do not have to be imported when a new partition is initialized.


4.5.2 Imports on the LANSA IBM i Software DVD or CD-ROM

This table describes the supplied LANSA IBM i material.

Object | /AS400I directory | Multilingual Partition
System fields | /SYSFLDS | No
System fields - changes only | /SYSFLDU | No
System variables | /SYSVAR | No
System variables changed | /SYSVARU | No
LANSA templates | /TEMPLATE | No
Multilingual help | /HELP_ML | Yes
Non-multilingual help | /HELP_NML | No
Data Modeler | /MODELER | Yes
Personnel Demonstration System | /PERSYS | Yes
LANSA Client enable | /CLIENT | Yes
e-Business Framework Wizard | /LWEBWIZ2 | Yes
RDMLX Fields | /SYS_FLDX | Yes

Note:

· LWEBSF AND WEBLETS are Save files in the program library. They are imported together into an RDMLX partition if the Web enable option is selected. WEBLETS cannot be imported into an RDML partion.

· LWEBSF - Web Enable.

· WEBLETS - the WAM weblets.

· The Data Modeler is no longer installed during the Partition Initialization. If it is required, you can import it using the Partition Initialization option on the Administration menu.


5. LANSA IBM i License

When you install a new LANSA product you must enter the appropriate license codes. The license codes are CPU specific and will be provided by your local LANSA vendor. You must supply your product vendor with the CPU number and IBM i model number of each IBM i on which LANSA is installed.

For more information about LANSA licenses, refer to:

Task: Enter the LANSA License Code

Battery License

LANSA License Codes

Maintenance Contract

Requesting a LANSA Product License

If you need to request a LANSA product license, you will need to provide information about your IBM i. Refer to Identify your IBM i Details for how to do this.


5.1 Task: Enter the LANSA License Code

If you are upgrading an existing LANSA system, your license codes should have already been entered.

To record a LANSA license, you will carry out these steps:

Before You Begin Checklist

Step 1. Sign on and Execute LANSA License Program

Step 2. Insert a Permanent License Code

Step 3. Display the License Status


5.1.1 Before You Begin Checklist

Before you begin the to enter LANSA License codes, check the following:

· Do you have the QSECOFR password or access to the LANSA Product Owner user profile? You will require one of these profiles to execute the LANSA license program.

· Do you know the name of the LANSA program library (<pgmlib>) for the LANSA system?

· Do you have all of the required CPU specific license codes for the installed LANSA products? (Refer to List of License Codes.)

Go to Step 1. Sign on and Execute LANSA License Program.


5.1.2 Step 1. Sign on and Execute LANSA License Program

Sign on to the IBM i using one of the following profiles:

· QSECOFR user profile, or

· partition security officer profile for SYS partition.

From an i5/OS command entry (CALL QCMD), execute the LANSA license facility using the command:

<pgmlib>/LANSA LICENSE

where <pgmlib> is the name of the program library specified during the installation of LANSA.

The Work With Licenses menu is displayed.

DC@P803501 Work With Licenses

Enter number of function or place cursor on same line and press Enter.

2 1. Display Current Licensing Status

2. Insert a Permanent License Code

F1=Help F3=Exit F14=Messages

Select the Insert a Permanent License Code function by either entering the line number (in this case 2), or moving the cursor to the Insert a Permanent License Code line and pressing Enter.

Battery license

To process a Battery license, you will use the Work With Licenses window. To see the battery license related entries, change position 750, in Data Area DC@A07 to Y.

DC@P803501 Work With Licenses

Enter number of function or place cursor on same line and press Enter.

2 1. Display Current Licensing Status

2. Insert a Permanent License Code

3. Use up some Battery License Time

4. Prepare a Request for a Battery License Recharge/Replacement

5. Insert a Battery License Recharge/Replacement

F1=Help F3=Exit F14=Messages

Go to Step 2. Insert a Permanent License Code.


5.1.3 Step 2. Insert a Permanent License Code

When you select the Insert a Permanent License Code option from the Work With Licenses menu, the Insert a Permanent License Code screen is displayed.

DC@P803502 Insert a Permanent License Code

Specify New License Code and press Enter.

New License Type . . . . . . XXX

New License Code . . . . . . ___________

F1=Help F3=Exit F12=Cancel F14=Messages

Use this screen to insert each new permanent or temporary license code supplied by your product vendor. The license code can only be inserted on the IBM i for which it was issued.

New License Type

Enter the Type of License issued to you.

New License Code

Enter the License Code assigned to your IBM i.

As this is quite a long code, care must be taken to enter it correctly. To assist you, below the code are the numbers and letters of the code, printed in words.

For example, code "103OVX58" would be printed in words as:

ONE ZERO THREE OSCAR VICTOR XRAY FIVE EIGHT.

Press Enter to update.

AFTER UPDATING LICENSE DETAILS, SIGN OFF AND ON AGAIN.

Go to Step 3. Display the License Status.


5.1.4 Step 3. Display the License Status

Check the status of your licenses to confirm the newly entered codes.

From the Work With Licenses menu, select the Display Current Licensing Status option.

The Display Current Licensing Status screen is displayed.

DC@P803502 Display Current Licensing Status

Your Permanent Licenses are . . :

DEV Permanent LXX Permanent

D03 Permanent RUM Permanent

LCE Permanent WEB Permanent

F1=Help F3=Exit F12=Cancel F14=Messages

A list of all licenses available is displayed with each one followed by the current status.

A LANSA license is either a full development license, with no restriction on the number of developers, or a seat license, for a number of concurrent users.

Seat License Types are in the format 'Xnn' where 'X' is the product code and 'nn' is a hexadecimal number representing the number of seats. It is possible to have up to 255 seats.

For a list of license codes, refer to List of License Codes

Once you have checked your licenses, exit the display.

Sign off the IBM i.

The LANSA license code update task is now complete.

Battery license

In most cases, you will not be interested in the remaining Battery license. Should you wish to see the remaining Battery license and the Date(s) Used, change position 750 to Y, in Data Area DC@A07 to view the details as shown below.

DC@P803502 Display Current Licensing Status

Your Permanent Licenses are . . :

DEV Permanent LXX Permanent

D03 Permanent RUM Permanent

LCE Permanent WEB Permanent

You have nn days of Battery License time remaining

Battery license discharges have been made as follows . . . :

Date Used Discharged Effective From Effective To Status

(YYYY/MM/DD) By User (YYYY/MM/DD) (YYYY/MM/DD)

F1=Help F3=Exit F12=Cancel F14=Messages


5.2 Battery License

A Battery License is for temporary or emergency use of LANSA for iSeries. If you do not have a current development license, you can use the battery license to do development for a limited number of days.

A battery license contains a "charge" of "n" days of full development time. This is equivalent to "n" days of a permanent DEV or Dnn license. All newly installed systems have an initial charge of 10 days provided free of charge.

The battery "charge" can be "discharged" for a day or number of days, whenever required. The battery charge is reduced by the number of days discharged. The "charge" in a battery license can be "recharged" at any time.

For more information about Battery Licenses, refer to:

Using up Some Battery License Time

Requesting a Battery License Recharge or Replacement

Inserting a Battery License Recharge or Replacement


5.2.1 Using up Some Battery License Time

To obtain some extra license time for an expired DEV or Dnn license, select the Use up some Battery License Time option from the Work with Licenses screen.

On the Use Up some Battery License Time screen, enter the amount of time you require. Remember that once you have pressed Enter, you can never reclaim this time, you can only "recharge" it by buying more battery license time. It is therefore recommended that you use up battery license time in small units of 1 or 2 days.

A "day" is one calendar day. It is not a 24 hour time period. Once the battery license starts, it will last for the day specified. The license is based on calendar date. It is not based on the number of hours used.

DC@P803504 Use Up some Battery License Time

Specify Details of Time to be used and press Enter.

Effective Start Date (YYYY/MM/DD format) . . . . ___________

Effective End Date (YYYY/MM/DD format) . . . . . ___________

Total Number of Days . . . . . . . . . . . . . . __

===================> WARNING <===================

Once this battery license time has been assigned it can NEVER be

reclaimed or reused. It is better to use up battery license time

in small units (1 or 2 days) than in large amounts in case your

usage requirements change during the discharge period.

F1=Help F3=Exit F12=Cancel F14=Msgs

Effective Start Date

Date from which the battery license discharge time is to start, in YYYY/MM/DD format. This date initially contains the current system date.

Effective End Date

Date on which the battery license discharge time is to end in YYYY/MM/DD format. This date initially contains the current date.

Total Number of Days

The number of days you wish to use. This number must be equal to the difference between the Start and End dates that you have entered.

Press Enter to update your Battery License.


5.2.2 Requesting a Battery License Recharge or Replacement

To request a Battery license recharge or replacement, select the Request a Battery License Recharge/Replacement option from the Work with Licenses panel. You must make this request on the machine for which the Battery Recharge is required.

When you have entered the request details, a recharge/replacement request report is produced. Print the report and send it to your product vendor. You will notice that on the request report there is a special request "code". Without this code the request cannot be processed.

Note: Once the recharge/replace has been requested, take care that you do not run the request again. If you do, the code that will be supplied in response to the first request will no longer be valid.

DC@P803505 Prepare a Request for Battery License Recharge/Replacement

Specify Details of request and press Enter.

Print Resulting Report and Send to Your Product Vendor.

Type of request . . . . . . . . . RECHARGE RECHARGE, REPLACE

Total Number of Days Required 1 1-365

F1=Help F3=Exit F12=Cancel F14=Messages

Type of Request

Must be either RECHARGE or REPLACE.

Total Number of Days Required

Must be in the range of 1 to 365.


5.2.3 Inserting a Battery License Recharge or Replacement

To record a Battery license recharge or replacement, select the Insert a Battery License Recharge/Replacement option from the Work with Licenses panel. You must record this code on the machine for which the Battery Recharge is required.

DC@P803506 Insert a Battery License Recharge/Replacement

Specify Battery License Recharge/Replacement Code and press Enter.

Recharge/Replacement Code . . . . .

F1=Help F3=Exit F12=Cancel F14=Messages

Recharge/Replacement Code

Enter the Recharge/Replacement Code that your product vendor has issued to you.

Press Enter to update.

When you have finished this update, go to the Display Current Licensing Status screen to check that the Battery Charge has been updated successfully.


5.3 LANSA License Codes

LANSA License codes are required for developing with LANSA products, and may be required for executing applications created with specific LANSA products.

For more information about LANSA License Codes, refer to:

LANSA License Categories

List of License Codes

General Licensing Considerations


5.3.1 LANSA License Categories

The LANSA license categories are:

· Permanent

· Temporary

· Key

· Battery - for LANSA for iSeries developers only.

Each license code is valid for only one CPU serial number and cannot be transferred to another. If you plan to change your CPU, ensure that you obtain a new license before the change takes place.

Permanent License

A permanent license gives you complete access to all the facilities that LANSA provides for the product(s) for which you have the permanent license.

If the start date is in the future, the facility will not be available until that date. Permanent licenses with a future start date will be shown in the License status display with that date.

Temporary License

A temporary license is a license with an expiry date. When the expiry date is passed, the facility will stop running with a message indicating the reason.

A temporary license could be issued for the time up to changing to another CPU or for a trial of a LANSA product.

Temporary licenses are added and updated using the same procedures as permanent licenses.

Key License

Key licenses are used by LANSA Integrator. These may be permanent or temporary. If LANSA Integrator was linked to this LANSA system when installed, then the LANSA Integrator licenses will be shown.

Many of the LANSA Integrator services and tools are individually licensed or licensed as collections or bundles. You may not be licensed to use all the services and tools available.

Battery License

A Battery License is for temporary or emergency use, for DEV and Dnn license types only. (DEV and Dnn licenses are for LANSA Application Development on the IBM i using LANSA for iSeries.)

A Battery license can be used to:

· Change LANSA production systems temporarily to development mode, to allow minor modifications to be made to an application.

· Allow a "trial" of the LANSA for iSeries product.

· Cover any short fall for the period between your DEV or Dnn license expiry date and receipt of the new permanent license. (You should avoid this 'down' period if at all possible.)

A battery license contains a "charge" of "n" days of full development time. This is equivalent to "n" days of a permanent DEV or Dnn license. All newly installed systems have an initial charge of 10 days provided free of charge.

The battery "charge" can be "discharged" for a day or number of days, whenever required. The battery charge is reduced by the number of days discharged. The "charge" in a battery license can be "recharged" at any time.

Note: If you tamper with the Battery License or have to restore it after a system disk failure, you will effectively invalidate the battery and be forced to replace it. The moment tampering is detected, all battery license details are totally invalidated and become useless.


5.3.2 List of License Codes

A LANSA license is either a full development license, with no restriction on the number of developers, or a seat license, for a number of concurrent users.

Seat License Types are in the format 'Xnn' where 'X' is the product code and 'nn' is a hexadecimal number representing the number of seats. It is possible to have up to 255 seats.

Following is a list of some of the LANSA license codes:

License Code | Type of License
AXX | Unlimited RAMP Choreographer license.
Ann | Seat limited RAMP Choreographer license (e.g. A05)
Cnn | LANSA Client seat license, where 'nn' is the maximum number of PC users that can use LANSA Client at the same time.
DEV | LANSA for iSeries full development license. With this license you have complete access to all LANSA for iSeries development facilities.
Dnn | LANSA for iSeries development seat license, where 'nn' indicates the number of concurrent developers authorized to use the LANSA development facilities at the same time.
FCD | LANSA for the Web Commerce Edition Development License
FCE | Commerce Edition Direct
FCP | LANSA for the Web Commerce Production License
Jxx | Integrator License
LCE | LANSA Open (previously LANSA/Server)
LXX | LANSA SuperServer for dynamic access to the IBM i from the PC.
PWB | LANSA for the Web Production License
Snn | Seat limited LANSA Open License (e.g. S05)
WEB | LANSA for the Web Development License
Wnn | Seat limited LANSA for the Web Development License
Xnn | Seat limited SuperServer license (e.g. X05)


5.3.3 General Licensing Considerations

Following are some general considerations for LANSA licenses:

· To obtain a LANSA license code from your product vendor, you must supply the CPU number and IBM i model number of each IBM i on which LANSA is installed. For how to obtain these details refer to Identify your IBM i Details.

· The LANSA License program is installed on the Data/Application Server.

· To develop or maintain LANSA applications on the IBM i, you need a current LANSA development license.

· To develop or maintain LANSA for the Web applications on the IBM i, you need a current LANSA development license and a current LANSA for the Web development license.

· A LANSA for the Web development license also allows execution of LANSA for the Web applications.

· If you are only executing LANSA for the Web applications, then you do not require a WEB (LANSA for the Web Development) license. A PWB (LANSA for the Web Production) license is sufficient.

· You do not require license codes to use the LANSA for the Web PC-based Editor and Administrator.

· You do not require license codes to use the Open System Administrator.

· You require a license code for the LANSA Integrator.

· Remember that a Temporary License code has an expiry date.

For a list of license codes, refer to List of License Codes.


5.4 Maintenance Contract

A maintenance contract provides you with valuable services such as software upgrades, updates to documentation and a support line.

If you are using the LANSA workstation products, such as LANSA Open and LANSA Client, it is recommended that you also have a maintenance contract for LANSA for iSeries. This will ensure that you are automatically notified about all LANSA Repository enhancements.

The LANSA system administrator should receive and review the upgrade information and should have a means of keeping you up to date with the latest enhancements. The system administrator should also act as the liaison with your local LANSA vendor.

Many of the changes to the LANSA software have been the direct result of input from current LANSA users. Your comments are encouraged. The maintenance contract is part of your investment in the future of the software.

If your site's maintenance does not include LANSA for iSeries, contact your local LANSA vendor for details.


6. LANSA for the Web Configuration and Set Up on IBM i

If you are using LANSA for the Web on IBM i, you may need to perform one or more of the following configuration and set up tasks:

Task: Install LANSA for the Web Administrator and Function Editor

Task: Configure IBM i Web Server (powered by Apache)

Task: Configure Multi-tier IBM i LANSA for the Web Installation

Task: Upgrade from a Single-tier to a Multi-tier IBM i Web Model

Task: Install the e-Business Framework Wizard on IBM i

Task: Configure LANSA for the Web Security

Task: Set up IBM i Partition for Web Development

Task: LANSA for the Web Housekeeping


6.1 Task: Install LANSA for the Web Administrator and Function Editor

These two programs are installed on a Windows based PC and operated in a client/server mode to the IBM i Data/Application Server.

They are installed from the LANSA Windows Software DVD.

LANSA for the Web Administrator

The LANSA for the Web Administrator is used to configure the LANSA for the Web software on the Data/Application Server. It is only required by the LANSA system administrator.

LANSA Web Function Editor

The Web Function Editor is used to modify the LANSA generated HTML. It also used for working with Web components and graphic variables.

If you are using WebEvents, the Web Function Editor must be installed on each LANSA developer's PC.

If you are using WAMs, you do not need to install the Web Function Editor.

To install

On the required workstation, start the Installing LANSA on Windows DVD and select the Install Process. Select the Other LANSA Features as the Install Type and then, on the product selection list, tick LANSA for the Web and the Web Function Editor and/or the Web Administrator, as applicable.

Further information on this install can be found in the Installing LANSA on Windows Guide.


6.2 Task: Configure IBM i Web Server (powered by Apache)

LANSA for the Web supports CGI on IBM i.

If you have used a Typical Install or if you have selected CGI during the Custom Install of the LANSA for the Web, then a default IBM HTTP Server (powered by Apache) configuration will have been installed on your system named the same as your LANSA program library.

After reviewing the installation configuration, you should be ready to test your LANSA for the Web environment using the Simple test of LANSA for the Web on IBM i Data/Application Server.

Refer to Summary of Installed Objects.

If you are using a Multi-tier installation, go to Task: Configure Multi-tier IBM i LANSA for the Web Installation.

If you wish to configure the IBM HTTP Server and CGI yourself, you will find instructions for doing so on the LANSA Web site www.LANSA.com/support titled Configuration of IBM HTTP Server using CGI.


6.3 Task: Configure Multi-tier IBM i LANSA for the Web Installation

If you are using a Multi-tier LANSA for the Web Installation, you must perform the following tasks to complete your Web server configuration:

Configure LANSA for the Web on a Multi-tier IBM i Web Server

Configure IBM i Web Server for Communications with IBM i Data/Application Server

Once you have completed these steps, go to Simple WebEvent test LANSA for the Web on IBM i Data/Application Server


6.3.1 Configure LANSA for the Web on a Multi-tier IBM i Web Server

These instructions describe the configuration of a Multi-tier LANSA for the Web installation with a CGI based IBM i Web Server using the W3@P2901 program.

The Configure LANSA for the Web on a Multi-tier IBM i Web Server task includes the following steps:

Before You Begin Checklist

Step 1. Execute W3@P2901

Step 2. Work with Communication Routing on IBM i

Step 3. Add Routing Record on IBM i

Step 4. Configure IBM i Web Server

Step 5. Maintain System Information on IBM i Web Server

Step 6. Add New System Information on IBM i Web Server

Other Considerations for Multi-tier Installations


Before You Begin Checklist

Before you begin the Multi-tier Configuration Web Server task, check the following:

· Have you completed the LANSA for the Web software installation on the Web Server? If not, refer to Step 2. Select Software Components of the Custom Installation Task.

· Do you have the QSECOFR user profile?

· Do you know the name of the LANSA program library on the Data/Application Server?

· Do you know the name of the LANSA for the Web Administration Library?

· Do you know the name of the image file directory to be used on the IFS?

· Do you know the name of the CGI libraries to be used for the Web Server?

· Do you know the LANSA Listener configuration on the Data/Application Server?

· Do you have an IBM i user profile on the Data/Application Server which can be used for the communications sessions?

· Have you confirmed that the IBM i Web Server and IBM i Data/Application Server can communicate with each other?

Go to Step 1. Execute W3@P2901


Step 1. Execute W3@P2901

Sign on to the IBM i using the QSECOR profile. (You require *ALLOBJ and *SECADM special authority.)

Add the LANSA for the Web Administration library to the library list using the ADDLIBLE command. For example,

ADDLIBLE LIB(DCXPGMLIB)

From an i5/OS command entry (CALL QCMD), execute the W3@P2901 program using the command:

CALL <pgmlib>/W3@P2901

The Web Server Configuration menu is displayed.

Select Work with Communication Routing and press Enter.

Go to Step 2. Work with Communication Routing on IBM i.


Step 2. Work with Communication Routing on IBM i

When you select the Work with Communication Routing option from the Web Server Configuration menu, a list of all defined routings to other IBM i servers is displayed.

Press F6=Add to create a new routing entry to your Data/Application Server.

Go to Step 3. Add Routing Record on IBM i.


Step 3. Add Routing Record on IBM i

The routing information you enter on this screen is stored in the communications routing table /LANSA_adminlib/connect/lroute.dat where LANSA_adminlib is your LANSA administration library.

Enter the following information:

Partner LU name (Host)

This is the name for the Data/Application Server. (For example, the name might appear as S102ABCD.) This name is simply used to represent the fully qualified name. You will enter this name in Step 6. Add New System Information on IBM i Web Server.

Fully qualified name

For an IP connection, the fully qualified host name can be the IP address (for example 123.123.123.123) or it can be the assigned TCP Host Name (for example S102ABCD.APPN.SNA.IBM.COM) for the Application/Data Server.

Communications method

Enter SOCKET.

Press Enter to update.

Go to Step 4. Configure IBM i Web Server.


Step 4. Configure IBM i Web Server

From the Work Web Server Configuration menu, select the Configure Web Server option to display the Configure Web Server screen.

This information is stored in the data area DC@RWEB.

Enter the following information:

CGI

Specify CGI-BIN as the location of the CGI files used by the Web Server software.

This alias must be defined in the IBM's HTTP Server (powered by Apache) configuration.

Image Files

Enter the location of the image files used by LANSA for the Web. LANSA for the Web expects to find all the image files in a single location.

This alias must be defined in IBM's HTTP Server (powered by Apache) configuration.

Authentication Library

Specify AUTHLIB as the name of the library set up for user authentication on the IBM i Web Server. This is used by partial authentication.

This alias must be defined in the IBM's HTTP Server (powered by Apache) configuration.

Home Page

Enter the URL to be called when the user selects the Home button in LANSA functions.

By default, this parameter is left blank. If it is blank, LANSA for the Web will call the home page as defined in the IBM's HTTP Server (powered by Apache).

Working Library

Enter the name of the library on the Web serving IBM i where LANSA for the Web will create its internal objects at runtime.

Router Job Subsystem

This is the name of the JOB QUEUE for the subsystem where the LANSA Web jobs (LWEB_WSRV) will run on the Web Server. Do NOT enter the subsystem name. You will use this name in Configure IBM i Web Server for Communications with IBM i Data/Application Server.

Web Job Priority

Enter the priority of LWEB_WSRV jobs started by the CGI program.

Response Timeout

Enter the time (in seconds) that the CGI program should wait for the Application Server to return the request. This value must always be greater than the related response timeout defined on the Application Server otherwise strange and unpredictable problems may occur. The extra time should exceed the maximum expected delay for the data traveling between the Application Server and the Web Server.

Reset Monitor

Use this field when you wish to reset the transaction monitor job (LWEB_WMON).

Monitor Checks

Specify the time interval (in seconds) for the transaction monitor to check the status of the LWEB_JOB jobs. A typical Web site might specify 120 seconds (2 minutes).

Monitor Job Queue

Enter the JOB QUEUE name used for the subsystem where the LANSA Web jobs (LWEB_JOB) will run on the Web Server. This can be the same job queue used for the router jobs.

Monitor Job Priority

Enter the priority of the remote web monitor job.

Go to Step 5. Maintain System Information on IBM i Web Server.


Step 5. Maintain System Information on IBM i Web Server

Select the Maintain system information option from the Work Web Server Configuration menu to display the Maintain System Information screen. This screen will list all systems defined to LANSA for the Web.

Press F6=Add, to create a new system definition.

Go to Step 6. Add New System Information on IBM i Web Server.


Step 6. Add New System Information on IBM i Web Server

This information is stored in the file DC@W12 in the LANSA Communications Library.

Enter:

System Name

This is the system name or IP address of the IBM i Web Server.

If you are not using multi-homing support, enter *DEFAULT as the System Name.

If you are using multi-homing support, enter either the DNS Name (for example: demo.lansa.com) or the IP Address (for example: 123.123.123.123) in the System Name field.

Port

This is the port on which the IBM i Web Server software is listening.

If you are using the default port, 80, you may enter 99999.

Port 443 is only defined when SSL is enabled. The Web Server configuration must have the same information.

LANSA library

The LANSA program library on the Data/Application Server. The default is DCXPGMLIB.

Partition

Specify the partition if you want to have all the requests for that port use a particular LANSA partition. If a partition is specified, it will override any partition specified in the URL.

If no partition is specified, you must specify the partition parameter in your URL.

Remote System Information

Use Remote System

Set to 'R' for Multi-tier configuration.

System Name

Specify the name of the IBM i which is acting as your Application/Data Server. This must match the system name defined in Step 3. Add Routing Record on .

User ID/Password

Specify a user profile and its password. A user profile is required to allocate a communications conversation between the IBM i Web Server and the IBM i Application/Data Served.

Note: This user profile must exist on the IBM i Application/Data Server and must have sufficient authority to start jobs. It must also be enabled and include the libraries QTEMP, <LANSA Communications library>, <LANSA program library> and <LANSA data library> in its JOBD.

Note: Passwords are case sensitive. For example: "ABCDEF", "AbCdEf" and "abcdef" are not the same value.

Web Server Settings

Host CCSID

The Host CCSID used for data translation purposes. The default is 00037.

Client CCSID

The Client CCSID used for data translation purposes. The default is 00819.

Press enter to go to the next screen.

Default Technology Service

The technology service to use if no specific technology service is nominated in the user agent request.

General System Settings

SSL (Secured Sockets Layer) Support

Select this option if you want to enable SSL for this system.

The default LANSA library is the LANSA system assigned to port 80. This is the default port identifier for the HTTP protocol.

If you have SSL support enabled, remember that the default port for SSL is 443.

Server Side Include (SSI) Support

Select this option if you want to enable SSI support for this system. Make sure that your Web serving product is capable of supporting this feature before enabling this option.

HTTP Header Variable Support

Select this option if you wish to enable header variable support.

Spool File Access

Specify N. Spool file access is not allowed for this system

Hold System Information

Hold System

Specify N. Incoming requests for this system will not run but a hold message will be displayed.

Hold Message

If the Hold System option is specified 'Y'. This message will be displayed for all requests to this system.

Go to Other Considerations for Multi-tier Installations.


Other Considerations for Multi-tier Installations

Following are some important considerations for Multi-tier Installations.

Listener running on Application/Data Server

Check that the Listener program is running at the Application/Data Server.

Using a Validation List for Standard Authentication

The validation list must be created on the IBM i Web Server. You should be able to add or delete users from the validation list using the ADMIN IBM HTTP Server instance or calling LANSA's W3@P2301 program.

If you are using W3@P2301, the LANSA programs W3@P2301 and DC@P9002 must be installed on the Web Server. Copy them from the Application/Data Server (provided that it is version-compatible) to the Web Server's LANSA Administration library.

Add authority *PUBLIC *USE to both of these programs.

Add authority *PUBLIC *USE to both the validation list and the library it resides in.

You have now completed the steps to Configure LANSA for the Web on a Multi-tier IBM i. Now you must Configure IBM i Web Server for Communications with IBM i Data/Application Server.


6.3.2 Configure IBM i Web Server for Communications with IBM i Data/Application Server

When using TCP/IP for communication between the IBM i Web Server and IBM i Data/Application Server, you may wish to create a subsystem for executing the Web Server router jobs (LWEB_WSRV). For installation of new systems, these steps are not necessary has it has been handled in the install process.

For more details, refer to the Router Job Subsystem in Step 4. Configure IBM i Web Server in the Configure LANSA for the Web on a Multi-tier IBM i Web Server task. This set up is very similar to the LANSA Listener set up on the Data/Application Server.

The Configure IBM i Web Server for Communications with IBM i Data/Application Server task includes the following steps:

Before You Begin Checklist

Step 1. Sign On to IBM i Web Server

Step 2. Create LANSAWORK Job Queue

Step 3. Create LANSAWORK Subsystem Description

Step 4. Create LANSAWORK Job Description

Step 5. Add a LANSAWORK Job Queue Entry

Step 6. Add a LANSAWORK Auto Start Job Entry

Step 7. Create the LANSAWORK Class

Step 8. Add a LANSAWORK Routing Entry

Step 9. Add a Second LANSAWORK Routing Entry

Step 10. Start the LANSAWORK Subsystem

Step 11. Verify LANSAWORK Subsystem is Active.


Before You Begin Checklist

Only begin the Configure IBM i Web Server for Communications with IBM i Data/Application Server task if you can answer Yes to these questions:

· Is a LANSA Listener configured on the Data/Application Server?

· Have you tested any communications (non-LANSA) between the Web Server and Data/Application Server?

Go to Step 1. Sign On to IBM i Web Server.


Step 1. Sign On to IBM i Web Server

Sign on to the IBM i Web Server using a user profile with sufficient authority to work with job queues, job descriptions and subsystems. (QSECOFR is recommended.)

Go to Step 2. Create LANSAWORK Job Queue.


Step 2. Create LANSAWORK Job Queue

From an i5/OS command entry (CALL QCMD), use the CRTJOBQ command.

Press F4 to prompt the Create Job Queue command.

Enter:

Library: | QGPL - where most job queues are created by default.
Job queue: | LANSAWORK - suggested default.
Text description: | LANSA FOR THE WEB SUBSYSTEM QUEUE - suggested naming convention.

The command should appear as follows:

CRTJOBQ JOBQ(QGPL/LANSAWORK) TEXT('LANSA FOR THE WEB SUBSYSTEM QUEUE')

The name of the job queue must match the Router Job Subsystem name defined in Step 4. Configure IBM i Web Server in the Configure LANSA for the Web on a Multi-tier IBM i Web Server task.

Go to Step 3. Create LANSAWORK Subsystem Description.


Step 3. Create LANSAWORK Subsystem Description

From an i5/OS command entry, use the CRTSBSD command.

Press F4 to prompt the Create Subsystem Description command.

Enter:

Library: | QGPL - required to run in this library.
Subsystem description: | LANSAWORK - suggested default.
Pool identifier: | 1 - required value.
Storage size: | *BASE - required value.
Text 'description': | LANSA FOR THE WEB SUBSYSTEM

The command should appear as follows:

CRTSBSD SBSD(QGPL/LANSAWORK) POOLS((1 *BASE)) TEXT('LANSA FOR THE WEB SUBSYSTEM')

Go to Step 4. Create LANSAWORK Job Description.


Step 4. Create LANSAWORK Job Description

From an i5/OS command entry, use the CRTJOBD command.

Press F4 to display the Create Job Description parameters.

Press F10 for additional parameters (press PageDown or Shift-Rollup to see additional parameters).

Enter:

Library: | QGPL - where most job descriptions are created by default.
Job description: | LANSAWORK - suggested default.
Job queue: | LANSAWORK - name of the job queue created in Step 2.
Library: | QGPL - library specified in Step 2.
User: | Should be the LANSA owner, normally QOTHPRDOWN.

The command should appear as follows:

CRTJOBD JOBD(QGPL/LANSAWORK) JOBQ(QGPL/LANSAWORK) TEXT('LANSA WEB JOBD') USER(QOTHPRDOWN)

Go to Step 5. Add a LANSAWORK Job Queue Entry.


Step 5. Add a LANSAWORK Job Queue Entry

From an i5/OS command entry, use the ADDJOBQE command.

Press F4 to prompt the Add Job Queue Entry screen.

Enter:

Library: | QGPL - required to run in this library
Subsystem description: | LANSAWORK - description as entered in Step 3. Create LANSAWORK Subsystem Description.
Library: | QGPL - required to run in this library
Job queue: | LANSAWORK - job queue created in Step 2. Create LANSAWORK Job Queue.
Maximum active jobs: | *NOMAX - required value

The command should appear as follows:

ADDJOBQE SBSD(QGPL/LANSAWORK) JOBQ(QGPL/LANSAWORK) MAXACT(*NOMAX)

Go to Step 6. Add a LANSAWORK Auto Start Job Entry.


Step 6. Add a LANSAWORK Auto Start Job Entry

From an i5/OS command entry, use the ADDAJE command to add an auto start job entry to the LANSAWORK subsystem.

Press F4 to prompt the Auto Start Job Entry command.

Enter:

Library: | QGPL - required to run in this library.
Subsystem description: | LANSAWORK - description as created in Step 3. Create LANSAWORK Subsystem Description.
Job name: | LANSAWORK
Library: | QGPL - required to run in this library.
Job description: | LANSAWORK - description created in Step 4. Create LANSAWORK Job Description.

The command should appear as follows:

ADDAJE SBSD(QGPL/LANSAWORK) JOB(LANSAWORK) JOBD(QGPL/LANSAWORK)

Go to Step 7. Create the LANSAWORK Class.


Step 7. Create the LANSAWORK Class

From an i5/OS command entry (CALL QCMD), use the CRTCLS command.

Press F4 to prompt the Create Class command.

Enter:

Library: | QGPL
Class: | LANSAWORK - suggested default.
Text description: | LANSA FOR THE WEB CLASS

The command should appear as follows:

CRTCLS CLS(QGPL/LANSAWORK) TEXT('LANSA FOR THE WEB CLASS')

Go to Step 8. Add a LANSAWORK Routing Entry.


Step 8. Add a LANSAWORK Routing Entry

From an i5/OS command entry, use the ADDRTGE command to add the first routing entry for the LANSAWORK subsystem.

Press F4 to prompt the Add Routing Entry command.

Enter:

Library: | QGPL - as specified in Step 3. Create LANSAWORK Subsystem Description.
Subsystem description: | LANSAWORK - subsystem description as created in Step 3. Create LANSAWORK Subsystem Description.
Routing entry sequence #: | 10 - suggested sequence.
Compare value: | QCMDI - required compare value.
Program to call: | QCMD - system program to execute.

The command should appear as follows:

ADDRTGE SBSD(QGPL/LANSAWORK) SEQNBR(10) CMPVAL(QCMDI) PGM(QCMD)

Go to Step 9. Add a Second LANSAWORK Routing Entry.


Step 9. Add a Second LANSAWORK Routing Entry

Two routing table entries are required for the subsystem description.

To add an additional routing entry for the LANSAWORK subsystem description, use the ADDRTGE command again.

Press F4 to prompt the Add Routing Entry command.

Enter:

Library: | QGPL
Subsystem description: | LANSAWORK - subsystem description as created in Step 3. Create LANSAWORK Subsystem Description.
Routing entry sequence #: | 999 - required value
Compare value: | *ANY - required compare value
Program to call: | QCMD - system program to execute

The command should appear as follows:

ADDRTGE SBSD(QGPL/LANSAWORK) SEQNBR(999) CMPVAL(*ANY) PGM(QCMD)

Go to Step 10. Start the LANSAWORK Subsystem.


Step 10. Start the LANSAWORK Subsystem

To start the LANSAWORK subsystem, use this command:

STRSBS LANSAWORK

Go to Step 11. Verify LANSAWORK Subsystem is Active.


Step 11. Verify LANSAWORK Subsystem is Active

To verify that the LANSAWORK subsystem is running, use this command:

WRKACTJOB

You should see the following items in the Work Active Job display:

Subsystem created in step 3: | LANSAWORK
Active Job: | LANSAWORK

You have now completed the steps to Configure IBM i Web Server for Communications with IBM i Data/Application Server which completes the Task: Configure Multi-tier IBM i LANSA for the Web Installation.


6.4 Task: Upgrade from a Single-tier to a Multi-tier IBM i Web Model

The following instructions describe the process of changing a Single-tier IBM i model to a Multi-tier IBM i model where the Web Server is another IBM i.

If you currently have a Single-tier model and you are changing to a Multi-tier model, you will need to complete the following steps:

Before You Begin Checklist

Steps for Installing Programs on the IBM i Web Server

Other Considerations When Changing to Multi-tier

If you wish, you can continue to use the Web serving software on the Data/Application Server. You can use a combined Single-tier and Multi-tier system. One Data/Application Server can be used with both local and remote Web Servers.


6.4.1 Before You Begin Checklist

Before you begin the Upgrade from a Single-tier IBM i Model to a Multi-tier IBM i Model task, check the following:

· Do you have a LANSA for the Web deployment license for the IBM i Web Server?

· Do you have the LANSA Listener running on the Data/Application Server?

· Have you reviewed Other Considerations When Changing to Multi-tier?

If you can answer Yes to these questions, go to Steps for Installing Programs on the IBM i Web Server.


6.4.2 Steps for Installing Programs on the IBM i Web Server

To install and configure the LANSA for the Web software components on the Web Server, complete the following tasks:

1. Complete the steps in Multi-tier LANSA for the Web Installation (LANSA for iSeries installed) .

2. Task: Configure IBM i Web Server (powered by Apache).

If you wish, you can continue to use the Web serving software on the Data/Application Server. You can use a combined Single-tier and Multi-tier system. One Data/Application Server can be used with both local and remote Web Servers.


6.4.3 Other Considerations When Changing to Multi-tier

Following are some additional considerations when changing from a Single-tier model to a Multi-tier model:

· You must move or copy any of your customized or application image files which were stored on the Data/Application Server IFS to the Web Server IFS.

· If you are planning to use the e-Business Framework Wizard in the Multi-tier model, refer to Considerations for Using the Wizard in the LANSA for the Web e-Business Frameworks Wizard Guide.

· If you are using SSI (Server Side Includes), remember that these are URL dependant and may require files to be moved to the IFS on the Web Server.

· If you are using validation lists for standard authentication, these lists must be created on the Web Server.


6.5 Task: Install the e-Business Framework Wizard on IBM i

If you are already using an earlier version of LANSA for the Web e-Business Framework Wizard, it is recommended that you review Impact on Existing Applications in the Web Functions Wizard Guide before you continue with these steps.

The LANSA for the Web e-Business Framework Wizard consists of a set of LANSA files, functions, system variables and Web components that are shipped in an IBM i save file named LWEBWIZ2, located in the LANSA program library.

The e-Business Framework Wizard:

· must be installed in each partition you wish to use for development.

· does not need to be installed in a partition that will be used for execution only.

The save file includes three LANSA processes (WIZARD2, WIZARD3 and WIZARDX) and their related functions. A number of Web components are also imported into your system. These components are prefixed with WIZ.

The e-Business Framework Wizard images are placed in the same IFS directory as the standard LANSA for the Web images.

If you have created a partition after the install or upgrade process has been run, or if you didn't select the LANSA for the Web e-Business Framework Wizard option during the Partition Initialization process, you will need to manually import LWEBWIZ2 using the following steps. Some of these steps are optional and will depend on the install/upgrade steps that have already been completed:

Before You Begin Checklist

IBM i Import of LWEBWIZ2 Option

Test the Wizard Installation

Wizard Security Configuration

It is recommended that you review all sections before you begin the installation process.

The e-Business Framework Wizard does not require any special LANSA software installed on the PC although you must have the standard Web Functions Editor installed if you wish to manually review the Web components and variables created by the Wizard.

Online Documentation

For details about the e-Business Framework Wizard, refer to What is the e-Business Framework Wizard?.

You will find the Web Functions Wizard Guide with the LANSA online guides that are installed with LANSA on Windows.

Tutorials

In order to learn how to use the Wizard, a set of online tutorials has been supplied in Wizard Tutorials in the Web Functions Wizard Guide.


6.5.1 Before You Begin Checklist

Before you begin to install the e-Business Framework Wizard into a partition, please ensure that:

· A LANSA development environment is installed and operational.

· The partition you will be using is Web enabled. That is, the Web Enable option was selected for this partition during the Partition Initialization process.
If the partition is not Web enabled, you must import the LWEBSF Save File as described in IBM i Import of LWEBSF Save File.
(You can check if a partition is Web enabled using the Work with Files option and checking for the DC@W** file definitions.)

· The partition is defined with multilingual support set to Yes.
If it is not defined as multilingual, you must change it before continuing. How to do this is described in Change Partition to Multilingual. (You can return the partition to non-multilingual after the e-Business Framework Wizard has been imported.)

· You have QSECOFR profile authority.

· For Wizard execution only, be sure to review the Application Import/Export of the Web Functions Wizard Guide to ensure that your application is properly exported and imported.

As appropriate, go to
Change Partition to Multilingual

or
IBM i Import of LWEBWIZ2 Option.


6.5.2 IBM i Import of LWEBWIZ2 Option

Complete the following steps:

1. If the partition is non-multilingual, you must change it to multilingual as described in Change Partition to Multilingual before you start these steps. This import will fail if the partition is not made multilingual.

2. Ensure you have QSECOFR profile authority.

3. From an i5/OS command line (CALL QCMD), execute the LANSA command:

<pgmlib>/LANSA PARTITION(ppp) DEVELOPER(A)

where ppp is the partition in which the e-Business Framework Wizard is to be used.

4. rom the Administration Menu, select the Partition Initialization option.

5. From the Partition Initialization list, select LWEBWIZ2 and press Enter.

6. Once the job is completed, check the import job log.

7. If the import has been successful you can return the partition to non-multilingual status as described in the steps Change Partition to non-Multilingual.

If you are not familiar with the LANSA import procedures, you will find a complete description in The Steps Involved in Importing in the LANSA for iSeries User Guide.

Now go to Test the Wizard Installation.


Change Partition to Multilingual

These steps must be carried out before you import a Partition Initialisation option that requires the partition to be multilingual. Once you have completed the job, you can return the partition to non-multilingual.

1. Temporarily suspend all development work in the partition.

2. From the Housekeeping Menu, use the Create or change system partition definitions option. Select the partition and then change the partition Multilingual support to YES.

3. From the Housekeeping Menu, use the Work with partition multilingual attributes option. Add language ENG (English) as a valid language. Ensure that a default language is nominated.


Change Partition to non-Multilingual

When you have completed importing an option in the Partition Initialization process, follow these steps to return the partition to non-multilingual status if required. Be sure to complete ALL these steps.

1. Change the partition definition back to Multilingual support NO.
Important Note: The job may fail with message DCM0858 indicating the language selected is not available - this is normal.

2. Use the DSPLIBL command to ensure that the library list contains the LANSA program and data libraries.

3. From an i5/OS command line (CALL QCMD), call program
W3@P2714 PARM(ppp) where ppp is the partition. This program will convert page data back to NAT.

4. You MUST recompile the WIZARD2 and WIZARD3 processes after the partition is changed back to MULTILINGUAL NO.

5. Sign off and then sign on again before resuming development.

Go to Test the Wizard Installation.


6.5.3 Test the Wizard Installation

In order to test that the Wizard has been installed correctly, complete Tutorial 1 - Executing the Wizard in the Web Functions Wizard Guide.

Go to Wizard Security Configuration.


6.5.4 Wizard Security Configuration

The e-Business Framework Wizard uses LANSA for the Web processes and functions that are imported into your partition. The LANSA for the Web security and authentication rules apply to the Wizard processes and functions. If you do not have security defined for your LANSA for the Web system, you may wish to set up process level authentication so that you have controlled access to the Wizard.

To set up process level authentication, refer to Partial User Authentication - Process Level Security. You will want to secure these processes:

WIZARD2

WIZARD3

WIZARDX

You can also use task tracking with the Wizard. If you have task tracking enabled, refer to Task Tracking in the Web Functions Wizard Guide.


6.6 Task: Configure LANSA for the Web Security

In order to determine the most suitable LANSA for the Web security model, review the following:

Introduction to LANSA for the Web Security

No User Authentication - Anonymous User Access

Full User Authentication

Partial User Authentication - Process Level Security

Modifying Multi-tier IBM i LANSA for the Web User Information

Modifying IBM i Validation Lists


6.6.1 Introduction to LANSA for the Web Security

To understand the LANSA for the Web security options, review the following:

Overview of the LANSA for the Web Security Models

Understanding the Web Server and IBM i User Profiles

LANSA for the Web and IBM i User Profiles


Overview of the LANSA for the Web Security Models

LANSA for the Web provides you with additional security features, on top of the security of the Web serving software.

There are three alternative security models for implementing user authentication in LANSA for the Web.

No User Authentication

You can assign a user profile that is used for anonymous access to your applications. You create the default user profile on your Data/Application Server. The casual visitor to your site uses the anonymous user access to execute your applications without entering a profile or password. The casual visitor does not know that LANSA is running on the Data/Application Server with a default user profile.

Full User Authentication

Full user authentication uses the CGI-BIN library to request user authentication from the Web Server. All requests to the Web Server and all LANSA for the Web requests will require the Web Server to authenticate the user. All users, even casual visitors to your applications, will be required to provide a user profile.

Partial User Authentication

Partial user authentication requires user profiles for only a specific set of LANSA processes. You can nominate one or more of your LANSA processes to require user authentication. This LANSA for the Web security model also allows for anonymous access to your applications. If a user accesses a process which has no authentication required, no user profile is requested - the anonymous user access and default profile are used.

This alternative is useful if you intend to deploy your applications over the Internet. It allows the casual visitor to use most of the applications on your Web site, but not all. You can secure parts of your applications that require strict user authentication.


Understanding the Web Server and IBM i User Profiles

Under full authentication, the Web Server will not permit you to access an application unless you provide a valid profile. If a valid profile is provided, then LANSA for the Web is invoked. The Web Server user profile is specific to the Web Server. It is not an IBM i user profile. The Web profiles are created as part of a Web Server validation list. Users are not entering IBM i user profiles over the Internet.

For process level authentication, LANSA for the Web checks if the Web Server user profile is a registered LANSA for the Web user. If the user is known to LANSA for the Web, an associated IBM i user profile is used to execute LANSA at the IBM i. LANSA for the Web will map the Web Server (external Internet profile) onto to a real IBM i (internal) user profile. This IBM i user profile will be used to determine the access rights to IBM i objects.

If the Web Server user profile is not registered with LANSA for the Web, the user will still be allowed to use LANSA for the Web, provided that there is an anonymous user registered. This means that LANSA for the Web will use the default user profile on the IBM i to determine the user's access rights to the IBM i objects. The default user profile should always have minimum authority to the IBM i and LANSA.

Note that once the user has been authenticated by the Web Server, the profile will persist throughout the life of the browser. This means that subsequent requests to LANSA for the Web will use the same user profile, irrespective of whether or not the LANSA process requires user authentication.

Note: You should NOT use the same user profiles and passwords throughout your system. If an individual learns your Internet userid and password, they would be able to access that particular Internet application. They would be able to use Telnet and log on to your IBM i!


LANSA for the Web and IBM i User Profiles

Web user profiles are maintained by the Web serving software. These user profiles are used by the Web Server to determine the authority levels against directories (or libraries) defined in the Web Server. For example, with full user authentication, the WWWCGI library is defined to require user authentication in the Web Server. In other words, Web user profiles are used by the Web Server. However, these user profiles are only used by the Web Server and they bear no relationship to IBM i user profiles. These are maintained separately.

IBM i user profiles are used to determine the authority level against IBM i objects. LANSA uses the IBM i user profile (not the Web user profile) to determine the authority level of the user.

LANSA for the Web provides a mapping facility between the Web user profiles and the IBM i user profiles so that you can map a Web user profile to an IBM i profile. This is a security feature since the Web user profile is the only user profile that is exposed. The IBM i user profile is not exposed at all. Since the Web user profile only allows you access to the Web Server and not IBM i objects, this LANSA for the Web facility provides you with an additional layer of security in your application. For example, you can change the authority level of the IBM i profile without changing any details of the Web user profile. You can even change the IBM i user profile mapped to a Web user profile.

As a security feature, it is strongly recommended that the Web and IBM i user profiles not be identical.

LANSA for the Web does not perform any object level authority checks. The object level authority checks are performed by LANSA. LANSA for the Web only provides you with a facility to map Web user profiles onto IBM i user profiles. In other words, when you run your Web enabled LANSA application, the object level authority checks are performed by LANSA. LANSA for the Web does not add or remove any of these authority checks from LANSA.


6.6.2 No User Authentication - Anonymous User Access

The Anonymous User Access security model uses a default user profile for all your LANSA applications. You should only use this alternative to test your Web applications, since it does not limit access to your applications by user profile.

This model does not require you to set up user authentication in the Web Server. In fact, the CGI-BIN library in the Web Server should not be set to require user authentication.

The anonymous user is defined as DFTUSR. This DFTUSR profile is registered to LANSA for the Web using the LANSA for the Web Administrator. The user profile defined for the anonymous user should only have minimal access rights.

For a LANSA partition it is possible to assign anonymous users in the form of DFT_<partition>, where <partition> is the name of your partition. This feature allows you to set the access for each partition.

Using this model, all your applications are executed using the anonymous user profile.

To use this model, review the Before You Begin Checklist and refer to Steps for Anonymous User Access.


Before You Begin Checklist

Before you begin the Anonymous User Access task, check the following:

· Do you have a LANSA partition security officer profile so that you can execute the LANSA for the Web Administrator?

· Do you have an IBM i user profile to map to DFTUSR?

· Have you checked the authority given to the IBM i user profile to be used with the DFTUSR?

Go to Steps for Anonymous User Access.


Steps for Anonymous User Access

IBM i Servers

The procedure for setting up anonymous user access is defined in Data/Application IBM i Server Configuration which is on the LANSA Web site www.LANSA.com/support.

For more details about IBM i user profiles, refer to Web and IBM i User Profiles.


6.6.3 Full User Authentication

Full user authentication via the Web Server involves setting up the CGI-BIN library to require user authentication. This means that all requests to LANSA for the Web will require the Web Server to authenticate the user. This model uses the Web Server validation and is not LANSA specific.

All users, even casual visitors to your applications, will be required to provide a user profile. This alternative is useful for deploying applications on an Intranet or an Extranet, where you want to control user access to your applications. You will have a defined number of users who are allowed access to your applications.

The Web Server will not permit the user to progress any further unless they provide a valid user profile. If a valid user profile is provided, then LANSA for the Web is invoked.

LANSA for the Web checks to determine if the Web Server user profile is a registered LANSA for the Web user. If the user is known to LANSA for the Web, the associated Data/Application user profile is used to execute LANSA. This user profile will be used to determine the user's access rights at the Data/Application Server.

If the Web Server user profile is not registered, the user will still be allowed to use LANSA for the Web, provided that there is an anonymous user registered in LANSA for the Web. This means that LANSA for the Web will use the default user profile at the Data/Application Server to determine the user's access rights.

If an anonymous user has not been registered, they will not be allowed to use LANSA for the Web.

When configuring the directory limits, remember to enable the GET and POST methods.

To configure Full User Authentication on an IBM i Web Server, complete the following steps:

Before You Begin Checklist

Step 1. Create IBM i Validation List & Add Users

Step 2. Define The Scope For Protection

Step 3. Set Security

Step 4. Register User in LANSA for Web

The screen examples used in these steps were created using the IBM HTTP Server (powered by Apache) shipped with V5R2.


Before You Begin Checklist

Before you begin to configure the Full User Authentication, check the following:

· Do you have the partition security officer profile & password to use with the LANSA for the Web Administrator? In order to change security definitions, you must use the partition security officer profile.

· Have you checked that you can execute the process and function without process authentication?

Go to Step 1. Create IBM i Validation List & Add Users


Step 1. Create IBM i Validation List & Add Users

If you do not already have a validation list, you must create one.

From an i5/OS command entry (CALL QCMD), create a validation list using the CRTVLDL command. To create a validation list named USERLIST in QGPL, enter the following:

CRTVLDL VLDL(QGPL/USERLIST) TEXT('Validation List')

Use the WRKOBJ command to ensure the validation list has *PUBLIC with *USE authority.

To add users to the newly created validation list, use the IBM Web Administration for i5/OS by starting the *ADMIN instance. From the browser select the Advanced tab, from the Internet Users and Groups section click on the Add Internet User.

You may also use the W3@P2301 program to add users to the validation list. For more details, refer to Modifying IBM i Validation Lists.

Go to Step 2.


Step 2. Define The Scope For Protection

The scope for the CGI-BIN must be defined for the validation list to operate within.

From within your server instance of the IBM Web Administration for i5/OS, expand the Server Properties menu and click on Container Mangement to display the Container Management page. Select the Locations tab.

From the Type column, select Location from the dropdown list.

From the URL path or expression column type in /cgi-bin as the URL path.

Click Apply to accept this configuration.


Step 3. Set Security

From within your server instance of the IBM Web Administration for i5/OS, expand the Server Properties menu and click on Security to display the Security page.

Use the Server area dropdown list set it to be Location: /cgi-bin

Select the Authentication tab. Choose the Internet users in validation lists.

Enter an authentication name of your choice.

Click Add to specify the location of your validation list on the IBM i.

Click Apply.

Sample IBM HTTP Server (powered by Apache)Configuration

Here is a sample IBM HTTP Server Instance configured for standard authentication running under V5R3 or later.

· This Instance will run on Port 80.

· The CGI library is DCXCOMLIB

· The Validation List it uses is USERLIST in QGPL.

All requests to the Web Server using cgi-bin will require authentication.

# LANSA for the Web Apache HTTP Configuration File

Alias /images /LANSA_dcxpgmlib/webserver/images
ScriptAliasMatch ^/cgi-bin/jsmdirect(.*) /QSYS.LIB/JSMLIB.LIB/JSMDIRECT.PGM$1
ScriptAliasMatch ^/cgi-bin/lansaweb(.*) /QSYS.LIB/DCXCOMLIB.LIB/LANSAWEB.PGM$1
ScriptAliasMatch ^/cgi-bin/lansaxml(.*) /QSYS.LIB/DCXCOMLIB.LIB/LANSAXML.PGM$1
Listen *:80
DocumentRoot /LANSA_dcxpgmlib/WebServer/www/htdocs
# DirectoryIndex /index.html
ServerRoot /www/dcxpgmlib
Options -ExecCGI -FollowSymLinks -SymLinksIfOwnerMatch -Includes -IncludesNoExec -Indexes -MultiViews
DefaultFsCCSID 37
DefaultNetCCSID 819
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
LogFormat "%{Cookie}n \"%r\" %t" cookie
LogFormat "%{User-agent}i" agent
LogFormat "%{Referer}i -> %U" referer
LogFormat "%h %l %u %t \"%r\" %>s %b" common
CustomLog logs/access_log combined
SetEnvIf "User-Agent" "Mozilla/2" nokeepalive
SetEnvIf "User-Agent" "JDK/1\.0" force-response-1.0
SetEnvIf "User-Agent" "Java/1\.0" force-response-1.0
SetEnvIf "User-Agent" "RealPlayer 4\.0" force-response-1.0
SetEnvIf "User-Agent" "MSIE 4\.0b2;" nokeepalive
SetEnvIf "User-Agent" "MSIE 4\.0b2;" force-response-1.0
SetEnvIf "User-Agent" ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0
ServerUserID DCXPGMLIB
<Directory />
Order Deny,Allow
Deny From all
</Directory>
<Directory /QSYS.LIB/JSMLIB.LIB>
Order Allow,Deny
Allow From all
</Directory>
<Directory /QSYS.LIB/DCXCOMLIB.LIB>
Order Allow,Deny
Allow From all
</Directory>
<Directory /LANSAIMG>
Order Allow,Deny
Allow From all
</Directory>
<Directory /LANSA_ii3pgmlib/WebServer/www/htdocs>
Order Allow,Deny
Allow From all
</Directory>
<Location /cgi-bin>
PasswdFile QGPL/USERLIST
AuthType Basic
AuthName "My Auth Realm"
Require valid-user
</Location>

Go to Step 4. Register User in LANSA for Web.


Step 4. Register User in LANSA for Web

If you have created a default user (DFTUSR) for LANSA for the Web, all users who pass the Web Server validation will use the anonymous user profile to access the LANSA System.

Alternatively if you are using individual user profiles in the Web Server validation list, you can map them to specific IBM i user profiles. The mapped IBM i user profile will be used to access the LANSA system. You will need to ensure that the IBM i user profiles have proper authority to LANSA and have the correct library lists, etc. For more details refer to Web and IBM i User Profiles.

For details of how to register the users, refer to Step 4. Register Web Users in Partial User Authentication.


6.6.4 Partial User Authentication - Process Level Security

The Partial User security model allows specific processes to be authenticated while the remainder of your application uses anonymous access. With this model you can choose which of your LANSA processes require user authentication.

When LANSA for the Web is invoked, it will check if the Web Server has passed a user profile. If the Web Server has not passed any user profile, then it determines if the requested LANSA process requires user authentication. If no authentication is required for the process, the user will be allowed access as an anonymous user.

However, when the user attempts to use a LANSA process that has been registered as requiring user authentication, LANSA for the Web will redirect the request to the LANSAWEB script program in a library which forces the Web Server to request a user profile. The Web Server will not permit any further progress until a valid user profile is provided. If a valid user profile is provided, then LANSA for the Web is invoked.

You do not have to modify the URL of your LANSA applications using this alternative. Your URL will still point to the CGI-BIN library. LANSA for the Web looks after the redirection of the request to the authentication library automatically for processes that have been set up for user authentication.

If a Web Server has passed a user profile, LANSA for the Web checks if it is a registered LANSA for the Web user. If the user is known to LANSA for the Web, the associated Data/Application Server user profile is used to execute LANSA. This user profile will be used to determine the access rights at the Data/Application Server.

If the Web Server user profile is not registered with LANSA for the Web, the user will still be allowed to use LANSA for the Web provided there is an anonymous user registered. This means that LANSA for the Web will use the default user profile to determine your access rights.

Note that once the Web Server has authenticated the user, the profile is persistent throughout the life of the browser. This means that a subsequent request to LANSA for the Web will use the same user profile, irrespective of whether or not the LANSA process requires user authentication.

To configure Partial User Authentication on an IBM i Web Server, complete the following steps:

Before You Begin Checklist

Step 1. IBM i Validation Lists & Add Users

Step 2. Update IBM i Web Server Configuration

Step 3. Execute Administrator to Define Process Authentication

Step 4. Register Web Users

For details of authentication using a Windows Web Server, refer to the Installing LANSA on Windows Guide.


Before You Begin Checklist

Before you begin to configure the Partial User Authentication, check the following:

· Do you have the partition security officer profile & password to use with the LANSA for the Web Administrator? In order to change security definitions, you must use the partition security officer profile.

· Have you checked that you can execute the process and function without process authentication?

Go to Step 1. IBM i Validation Lists & Add Users.


Step 1. IBM i Validation Lists & Add Users

Follow the instructions in Step 1. Create IBM i Validation List & Add Users as described for Full User Authentication.

You may wish to create a new validation list or use an existing validation list.

In this example, the validation list is named USERLIST.

Go to Step 2. Update IBM i Web Server Configuration.


Step 2. Update IBM i Web Server Configuration

Start the *ADMIN instance to use the IBM Web Administration for i5/OS to configure your server.

You will then need to create a Web Server alias for this library. By default, LANSA for the Web assigns the alias as AUTHLIB. Once the AUTHLIB alias is set up, you will then configure your LANSA Communications library, DCXCOMLIB, to require user authentication. This means that the CGI-BIN library does not require user authentication, but when processes require authentication, the request is always redirected to the AUTHLIB URL path for identification.

Create the Web Server alias for authentication.

Using the Web Administration for IBM i, expand the Server Properties menu tree.

1. Click on the URL Mapping menu item.

2. From the Alias Tab, click Add.

3. Select the Script Alias Match.

4. Set the URL path of the LANSAWEB CGI program to ^/authlib/lansaweb(.*)

5. Set the Host directory or file to /QSYS.LIB/DCXCOMLIB.LIB/LANSAWEB.PGM$1

6. Repeat steps 1 - 5 for to set the Script Alias Match directive the URL path ^/authlib/lansaxml(.*)for the host file /QSYS.LIB/DCXCOMLIB.LIB/LANSAXML.PGM$1

7. Press the Apply button.

Your configuration now contains the added lines:

ScriptAliasMatch ^/authlib/lansaweb(.*) /QSYS.LIB/DCXCOMLIB.LIB/LANSAWEB.PGM$1

ScriptAliasMatch ^/authlib/lansaxml(.*) /QSYS.LIB/DCXCOMLIB.LIB/LANSAXML.PGM$1

Define the location path for authentication.

1. From Container Management, check you are in the Server area: Global configuration.

2. Select the Locations tab.

3. Add a Location type to the /authlib URL path.

4. Press the Apply button.

Define the scope of protection and set the security.

1. From Security, ensure Server area is set to Location: /authlib

2. From the Security menu item, select the Authentication tab.

3. Choose the Internet users in validation lists.

4. Type in your authentication name/realm of your choice.

5. Click Add to specifiy the location of your validation list on the IBM i.

6. Press the Apply button.

Your configuration now contains the added lines:

<Location /authlib>

PasswdFile QGPL/USERLIST

AuthType Basic

AuthName "My Auth Realm"

Require valid-user

</Location>

Sample IBM HTTP Server (powered by Apache)Configuration:

Following is a sample IBM HTTP Server Instance configured for standard authentication running under V5R3 or later.

This Instance will run on Port 80.

The CGI library is DCXCOMLIB

The Authenticated library is DCXCOMLIB

The Validation List it uses is USERLIST in QGPL.

Once a LANSA for the Web Process is configured for Process Authentication using the Web Administrator, the following IBM HTTP Server Configuration will prompt the User for User ID and Password. This is validated against the USERLIST Validation List in QGPL.

# LANSA for the Web Apache HTTP Configuration File

Alias /images /LANSAIMG/

ScriptAliasMatch ^/cgi-bin/jsmdirect(.*) /QSYS.LIB/JSMLIB.LIB/JSMDIRECT.PGM$1

ScriptAliasMatch ^/cgi-bin/lansaweb(.*) /QSYS.LIB/DCXCOMLIB.LIB/LANSAWEB.PGM$1

ScriptAliasMatch ^/cgi-bin/lansaxml(.*) /QSYS.LIB/DCXCOMLIB.LIB/LANSAXML.PGM$1

ScriptAliasMatch ^/authlib/lansaweb(.*) /QSYS.LIB/DCXCOMLIB.LIB/LANSAWEB.PGM$1

ScriptAliasMatch ^/authlib/lansaxml(.*) /QSYS.LIB/DCXCOMLIB.LIB/LANSAXML.PGM$1

Listen *:80

DocumentRoot /www/dcxpgmlib/htdocs

# DirectoryIndex /index.html

ServerRoot /www/dcxpgmlib

Options -ExecCGI -FollowSymLinks -SymLinksIfOwnerMatch -Includes -IncludesNoExec -Indexes -MultiViews

DefaultFsCCSID 37

DefaultNetCCSID 819

LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined

LogFormat "%{Cookie}n \"%r\" %t" cookie

LogFormat "%{User-agent}i" agent

LogFormat "%{Referer}i -> %U" referer

LogFormat "%h %l %u %t \"%r\" %>s %b" common

CustomLog logs/access_log combined

SetEnvIf "User-Agent" "Mozilla/2" nokeepalive

SetEnvIf "User-Agent" "JDK/1\.0" force-response-1.0

SetEnvIf "User-Agent" "Java/1\.0" force-response-1.0

SetEnvIf "User-Agent" "RealPlayer 4\.0" force-response-1.0

SetEnvIf "User-Agent" "MSIE 4\.0b2;" nokeepalive

SetEnvIf "User-Agent" "MSIE 4\.0b2;" force-response-1.0

SetEnvIf "User-Agent" ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0

ServerUserID DCXPGMLIB

<Directory />

Order Deny,Allow

Deny From all

</Directory>

<Directory /QSYS.LIB/JSMLIB.LIB>

Order Allow,Deny

Allow From all

</Directory>

<Directory /QSYS.LIB/DCXCOMLIB.LIB>

Order Allow,Deny

Allow From all

</Directory>

<Directory /LANSAIMG>

Order Allow,Deny

Allow From all

</Directory>

<Directory /www/dcxpgmlib/htdocs>

Order Allow,Deny

Allow From all

</Directory>

<Location /authlib>

PasswdFile QGPL/USERLIST

AuthType Basic

AuthName "My Auth Realm"

Require valid-user

</Location>

You must enable the GET and POST methods.

Please be sure to review, on the LANSA Web site, www.LANSA.com/support, the Important Notes for IBM HTTP Server Configuration in the Example IBM HTTP Server Configuration in Configuration of IBM HTTP Server using CGI.

Go to Step 3. Execute Administrator to Define Process Authentication.


Step 3. Execute Administrator to Define Process Authentication

1. Using the LANSA for the Web Administrator, connect to the desired partition. (You must use the partition security officer profile when connecting to the IBM i.)

2. Select the Security menu and choose the Process Authentication option.

The Process Authentication dialog will list all processes requiring authentication.

3. To add a new process, press the Add. . . button.

The Add Process dialog box is displayed.

4. Enter the name of the process to be secured.

Use the default for the Authentication Library.

5. Press the OK button.

Go to Step 4. Register Web Users.


Step 4. Register Web Users

You must now register the Web Users in the validation list to specific IBM i user profiles.

1. Using the LANSA for the Web Administrator, connect to the desired partition. (You must use the partition security officer profile when connecting to the IBM i.)

2. From the Security menu, select User Registration.

The User Registration window is displayed.

3. To create a new user press the Add. . . button or right click on the Web User ID column and select Add from the pop-up menu displayed.

The Add User window is opened.

4. Add your IBM i Host User Information (User ID and Password) so that the Web Users added to the validation list will be mapped to the corresponding IBM i user profiles when executing LANSA for the Web.


6.6.5 Modifying Multi-tier IBM i LANSA for the Web User Information

On the Web Server, in multi-tier situations where the Administrator is not available to modify the user information, you will use the program, W3@P2300 to do the modifications.

At the same time, as calling W3@P2300, you can call W3@P2301 to update an IBM i validation list for the IBM HTTP Server for the IBM i. This allows you to maintain the Web user profiles as well as the mapping between Web and IBM i user profiles.

Alternatively, you can write a CL program that calls the user configuration functions provided by the Web serving product.

The first parameter to the W3@P2300 program is the action you request. Depending on the action parameters, the other parameters differ.

Refer to the following:

Add a New User Profile

Modify Existing User Information

Delete an Existing User Profile


Add a New User Profile

To add a new user profile mapping information to LANSA for the Web, call the W3@P2300 program with the following parameters:

Parameter | Type | Description
Action | CHAR(3) | This will be 'ADD' if you are adding a new user profile mapping.
Web user profile | CHAR(256) | This is the Web user profile as defined in your Web serving product. This value is case sensitive and must be entered in the actual case.
System Name | CHAR(50) | This is the system name to be used by the Web user. Use *DEFAULT as your Default Parameter or specify either the IP Address or DNS Name.
Port Number | SIGNED(5,0) | This is the port number corresponding to the Web user profile and System Name.
IBM i User profile | CHAR(10) | This is the IBM i profile associated with the Web user profile.
IBM i user password | CHAR(256) | This is the password associated with the IBM i user profile. This value is case sensitive and must be entered in the actual case.
Timeout period for this new user | SIGNED(11,0) | This parameter is optional. The timeout period must be specified in seconds.

For example:

CALL W3@P2300 PARM('ADD' 'WEBUSER' '*DEFAULT' '99999' 'QPGMR' 'PASSWD' '600')


Modify Existing User Information

To modify an existing user's information in LANSA for the Web, the parameters to the W3@P2300 program would be:

Parameter | Type | Description
Action | CHAR(3) | This is 'CHG' if you want to modify an existing user profile.
Web user profile | CHAR(256) | This is the Web user profile you want to modify. This value is case sensitive and must be entered in the actual case.
System Name | CHAR(50) | This is the system name to be used by the Web user. Use *DEFAULT as your Default Parameter or specify either the IP Address or DNS Name.
Port Number | SIGNED(5,0) | This is the port number corresponding to the Web user profile and System Name.
Password in existing user information | CHAR(256) | This is the password currently held in the user information table in LANSA for the Web. This value is case sensitive and must be entered in the actual case.
New password to use for user profile | CHAR(256) | This is the new password for the user profile. This value is case sensitive and must be entered in the actual case.
Timeout period | SIGNED(11,0) | This parameter is optional. If this parameter is not specified, the timeout period for the user is not modified.

For example:

CALL W3@P2300 PARM('CHG' 'WEBUSER' '*DEFAULT' '99999' 'CURRPASSWD' 'NEWPASSWD')


Delete an Existing User Profile

To delete a user profile from the LANSA for the Web user information table, the parameters used with the W3@P2300 program would be:

Parameter | Type | Description
Action | CHAR(3) | This will be 'DLT' if you want to delete a user profile.
Web user profile | CHAR(256) | This is the Web user profile held in the user information table. This value is case sensitive and must be entered in the actual case.
System Name | CHAR(50) | This is the system name to be used by the Web user. Use *DEFAULT as your Default Parameter or specify either and IP Address or DNS Name.
Port Number | SIGNED(5,0) | This is the port number corresponding the Web user profile and System Name.
Password | CHAR(256) | This is the password as currently defined in the LANSA for the Web user information table. This value is case sensitive and must be entered in the actual case.

For example:

CALL W3@P2300 PARM('DLT' 'WEBUSER' '*DEFAULT' '99999' 'CURRPASSWD')


6.6.6 Modifying IBM i Validation Lists

LANSA for the Web provides you with a program, W3@P2301, which allows you to update an IBM i validation list that is used by the IBM HTTP Server for the IBM i for user authentication.

The first parameter to the W3@P2301 program is the action you request. The other parameters differ, depending on the action.

Refer to the following:

Add a New Validation List User

Modify an Existing Validation List User

Delete An Existing Validation List User


Add a New Validation List User

To add a new user to an IBM i validation list, you can call the W3@P2301 program with the following parameters:

Parameter | Type | Description
Action | CHAR(3) | This will be 'ADD' if you are adding a new user.
Validation list name | CHAR(10) | This is the IBM i validation list name.
Web User profile | CHAR(256) | This is the IBM i user profile name.
Web user password | CHAR(256) | This is the password associated with the IBM i user profile.
Convert user profile name and password to uppercase | CHAR(1) | This is an optional parameter. The default is "Y" which converts both user profile name and password to upper case. A value of "N" will not convert to upper case.

For example:

CALL W3@P2301 PARM('ADD' 'USERIST' 'QPGMR' 'PASSWD')


Modify an Existing Validation List User

To modify an existing user in an IBM i validation list, the parameters to the W3@P2301 program would be:

Parameter | Type | Description
Action | CHAR(3) | This is 'CHG' if you want to modify an existing user.
Validation list name | CHAR(10) | This is the IBM i validation list name.
Web User profile | CHAR(256) | This is the IBM i user profile name.
New password to use for user profile | CHAR(256) | This is the new password for the user profile.
Convert user profile name and password to uppercase | CHAR(1) | This is an optional parameter. The default is "Y" which converts both user profile name and password to upper case. A value of "N" will not convert to upper case.

For example:

CALL W3@P2301 PARM('CHG' 'USERIST' 'WEBUSER' 'PASSWD')


Delete An Existing Validation List User

To delete a user from an IBM i validation list, the parameters used with the W3@P2301 program would be:

Parameter | Type | Description
Action | CHAR(3) | This will be 'DLT' if you want to delete a user profile.
Validation list name | CHAR(10) | This is the IBM i validation list name.
Web User profile | CHAR(256) | This is the IBM i user profile name.
Convert user profile name and password to uppercase | CHAR(1) | This is an optional parameter. The default is "Y" which converts both user profile name and password to upper case. A value of "N" will not convert to upper case.

For example:

CALL W3@P2301 PARM('DLT' 'USERIST' 'WEBUSER')


6.7 Task: Set up IBM i Partition for Web Development

In order to execute or to develop with LANSA for the Web in a new LANSA partition, you must first prepare the partition. You can do this using Partition Initialization during a Custom Install or Upgrade process, or you can manually do it using these instructions.

Complete the following steps (the order of these steps is important):

Before You Begin Checklist

IBM i Import of LWEBSF & WEBLETS

Web Enable IBM i Partition using LANSA for the Web Administrator

Optional: Default User for the IBM i Partition

Do you want to use the e-Business Framework Wizard in the partition? (It is recommended that you use the Wizard in all of your development partitions.) If yes, after you have completed these steps, refer to Task: Install the e-Business Framework Wizard on IBM i.


6.7.1 Before You Begin Checklist

Before you begin this task, check the following:

· Is your partition Web enabled? That is, did you select the Web Enable option for the partition during the Partition Initialization process?

You can check if a partition is Web enabled using the Work with Files option and checking for the DC@W** file definitions.

Go to Web Enable IBM i Partition using LANSA for the Web Administrator.


6.7.2 IBM i Import of LWEBSF & WEBLETS

The LWEBSF and WEBLETS save files must be imported into the partition before you begin any LANSA for the Web configuration or development. For Weblets, the partition must be RDMLX.

These steps only are required if:
you did not use Web Enable option in Partition Initialization during the install or upgrade process to Web enable the partition. (Refer to the Before You Begin Checklist.)
or
you created a new partition after you installed LANSA.

To import the LWEBSF Save file, complete the following step:

1. Sign on to the IBM i using a user profile which has authority to the LANSA system.

2. From an i5/OS command line (CALL QCMD), execute the LANSA command:

<pgmlib>/LANSA PARTITION(ppp) DEVELOPER(A)

where ppp is the partition which is to be Web enabled.

3. From the Administration Menu, select the Partition Initialization option.

4. Select the Web Enable option to automatically Web Enable the partition. Weblets will also be imported if the partition is RDMLX.

5. Once the job is completed, check the import job log to ensure that the job has completed successfully.

General Information

You must import the LWEBSF and WEBLETS IBM i save files into each partition in which you plan to use LANSA for the Web. The import is needed only once (per LANSA version) to each web enabled partition.

The LWEBSF and WEBLETS save files are stored in the LANSA program library. Do NOT delete these save files.

The import can be done during Partition Initialisation (refer to System Initialization with the with install process or System Initialization with the upgrade process.

Always check the job log after the import has been completed.

If you have NOT imported LWEBSF and you attempt to use the LANSA for the Web PC-based Administrator, you will receive the following type of LANSA Validation Message "No file definition found with full or partial name . . .".

If you use the e-Business Framework Wizard, you will also need to import the LWEBWIZ2 save file. Refer to Task: Installing the e-Business Framework Wizard on IBM i.

Go to Web Enable IBM i Partition using LANSA for the Web Administrator.


6.7.3 Web Enable IBM i Partition using LANSA for the Web Administrator

You must use the LANSA for the Web Administrator to Web enable the partition.

Complete the following steps:

1. Start the Web Administrator.

2. Connect to the IBM i Data/Application Server as Partition Security Officer.

3. Choose the Tools menu and select the Enable Partition… command.

The Enable Partition dialog will open.

4 Enter the 3 character partition identifier (such as DEM) and press OK to Web enable the partition.

This option will create the required Standard HTML pages in the partition. You should Web enable a partition only once.

5. Exit the LANSA for the Web Administrator.

Go to Optional: Default User for the IBM i Partition.


6.7.4 Optional: Default User for the IBM i Partition

These steps are optional.

If you are using anonymous user access to the Web site, you can configure a partition-specific default user profile.

1. Start the Web Administrator.

2. Connect to the IBM i Data/Application Server as partition security officer.

3. Choose the Security menu and select the User Registration… command.

The User Registration window is displayed:

5. Press the Add button on the Add User dialog to register a new user.

6. Enter the required information. For the Web User, choose Anonymous user for partition and enter the three character partition identifier. For details about the IBM i user profile, refer to Web and IBM i User Profiles.

7. Exit from the LANSA for the Web Administrator.

The new partition is now ready for use.

You have completed the Web Enable New IBM i Partition using Web Administrator task.


6.8 Task: LANSA for the Web Housekeeping

Following is some general information and housekeeping information for LANSA for the Web:

IBM i Clean Up System

Hold/Release LANSA for the WEB Systems

Pre-Start the IBM i Web Jobs

Pre-start the IBM i Transaction Monitor

HTTP Header Variables Support

Web and IBM i User Profiles

Considerations When Exporting LANSA for the Web Applications

Considerations When Importing LANSA for the Web Applications

Storing Application Images

Program Summary for LANSA for the Web on IBM ii


6.8.1 IBM i Clean Up System

LANSA for the Web provides you with a clean up program. The clean up program resets the Transaction Monitor and cleans up any resources used by LANSA for the Web. It also terminates any LANSA for the Web jobs that are still active.

It is recommended that you run the clean up program after you have closed your Web Server or before restarting your Web Server. Ideally, it should be added to your end-of-day job schedules for your machine (or the start-of-day job schedules).

You can invoke the clean up program from the LANSA for the Web Administrator
or
you can invoke it from a command line.

If you are using an IBM i, the clean up program is called W3@P2200. It can be invoked to clean up individual LANSA systems. This is achieved by passing the LANSA systems to clean up as parameters to the program. For example, the call below instructs the program to only clean up the DCXPGMLIB system.

CALL PGM(W3@P2200) PARM('DCXPGMLIB')

If you have more than one system, you can pass more than one system in the PARM parameter.

If you have multiple Web-enabled LANSA systems on your IBM i, it is strongly recommended that each of these systems has its own separate LANSA for the Web working library. When the clean up program is invoked, it clears the working library for the system. If more than one LANSA system shares the same working library, you may cause unpredictable results in the other systems that share the working library.

Multi-tier Model

If you are deploying your application using the Multi-tier model, the clean up program should be invoked at the Data/Application Server.

If you are using an IBM i Web Server, LANSA for the Web provides you with a separate clean up program, W3@P2800. This program terminates the LANSA for the Web routing jobs on both the Web Server and the Data/Application Server.


6.8.2 Hold/Release LANSA for the WEB Systems

To prevent users accessing a LANSA for the Web system, you can place the system on "Hold". Normally you would do this using the Hold System option in the LANSA for the Web Administrator. For further details on using this option, refer to the Installing LANSA on Windows Guide or the online help provided with the LANSA for the Web Administrator.

LANSA for the Web is also provided with program W3@P2903 which you can use to Hold/Release LANSA Systems.

The parameters to the W3@P2903 program are:

Parameter | Format | Contents
Action | CHAR (3) | HLD indicates that you want to Hold System. RLS indicates that you want to Release System.
System Name | CHAR (50) | Use *DEFAULT as your Default Parameter or specify either IP Address or DNS Name.
Port Number | CHAR (5) | The port number for the System Name

For example, to Hold ALL Systems, you would call W3@P2903 with these Parameters:

CALL W3@P2903 PARM('HLD')

To Hold only the DCXPGMLIB System on Port 80, you could call W3@P2903 with these Parameters:

CALL W3@P2903 PARM('HLD' '*DEFAULT' '80')

To Release all Systems, you would use these Parameters:

CALL W3@P2903 PARM('RLS')

To Release only the DCXPGMLIB System on Port 80, you would use these Parameters:

CALL W3@P2903 PARM('RLS' '*DEFAULT' '80')


6.8.3 Pre-Start the IBM i Web Jobs

LANSA for the Web starts a job on the Data/Application Server for each LANSA request. The request could be for a LANSA process or a direct function call. The time taken to start a job on the Data/Application Server can be a significant factor in the performance of your applications, especially if your applications contain a high number of direct function calls.

LANSA for the Web allows you to pre-start a defined number of LANSA for the Web jobs. These pre-started jobs form a pool of Web jobs that are then available to handle any subsequent LANSA requests. Since these jobs are already started when the LANSA request is processed, this feature greatly increases the performance of your applications.

When your LANSA application terminates or if the Transaction Monitor terminates the application because it has timed out, LANSA for the Web does not terminate the Web job. Instead, the job is reassigned to the pool of pre-started Web jobs that are available to handle subsequent LANSA requests.

The LANSA for the Web Administrator allows you to configure the minimum and maximum number of jobs that are available in this pre-started pool of Web jobs. You should configure these numbers based on the traffic of your Web site and the capacity of your Data/Application Server.

The Transaction Monitor ensures that the pool of pre-started Web jobs contains the defined minimum number of jobs. However, if the number of Web jobs in the pool exceeds the defined maximum number of jobs, the Transaction Monitor will terminate any excess Web jobs, thus freeing the resources allocated to these jobs.


6.8.4 Pre-start the IBM i Transaction Monitor

The Transaction Monitor is started when the first LANSA request is processed. The Transaction Monitor is responsible for maintaining the pool of pre-started Web jobs. This means that the first LANSA request will have a performance impact since there are no pre-started jobs available to handle this initial request.

You can overcome this problem if you pre-start the Transaction Monitor as part of your Start of Day procedures. This ensures that there will be jobs in the pool of pre-started Web jobs to handle the LANSA requests.

The Transaction Monitor program is W3@P2000. It requires four parameters, the LANSA program library and its data library, the Domain Name for your LANSA system and its port identifier.

On your IBM i Data/Application Server, you can start the Transaction Monitor by issuing:

SBMJOB CMD(CALL PGM(DCXPGMLIB/W3@P2000) PARM('DCXPGMLIB' 'DCXDTALIB' '*DEFAULT'
'99999')) JOB(LWEB_MON) JOBQ(QINTER)

This example assumes that your LANSA program library is DCXPGMLIB and the data library is DCXDTALIB and your system is not configured for multi-homing support.

If you have enabled your LANSA system for multi-homing support, you need to specify the Domain Name for your system in place of the *DEFAULT keyword. If you want to start the Transaction Monitor for a particular port, use the port identifier in place of the 99999 parameter.

The name assigned by LANSA for the Web for the Transaction Monitor job is LWEB_MON.

Once the Transaction Monitor is started, it will then start the defined number of Web jobs for the pool of pre-started Web jobs.


6.8.5 HTTP Header Variables Support

LANSA for the Web is capable of retrieving the values of specified HTTP Header Variables from the browser and passing them on as function parameters to the Web application. If these values cannot be retrieved, the specified default values will be passed on instead.

The HTTP Header Variables for which you want to retrieve the values have to be specified with the LANSA for the Web Administrator. For information about specifying HTTP Header Variables or on how to enable this feature please refer to the HTTP Header Variables in the Web Housekeeping Guide.

Function parameters used as part of the URL take priority over the function parameters from the HTTP Header Variables.

The maximum number of parameters that may be passed to the Web application per URL requested is twenty.


6.8.6 Web and IBM i User Profiles

All of the LANSA for the Web security profiles, such as DFTUSR (default user), must be associated with an existing IBM i user profile.

When you create a new IBM i user profile or select an existing IBM i user profile for the DFTUSR, you should consider the following:

· What special authorities are required for the user profile?

· What job description and associated library list is being used?

Note:

· The LANSA program library and LANSA data library are required in the library list.

· The QGPL and QTEMP are required in the library list.

Refer to User Registration section of the Installing LANSA on Windows Guide for more information.

The DFTUSR profile should have minimal access rights on the IBM i. Do not use the LANSA partition security officer or LANSA system owner with the DFTUSR profile.


6.8.7 Considerations When Exporting LANSA for the Web Applications

If you are exporting a LANSA for the Web application, following are some considerations:

· When you export a LANSA process, all process level Web components are automatically exported with the process.

· When you export a function, all related HTML pages specific to the function will be exported including the associated Process details.

· Web components must be registered in the LANSA Web Function Editor in order to be exported. For example, if you create an HTML page using the Editor, you must register this page as a Web Page component.

· If you have created an HTML page using the LANSA Web Function Editor, it must be registered as a Web Page component to be exported.

· When working with the export list, there are options to add Web HTML, Web XML components, Web XML applications and Web XSL Style sheets.

· If you have created any Web skeletons, be sure to copy them to your new system.


6.8.8 Considerations When Importing LANSA for the Web Applications

If you are importing a LANSA for the Web application into a partition, following are some considerations:

· The partition must be prepared for LANSA for the Web use before you perform the import into the partition. Refer to Task: Set up IBM i Partition for Web Development if necessary.

· LANSA for the Web applications may contain graphic variables which use LANSA system variables. The system variables are system wide and will impact other partitions.

· LANSA for the Web components are partition specific.

· If you are only executing an application which was customized with the e-Business Framework Wizard, then LWEBWIZ2 is not required, however, to develop with the e-Business Framework Wizard, you must import LWEBIZ2 as described in IBM i Import of LWEBWIZ2 Option.

IBM i Multilingual Imports into a Non-Multilingual Partition

If you are importing a multilingual import into a non-multilingual partition, you must use temporarily change the partition to multilingual before you perform the import. The steps required to convert the partition to multilingual and back again are described in Change Partition to Multilingual and Change Partition to non-Multilingual.


6.8.9 Storing Application Images

Before setting up the directories to contain the images to be used in your LANSA for the Web applications, some thought and planning should be given to the directory structure and naming. Planning at this point will make maintenance of your images easier in the future.

A possible directory structure is to house common images in one directory and then application specific images in other directories and sub directories. Also, when you are performing development on production applications, additional and changed images can be located in a separate directory so they can be easily identified and relocated when required.

The LANSA export facility can be used to relocate your LANSA details but it will not identify or move your images. The care and maintenance of your images is your responsibility and for this reason, planning the structure of your image directories is worth the effort.


6.8.10 Program Summary for LANSA for the Web on IBM ii

Following is a list of the LANSA for the Web programs that you may need on the IBM i. How they are used is included in the relevant topic elsewhere in this guide. Also refer to the LANSA for the Web Guide.

Program | Description
W3@P2000 | Transaction Monitor for the IBM i Data/Application Server. For details, refer to How do I restart the LANSA for the Web monitors?
W3@P2001 | Start the Transaction Monitor for the IBM i Web Server. This program is only used for a Multi-tier deployment.
W3@P2200 | Clean up program for an IBM i Data/Application Server. For details, refer to IBM i Clean Up System.
W3@P2300 | Web user maintenance program. For details, refer to Modifying Multi-tier IBM i LANSA for the Web User Information.
W3@P2301 | i5/OS validation list maintenance program. For details, refer to Modifying IBM i Validation Lists.
W3@P2800 | Clean up program for an IBM i Web Server. For details, refer to IBM i Clean Up System.
W3@P2901 | 5250-mode administration program for the IBM i Web Server in a Multi-tier deployment. For details refer to Configure LANSA for the Web on a Multi-tier IBM i Web Server. This program is used instead of the LANSA for the Web Administrator when LANSA is not installed on the Web Server.


7. LANSA Integrator Configuration and Set Up on IBM i

Once the LANSA Integrator has been installed on the IBM i, you must perform some tasks to complete the configuration of the Java Service Manager. These are described in Task: Configure the Java Service Manager on IBM i.

Once the LANSA Integrator has been installed on the IBM i, you must perform some tasks to complete the configuration of the Java Service Manager.

If you encounter any problems when installing or executing the Java Service Manager, review the Troubleshooting section of the LANSA Integrator Guide.

The Configuration of LANSA Integrator includes the following tasks:

Task: Configure the Java Service Manager on IBM i

Task: Configure JSMDirect on IBM i

Task: Install LANSA Integrator Software on Windows PC


7.1 Task: Configure the Java Service Manager on IBM i

After you have installed the LANSA Integrator, you must check that the default instance values are suitable.

Before You Begin

· Review the work management objects created in the Java Service Manager library.
A library (default JSMLIB) is created during the install and stores objects used by the Java Service Manager. This includes a number of work management objects such as the JSM subsystem description and JSM job description.

If you specified a LANSA program library when installing the Java Service Manager then the work management objects will have been adjusted to use the correct LANSA libraries.

Step 1. ADDLIBLE JSMLIB

Use the ADDLIBLE LIB(<jsmlib>) (e.g. JSMLIB) command to include the JSM library to your library list.

Step 2. Go JSM

Use the command GO JSM to call the Java Service Manager Administrator Menu.

Step 3. Check configuration values

Check the *DEFAULT value of the JSM instance directory to confirm that the location is the same as the directory to which the JSM manager was restored.

DSPDTAARA DTAARA(JSMMGRDTA)

Data area . . . . . . . : JSMMGRDTA

Library . . . . . . . . : DEVJSM

Type . . . . . . . . . : *CHAR

Length . . . . . . . . : 50

Text . . . . . . . . . : JSM Manager Configuration

Offset *...+....1....+....2....+....3....+....4....+....5

0 '/LANSA_<jsmlib>/jsm/instance '

Check the default value of the JSMClient host and port value. This value must match the tcp.interface and tcp.port entry from the manager.properties file.

DSPDTAARA DTAARA(JSMCLTDTA)

Data area . . . . . . . : JSMCLTDTA

Library . . . . . . . . : DEVJSM

Type . . . . . . . . . : *CHAR

Length . . . . . . . . : 100

Text . . . . . . . . . : JSM Client Configuration

Offset *...+....1....+....2....+....3....+....4....+....5

0 'LOCALHOST:4560 '

50 'JSM '

Use menu option 4. Edit Manager Properties of the Java Service Manager Administrator Menu, to display the contents of the manager.properties file.

Edit File: /devjsm/instance/system/manager.properties

#

# Java Service Manager configuration

#

tcp.port=4560

tcp.backlog=20

tcp.interface=*all

#

console.tcp.port=4561

console.tcp.backlog=5

console.tcp.interface=*all

The tcp.interface value of *all means all interfaces on the machine, so LOCALHOST is valid.

Step 4. Optimize Java Service Manager

If you did not run this process when you installed LANSA Integrator, you will need to optimise the supplied jar files now.

The optimize process uses the CRTJVAPGM command to create i5/OS objects from the JSM jar files.

These i5/OS objects are used by the JAVA command for direct program execution.

Use option 3. Optimize Java Service Manager of the Java Service Manager Administrator Menu.

Note that this job is submitted to batch and is a long running task.

You have now completed the Java Service Manager installation.


7.2 Task: Configure JSMDirect on an IBM i

If you intend to use the CGI program JSMDIRECT, then you will need to have the correct mapping in your HTTP server configuration.

If you have installed LANSA for the Web with your LANSA system, then the default HTTP configuration will already have the information for JSMDIRECT.

If you are using the IBM Original HTTP server your configuration should contain an entry as follows:

Exec /cgi-bin/jsmdirect /QSYS.LIB/<jsmlib>.lib/JSMDIRECT.PGM %%BINARY%%

If you are using the IBM Apache HTTP server, your configuration should contain the following entries:

<Directory /QSYS.LIB/<jsmlib>.LIB>
Order Allow,Deny
Allow From all
Options -ExecCGI
CGIConvMode %%BINARY/BINARY%%
</Directory>


7.3 Task: Install LANSA Integrator Software on Windows PC

The LANSA Integrator software includes a number of Windows-based tools including:

· Integrator Studio

· User Agent

· RFI Example

To use any of these tools, perform the relevant installation tasks as described in the Installing LANSA on Windows Guide.


8. Other Configuration and Setup Tasks on IBM i

These are the additional configuration and setup tasks on the IBM i:

Task: LANSA Open Setup on IBM i

Task: LANSA Client Setup on IBM i

Task: LANSA Email Setup on IBM i

Task: Test LANSA for iSeries on IBM i

Task: Test LANSA for the Web

Testing using the DEM Partition

LANSA for iSeries - What's Next?

Task: Upgrade an Additional Listener in the LANSA Communications Setup Guide.


8.1 Task: LANSA Open Setup on IBM i

LANSA Open, previously called LANSA/Server, is 'middleware' or software that facilitates the high-speed transfer of information and data between PC-based client applications and an IBM i server using LANSA.

Before you can run LANSA Open, you must have:

· LANSA for iSeries software loaded on the IBM i.

· A LANSA Open license installed on the IBM i.

· LANSA Open software installed on the workstation.

For details about the tasks to be completed on the IBM i, review the following:

Preparing LANSA for iSeries for LANSA Open

Adjusting the DC@A1O Buffer/Data Area

TCP/IP and LANSA Listeners


8.1.1 Preparing LANSA for iSeries for LANSA Open

If you are not already using LANSA Open, you will need to prepare the IBM i server for access by your client/server applications. Following is an outline of the steps you will need to perform when using an IBM i server as the host to LANSA Open.

1. Sign on to the IBM i with a user profile that has the authority to carry out these steps

2. Check that your LANSA system is at Version 12.0 or later and that all required EPCs (Expedited Program Changes) have been applied. If your LANSA system is not at the required level, you must upgrade it before using this version of LANSA Open.

For how to check the EPCs that have been loaded, refer to For information about Expedited Program Changes (EPCs), in the iSeries User Guide.

3. Set up IBM i User Profiles for the PC users to access the data on the IBM i.

When these user profiles are created, be sure that they are granted authority for access to LANSA programs and that a proper job description is specified. The job description for the user profile must have a library list which contains the following libraries:

QGPL

QTEMP

LANSA for IBM i program library

LANSA Communications library

4. Add a directory entry to the System Distribution Directory for each IBM i User Profile.

Ensure that the User Profiles are enabled to connect to the IBM i via TCP/IP.

5. Enter the LANSA Open license code supplied by your LANSA vendor. See LANSA IBM i License. If you need more information, refer to LANSA License Codes.

6. Review and set the DC@A10 data area to a level suitable for your applications. For more details, refer to Adjusting the DC@A1O Buffer/Data Area.

7. Review the settings for

· Support Client, SuperServer or Server (*IOMXSERVER)

· Support high speed record blocking in PF key order (*IOMBLOCKBYKEY)

· Support high speed record blocking in RRN order (*IOMBLOCKBYRRN)

Note that if you change these keywords you must compile (or recompile) the I/O modules of the files to be accessed. Refer to Work with Compile and Edit Settings in the LANSA for iSeries User Guide for more information about these keywords.

8. You must configure and start a LANSA Listener if you have not already done so. Refer to TCP/IP and LANSA Listeners.

9. Make the fields and files to be accessed via LANSA Open known to the LANSA Repository on the IBM i. Refer to the Introduction to LANSA for iSeries Guide for details on the options available.

10. Once you have made your files known to LANSA, you may want to extend their functionality through the use of virtual fields, predetermined joins, access routes, or any of the many Repository features. To learn more about implementing these features refer to the LANSA for iSeries User Guide.


8.1.2 Adjusting the DC@A1O Buffer/Data Area

The DC@A10 data area is an optional data area used by LANSA Open to buffer requested data.

When the IBM i receives a request to select records, and to save all the records selected pending transfer to the workstation, it uses this user space to hold the selected records.

By default, the size of this user space is 500,000 bytes. If you wish to allow larger requests or limit requests, specify the value in data area DC@A10.

For example, records are stored in this data area when an LceRequestSelect function is used with the *RECEIVEIMMED option not set, pending the receipt of the LceReceiveSelect function. Note that if the LceRequestSelect selects records which exceed the space specified, an error will occur.

The LANSA data areas are described in detail in the System Data Areas in the LANSA for iSeries User Guide.


8.1.3 TCP/IP and LANSA Listeners

When you use TCP/IP for LANSA Open communications to the IBM i, you will require a LANSA Listener.

A Listener is simply a communications manager. The IBM i Listener is a subsystem and group of jobs which are defined to accept requests from LANSA Open. The subsystem is used to manage the LANSA Listener jobs for communication to the workstation products.

To install a LANSA Listener, go to Configure LANSA Listener on the IBM i Data/Application Server .


8.2 Task: LANSA Client Setup on IBM i

LANSA Client is LANSA's end user query and reporting tool which executes under Windows to access the repository that resides on the IBM i.

Before you can run LANSA Client, you must have:

· LANSA for iSeries software loaded on the IBM i.

· A LANSA Client license installed on the IBM i.

· Specific LANSA Client components installed in each partition which LANSA Client will be using.

· LANSA Client software installed on the workstation.

The installation of these components is described in the LANSA Client Guide.

LANSA Client is supplied with a Tutorial that gives a step-by-step introduction to the LANSA Client features. For details of installing the partition and files, refer to the LANSA Client Guide:

· for an IBM i host, refer to Set up the Tutorial files on an IBM i Host.

or

· for a Windows host, refer to Set up the Tutorial files on a Windows Host.

To see LANSA Client running against a pre-existing set of files, you can install the client side software and immediately run LANSA Client against the DEM partition. The DEM partition is supplied with all new LANSA for iSeries systems. It contains the fields, files, processes and functions to run a mini Personnel System.


8.3 Task: LANSA Email Setup on IBM i

The LANSA Email Setup on IBM i task includes the following steps.

Step 1. Configure TCP/IP

Step 2. Configure Simple Mail Transfer Protocol (SMTP)

Step 3. Setup the Mail Server Framework (MSF)

Step 4. Set System Value QUTCOFFSET

Step 5. Grant object authorities to the LANSA Product Owner

Step 6. Test your Configuration

You may also wish to review the Sample LANSA Email Function.


8.3.1 Step 1. Configure TCP/IP

Refer to the i5/OS IBM i TCP/IP Configuration and Reference guide (SC41-5420-00). Read the chapter named Configuring TCP/IP for details of the basic TCP/IP configuration.

You may wish to automate the startup of TCP/IP so it is automatically started after IPL.

Ensure your TCP/IP configuration is working properly before proceeding any further. Use the ping command to verify you can reach another machine through TCP/IP.


8.3.2 Step 2. Configure Simple Mail Transfer Protocol (SMTP)

Once you have TCP/IP working correctly, the next step is to configure SMTP. Read the chapter Simple Mail Transfer Protocol (SMTP) in the i5/OS TCP/IP Configuration and Reference guide (SC41-5420-00).

This IBM guide explains how to send and receive mail with OfficeVision or with the SNDDST and RCVDST commands if you don't have OfficeVision. Although it is not required that you learn how to use these commands to send and receive mail, they can be very useful for testing and troubleshooting at a later stage.

You don't need to setup the distribution directory to send messages using the LANSA Email Built-In Functions. The LANSA Email Built-In Function MAIL_ADD_RECIPIENT accepts a full SMTP address. Refer to the LANSA Technical Reference Guide for details of the Email Built-In Functions.

Tip

Define one remote SNADS name with its corresponding SMTP alias to use when testing the sending of messages using either OfficeVision or the SNDDST command. This SNADS name must have SMTP as its preferred address.

Note:

· If you want to use the current user as the default originator, that is, you won't be adding an originator with the built-in function MAIL_ADD_ ORIGINATOR, then the current user must be registered in the SNADS distribution directory with SMTP as his/her preferred address and have a SMTP alias.

· If you want to receive replies to your mail messages, which would be outside LANSA (either using OfficeVision or the RCVDST command) you will need to be registered in the SNADS distribution directory and have your SMTP alias to allow SNADS to translate the SMTP address of the incoming mail into your SNADS name.

If you will be sending mail over the Internet, the remote name server that you nominate should be able to resolve domain names (i.e. be a Domain Name Server).


8.3.3 Step 3. Setup the Mail Server Framework (MSF)

The Mail Server Framework (MSF) is the distribution framework which supports mail on the IBM i.

You don't need to configure MSF to use LANSA Email Built-In Functions. LANSA writes MSF messages which mimic a SNADS generated mail message and is handled by the IBM provided MSF exit point programs (the programs which process the mail messages written to MSF).

To start MSF manually enter the command:

STRMSF NBRMSFJOB(n)

Where n is the number of MSF jobs you want to start. Each MSF job processes a message from start to end before processing the next one in the queue. The more MSF jobs you nominate in the "Number of MSF Jobs" parameter, the more messages can be processed concurrently.

To end MSF manually enter the command:

ENDMSF

The MSF jobs run in subsystem QSYSWRK. Note that by default, QSYSWRK has an autostart job (QZMFECOX) which starts MSF jobs. You may want to customize this autostart job.

For more details about these commands, refer to the chapter Operations Considerations in the AnyMail/400 Mail Server Framework Support Guide (SC41-5411-00).


8.3.4 Step 4. Set System Value QUTCOFFSET

This system value stores the Coordinated Universal Time Offset. If this value is not set you must set it up so that your mail messages will be stamped with the correct date and time.


8.3.5 Step 5. Grant object authorities to the LANSA Product Owner

LANSA uses MSF API programs to create mail messages. IBM ships these API programs with an object authority of user *PUBLIC with authorization *EXCLUDE to restrict access to the APIs.

You must grant the LANSA Product Owner *USE authority to the following MSF API programs:

Program | Library
QZMFACRT | QSYS
QZMFARTV | QSYS


8.3.6 Step 6. Test your Configuration

Use this step to confirm you have completed the previous steps correctly. You will need access to another IBM i or a PC to which you will send the test mail message.

1. Send a mail message using OfficeVision or the SNDDST command to your test recipient (as described in Step 2).

2. Send a mail message from a LANSA function using the Email Built-In Functions. You may use the following sample function or create one of your own. To keep the example simple we have omitted error handling, but you would normally check the return codes in your real-life application:

FUNCTION OPTIONS(*DIRECT);

********** COMMENT();

********** COMMENT(Working fields, lists and groups);

********** COMMENT();

DEFINE FIELD(#ORGL) TYPE(*CHAR) LENGTH(60) LABEL('From') DESC( 'Mail message originator');

DEFINE FIELD(#RCPL) TYPE(*CHAR) LENGTH(60) LABEL('To') DESC('Mail message recipient');

DEFINE FIELD(#SUBJECT) TYPE(*CHAR) LENGTH(60) LABEL('Subject') DESC('Mail message subject');

DEFINE FIELD(#RET_CODE) TYPE(*CHAR) LENGTH(2) DESC('BIF returncode');

GROUP_BY NAME(#PANELDATA) FIELDS(#ORGL #RCPL #SUBJECT);

********** COMMENT();

BEGIN_LOOP;

REQUEST FIELDS(#PANELDATA)

********** COMMENT(Start a mail message);

USE BUILTIN(MAIL_START) TO_GET(#RET_CODE)

********** COMMENT(Add the originator);

USE BUILTIN(MAIL_ADD_ORIGINATOR) WITH_ARGS(#ORGL) TO_GET (#RET_CODE);

********** COMMENT(Add the recipient);

USE BUILTIN(MAIL_ADD_RECIPIENT) WITH_ARGS (TO #RCPL) TO_GET(#RET_CODE);

********** COMMENT(Set the mail message subject);

USE BUILTIN(MAIL_SET_SUBJECT) WITH_ARGS(#SUBJECT) TO_GET (#RET_CODE);

********** COMMENT(Send the mail message);

USE BUILTIN(MAIL_SEND) TO_GET(#RET_CODE);

END_LOOP;

RETURN;


8.3.7 Sample LANSA Email Function

This example of a LANSA function will generically copy an IBM i spooled file (i.e. a report) and email it to a nominated address. If you have Visual LANSA you can directly cut-and-paste this example into your system and then check it into your IBM i:

FUNCTION OPTIONS(*DIRECT);

********** COMMENT();

********** COMMENT(Fields that the caller can optionally exchange in);

********** COMMENT(which should really be defined in the dictionary);

********** COMMENT();

DEFINE FIELD(#EMSPLFN) TYPE(*CHAR) LENGTH(010) DESC('Report AS/400 Spooled File Name') DEFAULT(O@PRTF1);

DEFINE FIELD(#EMSPLFD) TYPE(*CHAR) LENGTH(001) DESC('Delete Spooled File at Completion') DEFAULT(N);

DEFINE FIELD(#EMORIGIN) TYPE(*CHAR) LENGTH(060) DESC('Email Originator Name') DEFAULT(*FUNCTION);

DEFINE FIELD(#EMRECPNT) TYPE(*CHAR) LENGTH(060) DESC('Email Recpient Name') DEFAULT(*BLANKS);

DEFINE FIELD(#EMSUBJECT) TYPE(*CHAR) LENGTH(060) DESC('Email Subject') DEFAULT(*BLANKS);

********** COMMENT();

********** COMMENT(Local Fields for this function);

********** COMMENT();

DEFINE FIELD(#EMLINE) TYPE(*CHAR) LENGTH(132) DESC('Line of the report');

DEFINE FIELD(#EMRETC) TYPE(*CHAR) LENGTH(002) DESC('Return code');

********** COMMENT();

********** COMMENT(Create the holding file SPOOLDTA in QTEMP);

********** COMMENT();

EXEC_OS400 COMMAND('CRTPF QTEMP/SPOOLDTA RCDLEN(132) AUT(*ALL)') IF_ERROR(*NEXT);

USE BUILTIN(CLR_MESSAGES);

EXEC_OS400 COMMAND('CPYSPLF FILE(#EMSPLFN) TOFILE(QTEMP/SPOOLDTA) SPLNBR(*LAST)');

********** COMMENT();

********** COMMENT(Start the mail and read and send all lines in report);

********** COMMENT();

USE BUILTIN(MAIL_START) TO_GET(#EMRETC);

EXECUTE SUBROUTINE(CHECKERROR);

USE BUILTIN(MAIL_ADD_RECIPIENT) WITH_ARGS(TO #EMRECPNT) TO_GET(#EMRETC);

EXECUTE SUBROUTINE(CHECKERROR);

IF COND('#EMORIGIN *NE *BLANKS');

USE BUILTIN(MAIL_ADD_ORIGINATOR) WITH_ARGS(#EMORIGIN) TO_GET(#EMRETC);

EXECUTE SUBROUTINE(CHECKERROR);

ENDIF;

IF COND('#EMSUBJECT *NE *BLANKS');

USE BUILTIN(MAIL_SET_SUBJECT) WITH_ARGS(#EMSUBJECT) TO_GET(#EMRETC);

EXECUTE SUBROUTINE(CHECKERROR);

ENDIF;

USE BUILTIN(ACCESS_FILE) WITH_ARGS(OPEN SPOOLDTA QTEMP) TO_GET(#EMRETC);

EXECUTE SUBROUTINE(CHECKERROR);

USE BUILTIN(ACCESS_FILE) WITH_ARGS(READ SPOOLDTA QTEMP) TO_GET(#EMRETC #EMLINE);

EXECUTE SUBROUTINE(CHECKERROR);

DOWHILE COND('#EMRETC = OK');

USE BUILTIN(MAIL_ADD_TEXT) WITH_ARGS(#EMLINE) TO_GET(#EMRETC);

EXECUTE SUBROUTINE(CHECKERROR);

USE BUILTIN(ACCESS_FILE) WITH_ARGS(READ SPOOLDTA QTEMP) TO_GET(#EMRETC #EMLINE);

EXECUTE SUBROUTINE(CHECKERROR);

ENDWHILE;

********** COMMENT();

********** COMMENT(Close the temporary file and send the mail);

********** COMMENT();

USE BUILTIN(ACCESS_FILE) WITH_ARGS(CLOSE SPOOLDTA QTEMP) TO_GET(#EMRETC);

EXECUTE SUBROUTINE(CHECKERROR);

USE BUILTIN(MAIL_SEND) TO_GET(#EMRETC);

EXECUTE SUBROUTINE(CHECKERROR);

********** COMMENT();

********** COMMENT(Delete the spool file if required);

********** COMMENT();

IF COND('#EMSPLFD = Y');

EXEC_OS400 COMMAND('DLTSPLF FILE(#EMSPLFN) SPLNBR(*LAST)');

ENDIF;

********** COMMENT(Finished);

RETURN;

********** COMMENT();

********** COMMENT(Error checking subroutine);

********** COMMENT();

SUBROUTINE NAME(CHECKERROR);

IF COND('(#EMRETC *NE OK) *AND (#EMRETC *NE EF)');

ABORT MSGTXT('Fatal error detected during Email transfer. See previous messages for cause.');

ENDIF;

ENDROUTINE;

Once you have this function compiled on your IBM i you could add code like this to the end of new or existing reporting programs :

<< PRODUCE THE REPORT >>>

ENDPRINT

CHANGE FIELD(#EMRECPNT) TO('name.user@site');

EXCHANGE FIELDS(#EMRECPNT);

CALL PROCESS(*DIRECT) FUNCTION(<email function name>);

This will send a copy of the report to name.user@site.

Similarly:

CHANGE FIELD(#EMRECPNT) TO('name.user@site');

CHANGE FIELD(#EMSUBJECT) TO('YTD Budget Report');

EXCHANGE FIELDS(#EMRECPNT #EMSUBJECT);

CALL PROCESS(*DIRECT) FUNCTION(MAILRPT);

will send a copy of the report under the subject ''YTD Budget Report''.


8.4 Task: Test LANSA for iSeries on IBM i

Once you have completed the LANSA software installation and configuration tasks, you are ready to test your system by creating and executing a simple LANSA function.

If you have installed the DEM partition, you can perform a test using the Personnel System Demonstration Files.

The Test LANSA for iSeries on IBM i task includes the following steps:

Before You Begin Checklist

Step 1. Log on to LANSA

Step 2. Create a Test Process and Function

Step 3. Compile the Test Function

Step 4. Execute the Test Function

If you encounter any problems, refer to Troubleshooting.

These instructions have been written to test a LANSA function using the Personnel System in the DEM partition. The DEM partition is installed with the LANSA software. The partition must be Web enabled. Refer to Testing using the DEM Partition.

Once you have completed Testing LANSA for iSeries on an IBM i, you have completed the LANSA installation.


8.4.1 Before You Begin Checklist

Before you begin the Test LANSA for iSeries task, check the following:

· Do you have the DEM partition installed?

· Do you have the Personnel System imported into the DEM partition?

· Have you reviewed the information about the Personnel System Demonstration Files?

· Have you reviewed Testing using the DEM Partition?

· Do you have the appropriate LANSA licenses installed?

· Do you have a user profile and password with authority to the DEM partition?

Go to Step 1. Log on to LANSA.


8.4.2 Step 1. Log on to LANSA

1. Sign on to the IBM i using a user profile which has authority to the DEM partition. The QOTHPRDOWN profile is recommended. (Default password is QOTHPRDOWN.)

2. From an i5/OS command entry (CALL QCMD), execute LANSA using the following command:

<pgmlib>/LANSA PARTITION(DEM) DEVELOPER(A)

3. The LANSA Main System Menu (Advanced) should be displayed.

Go to Step 2. Create a Test Process and Function.


8.4.3 Step 2. Create a Test Process and Function

In this step, you will create a test process named iiPROC00 Test Process and a test function named iiFN000. The test function will use the FRENQ02 template to create a function which can be used to display information in the Department (DEPTAB) and Section (SECTAB) files.

1. From the LANSA Main System Menu (Advanced), select the Work with Processes option.

2. Press function key F6 to create a new process. Enter the following details (and then press Enter):

New process name | iiPROC00 (where ii are your initials)
Description | Test Process

3. From the Work with Processes menu, use option 2=Review/Change Functions to work with your iiPROC01 process.

4. Press the F6 function key to create a new function. Enter the following details, then press Enter:

New function name | iiFN000 (where ii are your initials)
Description | Display Sections.
New function type | 1 (Generate from Application Template)

5. When the Application Template Selection screen appears, scroll down and select the FRENQ02 Header/Detail Inquiry template. Answer the template questions as shown in the table below. Use the online help if you need additional information about the answer to each template question.

TEMPLATE QUESTION | ANSWER
Enter the name of the base file to be used by this template | DEPTAB
Select related files to be used | Select Section code table SECTAB
Do you want this function to be part of an action-bar style process? | N
Fields in Header Area | Select all fields
Fields in Detail/List Area | Select DEPTMENT, SECTION, SECTDESC, SECPHBUS
Design the fields in the header are DOWN the screen or ACROSS the screen? | DOWN

6. Your function is now created and saved. It is ready for compilation. It is not necessary to edit the RDML.

7. Press F12 to exit Work with Functions. The status of your RDML functions will be displayed. Simply press Enter or F12 to return to the Work with Processes menu.

Go to Step 3. Compile the Test Function.


8.4.4 Step 3. Compile the Test Function

1. From the Work with Processes menu, use option 7=Compile to compile your iiPROC00 process and its function.

2. Use the default options on the Compile/Recompile a Process screen. Simply press Enter to submit the compile.

3. Check that the compile completed successfully.

Go to Step 4. Execute the Test Function.


8.4.5 Step 4. Execute the Test Function

1. From the Work with Processes menu, use option 10=Use to execute your iiPROC00 process.

2. When the Test Process menu appears, select the Display Sections.

3. When the Display Sections function appears, enter a Department code of ADM and press Enter to see all Sections in the Administration department.

4. Exit the function.

5. Exit the process.


8.5 Task: Test LANSA for the Web

After you have installed and configured LANSA for the Web, you can execute the following URL as a simple test of your web configuration:

http://<your path>/cgi-bin/lansaweb?procfun+lansatest+webtest+dem

The following page should be displayed:

If this image does not appear, refer to What if my images do not appear in my applications? and other Web Troubleshooting topics.


8.6 Testing using the DEM Partition

The DEM partition is a default demonstration partition loaded with a new LANSA system. The DEM partition includes a very simple Personnel System demonstration application and files. For details about the application, refer to Personnel System Demonstration Files.

In order to use the DEM partition with LANSA for the Web, you must have Web enabled the DEM partition when you installed LANSA for iSeries. If you didn't Web enable the DEM partition, you can do so manually using the steps in the Task: Set up IBM i Partition for Web Development.

If you do not have a DEM partition, you may perform a test in any of your existing LANSA partitions that you have Web enabled. You will simply need to create a Web enabled process and test function.

If you wish to follow the instructions in this guide, you can create a DEM partition on the IBM i and import the PERSYS save file using the Partition Initialization option on the Work with Administration menu or use the Import objects into this partition option from the Housekeeping menu. For Windows, use the Partition Initialization option after you have installed LANSA for Windows on a PC.

If you are using a Visual LANSA development environment, the Partition Initialization will load the Personnel System database and executable objects. In order to add data to the database files, it is recommended that you execute the Visual LANSA form VL_INIT. When you execute the Visual LANSA demonstration programs, you can copy data into the Personnel System files.


8.6.1 Personnel System Demonstration Files

The company has a simple organizational structure. It is divided into departments such as Administration, Audit, Information Services, Legal, Travel, etc. Each of these departments may have one or more sections such as Accounting, Purchasing, Sales, etc. The Department table (DEPTAB) stores the list of departments. The Section table (SECTAB) is used to store the sections within each department.

The Personnel Master file (PSLMST) stores details about each employee. For example, the employee's name, address, and telephone number are stored in this master file. As each employee works in a section of a department, this information is also stored in the Personnel Master file.

Each employee also has a list of skills. For example, an employee might have Cobol, C and C++ programming skills or management and administration skills. A Skills table (SKLTAB) is used to store the skill codes. A Personnel Skills file (PSLSKL) stores the specific skills of each employee.

The Personal Event Log file (PSLEVENT) allows significant events and notes to be recorded against an employee. It logically extends the PSLMST file. It is an RDMLX file and therefore will only be available in an RDMLX partition.

The Personnel Time Sheet file (PSLTIMES) records employee time sheet details. Details are recorded by week number (1 to 52) within a year for each employee. It is designed mostly for use with L/Client and to show extensive trigger power by performing relatively complex calculations and storing them in the DBMS without the application needing to know what is happening. Note that all the data is created and stored in the DBMS when information is created or updated, which means that LANSA Client applications have read access to it without needing to use the triggers. It is an RDMLX file and therefore will only be available in an RDMLX partition. It contains examples of a number of RDMLX field types including BLOB.

The physical database layout follows.

Note: The LANSA Personnel Demonstration System was originally created in 1987 to execute on a System 38. This same application can still be executed on IBM i as well as Windows, WEB and Linux platforms. The original database and application are virtually unchanged. There have been some extensions to the database to demonstrate RDMLX concepts. This shows how LANSA can protect your investment in your applications.
There are two web versions of the Personnel System, one uses WEBEVENT technology and the other uses WAMs. These are included with the IBM i demonstration material and can be checked out to a Visual LANSA environment as required. These applications can be used to give you ideas of how to create and include the elements required for both WEBEVENT and WAM processing.
webevent (web enabled RDML or RDMLX partition):
http://<your path>/cgi-bin/lansaweb?procfun+lansadem+ldem+dem

wam (web enabled RDMLX partition, only supported for technology service LANSA:XHTML):
http://<your path>/CGI-BIN/lansaweb?webapp=LWAMDEM+webrtn=ldemhome+ml=LANSA:XHTML+part=DEX

Physical Database Map of Personnel System

(Including Virtual and Predetermined Join Fields)


8.7 LANSA for iSeries - What's Next?

After completing an install or upgrade of a LANSA system, there are several activities that should be completed to help you get the best use from your LANSA system.

Review the following:

Learning About LANSA

Getting Started with LANSA on System i

System Settings

Installing Other Products and System i Tasks.


8.7.1 Learning About LANSA

Online Reading

Whether you have installed a new system or upgraded to the current version, there is some information for you to read to ensure you are aware of what is new and available to you.

For details of new features, refer to the What's New document. You can access it and the other online guides from the LANSA Windows CD. The online LANSA documentation can be installed on your Windows PC or read from the LANSA Windows CD. It is viewed using an Internet Explorer browser.

For new LANSA users, the online guide Introduction to LANSA on the iSeries is a good starting point.

Tutorials

The LANSA for iSeries Tutorials are provided with the LANSA documentation to give you an introduction to the major LANSA features. The tutorials can be viewed online or printed. If printing, first review the advice given in Printing tips the Tips Guide.

Personnel Demonstration System

If you are not familiar with LANSA and the features it offers, you may find it helpful to use the Personnel Demonstration System that is provided in all new LANSA systems. This application comprises a group of fields, files, processes and functions in the DEM partition and demonstrates many of LANSA's Repository and display features. The application is compiled and ready to run in both native System i mode and from a browser. Data is included.

There is no documentation for this application but there is extensive help text. We suggest you "play" with the application and look at the file and function source that drives it, to gain a good understanding of a LANSA application.

You should load this application if you are planning to use any of the tutorials in the LANSA guides. All tutorials are based on the Personnel Demonstration System.

For more details, refer to Testing using the DEM Partition and Personnel System Demonstration Files.

Visit LANSA's Web Site

The LANSA web site can be found at www.LANSA.com/support

If you are not already familiar with this web site you will find that it contains detailed information about product versions, support desk tips and techniques, courses available, support contact details, demonstrations, etc.


8.7.2 Getting Started with LANSA for iSeries

Perform Imports

A newly installed system is provided complete with a full set of system fields, system variables and templates.

With each new LANSA version, updated versions of these and other LANSA definitions are provided to help maintain existing LANSA systems and for when you set up new partitions.

During an upgrade, Partition Initialization is provided for you as a quick and convenient way to update the definitions. However, if you have upgraded a LANSA system and you bypassed this step, refer to the Initialization Imports for an list of the imports and an indication of whether they need to be imported into your system.

Create New Partitions

If you are using LANSA for the first time or if you are getting reacquainted with LANSA to use one of the other products in the LANSA family, it is probably appropriate for you to create at least one new partition for development. Refer to LANSA Partitions in the Introduction to LANSA for iSeries Guide for a description of partitions and how to create a new one.

Give Authority to Users

If you have created a new partition or wish to use new features on the LANSA menus, you must provide your users with the authority to use the new features. To give users the required authority, sign on as QSECOFR or the partition security officer then, from the Housekeeping Menu, choose option 2. Review user access to LANSA system. To simplify the administration of the Repository and LANSA applications, it is recommended that you give authority to a group profile rather than to each individual.

Menu authority is now available in Visual LANSA. Slave Visual LANSA systems are configured from their IBM i masters.


8.7.3 System Settings

Many of LANSA's system wide settings are held in data areas, which can be found in the LANSA program library (this is usually DCXPGMLIB, but it may be different on your machine). You should familiarize yourself with the contents of the data areas using the Review System Settings facility in the LANSA for iSeries User Guide.

Target Version

A system setting that you should particularly consider before beginning development is the target version for compiles. Your LANSA system is installed with a default, but this value should be reviewed to ensure its suitability for your requirements. For more information, refer to Compile and export i5/OS target release in Work with Export and Import settings in the LANSA for iSeries User Guide.


8.7.4 Installing Other Products and IBM i Tasks

If you installed LANSA for iSeries to support another LANSA product in the LANSA family, return now to that section of this guide describing that product.

Setup LANSA Open on IBM i

If you are intending to use LANSA Open to build client/server applications, you should complete the Task: LANSA Open Setup on IBM i.

Setup LANSA Client on IBM i

If you are intending to use LANSA Client query and reporting tool with your LANSA for iSeries system, you should complete the Task: LANSA Client Setup on IBM i .

Set up LANSA Email on IBM i

If you are intending to use the LANSA Email option, you should complete the Task: LANSA Email Setup on IBM i . You will find a description and an example for using each of the Email Built-In Functions in the online LANSA Technical Reference Guide.

Set up an extra Listener

If you need to set up an extra Listener, refer to Set up a Separate Listener in the LANSA Communications Setup Guide.

Applying EPCs on IBM i

For information about Expedited Program Changes (EPCs), in the iSeries User Guide.


9. Troubleshooting

Before you contact your local vendor for technical support, please review the relevant Troubleshooting section.

The troubleshooting information is divided into the following categories:

Troubleshooting Checklist

Troubleshooting LANSA Listener on

Troubleshooting Email Setup

Web Troubleshooting

You may wish to review some of the Requirements Checklists specifically:

· General Installation/Update Requirements Checklist

· Web Server Software Requirements in the LANSA for the Web IBM i Requirements.


9.1 Troubleshooting Checklist

Before you contact your local LANSA vendor for support, please complete the following checklist and have the answers available.

IBM i Servers with LANSA for the Web

· Do you have TCP/IP (STRTCP) running?

· Do you have the HTTP Web Server configured and running?

· Are you able to display the index or home page for the Web Server by entering the IP address of the Web Server into a browser?

· If you are using the IBM HTTP Server for the IBM i and you are using the default user profiles for the IBM HTTP Server configuration, have you checked that both the QTMHHTTP and QTMHHTP1 user profiles are enabled?

· Do you have a LANSA Listener running?

· Have you used WRKACTJOB to confirm that Web Server instances and the LANSA Listener jobs are running?

· Have you used NETSTAT to confirm the Listener port is being listened on?
(For example, NETSTAT *CNN - followed by F13, select local port, F14 - normally port 4545.)

· Do you have a LANSA for iSeries and LANSA for the Web development license installed?

· Have you installed the LANSA for the Web PC-based Administrator?

· Have you web enabled the partition using Partition Initialization or have you imported the LWEBSF save file into the partition? You must import LWEBSF before you Web Enable a partition using the LANSA for the Web Administrator.

· Is the partition Web enabled?

· Have you created a Default User (DFTUSR) to allow anonymous user access (from the LANSA for the Web Administrator)?

· Have you confirmed that the IBM i user profile associated with the Default User exists and has the correct library list and authority? (For example, QTEMP, QGPL, DCXPGMLIB should be in the library list and the user should have *JOBCTL authority.)

· Have you set the user profile(s) used to run the LISTENER, TP, LWEB_MON, LWEB_JOB so that they have a JOBD with its message logging set to *SECLVL.

· Have you Web enabled the test process you are using? (To do this, select option 28 (Work with Processes) on the Advanced Work with menu.)

· Have you recompiled the functions after Web enabling the process? (See step above.)

· Have you configured LANSA for the Web to access your LANSA system correctly using the LANSA for the Web Administrator? Specifically, have you configured LANSA for the Web, including the file location, the working library and the Transaction Server settings, other than the defaults?

· If you have pre-started your transaction monitor, have you used WRKACTJOB to confirm that LWEB_MON and the LWEB_JOBS are active?

· Have you checked that the HTML pages were successfully created for a test function by viewing them in the Web Function Editor? You should also check that the LANSA shipped standard and default pages can be seen from the LANSA HTML editor and that version zero of the pages have code.

· Have you checked the Maintain System definitions using the LANSA for the Web Administrator to ensure that you have complete details for the system? For example, do you know the port being used with your system or partition? Initially, and before you change the basic defaults, test this with System Name set to "*DEFAULT"; PORT set to your port number i.e. 80; LANSA Library set to DCXPGMLIB or your PGM library and Partition left blank.)


9.2 Troubleshooting LANSA Listener on IBM i

Following are some of the common errors that may be encountered when executing the LANSA Listener:

What should I see if the i5/OS Listener is running?

How do I know if the i5/OS Listener port is active?

How do I know if the port is accessible from the Internet?

The Listener i5/OS sub-system starts but there are no jobs

The Listener i5/OS sub-system starts and a job starts and then stops. There are no jobs running

Web Troubleshooting.


9.2.1 What should I see if the i5/OS Listener is running?

You should see at least three items in the Work Active Job display when you execute the WRKACTJOB command:

Subsystem named: | LANLISTEN
Listener Job defined in the Job Description: | LISTENER
A TP (Transaction job): | TP00000001

If you do not see the subsystem or jobs, then the Listener is not executing properly.

When you start the LANSA for the Web Editor, for example, you should see another job, such as TP000000002, being started. However, bear in mind that if you use a custom prefix for the transaction jobs, then that will be the name of the jobs rather than TP000000nn

Note: In this section, "LANLISTEN" and "TP000000nn" are used as the default names for the Subsystem name and the Transaction Jobs. These are the names used by LANSA when a standard LANSA install is performed. Depending on your chosen naming convention, your Subsystem and Transaction jobs may be named differently.


9.2.2 How do I know if the i5/OS Listener port is active?

Use the i5/OS command NETSTAT.

Select the option to Work with IPv4 connection status.

Look for Local Port 4545 (default) and check that the state is LISTEN.


9.2.3 How do I know if the port is accessible from the Internet?

If you are using the Internet and cannot access the port, check with your network administrator to ensure that the port is open to Internet access.

If you are using your IBM i on the Internet, there may be firewalls and other servers which may protect the ports being used on the IBM i. Even if the port appears open on the IBM i and the Listener is active, the port could be blocked by a firewall. You must consider your own firewall as well as firewalls used by your customers and your ISP. If any one of these blocks the port, access will not be allowed.


9.2.4 The Listener i5/OS sub-system starts but there are no jobs

If you see a LANLISTEN subsystem started but no jobs listed in the subsystem, then select option 5 to Work with the subsystem, display the job logs by selecting option 10, and look for any errors.

Also look in the QEZJOBLOG out queue for the job logs of the programs that ran and failed. Check for any authority problems.

Also check the library lists being used for the jobs. Make sure that the proper libraries such as QTEMP, QGPL and the LANSA program library are included - in that sequence. (QOTHPRDOWN is used in the instructions for setting up the LANLISTEN Subsystem. QOTHPRDOWN, by default, has a job description QDFTJOBD. This usually does not have DCXPGMLIB in its library list.)


9.2.5 The Listener i5/OS sub-system starts and a job starts and then stops. There are no jobs running.

When you start the LANLISTEN subsystem, you may see jobs start and then stop.

Look in the QEZJOBLOG for the job logs of the programs that ran and failed. These transaction jobs will have a prefix of TP (unless you have changed the default prefix). Check for any authority problems. If no job logs are generated, you should change the jobs message logging level to LOG (4 00 *SECLVL) to get full details in the job log.

Also check the library lists being used for the jobs. Make sure that the proper libraries such as QTEMP, QGPL and the LANSA program library are included - in that sequence. (QOTHPRDOWN is used in the instructions for setting up the LANLISTEN Subsystem. QOTHPRDOWN by default has a job description QDFTJOBD. This usually does not have DCXPGMLIB in its library list.)

For multiple systems, ensure that there are separate names for the User Queue for Session Jobs otherwise you may receive errors such as "Message . . . . : Lock operation for object LCOTPJOBS not satisfied" in the job logs.


9.3 Troubleshooting Email Setup

Troubleshooting a mail application is not easy because:

· there are many components involved, and

· it involves communications with other machines or networks.

For more information, refer to:

Finding the Email Problem

LANSA Email Tracing


9.3.1 Finding the Email Problem

Configuration and setup:

1. Are TCP/IP and MSF running?

2. Check the delivery schedule of the SMTP distribution queues.

3. If your recipient machine is an IBM i and you are using OfficeVision, is SNADS running?

4. Is your SMTP configuration correct? Have you nominated a Remote Name Server? Is the address of the Remote Name Server correct?

5. Has your IBM i exceeded the configured system storage threshold? It is usually shipped as 90%. The current usage can be checked by using command DSPSYSSTS.

Where to look:

If LANSA Email is not working, you can attempt to identify where the problem is by looking at:

1. The return code of the Email BIFs. If they return an error status, review the job log of the job where the LANSA function is running to read any diagnostic messages issued by LANSA.

2. The job log of the MSF job. The MSF job handles the processing of the mail message once it is written to MSF by LANSA. Review the job log to see if there is any indication of a problem.

3. The LANSA Email Tracing spooled file. This file traces the mail messages as they are processed by the MSF exit points. Refer to LANSA Email Tracing for details about tracing LANSA Email messages.

4. The chapter Simple Mail Transfer Protocol (SMTP) in the i5/OS TCP/IP Configuration and Reference guide (SC41-5420-00) explains how to send and receive mail with OfficeVision or with the SNDDST and RCVDST commands, if you don't have OfficeVision. You should ensure that SNDDST is set up and functions correctly before setting up LANSA Email.

Mail message options:

The mail message options PRIORITY, SENSITIVITY, IMPORTANCE and RECEIPT_REQUESTED may be ignored by some mail clients. If your application is only used within your organization, then you can verify that these options are being recognized. If you are sending mail messages over the Internet and you make these options available to the application users, it is your responsibility to advise them that these options may not be recognized.


9.3.2 LANSA Email Tracing

LANSA for iSeries provides an exit point program which can be registered to MSF for the purpose of tracing mail messages as they are processed by MSF. To register the LANSA Email tracing program perform these steps:

Step 1

Work with registration information for exit point.
Enter this command:

WRKREGINF EXITPNT(QIBM_QZMFMSF_TRK_CHG)

Step 2

Choose the option to work with exit programs. If there is already a registered exit point program, it is important that you write down its details. You will need these details when and if you need to restore this exit point program.

Step 3

Register (add) the LANSA Email tracing program (DCXP8711). This program is installed in your LANSA program library (normally DCXPGMLIB). Use these parameters:

Add Exit Program (ADDEXITPGM)

Type choices, press Enter.

Exit point . . . . . . . . . > QIBM_QZMFMSF_TRK_CHG

Exit point format . . . . . > MSFF0100 Name

Program number . . . . . . . > 1 1-2147483647, *LOW, *HIGH

Program . . . . . . . . . . > DCXP8711 Name

Library . . . . . . . . . . > DCXPGMLIB Name, *CURLIB

Text 'description' . . . . . LANSA Email tracing____________

________

Additional Parameters

Replace existing entry . . . > *NO *YES, *NO

Create exit point . . . . . *NO *YES, *NO

More

F3=Exit F4=Prompt F5=Refresh F12=Cancel

F13=How to use this display F24=More keys

continued …

Add Exit Program (ADDEXITPGM)

Type choices, press Enter.

Exit program data:

Coded character set ID . . . *NONE Number, *NONE, *JOB

Length of data . . . . . . . 8 0-2048, *CALC

Program data . . . . . . . . TCMM0100

_____________________________________________________

_____________________________________________________

_____________________________________________________

_____________________________________________________

_____________________________________________________

_____________________________________________________

_____________________________________________________

Bottom

F3=Exit F4=Prompt F5=Refresh F12=Cancel

F13=How to use this display F24=More keys

Step 4

To start tracing you need to restart the MSF job. When you trace messages it is recommended that you start only one MSF job.

Step 5

To see the contents of the trace file, find the active MSF job and work with its spooled files. Note that the spooled file won't be opened until mail messages are written to the MSF.

Step 6

When you have finished tracing, remove DCXP8711 from the registered point (restore the previous exit point program if there was one).

Note:

· DCXP8711 traces all mail messages written to MSF, not just the mail messages generated with LANSA.

· Due to buffering, the last message(s) may not appear in the trace spooled file. You may need to send an extra dummy mail message to make visible the mail message you are looking for.

Tracing will have a significant impact on the performance of your mail processing jobs. You should disable tracing during normal operations.


9.4 Web Troubleshooting

Following are common questions asked about installing, configuring and executing LANSA for the Web applications:

How can I test if I have a problem with my Web Server configuration?

Where do I look for details about problems using i5/OS?

What if my functions are not responding on the IBM i?

Is there a simple WebEvent test function I can use to test my web configuration?

Is there a simple way to review my system and web configuration settings?

How do I restart the LANSA for the Web monitors?

What if my buttons do not work properly in my applications?

What if my graphic variables do not work properly in my applications?

What if my images do not appear in my applications?


9.4.1 How can I test if I have a problem with my Web Server configuration?

You can try three different tests:

Test 1. Using a browser, enter the IP or domain name for your Web Server. You should receive a default index page or home page specified for the Web Server. If you do not receive this page, you must review the Web Server configuration. The problem will need to be resolved before starting LANSA for the Web

Test 2. Use the LANSA for the Web Administrator and use the Maintain System option to put the system on hold. If you get the hold message displayed when you try to access your application, then the Web Server configuration is working. (This test does not mean that your LANSA application is working properly.)

Test 3. Enter the URL for your Web site up to LANSAWEB? For example, you might enter:

http://123.45.67.89/cgi-bin/lansaweb?

If the configuration is working properly, it will find the LANSAWEB CGI program and you should receive this message: "JOB HAS ALREADY TIMED OUT".


9.4.2 Where do I look for details about problems using i5/OS?

If you work with the active jobs (WRKACTJOB), view the job logs for the LWEB_JOBS jobs to see if there are any errors stated in the log.

Also, work with the jobs and check that the library list is correct. The jobs must contain the LANSA libraries in order to execute properly.

The LWEB_JOBS will run as your Default User. Be sure to check the associated library list.


9.4.3 What if my functions are not responding on the IBM i?

If your LANSA for the Web function initially displays properly but will not respond to your input, check the status of the LANSA for the Web monitor (LWEB_MON job) and the LWEB_JOB jobs.

Remember to use the appropriate LANSA button to submit your function from the browser and do not press the Enter key. Pressing Enter does not always submit your HTML page request back to the Web Server (as it will depend upon your JavaScript).

Do not execute WEBEVENT functions from a LANSA for the Web Process Menu. Call your WEBEVENT functions directly using the PROCFUN parameter in the URL.


9.4.4 Is there a simple WebEvent test function I can use to test my web configuration?

After you have installed and configured LANSA for the Web, you can execute the following URL as a simple test of your web configuration:

http://<your path>/cgi-bin/lansaweb?procfun+lansatest+webtest+dem

The following page should be displayed:

If this image does not appear, refer to What if my images do not appear in my applications?

If the Next button does move to the next page, refer to What if my buttons do not work properly in my applications?


9.4.5 Is there a simple WAM I can use to test my web configuration?

After you have installed and configured LANSA for the Web for an RDMLX partition, you can execute the following URL as a simple test of your web configuration:

http://<your path>/CGI-BIN/lansaweb?webapp=LWAMTEST+webrtn=lwamtest1+ml=LANSA:XHTML+part=<your RDMLX partition>

The following page should be displayed:

If this image does not appear, refer to What if my images do not appear in my applications?


9.4.6 Is there a simple way to review my system and web configuration settings?

To review your system and web configuration execute the following URL:

http://<web server>:<port>/cgi-bin/lansaweb?procfun+lansaweb+about+<partition>

You will see something like this:

The web browser information can be collected, saved in the IFS and, using the option provided, emailed to LANSA Support.

Information displayed includes: LANSA version, OS version, LANSA program and communications library, Integrator library, LANSA system owner plus links to the EPC log and licensing details.

This same information is also available by executing, from a command line on your IBM i, the command:

LANSA ABOUT


9.4.7 How do I restart the LANSA for the Web monitors?

To restart the monitors, you may use the LANSA for the Web Administrator.
Choose the Tools menu and select the Configure System command.
Under the Transaction Monitor tab, you will see a check box to Reset the Transaction Monitor.

If you prefer to restart the LANSA for the Web from the IBM i command line, then you will:

1. Terminate the transaction monitor using program W3@P2200.

2. Restart the transaction monitor using this command:

SBMJOB CMD(CALL PGM(W3@P2000) PARM(<pgmlib> <datalib> *DEFAULT 99999))

JOB(LWEB_MON)

JOBQ(<jobq name>)


9.4.8 What if my buttons do not work properly in my applications?

If the buttons in your LANSA for the Web function do not work properly, this may be a code page problem. The symbol & is not being translated properly. This problem may occur if you have code page 65535 set in system value QCCSID.

On the IBM i, use the DSPJOB command. On the last page, there should be an entry that mentions a code page. This is the code page to use. Look for "Standard ID of the code character page".


9.4.9 What if my graphic variables do not work properly in my applications?

Use the Web Function Editor and check for the specified graphic variable.

If the graphic variable is a file type variable, check that the file is in the correct directory. The File Location directory can be checked using the LANSA for the Web Administrator. Refer to What if my images do not appear in my applications?

Using LANSA for iSeries, check that the associated system variable exists. Each graphic variable is associated with a LANSA system variable. Remember, system variables are system wide. They are shared by all partitions.

If the system variables do not exist, import the SYSVAR save file from the LANSA IBM i software DVD or CD-ROM.


9.4.10 What if my images do not appear in my applications?

Check your Web Server configuration using the LANSA for the Web Administrator. Make sure that the proper File Location has been specified.

Check that the specified directory exists and that the specified images exist. On the IBM i, the default IFS directory is /LANSAIMG.

If you are using a multi-tier model, remember that your images are stored on the Web Server and not on the Data/Application Server. Check the directories on the Web Server.

If default images like the company logo are not appearing, refer to What if my graphic variables do not work properly in my applications?


10. Using Independent Auxiliary Storage Pool (IASP)

This description assumes that you understand the purpose of using IASPs. For more information than provided here, please refer to IBM documentation for IASPs.

Also see

Upgrade


10.1 Upgrade

Before running the LODRUN command you must set the IASP group in which LANSA has been installed.

    · Make sure that the IASP group is online.

    · Use the IBM i command SETASPGRP<IASPGROUP>

This will allow the LANSA upgrade to include the LANSA system in that IASP group to the list of LANSA systems that may be upgraded. This will not display any LANSA systems in any other IASP groups.

Regardless of the IASP group used, the Install/Upgrade will display all the LANSA systems that are installed in *SYSBASE ASP to the list of LANSA systems that may be upgraded.


10.2 Install

The following LANSA components can be installed in an IASP:

· LANSA

· LANSA for the WEB

· LANSA Integrator

· Open system Utilities

The following cannot be installed in an IASP:

· LANSA Web server (multi-tier only)

Also see

10.2.1 IFS objects

10.2.2 Limitations


10.2.1 IFS objects

When installing, the IFS path is displayed without the IASP path name. When the IFS path is created and stored in the data area, it uses the absolute path name.

For example, the IFS path may be displayed as /LANSA_pgmlib but it is created and stored as /IASP/LANSA_pgmlib.


10.2.2 Limitations

You cannot use the same user profile name that is used by a LANSA system that is already installed. You must use different users for each LANSA system.

This is not an issue if the LANSA systems are in the *SYSBAS asp as the user profile name is by default the same as the LANSA program library name but it may be an issue when LANSA systems are installed into IASP groups.

For example, you can install two LANSA systems with the same library names in two different IASP groups but the following must be unique across the IBM i system:

  • Partition security officer cannot be the same
  • If WEB is used you cannot have the same HTTP Instance name.

    • During an install, the default subsystem description for the LANSA system is created and placed in the LANSA program library. This subsystem is not able to be started due to a limitation of the current IBM i operating systems. It is possible to move this subsystem description into the *SYSBAS asp or create your own subsystem description in the *SYSBAS asp and configure this with the LANSA job entries.

    The default job descriptions are also created and placed in the LANSA program library. But the job description that is used for the Partition security officer user profile must be manually moved to a *SYSBAS asp.

    The default work management objects that are created during the install of a LANSA system are essentially created for LANSA to function in a *SYSBAS asp environment but the necessary changes have been made to be compatible with the use of IASPs. These changes may not be correct for your operational environment. It is strongly recommended that you review and make any necessary changes that are appropriate for your operational environment.


10 Using Independent Auxiliary Storage Pool IASP

10.3 How we installed a LANSA System on IASP

The LANSA system was installed on an IBM i V7R1 system using the following values for the ASP parameters:

Auxiliary Storage Pool | *ASPDEV
ASP Device | IASP1 Where this is your ASP device name
ASP Group | IASP1 Where this is your ASP group name

· Once the install is completed the listener subsystem will not start automatically, such as it does when installing in the *SYSBAS asp.

· Following are the steps carried out by LANSA after the install. These steps are for your guidance:

1. Sign on as the QSECOFR or the profile that used to do the install.

2. SETASPGRP IASP1 (your ASP group).

3. Duplicate the Subsystem Description from LANSA Program Library to a Library in the *SYSBAS asp for this we used QGPL.

4. Find the Job Description name and the Library from the Partition Security Officer User Profile that was created by install.

5. Duplicate this Job Description from the LANSA Program Library to *SYSBAS asp library (we used QGPL for this).

6. Change the User Profile Job Description Library to use this Library (we used QGPL).

7. Start this Subsystem and the Listener Jobs will start as normal.

8. This user profile is used to sign on and run the LANSA command to start LANSA.


Appendix A. IBM i Objects & Parameters

When the install has been completed, a number of objects will have been added to the IBM i.

Summary of Installed Objects contains a list of the default objects that may be installed, if a typical install is selected.

The parameters used for the install are stored in data areas. These data areas are used for the next LANSA for iSeries upgrade. For further information refer to LANSA IBM i Install/Upgrade Data Areas.


Summary of Installed Objects

The LANSA IBM i Installation program will install some or all of the following objects depending upon the options selected during the installation:

LANSA for iSeries (defaults)

· New libraries will be created for the LANSA programs, data and communications including:

· DCXPGMLIB

· DCXDTALIB

· DCXMODLIB

· DCXDEMOLIB

· DCXCOMLIB

· QOTHPRDOWN user profile will be created.

· DCXPGMLIB user profile as the LANSA for iSeries Partition Security Officer.
Note that this partition security officer has no special authority outside the LANSA system. You must give authority to this user profile (or user profile of your choice) to the IFS directory, which is used by the Listener.

· Password: LANSA

· Expiry: No.

· Job description: DCXJOBD.

· LANSA directory tree:

· /LANSA_dcxpgmlib (_dcxpgmlib will be replaced with the name that was selected during install.)

· /LANSA_dcxpgmlib/connect - used by Listener

· /LANSA_dcxpgmlib/jsm - used by LANSA Integrator

· /LANSA_dcxpgmlib/support - used by the About function to store the save file that might require by LANSA support

· /LANSA_dcxpgmlib/tmp - LANSA directory used as a work directory

· /LANSA_dcxpgmlib/webserver/images - used by LANSA for the Web

· /LANSA_dcxpgmlib/webserver/servlet - used by LANSA for the Web. No longer applicable.

· /LANSA_dcxpgmlib/webserver/www - used for the HTTP server

· RDMLX object directories:

· /LANSA_dcxpgmlib/x_LANSA/source

· /LANSA_dcxpgmlib/x_LANSA/bin

· /LANSA_dcxpgmlib/x_LANSA/web

· /LANSA_dcxpgmlib/x_LANSA/x_DEM

· /LANSA_dcxpgmlib/x_LANSA/x_SYS

Any new partition will have the same format as DEM and SYS above.

· If LANSA PASE objects are installed, the following directories will be created:

· /QOpenSys/LANSA_dcxpgmlib/

· New Listener configuration file will be created in the IFS directory LANSA_dcxpgmlib/connect

· New subsystem will be created for the Listener.

· DCXPGMLIB

· New job description will be created for the Listener.

· DCXLISTJQ

· New job queue will be created for the Listener.

LANSA for the Web (defaults)

· New work library will be created:

· DCXWRKLIB

· New directories will be created on the IFS including:

· /LANSA_dcxpgmlib/webserver/images

· /LANSA_dcxpgmlib/webserver/servlet - No longer applicable

· New HTTP configuration instance will be defined with the name DCXPGMLIB. (Note: The IBM HTTP Server does not allow the use of Secure Socket Layers when the configuration instance name contains an "@" character. It you require SSL, you cannot use this default configuration. Simply create a new instance.)

LANSA for the Web - Web Server Only (defaults)

· New libraries will be created for the LANSA programs including:

· DCXADMLIB

· DCXCOMLIB

· DCXWRKLIB

· QOTHPRDOWN user profile will be created.

· New directories will be created on the IFS including:

· /LANSA_dcxpgmlib/webserver/images

· /LANSA_dcxpgmlib/webserver/servlet - No longer applicable

LANSA Integrator (defaults)

· Java Service Manager objects will be restored to the nominated library named JSMLIB.

· QOTHPRDOWN user profile will be created.

· New directory LANSA_dcxpgmlib/jsm/instance or LANSA_JSMLIB/jsm/instance will be created on the IFS for Java Service Manager files.

· New job description will be created for the Java Service Manager.

· New subsystem description will be created for the Java Service Manager.

Open System Utilities (defaults)

· Programs will be restored to the nominated library named DCXOSULIB.

Partition Initialization (defaults)

· File contents will be updated in the LANSA data library.

· Objects will be restored to the SYS partition library named DCXMODLIB.

· Objects will be restored to the DEM partition library named DCXDEMOLIB.


Objects Created but not Deleted by LANSA_CLN

If your install or upgrade has been unsuccessful, some objects may remain in the LANSA Work library. This library is created during the install and upgrade and is deleted by LANSA_CLN if the install was successfully completed. The Work Library's name is LANSAINSxx (where xx is a derived number.) Each install and upgrade process will create its own unique version of the work library.

You should delete this library if it remains after the install or upgrade.


LANSA IBM i Install/Upgrade Data Areas

The data areas used by this upgrade are a subset of the LANSA data areas described in the LANSA Technical Reference Guide.

The values in these data areas are inserted during the initial IBM i LANSA install. No changes are made to these areas when equivalent changes are made to the LANSA objects for which the values are stored. If, for example, the library names are changed after you have installed LANSA, the information displayed will not refer to the new names unless it is manually changed in these data areas.

Should you wish to change the parameters displayed in the summary screens of the Upgrade process, you will do so by changing the value in the relevant data area.

Great care should be taken when updating the data area details.

The maintenance of the LANSA system data areas should be assigned to the LANSA System Administrator, as one of the LANSA System Administrator's tasks is to review and maintain the system defaults to ensure that they are appropriate.

The data areas used by the IBM i Install/upgrade process are:

DCXLOADA01

DCXLOADA02

DCXLOADA04

DCXLOADA05


DCXLOADA01

This data contains the LANSA install/upgrade screen's default field values.

Field/Item | Length | From | To | Description | Options
PGMLIB | 10 | 1 | 10 | Program Library |
DTALIB | 10 | 11 | 20 | Data Library |
COMLIB | 10 | 21 | 30 | Share / Common Library |
SYSLIB | 10 | 31 | 40 | SYS Partition Library |
DEMLIB | 10 | 41 | 50 | DEM Partition Library |
CONNIFS | 128 | 51 | 178 | LANSA Connect IFS | Full Path
COMPANY | 30 | 179 | 208 | Company Name |
SYSOWN | 10 | 209 | 218 | Product Owner |
SECOFR | 10 | 219 | 228 | Partition Security Officer | DEM & SYS
MULTSUPP | 1 | 229 | 229 | Install Multilingual Support | Y/N
DEVLNG | 4 | 230 | 233 | Development Language | ENG, FRA, JPN
IN_ISERIES | 1 | 286 | 286 | LANSA IBM i Install/Update |
IN_WEB | 1 | 287 | 287 | LANSA Web Single Tier Install/Upgrade |
WEBSRV | 1 | 288 | 288 | Web Server |
IN_INT | 1 | 289 | 289 | LANSA Integrator Install/Upgrade with this LANSA system |
IN_OSU | 1 | 290 | 290 | Open System Utilities install/Upgrade with this LANSA system |
ADMLIB | 10 | 302 | 311 | Administration Library - Web server Multi-tier install |
OSVERSION | 1 | 312 | 312 | OS Version |
JSMLIB | 10 | 500 | 509 | LANSA Integrator - JSM Library | If not Installed with LANSA it will blank
JSMPATH | 256 | 510 | 765 | LANSA Integrator - JSM Path | If not Installed with LANSA it will blank
LST_JOBQ | 10 | 766 | 775 | Listener Job Queue |
LST_JOBD | 10 | 776 | 785 | Listener Job Description |
LST_SBS | 10 | 786 | 795 | Listener Subsystem |
JOBD | 10 | 796 | 805 | Default job description |
USER | 10 | 806 | 815 | Default user |
Directory | 40 | 872 | 911 | LANSA IFS | LANSA Path
ASP | 7 | 960 | 966 | Auxiliary Storage Pool (ASP) |
ASPDEV | 10 | 967 | 976 | ASP Device |
ASPGRP | 10 | 977 | 986 | ASP Group |


DCXLOADA02

This data area contains the LANSA for Web install/upgrade screen's default field values (except the required PGM library for Web server install).

Field/Item | Length | From | To | Description | Options
WEBSRVIFC | 1 | 1 | 1 | Web server interface | 1- CGI
WEBWRKLIB | 10 | 2 | 11 | Web work library |
WEBCGILIB | 10 | 12 | 21 | CGI library |
WEBAUTLIB | 10 | 22 | 31 | Authentication library |
HOSTCCSID | 5 | 32 | 36 | Host CCSID |
CLNTCCSID | 5 | 37 | 41 | Client CCSID |
WEBIMGIFS | 256 | 50 | 305 | Web Images Path |
WEBJVAIFS | 256 | 306 | 561 | Not applicable |
WEBUSER | 10 | 562 | 571 | LANSA Web default user profile |
WEBJOBD | 10 | 572 | 581 | LANSA Web default Job description |
WEBLIBBKUP | 10 | 582 | 591 | LANSA Multi-tier back out library |
WEBPORT | 5 | 592 | 596 | Web instance default port |
MON_JOBQ | 10 | 601 | 610 | Web Monitor Job queue |
LWEB_JOBQ | 10 | 611 | 620 | Web- LWEB Job queue |
HTTPSRV | 256 | 621 | 876 | Apache HTTP Path |
HTTPTYP | 1 | 877 | 877 | HTTP server type | 1= APACHE 2= Original


DCXLOADA04

This data area contains the LANSA Integrator install/upgrade screen's default field values.

Field/Item | Length | From | To | Description | Options
PDBLIB | 10 | 1 | 10 |  |
JSMLIB | 10 | 11 | 20 | LANSA Integrator - JSM Library |
JSMPATH | 40 | 21 | 276 | LANSA Integrator - JSM Path |
 | 4 | 277 | 280 | Not used |
OWNER | 10 | 297 | 306 | JSM Owner |
PREFIX | 3 | 342 | 344 | Library prefix |
JSMJOBUSR | 10 | 385 | 394 | JSM Job user profile |
JSMSBS | 10 | 395 | 404 | JSM subsystem name |
JSMAPORT | 5 | 405 | 409 | JSM Port no |
JSMPORT | 5 | 410 | 414 | JSM Port No |


DCXLOADA05

This data area contains the LANSA Open System Utilities install/upgrade screen's default field values.

Field/Item | Length | From | To | Description | Options
OSULIB | 10 | 1 | 10 | Open system library |
OSUOWN | 10 | 11 | 20 | Owner |
LPGMLIB | 10 | 21 | 30 | LANSA Program library |
OSVERNO | 4 | 52 | 55 | Version |


Appendix B. IBM i Operator Procedures

These procedures are described in this appendix:

How to check for Active Users

Back up your Libraries

If not using QOTHPRDOWN as the Product Owner

Identify your IBM i Details

Check LANSA_CLN


How to check for Active Users

To check for active users in your LANSA system, use the following procedure:

1. Sign on to the IBM i using the Partition Security Officer profile QSECOFR or as some other user that is part of the QSECOFR group.

2. If the Command Entry screen is not already displayed, then invoke it by using this command:

CALL QCMD

3. Make sure that no jobs/users are accessing LANSA using the following commands:

WRKOBJLCK <pgmlib>/DC@A01 *DTAARA

WRKOBJLCK <datalib>/DC@F02 *FILE *FIRST

4. If locks exist, ask the users to sign off or wait until the batch jobs have ended before continuing with the upgrade.
If you use LANSA workstation products connected to your LANSA system, you may find that the listener job has a lock on the system. If a listener job is active, stop it by ending the subsystem it is running in.

Repeat both of these commands until there are no locks on the specified objects.

Note 1: The upgrade process will not commence if active users are found.


Back up your Libraries

Back up LANSA Libraries

You must back up the LANSA libraries and IFS directories that you will be upgrading.

As an example, LANSA IFS directories named:

/LANSA_xxxpgmlib and QOpenSys/LANSA_xxxpgmlib

Should the upgrade fail or be interrupted, you will need to restore the old version from this backup before attempting the upgrade again. In the event of a failure, you must follow the restart/recovery procedures that are printed at the end of the job log.

During earlier versions of LANSA, the LANSA install and upgrade objects were placed in QGPL. Now, the LANSA install and upgrade will create its own work library. This work library is LANSAINSxx (where xx is a derived number), for example LANSAINS01. This library is deleted after a successful install or upgrade.

Move communication objects from QGPL?

If you wish to move the communications objects from QGPL before the upgrade, plan to do this now. Refer to LANSA Communications Library for further information.

Do not continue until you are sure that this backup has been completed successfully. It is also recommended that you check your backup to ensure that the backup media has no errors. For example, you might use a DSPTAP command to check your backup tapes.


If not using QOTHPRDOWN as the Product Owner

If you are NOT planning to use the QOTHPRDOWN profile as the LANSA product owner, then you must perform the following steps where "other profile" is used as the name of your chosen profile:

1. Create the other profile with all the defaults and minimum authority.

2. Proceed with the Installation or Upgrade as described in this guide.

3. After the installation/upgrade has been completed, check if this other profile owns any objects. If it owns any, transfer the ownership to the profile that was used as the LANSA product owner.

4. Delete the other profile.

It is strongly recommended that QOTHPRDOWN profile is the LANSA product owner.


Identify your IBM i Details

You will need to provide the following details when you request a license. You will also need to supply this information when requesting support.

· Processor, Serial and Model Number

· LANSA System

· i5/OS version level

If you are using LANSA, you can use the LANSA command: LANSA ABOUT to locate this information.

If you're not yet using LANSA, you can obtain this information using the WRKSYSVAL command from an i5/OS Command Entry. On the Work System Values screen, use option 5 to display the required values:

· System serial number (QSRLNBR)

· System model number (QMODEL)

· Processor Feature (QPRCFEAT).

To display a single system value, you may also use the DSPSYSVAL command. For example, DSPSYSVAL QPRCFEAT will display the Processor Feature code.


Check LANSA_CLN

Some LANSA imports require partitions to be multilingual for the import to be successful during the Initialization process. Partitions affected are automatically changed to multilingual during the import process.

The LANSA_CLN job changes these partitions back to non-multilingual status at the end of the upgrade/install process.

We recommend that you always check that LANSA_CLN has completed successfully.

Unsuccessful LANSA_CLN process

If LANSA_CLN hasn't completed successfully:

· some partitions may be left as multilingual.

· the LANSA work library that was created by the install or upgrade will not be deleted.

Always check the Job Log for the reason for the job not completing successfully.


Appendix C. What is LANSA?

LANSA is an integrated family of highly productive design, development and maintenance products for multi-platform host and network applications. This family of products provides an extremely flexible application development environment where a developer can use a single skill set to build and deploy applications for the IBM i, Windows or Internet environments.

LANSA's powerful Repository-based 4GL has enabled developers to quickly deploy applications across computing boundaries and across computing paradigms. A simple recompile can transform a host-centric IBM i application using RPG/ILE into a client/server Windows application using C/C++ or a browser-based Internet application using HTML and IIS Plug-in.

Developer productivity and ease-of-use are LANSA trademarks. For years, developers have enjoyed the benefits of LANSA's Rapid Development and Maintenance Language (RDML) that insulated them from low-level languages and platform complexities. RDML can build IBM i applications, graphical event-driven Windows applications and Web applications. The LANSA Repository provides a centralized application definition and platform independent database architecture. This powerful combination has protected companies' information technology investments for over 10 years.

LANSA was the first IBM i development tool to fully embrace the Internet and Web technology. LANSA for the Web has allowed developers to construct Internet, Intranet and Extranet applications. Today, there are hundreds of thousands of people using LANSA Web-based applications in retail, health care, insurance, manufacturing, government, communications and many other industry sectors.

As an introduction to the LANSA family of products, review the following:

What is LANSA for iSeries?

What is Visual LANSA?

What is Visual LANSA Framework?

What is LANSA for the Web?

What is the e-Business Framework Wizard?

What is Commerce Edition?

What is the LANSA Integrator?

What is LANSA Open?

What is LANSA Client?


What is LANSA for iSeries?

LANSA for iSeries is an award winning application development tool originally designed to create applications for IBM i servers. LANSA for iSeries provides a total, integrated environment for modeling, designing, programming, testing, implementing and maintaining application systems. The LANSA applications may execute as host applications, Web-enabled applications or client/server applications.

The LANSA for iSeries development environment greatly increases developer productivity by using LANSA's Repository-based 4GL technology. Developers can rapidly assemble applications using the LANSA RDML (Rapid Maintenance and Development Language). RDML allows the developer to create a platform independent application definition. LANSA's RDML language can be compiled into a number of different languages including RPG/ILE on the IBM i and C/C++ for Windows platforms.

A major component of the LANSA for iSeries software is the LANSA Repository. The LANSA Repository can be used independently of the development aspects of LANSA for iSeries in conjunction with other LANSA products. The LANSA Repository on iSeries can be used as the server for the workstation-based products such as LANSA Client, LANSA SuperServer, LANSA Open and LANSA for the Web. As such, you may be required to install LANSA for iSeries to support one of these other LANSA products.

Ý Appendix C. What is LANSA?


What is Visual LANSA?

Visual LANSA provides a comprehensive Windows-based development environment for building your LANSA Repository and RDML functions. IBM i developers can use Visual LANSA as a power workstation in a distributed development environment with LANSA for iSeries. This allows you to develop both client and server programs using only one set of easy-to-learn skills. You can rapidly edit and debug your RDML using a powerful graphical development environment.

Visual LANSA can be used on a stand-alone workstation or on a workstation that is part of a network configuration. Visual LANSA supports a variety of configurations to support the diverse requirements of your application development environments.

Visual LANSA includes component technology that allows you to develop advanced GUI applications for Windows. These visual components, which you create, are stored in LANSA's Repository along with the fields and files you are using in your applications. Components support a full range of properties, events and methods for building powerful event-driven applications.

With Visual LANSA, your applications can be deployed onto a variety of platforms in flexible, multi-tier combinations that can include IBM i, Windows, Linux, Solaris and more.

Visual LANSA's application environment fully supports LANSA for the Web (including Commerce Edition and the E-Business Framework Wizard) and LANSA Integrator. The LANSA Client query and reporting tool can also be used to query your LANSA applications in the Visual LANSA environment.

Ý Appendix C. What is LANSA?


What is Visual LANSA Framework?

Visual LANSA Framework Wizard is a framework that helps you design and implement large scale and highly integrated Visual LANSA applications both for Windows and web. You can use the executable framework to very rapidly prototype Visual LANSA application designs without writing a single line of code. You can easily convert your prototype designs into real applications by snapping in your own tailor-made Visual LANSA components.

The Framework is the executable environment that provides the structure and the basic functionality for applications, business objects, commands, menus, etc. It has prototyping and program coding assistants and integrated tutorials that guide you in creating your application.

Ý Appendix C. What is LANSA?


What is LANSA for the Web?

LANSA for the Web allows you to build Web applications quickly and easily. It is a toolkit that integrates seamlessly with the LANSA Application Development Environment (either Visual LANSA or LANSA for iSeries). You can use graphical HTML forms or XML-based applications using the same Repository and RDML skill set used to build your IBM i and Windows applications. In fact, a LANSA program can be deployed to the IBM i, Windows, or the Web using a single RDML program definition.

LANSA for the Web allows you to build dynamic data retrieval applications for the Web. It also allows you to deploy the applications across a number of combinations of platforms including the IBM i and Windows. Each of these platforms can be used as the Application/Data Server for the Web Server which allows you to deploy your applications in a mixed multi-tiered architecture.

LANSA for the Web shields you from the technologies you would normally have to learn to deploy Web-enabled applications. You do not need to learn code-intensive CGI to build dynamic Web applications. You simply use LANSA's repository-based 4GL environment to build your application definition. LANSA for the Web allows the developer to work at the 4GL level. LANSA will automatically generate the HTML or XML pages for you. LANSA for the Web hides much of the complexity from the developer.

LANSA for the Web also incorporates a Transaction Server, which provides your user sessions with a persistent connection between their browser and your Data Server. Persistent connections are not available in the Hypertext Transfer Protocol (HTTP), the protocol used in serving the Web.

The huge growth and demand for Internet access from organisations has prompted LANSA to extend its offering beyond the traditional application development environment. LANSA offers a set of application specific frameworks to help companies deploy their e-Business solutions at an even more astounding rate. The e-Business Framework Wizard and Commerce Edition are part of the natural evolution of the LANSA product family. Along with LANSA's powerful application development environment, Web developers will now benefit from Commerce Edition to help accelerate Web application development.

For more details, refer to the Introduction to LANSA for the Web in the LANSA for the Web Guide.

Ý Appendix C. What is LANSA?


What is the e-Business Framework Wizard?

If you are using WebEevent function programs (as opposed to Web Application Modules) , the e-Business Framework Wizard allows you to quickly and easily customize the presentation of your LANSA Web applications. The Wizard is not used to create your LANSA functions. It is used to alter their appearance using Web-based functions executed from your browser. The Wizard removes the need to manually code HTML and JavaScript. It simplifies the implementation of graphic variables and Web components. You can change the look-and-feel of your applications without having to recompile any of the functions in your application.

The Wizard allows the RDML programmer to concentrate on the functionality of the application, without having to worry about the presentation attributes. The presentation can be quickly assembled using simple menu choices and presentation options. The Wizard gives you the flexibility of deciding which components to include or exclude from the presentation.

The Wizard allows you to convert the default look-and-feel of a LANSA function into a contemporary Web look-and-feel. The pre-shipped images, color schemes and presentation schema reduce the need for specialized graphic skills as part of the application development and implementation.

The LANSA for the Web e-Business Framework Wizard is a standard feature of LANSA for the Web. A separate license is not required to use this product. It is installed at the partition level.

For more details, refer to the LANSA for the Web Functions Wizard Guide.

Ý Appendix C. What is LANSA?


Web Application Modules (WAMs)

WAMs are a component-based Web technology used for building applications for the Internet or other networks. WAMs use an XML/XSL technology. They offer the ability to deliver content in multiple formats such as HTML, WML, or XML from a single WAM component.

The LANSA for the Web WAM technology is an extension of the LANSA development environment. If you have Repository and RDML/RDMLX skills, you can apply them to building Web-based applications using WAMs.

Weblets are shipped with the software to provide wizards or building blocks that facilitate the rapid development of HTML browser-based applications. To create your own Weblets, or complex HTML pages, you will need XSL, HTML and JavaScript skills.

The XSL used for transformation of the XML WEBROUTINE document conforms to the standard W3C XSL 1.0 specification.

Refer to the Web Application Module Guide for more information.

Ý Appendix C. What is LANSA?


What is Commerce Edition?

LANSA Commerce Edition is a suite of Business-to-Business (B2B) and Business-to-Consumer (B2C) components that are built on LANSA for the Web. Commerce Edition allows you to rapidly generate e-business applications that integrate existing IBM i, RPG and COBOL applications with the Web and Wireless world.

LANSA Commerce Edition provides an easy, rapid and configurable solution to help you extend your core IBM i applications to both customers and business partners alike. Commerce Edition is a component-based solution that allows you to choose the kinds of functionality you want to deploy on your B2B or B2C Web site.

Commerce Edition is a separately licensed product from LANSA for the Web.

For more details, contact your LANSA distributor.

Ý Appendix C. What is LANSA?


What is the LANSA Integrator?

LANSA Integrator enables integration of Application-to-Application (A2A) and Business-to-Business (B2B) transactions through XML and Java Services. LANSA Integrator allows bi-directional XML and other data formats to be exchanged between you and your trading partners regardless of what platforms they run on. It also enables integration of user-written Java Services with LANSA, RPG and COBOL applications. LANSA Integrator hides the complexities of interfacing XML and Java technologies, letting you concentrate on business requirements.

The LANSA Integrator is a Java service framework that allows you to integrate Java Services with LANSA and 3GL applications. Using the Java Service Manager you can integrate with any system on any platform using your choice of B2B technologies such as SOAP, IBM MQ Series, XML Parsing, XSL Transformation, FTP, HTTP, HTTPS, SMTP, and POP3.

LANSA Integrator can be installed as part of a LANSA system or in a standalone mode.

For more details, refer to the LANSA Integrator Guide.

Ý Appendix C. What is LANSA?


LANSA Composer

LANSA Composer provides a simple but powerful process orchestration capability that allows you to combine transport, transformation and custom business processing with processing Directives that provide conditional, iterative and other capabilities. A complete business process consisting of a number of steps may be defined, executed and managed as a single processing unit of work, without programming.

LANSA Composer provides ready-to-use Activities supporting widely-used transport protocols including:

· FTP Inbound (file transfer protocol)

· FTP Outbound (file transfer protocol)

· HTTP Inbound (hypertext transfer protocol)

· HTTP Outbound (hypertext transfer protocol)

· POP3 for inbound e-mail (post office protocol)

· SMTP for outbound e-mail (simple mail transfer protocol)

· Inbound and outbound via message brokering systems such as IBM MQ Series

To use these transport Activities with LANSA Composer, you simply need to provide configurations that specify the variable information required to connect or communicate with the other parties involved. There is no programming involved.

Using the supplied transport Activities, you can exchange business information such as orders and invoices with other parties, including external trading partners and internal business units, using agreed standards-based protocols as appropriate for each party.

LANSA Composer includes powerful visual mapping that allows you to define how to map data between disparate formats including:

· XML documents

· EDI documents

· Microsoft Excel 2007 (XLSX) files

· Text files (for example comma-separated values)

· Web service functions

· A wide range of databases, including IBM DB2 Universal Database for iSeries

The maps created with the visual mapping tool can be directly integrated into your business processes along with transport and other Activities.

With the transformation capabilities you can transform business information between external and internal formats as it is received or before it is sent. In this way you can readily extract information from corporate databases to send as, say, XML conforming to a schema agreed with your trading partner. Similarly you can transform in-coming XML documents and write them directly to your corporate database for further processing by your existing applications.

For further information, refer to the LANSA Composer Guide.

Ý Appendix C. What is LANSA?


What is LANSA Open?

LANSA Open is 'middleware' or software that facilitates the high-speed transfer of information and data between

· PC-based client applications, developed using any of the popular workstation development tools,

and

· a server (LANSA) on a IBM i, Windows, or Linux platform.

LANSA Open allows non-LANSA application developers to share and reuse LANSA's Repository and RDML technologies. It enables the rapid delivery of high performance client/server applications for the IBM i and other platforms. Developers can provide the Windows interface that users demand while maintaining the security and high performance necessary for mission critical applications. LANSA Open allows developers to use their favorite PC development tool with the speed of LANSA's middleware and the robustness of LANSA server applications.

An integral part of LANSA Open is the LANSA Object Repository, which contains all field and file details including the relevant business rules. This ensures that all PC applications are subjected to the same rigorous security checks, data validation and referential integrity checks as IBM i applications.

When using LANSA Open with LANSA for iSeries, setup tasks, which are outlined in this guide, need to be performed on the IBM i Server.


What are the Open System Utilities for IBM i?

The Open System Utilities facility is a library of utilities that allow experienced developers to manipulate the LANSA environment. These utilities enable global or system level manipulations of a LANSA for iSeries environment.

The types of manipulations the Open System Utilities perform require skill and care to be exercised whenever they are used. Source code and documentation for each utility is provided.

No warranty is expressed or implied in the provision of these utilities.

Some of the facilities provided by these utilities are:

· High-speed movement of complete partitions between environments and machines.

· Stripping down of non-development systems (i.e. to run-only) to minimal size.

· Change of LANSA program and/or data library names.

For details of the specific utilities included, refer to the Open System Utilities Guide.

Ý Appendix C. What is LANSA?


What is LANSA Client?

LANSA Client gives end users GUI access to IBM i or Windows databases with the power and protection of the LANSA Repository and RDML. You can report, chart and query from a single tool with unparalleled ease-of-use, as well as copy data to popular spreadsheets or other PC tools for analysis. Your data is protected with LANSA's file-level security. You can dramatically reduce the application backlog by empowering end users to create their own reports.

When using LANSA Client with LANSA for iSeries, setup tasks, which are outlined in this guide, need to be performed on the IBM i Server. Refer to the LANSA Client User Guide for the set up tasks required on the server.

Ý Appendix C. What is LANSA?


Appendix D. LANSA Listener Configuration on IBM i

The following section includes detailed steps for these tasks:

Configure LANSA Listener on the IBM i Data/Application Server

Configure LANSA Communications Extensions on the IBM i

A LANSA Listener is automatically installed as part of the LANSA for iSeries software installation.


Configure LANSA Listener on the IBM i Data/Application Server

To prepare the IBM i for TCP/IP and LANSA's Workstation Products, a Listener job must be started. (If you are not familiar with the LANSA Listener, refer to What is a Listener?.)

To configure the LANSA Listener on the IBM i Server, follow these steps:

Before You Begin Checklist

Step 1. Sign On to

Step 2. Create Listener Job Queue

Step 3. Create Listener Job Description

Step 4. Create Listener Subsystem Description

Step 5. Add Listener Job Queue Entry

Step 6. Add a Listener Auto Start Job Entry

Step 7. Add a Listener Routing Entry

Step 8. Add a Second Listener Routing Entry

Step 9. Start the Listener Subsystem

Step 10. Verify Listener is Active

Once you have completed these steps, go to Configure LANSA Communications Extensions on the IBM i.


What is a Listener?

A Listener is simply a communications manager. The IBM i Listener is a subsystem and group of jobs which are defined to accept requests from LANSA's workstation products such as the LANSA for the Web PC-based Administrator or Function Editor or Visual LANSA. The subsystem is used to manage the LANSA Listener jobs for communication to the workstation products.

The subsystem is defined with an autostart job which starts a LANSA listener program (i.e. SBMJOB CMD(LANSA REQUEST(STRLISTEN)) JOB(jobname) ) when the subsystem is started. A specific job description is created for the listener jobs to ensure the correct library list is being used.

Using the LANSA REQUEST(CONFIGURE) command, you can configure the communications definitions and listener records to assign which TCP/IP port is being used by the listener program. The Listener must be configured for a specific TCP/IP address and port and a specific LANSA system. You require at least one Listener for each LANSA system.

When a LANSA workstation product, such as the LANSA Web Function Editor, attempts to connect to the IBM i, the listener program will start a new LANSA job which allows communications with the LANSA system. Each LANSA workstation product will start a new job entry in the subsystem. For example, if you start the LANSA Web Function Editor and the Administrator, you will see two job entries in the subsystem.

The Listener does not impact your IBM i security as it can only be used to communicate with LANSA programs. All LANSA workstation products require a valid IBM i user profile and password.

The Listener is configured on the Data/Application Server. You can use encryption with the LANSA communications software.

For more details, refer to the LANSA Communications Setup Guide.


Before You Begin Checklist

Before you begin the Create a Listener on the IBM i task, check the following:

· Do you have the IBM i QSECOFR password or access to user profile with similar authority (requires *ALLOBJ and *SECADM special authorities)?

· Has TCP/IP been configured on the IBM i?

· Has port 4545 been enabled? (By default, the listener will use port 4545.)

Go to Step 1. Sign On to IBM i.


Step 1. Sign On to IBM i

Sign on to the IBM i using the QSECOFR profile (recommended).

You may also use another profile provided it has *ALLOBJ and *SECADM special authorities.

Go to Step 2. Create Listener Job Queue.


Step 2. Create Listener Job Queue

From an i5/OS command entry (CALL QCMD), use the CRTJOBQ command.

Press F4 to prompt the Create Job Queue command.

Enter:

Job queue: | LANLISTEN - suggested default.
Library: | QGPL - where most job queues are created by default.
Text description: | LANSA LISTENER JOB QUEUE - suggested naming convention.

The command should appear as follows:

CRTJOBQ JOBQ(QGPL/LANLISTEN) TEXT('LANSA LISTENER JOB QUEUE')

Go to Step 3. Create Listener Job Description


Step 3. Create Listener Job Description

From an i5/OS command entry, use the CRTJOBD command.

Press F4 to display the Create Job Description parameters.

Press F10 for additional parameters (press PageDown or Shift+Rollup to see additional parameters).

Enter:

Job description: | LANLISTEN - suggested default.
Library: | QGPL - where most job queues are created by default.
Job queue: | LANLISTEN - name of the job queue created in Step 2.
User: | Should be the LANSA owner, normally QOTHPRDOWN.
Request data or command: | SBMJOB CMD(XXXXXXXXX/LANSA REQUEST(STRLISTEN)) JOB(LISTENER) JOBQ(LANLISTEN) where XXXXXXXXX is the default LANSA Program Library.
Initial library list: | (QTEMP QGPL <pgmlib>) where <pgmlib> is the name of your LANSA program library.
Logging level: | (4 0 *SECLVL) - this setting will assist with program resolution.

The command should appear as follows:

CRTJOBD JOBD(QGPL/LANLISTEN) JOBQ(QGPL/LANLISTEN) TEXT('LANSA Listener')

USER(QOTHPRDOWN) RQSDTA('SBMJOB CMD(DCXPGMLIB/LANSA REQUEST(STRLISTEN)

JOB(LISTENER) JOBQ(QGPL/LANLISTEN))') INLLIBL(QGPL QTEMP DCXPGMLIB)

ENDSEV(30) LOG(4 0 *SECCLVL)

Go to Step 4. Create Listener Subsystem Description.


Step 4. Create Listener Subsystem Description

From an i5/OS command entry, use the CRTSBSD command.

Press F4 to prompt the Create Subsystem Description command.

Enter:

Subsystem description: | LANLISTEN - suggested default.
Library: | QGPL - required to run in this library.
Pool identifier: | 1 - required value.
Storage size: | *BASE - required value.
Text 'description': | LANSA Listener Subsystem.

The command should appear as follows:

CRTSBSD SBSD(QGPL/LANLISTEN) POOLS((1 *BASE)) TEXT('LANSA Listener Subsystem')

Go to Step 5. Add Listener Job Queue Entry.


Step 5. Add Listener Job Queue Entry

From an i5/OS command entry, use the ADDJOBQE command.

Press F4 to prompt the Add Job Queue Entry screen.

Enter:

Subsystem description: | LANLISTEN - description as entered in Step 4.
Library: | QGPL - required to run in this library
Job queue: | LANLISTEN - job queue created in Step 2.
Library: | QGPL - required to run in this library
Maximum active jobs: | *NOMAX - required value

The command should appear as follows:

ADDJOBQE SBSD(QGPL/LANLISTEN) JOBQ(QGPL/LANLISTEN) MAXACT(*NOMAX)

Go to Step 6. Add a Listener Auto Start Job Entry.


Step 6. Add a Listener Auto Start Job Entry

From an i5/OS command entry, use the ADDAJE command to add an auto start job entry to the LANLISTEN subsystem.

Press F4 to prompt the Auto Start Job Entry command.

Enter:

Subsystem description: | LANLISTEN - job description as created in Step 4.
Library: | QGPL - required to run in this library.
Job name: | LISTENER - job name used in Step 3.
Job description: | LANLISTEN - job description created in Step 3.
Library: | QGPL - required to run in this library.

The command should appear as follows:

ADDAJE SBSD(QGPL/LANLISTEN) JOB(LISTENER) JOBD(QGPL/LANLISTEN)

Go to Step 7. Add a Listener Routing Entry.


Step 7. Add a Listener Routing Entry

From an i5/OS command entry, use the ADDRTGE command to add the first routing entry for the LANLISTEN subsystem.

Press F4 to prompt the Add Routing Entry command.

Enter:

Subsystem description: | LANLISTEN - subsystem description as created in Step 4.
Routing entry sequence #: | 10 - suggested sequence.
Compare value: | QCMDI - required compare value.
Program to call: | QCMD - system program to execute.
Class: | QINTER - priority of job.

The command should appear as follows:

ADDRTGE SBSD(QGPL/LANLISTEN) SEQNBR(10) CMPVAL(QCMDI) PGM(QCMD) CLS(QINTER)

Go to Step 8. Add a Second Listener Routing Entry.


Step 8. Add a Second Listener Routing Entry

The Listener job requires two routing table entries for the subsystem description.

To add an additional routing entry for the LANLISTEN subsystem description, use the ADDRTGE command again.

Press F4 to prompt the Add Routing Entry command.

Enter:

Subsystem description: | LANLISTEN - subsystem description as created in Step 5.
Routing entry sequence #: | 999 - required value.
Compare value: | *ANY - required compare value.
Program to call: | QCMD - system program to execute.
Class: | QINTER - priority of job.

The command should appear as follows:

ADDRTGE SBSD(QGPL/LANLISTEN) SEQNBR(999) CMPVAL(*ANY) PGM(QCMD) CLS(QINTER)

Go to Step 9. Start the Listener Subsystem.


Step 9. Start the Listener Subsystem

To start the Listener job, use the following the command:

STRSBS XXXXXXXXX

where XXXXXXXXX equals the name of the subsystem created in Step 4.

Go to Step 10. Verify Listener is Active.


Step 10. Verify Listener is Active

To verify that the Listener job is running, use the following command:

WRKACTJOB

You should see these three items in the Work Active Job display:

Subsystem created in step 4: | LANLISTEN
Listener Job defined in the Job Description: | LISTENER
A TP (Transaction job): | started by the Listener job e.g. TP000000001

Go to Configure LANSA Communications Extensions on the IBM i.


Configure LANSA Communications Extensions on the IBM i

If you are planning to use the default TCP/IP communication port 4545 specified by LANSA for the Web, then you do not need to complete this step.

When you configured the LANSA Listener on the IBM i, you did not specify any TCP/IP communication details. The communications details are specified in a set of Listener records on the IBM i.

To configure LANSA Communication Extensions on the IBM i, follow these steps:

Before You Begin Checklist

Step 1. Work with Configuration Items

Step 2. Review Communication Definition

Step 3. Work with Listener Records


Before You Begin Checklist

Before you begin the Configure LANSA Communication Extensions on the IBM i task, check the following:

· Do you have a user profile with authority to the LANSA system?

· Has TCP/IP been configured on the IBM i? By default, the listener will use port 4545.

Go to Step 1. Work with Configuration Items.


Step 1. Work with Configuration Items

From an i5/OS command entry (CALL QCMD), enter the command:

LANSA REQUEST(CONFIGURE)

The Work with Configuration Items screen is displayed.

DC@P401601 Work with Configuration Items

Current position . : /

Select configuration item to be reviewed or changed:

Sel Configuration Item Description

_ COMMS_EXTENSIONS LANSA communications extensions

_ ILE_EXT LANSA ILE Extension

F1=Help F3=Exit F12=Cancel F14=Messages

Select the COMMS_EXTENSIONS.

A list of configuration items is displayed.

DC@P401601 Work with Configuration Items

Current position . : /COMMS_EXTENSIONS

Select configuration item to be reviewed or changed:

Sel Configuration Item Description

_ COMMS_DEFINITIONS LANSA communications definitions

_ COMMS_FACILITY_TRACE Communications facility tracing records

_ COMMS_LISTENER_RECS Communications listener records

_ COMMS_ROUTING_RECS Communications routing records

F1=Help F3=Exit F12=Cancel F14=Messages

This screen lists all configuration items related to LANSA Communications Extensions.

Go to Step 2. Review Communication Definition.


Step 2. Review Communication Definition

From the Work with Configuration Items menu, select configuration item COMMS_DEFINITIONS to review LANSA communications definitions.

The Display Communication Definitions screen is displayed.

LCOADMP401 Display Communications Definitions

Communications routing table . . . /etc/dc_pgmlib/lroute.dat

Trace file name . . . . . . . . . . /tmp/dc_pgmlib/lroute.trc

Maximum size of trace file (bytes) 640000

User queue for session jobs . . . . QUSRSYS/LCOTPJOBS

Job description for session jobs . *LISTENER

Prefix for session jobs' name . . . TP

Line turnaround wait & retry:

Wait time (milliseconds) . . . . 300

Number of retries . . . . . . . . 300

Object LCOA01 in library DCXPGMLIB now locked by this job.

F1=Help F12=Cancel F14=Messages F21=Change

This screen displays the basic definitions required to use LANSA Communications Extensions. LANSA provides default values which can be left unchanged unless you plan to set up multiple listeners. For more details, refer to the LANSA Communications Setup guide.

Return to the Work with Configuration Items menu.

Go to Step 3. Work with Listener Records.


Step 3. Work with Listener Records

From the Work with Configuration Items menu, select the COMMS_LISTENER_RECS to review these records.

The Work with Communications Listener Records screen is displayed.

LCOADMP404 Work with Communications Listener Records

Type options, press Enter.

2=Review/Change 4=Delete

Prestart Connection

Sel Comms Method Session Jobs Id

__ SOCKET 1 4545

Object LCROUT.DAT in library QGPL now locked by this job.
F1=Help F6=Add/Create F12=Cancel F14=Messages

This screen lists all the listener records stored in the LANSA Communications Extensions routing table.

There is one listener record for each supported communications method.

If a record has been defined for the system, make note of the Connection ID. You can use option 2 to change the connection ID if required.

If a record has not been defined, press F6=Add/Create.

The Add Communication Listener Record screen is displayed.

LCOADMP411 Add Communications Listener Record

Communications method . . . . . . . SOCKET

Number of session jobs to prestart _____1

Connection identifier . . . . . . . 4545

Cryptographic algorithm . . . . . . *NONE +

Data compression . . . . . . . . . YES

Login timeout (seconds) . . . . . 10

TCP_NODELAY TCP/IP socket option . YES

TCP_KeepAlive TCP/IP socket option NO_

Tracing Options

Errors . . . . . . . _ External IPC calls . IPC data . . . . . . _

Debug listener . . . _ Calls to CPIC . . . _ Internal IPC calls . _

CPIC data . . . . . _ System info . . . . _ Cryptographic info . _

Logging Options

Connect in . . . . . _ Connect out . . . . _

F1=Help F4=Prompt F12=Cancel F14=Messages

These input options are required on the Add Listener Record screen:

Communications Method

Specify SOCKET.

Number of Session Jobs to Prestart

Enter the number of session jobs to be prestarted by the listener job. Session jobs are prestarted to reduce the connection time from requesting clients by avoiding the time required by the operating system to start a job. It must be a positive number in the range 1 to 9,999.

Connection Identifier

For SOCKET (TCP/IP), this is the port number at which the listener job will listen for connection requests. If left blank, the default value of 4545 is used. The workstations must be configured to connect to the port number nominated here. If left blank, they will use the default value of 4545.

Cryptographic Algorithm

Specify the cryptographic algorithm used to encrypt transmitted data. It is recommended that you initially use *NONE -No encryption. This is compatible with prior releases of LANSA Communication extension.

Data Compression

Specify YES to allow LANSA Communications Extensions to compress the data before it is transmitted. This is the default value.

Don't change the defaults for:

Login timeout (seconds)

TCP_NODELAY TCP/IP socket option

TCP_KeepAlive TCP/IP socket option


Appendix E. Change the HTTP Install Instance

If you need to change the install HTTP instance, use the following IBM provided tools:

1. Start ADMIN HTTP Instance.

The HTTP Server (powered by Apache) can be configured via a browser interface. First you need to start the ADMIN HTTP instance using this command:

STRTCPSVR SERVER(*HTTP) HTTPSVR(*ADMIN)

2. Start HTTP Server Administration Interface.

Start your browser and access the HTTP Server Administration Interface with this URL:

http://[your System i name]:2001