Web Administration Guide

LANSA for the Web
Administration Guide

There are some tasks that are outside the realm of a web developer and for that reason they have been included in this guide.

There are also some housekeeping factors that are common to both development and maintenance and you will find these covered in this guide.

The LANSA for the Web Administrator is used to customize your web and WAM environment. The Administrator text in this guide is also available to you as context help from the Administrator software.

  • LANSA for the Web Administrator
  • Configuration Tasks
  • Maintenance Tasks
  • Occasional Tasks
  • Interactive Debugging
  • Multi-Tier Web System Set Up
  • Troubleshooting
  • Appendix A. LANSA for the Web Platform Differences
  • Appendix B. LANSA for the Web Programs

Edition Date June 6, 2014

© LANSA


1. LANSA for the Web Administrator

If you are not familiar with the LANSA for the Web Administrator, you should review:

1.1 Introduction to the LANSA for the Web Administrator

The LANSA for the Web Administrator includes the following menu categories:

1.2 Options Menu

1.4 Security Menu

1.5 Tools Menu (All platforms)

1.6 Help Menu


1.1 Introduction to the LANSA for the Web Administrator

In order to execute the LANSA for the Web Administrator, you should review the following topics:

1.1.1 What is the LANSA for the Web Administrator?

1.1.2 Connectivity to the Host

1.1.3 Starting the LANSA for the Web Administrator

1.1.4 User Profiles


1.1.1 What is the LANSA for the Web Administrator?

The LANSA for the Web Administrator is used to customize the LANSA for the Web settings used by the Data/Application Server and Web Server. It is used for both IBM i and Other (Windows and Linux) Servers.

Ý 1.1 Introduction to the LANSA for the Web Administrator


1.1.2 Connectivity to the Host

The LANSA for the Web Administrator is used for both IBM i and Other (Windows and Linux) Servers.

To use the LANSA for the Web Administrator, LANSA Open must be installed. If LANSA Open is not detected during the installation, the LANSA for the Web install will install the components required for TCP/IP connectivity between your workstation and the host.

For local configuration of a Windows Web Server using the LANSA for the Web IIS Plug-In (IIS Plug-In), a TCP/IP connection and LANSA Open is not required. The LANSA for the Web Administrator must be installed on the Windows Web Server when using local configuration for the IIS Plug-In.

Ý 1.1 Introduction to the LANSA for the Web Administrator


1.1.3 Starting the LANSA for the Web Administrator

Start the LANSA for the Web Administrator by opening the LANSA folder from the LANSA icon on your desktop. Select the Settings and Administration folder and choose the Web Administrator from the list. (This window may have a different name in your LANSA installation.)

Using the Options menu, you may start the Administrator to work with Local Configurations or work with a remote configuration by choosing Connect to Host

Ý 1.1 Introduction to the LANSA for the Web Administrator


Local Configurations

To work with a local configuration file on a Windows Web Server, select the Options menu and choose the Local Configuration option. You may create a New configuration file or Open an existing configuration file. For details of the options, go to 1.2.2 Local Configuration.

Once you have selected a configuration file option, the LANSA for the Web Administrator's main window is displayed. This document guides you through the various menu entries and dialog boxes that you will encounter.

The status bar at the bottom of the Window displays the name of the local configuration you have open.

Ý 1.1.3 Starting the LANSA for the Web Administrator


Connect to Host

To connect to an IBM i, Windows or Linux host, select the Options menu and choose the Connect option. You will be presented with the System Defaults dialog box. Using the System Defaults options, you can enter the details of the host system to which you want to connect, or you can choose a Profile, containing these options, which you have previously saved.

If the connection to a host IBM i s not successful, the commands in the Administrator will not be available to you.

For details of these options, go to the 1.2.1 Connect/Disconnect command on the Options menu.

Once you are connected to the host, the LANSA for the Web Administrator's main window is displayed. This document guides you through the various menu entries and dialog boxes that you will encounter.

The status bar at the bottom of the window shows you the connection status. If you are connected to a host, it displays information about the host you are currently connected to.

If you are running Task Tracking in LANSA, then when you add, change, or delete Components or Graphic Variables, the Administrator will prompt you for the Task ID as required by the Task Tracking level.

Ý 1.1.3 Starting the LANSA for the Web Administrator


1.1.4 User Profiles

When you start the LANSA for the Web Administrator and connect to a host, you will need to connect to the host using a valid user profile. The user profile specified must be configured to use the required LANSA system. For example, on the IBM i, it must have the LANSA program library in its library list.

If you wish to configure security on the systems, you must use the QSECOFR profile (on the IBM i) or a LANSA partition security officer profile.

Ý 1.1 Introduction to the LANSA for the Web Administrator


1.2 Options Menu

When the LANSA for the Web Administrator is first started, the Options menu includes these options:

  • 1.2.1 Connect/Disconnect
  • 1.2.2 Local Configuration
  • 1.2.3 Exit


1.2.1 Connect/Disconnect

The Connect command on the Options menu is used to connect to a different host.

Once you have specified the details of the system to which you want to connect in the Profile Details area, you can save these details using a Profile Name. Refer to Save As (Profile) .

If the connection is not made to a host system, the other commands in the Administrator's menu are not available to you.

The Disconnect command on the Options menu is used to disconnect from a different host.

Profiles

Select the Profile that you want from the drop down list.

or

enter the details in the Profile Details area.

To save the details you have specified in the Profile Details area, press Save As (Profile) ... and give your details a Profile Name.

Profile Details

This area contains the details of the connection, either recorded as a Profile, or entered each time you wish to connect to a host.

LANSA System

Mandatory. The name of your Host.

Host Type

Mandatory. Select the type of host you are connecting to. Supported host types are IBM i and Other. If you select host type Other (i.e. if the LANSA for the Web System you administer is located on a Windows or Linux Server) then the Mode is restricted to HTML only and non-IBM i settings will be disabled.

Partition

Mandatory. Enter the name of the LANSA partition to which you wish to connect.

Language

Optional. If the partition is a multilingual partition, you can specify the partition language you require. The Language must be left blank for a non-multilingual partition. If it is left blank for a multilingual partition, the default partition language will be used.

Userid

Mandatory. The user profile is used to determine if you have authority to execute the security-related commands, which are:

  • Process Authentication
  • User Registration
  • Enable Partition
  • Configure System
  • Maintain Systems
  • Clean Up Systems.

Password

Mandatory. The value specified here will be saved and redisplayed the next time you recall this command, if you select the Save Password option. The password is case sensitive on some hosts.

Save Password

Select this option if you want to save the password you have entered and use it the next time you connect or reconnect to a host. Be careful selecting this option, as anyone using your PC will be able to reuse the password.

If you select this option, be sure to press the Save button before you press OK.

Auto-connect on Startup

This option is not available for the Administrator.

Advanced System Options

Ý 1.2 Options Menu


Save As (Profile)

Use this option to save the details in the Profile Details area for use at a later date. In order to identify the saved details (called a Profile) you must give them a name.

Enter the name you wish to give to the Profile Details in the future, and then press OK.

Save button

If you press the Save button, the current connection parameters will be saved to the selected Profile Name.

Delete button

To delete a Profile, select the Profile that you want to delete from the Profile drop down list and press the Delete button. You will be asked to confirm the deletion. Note that you cannot delete the <Default> Profile.

Reset button

If you press the Reset button, all parameters for the Profile Details and the related Advanced settings will be reset to their default values.

Advanced... button

If you are running a non-English system, select the Advanced button to open the Advanced System Options dialog box.

Ý 1.2.1 Connect/Disconnect


Advanced System Options

If you are running a non-English system, you must insert the replacement characters to be used for the '@' and '#' symbols.

Ý 1.2.1 Connect/Disconnect


1.2.2 Local Configuration

The Local Configuration command on the Options menu is used to open a local configuration file (normally on a Windows Web Server). You use this option to configure the LANSA for the Web IIS Plug-In on the Web Server.

You may select one of the following options:

  • New
  • Open
  • Open Active

Once you have selected the configuration file option, the LANSA for the Web Administrator main page for Local Configuration is opened.

Ý 1.2 Options Menu


New

From the Options menu, select Local Configuration, then the New option to create a new local configuration file on the Windows Web Server.

The name of the configuration file will be specified if you try to save the new configuration for the first time.

The configuration file name can be specified using the Save (for a new configuration) or Save As option. When you Close the Administrator, you will be asked to save the settings if you have not already done so.

Ý 1.2.2 Local Configuration


Open

From the Options menu, select Local Configuration and then the Open option to open an existing configuration file on the Windows Web Server.

A standard file Open dialog will be displayed.

To open a local file on the Windows Web Server, a TCP/IP connection is not required. For details, refer to 1.1.2 Connectivity to the Host.

Ý 1.2.2 Local Configuration


Open Active

From the Options menu, select Local Configuration and then the Open Active option to open the configuration file, which IIS is currently configured to use.

For this to work, the Web Server where the LANSA for the Web IIS plug-in must be IIS 7 or later

Ý 1.2.2 Local Configuration


1.2.3 Exit

The Exit command on the Options menu is used to close the LANSA for the Web Administrator.

Ý 1.2 Options Menu


1.3 Options Menu (Local Configuration)

If you have already opened a local configuration file or are working on a new local configuration, the Options menu will include the following options:

  • 1.3.1 Save (Local Configuration)
  • 1.3.2 Save As (Local Configuration)
  • 1.3.3 Close (Local Configuration)


1.3.1 Save (Local Configuration)

The Save command on the Options menu is used to save the current local configuration file on the Windows Web Server.

If you are creating a new configuration file, you will be prompted to enter the file name. Refer to 1.3.2 Save As (Local Configuration).

If you wish to save the current file using a new name, use the 1.3.2 Save As (Local Configuration) command.

Ý 1.2 Options Menu


1.3.2 Save As (Local Configuration)

The Save As command on the Options menu is used to save the current local configuration file using a specified name on the Windows Web Server. A standard Windows Save dialog will be displayed to allow you to enter the file name and location.

For the LANSA for the Web IIS Plug-in, the file name should be specified as L4W3Serv.cfg.

The file should be stored in the LANSA for the Web IIS Plug-In installation directory (by default c:\Program Files\LANSA\WebServer\IISPlugin).

Ý 1.2 Options Menu


1.3.3 Close (Local Configuration)

The Close command on the Options menu is used to close the local configuration file.

If changes have not been saved, you will be prompted to save changes before closing the file. Refer to 1.3.2 Save As (Local Configuration).

Once the file is closed, the LANSA for the Web Administrator main window will be displayed to allow you to connect to a host or open another Local Configuration file.

Ý 1.2 Options Menu


1.4 Security Menu

Before you use the commands provided for security, it is recommended that you read LANSA for the Web Configuration and Set Up on IBM i in the Installing LANSA on IBM i Guide to gain an understanding of the user authentication alternatives provided by LANSA for the Web.

The Security menu will only appear if you are connected to a host. For details, refer to 1.1.3 Starting the LANSA for the Web Administrator and Connect to Host .

The Process Authentication and User Registration options in the Security Menu can only be used if you are signed on as QSECOFR or the partition security officer.

The Security menu includes the following options:

1.4.1 Process Authentication

1.4.2 User Registration


1.4.1 Process Authentication

This command allows you to work with the list of LANSA processes that require user authentication. You must be signed on as QSECOFR or the partition security officer to use it.

The processes listed in the Process Authentication dialog box are only used if you intend to implement the Configuring LANSA for the Web Security in the Installing LANSA on IBM i Guide.

The list of processes defined here restricts access to the LANSA processes. A request to any of the processes registered will require a valid Web user profile. The user profiles must be registered to LANSA for the Web.

To add a new process, press the Add... button. The Add Process dialog box is displayed.

To change a process, highlight the process to be changed and press the Change... button. The Change Process dialog box is displayed.

Refer to Add or Change Process.

Ý 1.4 Security Menu


Add or Change Process

Use Default

If you select Use Default, then *DEFAULT will be used for authentication.

Specify

If you select Specify, then you will need to enter the name of the Authentication Library you want to use.

Ý 1.4.1 Process Authentication


1.4.2 User Registration

LANSA for the Web allows you to map the Web Server user profile to a host user profile. The host profile is used by LANSA to determine the user's access rights on the host.

To use this command, you must be signed on as QSECOFR or the partition security officer.

To add a new user, press the Add... button. The Add User dialog box is opened and the entries are described in User Information.

To change the information of an existing user, you must know the password of the associated host user profile. You will not be allowed to change any information if you do not know the password. Refer to Changing a User for an example of the Change User dialog box.

You can delete any user profiles without having to know the user profile password.

Refer to:

Add User

User Information

Changing a User

Ý 1.4 Security Menu


Add User

To add a user, press the Add ... button on the User Registration dialog box. The User Information page of the Add User dialog box is displayed for you to enter the user's details.

Ý 1.4.2 User Registration


User Information

Web User

Mandatory.

This is the user profile registered to the Web Server. Choose Anonymous user for all partitions as a user profile to associate a host user profile for anonymous access to your LANSA applications. This entry will be seen as DFTUSR in the User Registration list

To define a host user profile for DFTPRT user profile for LANSA for the Web spool file display, specify DFTPRT as an Authenticated User. The access rights of the associated host user profile determine which spool files may be displayed.

You can assign partition level user access for the anonymous user by creating users using the Anonymous user for partition and specify the partition. This way you can assign certain rights to a particular partition. This entry will be seen as DFT_<partition> in the User Registration list

If you intend to provide support for an anonymous user, you must register the Anonymous user for all partitions. Map this Web user ID to a host user profile with minimal access rights.

Web User IDs are resolved in the following order. Ensure the System Name and Port Number correspond to the multi-homing system details.

Priority | Web User | Web Server Name | Web Server Port
1 | Authenticated User | Specified Name | Specified Port
2 | Authenticated User | Specified Name | Any
3 | Authenticated User | Any | Specified Port
4 | Authenticated User | Any | Any
5 | Anonymous user for partition | Specified Name | Specified Port
6 | Anonymous user for partition | Specified Name | Any
7 | Anonymous user for partition | Any | Specified Port
8 | Anonymous user for partition | Any | Any
9 | Anonymous user for all partitions | Specified Name | Specified Port
10 | Anonymous user for all partitions | Specified Name | Any
11 | Anonymous user for all partitions | Any | Specified Port
12 | Anonymous user for all partitions | Any | Any

Web Server - Name

Mandatory. If you are not using multi-homing support, choose Any as your Web Server Name.

If you are using multi-homing support, enter either the DNS Name (for example: sydaspect.lansa.com) or the DNS's IP Address (for example: 124.54.56.21) in the System Name field.

Web Server - Port

Mandatory. If you are not using multi-homing support, choose Any as your Web Server Port.

If you are using multi-homing support, enter the port number associated with the Web Server Name and the Web User.

Timeout

Mandatory. The timeout period for each user. Choosing Default means that the system wide timeout applies.

Host User ID, Password and Confirm

Mandatory. Enter the host profile to which the Web Server user profile is mapped. The password is case sensitive on some systems. You must confirm the password to be able to save.

Test

Try to establish a communication connection with the Data/Application Server with the user profile specified and the system you are currently connected to.

Ý 1.4.2 User Registration


Changing a User

If you select a user registration and press the Change... button, an Authority Check dialog will appear.

After passing the authority check, the Change User dialog box is displayed so that you can alter the User and/or the user's Timeout and Password.

Ý 1.4.2 User Registration


1.5 Tools Menu (All platforms)

The menu options that are displayed will depend upon your connection to the host, the type of host system being used and your installation model.

For all hosts:

  • 1.5.1 Enable Partition (Connected to host)
  • 1.5.2 Configure System (Connected to host)
  • Data/Application Server

For an IBM i host:

  • 1.5.3 Tools Menu (IBM i only)

For a local host:

  • 1.5.4 Tools Menu (Local Configuration)


1.5.1 Enable Partition (Connected to host)

The Enable Partition option will only appear if you are connected to a host. For details, refer to 1.1.3 Starting the LANSA for the Web Administrator and Connect to Host .

You must be signed on as QSECOFR or the partition security officer to enable a LANSA partition for LANSA for the Web. For details, refer to 1.1.4 User Profiles.

The Enable Partition option is only available when connected to an IBM i host.

Partition

Mandatory. Specify the name of the partition you want to enable. LANSA for the Web will create versions of the Standard pages in the newly enabled Web partition. These Standard pages are necessary for your applications to run properly in this partition.

Ý 1.5 Tools Menu (All platforms)


1.5.2 Configure System (Connected to host)

When configuring the LANSA for the Web system, the following options are available with
Configure System, Data/Application Server

  • Data/Application Server
  • Transaction Monitor
  • WAM Components
  • Web Functions
  • Load Management
  • Presentation
  • Backup
  • File Location
  • Miscellaneous tab

or with Configure System, Web Server:

  • Miscellaneous tab
  • File Location
  • Transaction Monitor

The Reset button will retrieve default values from the host system. This option is enabled if the host system to which you are connected supports retrieving default values. Note that you need to select OK to save the settings after you have retrieved them. Also note that Job Queues and Libraries are NOT replaced with default values.

IBM i Servers:

If you are using a single-tier IBM i installation, you will need to specify the options you wish to use for the Data/Application Server and the Web Server System (IBM i only).

If you are using a multi-tier IBM i installation with an IBM i CGI-based Web Server, you will need to specify the options you wish to use for the Web Server System (IBM i only). You will need to connect to the relevant IBM i to set up each of the systems. The Web Server setting can also be changed using the W3@P2901 program.

Other Servers:

If you are using a Windows Multi-Tier installation, then you will only need to specify the options you wish to use for the Windows Data/Application Server.

The Web Server settings for the parameters used by the LANSA for the Web IIS Plug-In are configured using the 1.2.2 Local Configuration section.

Ý 1.5 Tools Menu (All platforms)


Data/Application Server

To set up your Data/Application Server, select the Tools menu, choose Configure System and then the Data/Application Server sub menu command. (This command will vary depending on your server.)

You will only be able to set these options if you are signed on as QSECOFR (for IBM i servers) or the partition security officer. The options to be set are on these tabs:

Transaction Monitor

WAM Components

Web Functions

Load Management

Presentation

Backup

File Location

Miscellaneous tab

Ý 1.5.2 Configure System (Connected to host)


Transaction Monitor

The Transaction Monitor page allows you to specify the settings relating to the starting and stopping of the LANSA for the Web jobs by the Transaction Monitor.

Transaction Monitor

Check Interval (minutes)

The Transaction Monitor monitors all the LANSA jobs started by LANSA for the Web. It is responsible for terminating any jobs that have not been active after a defined period. There is only one instance of the Transaction Monitor for a given host.

Most of the time, the Transaction Monitor is dormant. It will be activated at predefined periods to perform its tasks. Use this option to define this time period. For example, if you define this time as 5 minutes, the Transaction Monitor will be activated every 5 minutes to perform its tasks.

The default value is 1 minute.

Job Priority (IBM i only)

Configure the job priority of the Transaction Monitor and reset the Transaction Monitor for this value to be in effect.

The default value is 20.

Job Queues

Transaction Monitor (IBM i only)

Enter the job queue for jobs to be submitted to run the Transaction Monitor.

The Transaction Monitor is identified as LWEB_MON.

This setting is disabled if you are connected to a host type Other.

The setting will not be reset to default.

Web Jobs (IBM i only)

Enter the job queue to submit the LANSA for the Web jobs.

The LANSA for the Web jobs are named as LWEB_JOB.

This setting is disabled if you are connected to a host type Other.

The setting will not be reset to default.

Web Job Management

Ready to Use - Minimum and Maximum

Enable this feature to use Ready to Use Web Jobs. Enter the Minimum and Maximum number of Ready to Use Web Jobs.

Disable this feature with caution as the result might be more Ready to Use Web Jobs than desired. In effect there will be no upper limit on how many Ready to Use Web Jobs are available for the system.

The default is Enabled and default values for Maximum and Minimum are 2.

Usage Count

Enter the number of times a Web Job can be used in the range 1-999.

The default value is 500. (IBM i and Linux)

The default value is 1. (Windows)

Minimum Web Job Id and Maximum Web Job Id (Windows and Linux host only)

Only applicable with a Data/Application Server running LANSA Version 11 SP5 or later.

Enter the Minimum and Maximum Web Job Id. The values can be in the range 1 - 999999.

The default value for Minimum is 1 and the default value for Maximum is 999999.

Ý Data/Application Server


WAM Components

The Configure Data/Application Server page allows you to specify WAM Component related settings for your system.

Default Session Key Method

Select the method to store and transfer web session identifiers (session keys) for WAMs with SessionKeyMethod property value of *DEFAULT. You can choose from:

  • HiddenField: The session key is stored in a hidden field and is transferred with posted data.
  • URL: The session key is added to the URL query string.
  • Cookie: The session key is stored and transferred in an HTTP cookie.
  • SecureCookie: The session key is stored and transferred in an HTTP cookie, but only for HTTPS (Secure HTTP) protocol.

Note that this setting has no effect at this stage.

The default value is HiddenField.

Timeout (minutes)

The time in minutes that a session is kept active before it expires. If this time elapses without interaction between the user agent and the server, the session status is updated to expired and the session data is marked as available for cleanup.

The default value is 5 minutes.

Cleanup (minutes)

The time interval (in minutes) between periodic cleanups performed by the transaction monitor. The cleanup deletes session data of expired sessions. A value of 0 means no cleanup occurs.

The default value is 60 minutes.

Session Locking

Only available with a Data/Application Server running LANSA Version 11 SP5 or later.

If you Enable WAM Session Locking, you must specify a timeout value in seconds. Either choose Default timeout, which is 1 minute, or Specify the timeout in seconds.

The option is enabled by default.

Disable LXML output

Check (select) this option to prevent LXML (Data XML) being accessed from the browser URL with the URL keyword: LXML= yes. Normally Data XML is transformed and the resulting output is returned, so access to Data XML in the browser is not required.

The default is to allow access, and this is required if you wish to expose your WAMs as Web Services. If you haven't exposed your WAMs as Web Services and you wish to prevent the browser from accessing Data XML resulting from WAM execution, you must check (i.e. select) this Disable LXML output option.

Disable pre-formatted output

Disable pre-formatted output. Pre-formatted output is only required if you use the Large List weblet (std_largelist). To use the std_largelist weblet, this option must be unchecked.

The option is disable by default.

Ý Data/Application Server


Web Functions

The Configure Data/Application Server page allows you to specify Web Function related settings for your system.

HTML Timeout (minutes)
XML Timeout (minutes)

The Transaction Monitor will terminate LANSA jobs that remain inactive after the timeout period has elapsed.

This timeout period is used when there is no specific timeout period specified in User Registration. A value of 0 indicates that there will be no timeout period.

The default value for HTML Timeout is 2 minutes.

The default value for XML Timeout is 1 minute.

Please note that the time of this timeout must be lower than the Response Timeout for an IBM i Web Server. Refer to Configure IBM i Web Server and Web Server System (IBM i only) for the equivalent IBM i settings.

Purge WEBEVENT function data (hrs)

The information needed to restart WEBEVENT functions will be held for the time you specify here. When a WEBEVENT function has been inactive for longer than this time, the data will be deleted. This means WEBEVENT functions that have been inactive for up to this time limit may be restarted with no loss of data.

The default period is 1 hour (stored in the data area in seconds).

Ý Data/Application Server


Load Management

This Configure Data/Application Server page allows you to specify a limit to the number of concurrent users on your Windows data/application server. For Visual LANSA Servers, this page also allows an Administrator to specify parameters for the Window Desktop Heap Management. These options can be used to 'fine tune' the system behavior under heavy load.

Concurrent Users

Enter the number of concurrent users allowed on your system at the same time.

When the maximum number of users is active and another user attempts to invoke the LANSA for the Web application, the user will be informed that the Server is unable to process the request at that point in time.

Choose Unlimited to indicate no maximum.

The default value is 20.

Note: Visual LANSA has a hard limit of 1500 concurrent users. That is, if you enter any value greater than 1500 or less than 0, the effective value will become 1500.

Windows Desktop Heap Management

Warning: Under normal circumstances you should not need to amend these settings. Changes to these settings have the capacity to affect the way your Windows server operates and should only be performed by an authorized Windows Administrator. Changing them without understanding the implications could affect Windows performance or stability. Contact your local LANSA distributor before continuing.

For further details, refer to WDTM...(Windows Desktop Heap Management) in the LANSA Communications Set up Guide.

Number of Window Desktops

By default, without changing the Maximum load per Window Desktop setting (see below), each Window Desktop is capable of hosting a maximum of 100 Web Jobs and/or LANSA Open sessions. Changing this value to 10 will support a maximum of 1000 Web Jobs and/or LANSA Open sessions for the whole Windows system.

The default setting is 8. (i.e. supporting a maximum of 800 Web Jobs and/or LANSA Open sessions)

The value must be greater than or equal to 0.

Set this value to 0 to disable Windows Desktop Heap Management. When Windows Desktop Heap Management is disabled and:

  • the Windows Services Manager option Allow service to interact with desktop for the listener service is not checked (this is the default setting) only a maximum of approximately 100 Web Jobs and/or LANSA Open sessions can be run. (This value has been found by various tests and may vary slightly depending on system configuration.)
  • the Windows Services Manager option Allow service to interact with desktop for the listener service is checked, then a maximum of approximately 500 Web Jobs and/or LANSA Open sessions can be run. (This value has been found by various tests and may vary slightly depending on system configuration.)

Note that the Windows Services Manager option Allow service to interact with desktop and can be changed in the Windows Services Manager. It is recommended that this option is NOT checked (selected) for production systems as this may significantly affect the stability of the system.

Note: Different Windows versions support different maximum number of Window Desktops. Although you may set the value to greater than the maximum number supported by the underlying Windows operating system, Visual LANSA will only create the maximum number of Window Desktops supported by the underlying Windows operating system. This may mean that the number of Window Desktops created do not exactly match the value you have set. Please refer to the Windows documentation for more information.

Advanced Options

These advanced options are used only for exceptional conditions and would not normally be changed. Please contact your local LANSA distributor before changing any of these options. To change these advanced options, users need to check the option Access Advanced Window Desktop Options.

Maximum load per Window Desktop

A Web Job or LANSA Open session has a loading factor of 5. For the default value 500, a Window Desktop supports a maximum of 100 Web Jobs and/or LANSA Open sessions. Increasing the value may allow more Web Jobs and/or LANSA Open sessions to be hosted in a Window Desktop. But that does not mean all these Web Jobs and/or LANSA Open sessions would be run reliably inside a Window Desktop. The default setting is the most failsafe value and should work reliably for most Windows systems. It is strongly recommended not to change this value.

The default setting is 500.

The value must be greater than or equal to 1.

Maximum number of processes per Window Desktop

This is the hard limit of the number of Web Jobs and/or LANSA Open sessions that can be hosted in a Window Desktop. Note that the Maximum load per Window Desktop setting above may limit the number of processes at runtime to a value smaller than this setting. The default setting is the most failsafe value and should work reliably for most Windows systems. It is strongly recommended not to change this value.

The default setting is 100.

The value must be greater than or equal to 1 and smaller than or equal to 500.

Maximum number of registered executables

Each LANSA installation requires two executables to be registered. So for the default value 20, at most, ten LANSA installations are supported by the Window Desktop Heap Management. If there is a requirement to have more than ten LANSA installations running simultaneously on the same Windows system, you may need to increase this value.

The default setting is 20.

The value must be greater than or equal to 1 and smaller than or equal to 200.

Windows Station name

Unless the default Window Station name is conflicting with users' other Windows applications, it is not recommended to change this value. Only the first 15 characters will be used. Do not use symbolic characters in the name.

The default setting is lxsta0.

Window Desktop name prefix

Window Desktop names will be generated by appending this prefix with an integer index, e.g. lxdesktop0.

Unless these Window Desktop names are conflicting with users' other Windows applications, it is not recommended to change this value. Only the first 15 characters will be used. Do not use symbolic characters in the prefix.

The default setting is lxdesktop.

Ý Data/Application Server


Presentation

The Presentation page allows you to control the presentation of your Web pages.

Allow selection from any column in table

If set to 'Y', LANSA for the Web will allow you to click on any column in the browse list to make a selection. (The 'Y' setting causes additional data to be sent from LANSA for the Web to the browser, to make each of the columns selectable.)

If set to 'N', you will have to click on the selection image in the browse list to make a selection.

The default setting is 'N'.

Present standard function keys in the body of the function

Enter 'Y', to have any buttons that are displayed in the Standard Header also be displayed in the body of the function.

Enter 'N', to have the buttons displayed in the Standard Header only (and not in the body of the function).

The default setting is 'N'.

Always show frames for CUA/SAA style processes

When set to 'Y', frames will be persistent in LANSA for the Web. This means that displays in LANSA functions will be displayed in the Client area of the frameset.

When set to 'N', frames will not be persistent. When displaying LANSA functions, the frames will be removed.

The default setting is 'N'.

Use Non Scrolling Header

When set to 'Y', LANSA for the Web will generate a separate frame for a non-scrolling header style for all the LANSA functions, which have been Web, enabled. The non-scrolling header style provides you with a separate frame that shows the STDHEADER page. The body of the function will be displayed in a separate frame. This feature allows you to scroll through the body of the function, with the buttons in the STDHEADER page displayed in a separate and static frame.

The default value is 'N'.

Menu frame width

This is the size of the Menu frame expressed as a percentage of the width of the browser, when frames are displayed in LANSA for the Web.

The default setting is 30.

Ý Data/Application Server


Backup

On this page you can specify if you wish to keep backups of the generated HTML and how many you wish to keep.

Enable automatic backups of generated HTML

If you select this option, LANSA will save the current HTML as a previous version when it generates HTML for functions.

If this option is not selected, when a function is recompiled, any changes made to the generated HTML will be discarded.

Previous versions of the generated HTML can be edited by using the LANSA for the Web Function Editor. You can then incorporate these changes into the current HTML by performing a 'Copy and Paste' operation.

The default setting is 'selected'.

Save previous copies

Enter the number of backup copies of your generated HTML that you want to be saved. The maximum number is 10. Note that the number of HTML backups retained will affect the size of the LANSA internal tables used to store the generated HTML.

Backups are only kept if you have also specified 'Y' in the Enable automatic backups of generated HTML option.

The maximum value is 10.

The default value is 2.

You can access these saved versions of the generated HTML via the LANSA for the Web Function Editor.

Ý Data/Application Server


File Location

Use this File Location page of the Configure Data/Application Server page to specify the location of various files.

CGI

Enter the alias name used for the location of the CGI files used by the Web Server software.

The default value is CGI-BIN.

Image Files

Enter the alias name used for the location of the image files used by LANSA for the Web. LANSA for the Web expects to find all image files in a single location.

The default setting is /IMAGES. (IBM i)

The default setting is /images. (Windows and Linux)

Authentication Library (IBM i only)

Enter the alias name for user authentication over particular processes.

Refer to Configuring LANSA for the Web Security in the Installing LANSA on IBM i Guide for details of this library and how it is used for user authentication.

The setting will not be reset to default.

HomePage (IBM i only)

Enter the URL to be called when the user selects the 'Home' button in LANSA functions.

Ý Data/Application Server


Miscellaneous tab

You specify the default location of the LANSA for the Web working library in the Miscellaneous page of the Configure Data/Application Server.

Working Library (IBM i only)

This library is used by LANSA for the Web to create its internal files.

If you have multiple LANSA systems on a single IBM i, it is strongly recommended that each of these LANSA systems is set up to have a different working library. This allows you to use the cleanup program, W3@P2200, against each individual system without disrupting the other LANSA systems on your IBM i.

This entry will be disabled if you connect to a host type Other.

The specified library must already exist on the IBM i.

The setting will not be reset to default.

Web Job Priority (IBM i only)

Configure the job priority of the Web jobs. New web jobs will now be assigned this job priority.

The default value is 19.

Response timeout

Response time is the given amount of time for which a primary job receives an acknowledgement from the secondary job. When the response time is reached, the primary job stops waiting for secondary job.

For a multi-tiered setup, the data application server has a default value of 300 seconds and the web server has a default value of 600 seconds response. The response time for the web server must always be set greater to that of the data application server to allow for network traffic.

In a single tier setup, this value has a default value of 300 seconds.

A value of 0 means there is no timeout.

Enable Extended Exchange (IBM i only)

The standard LANSA exchange list is used by LANSA for the Web to pass values between WEBEVENT functions. The exchange list has a limit of 2000 bytes. Functions that use large text areas quite often exceed the 2000 byte limit.

Set this flag to 'Y' if more than 2000 bytes can be passed between WEBEVENT functions.

Functions compiled when this flag is 'Y' will contain code to alert the Web controller to pass values to the function via the extended exchange.

The default value is 'N'

Copy Unreferenced Browselists

LANSA now correctly copies only referenced browselists. However, if you enable this option, LANSA will copy un-referenced browselists as well.

The default value is 'N'

Allow Interactive Debugging

Enable interactive debugging using the LANSA Development Environment.

The default value is 'N'

Decimal Symbol

This setting determines which decimal symbol is used for some of the Web related operations in the LANSA runtime. It needs to be in sync with the LANSA setting. The possible values are Dot, Comma and Default. If you select the Default option, the next time a web function runs it will use the LANSA runtime value.

The default value is Dot

File Serving

The following options are only available with a Data/Application server running LANSA Version 11 SP5 or later, and with IIS Plug-in or Apache Module for Linux.

Allow Files to be served from Web Server

If a web page contains an include file request (for example <!--#include file="/some/file"--> and if this option is NOT enabled, any #include file requests will return an HTTP error code 404 (File Not Found).

The default value is 'N'

Serve Files from this directory

If Allow Files to be served from Web Server is enabled, you must specify where to fetch the files from. Either choose the default location: {LANSA_INSTALL_ROOT}/tmp/fetch-files or specify a location.

For security reasons, only files within the specified directory will be served.

Note that if you enable this option, you must also enable the corresponding Web Server option.

By default these options are disabled.

Ý Data/Application Server


1.5.3 Tools Menu (IBM i only)

Tools menu when connected to an IBM i backend:

  • 1.5.1 Enable Partition (Connected to host)
  • 1.5.2 Configure System (Connected to host)
  • Data/Application Server
  • Web Server System (IBM i only)
  • HTTP Header Variables (Connected to IBM i Web Server)
  • Clean Up Systems
  • Clean Up Web Server (Connected to IBM i Web Server)
  • Clean Up Event Logging (Connected to host only)


Web Server System (IBM i only)

If the Web Server is on a different IBM i than the Data/Application Server, then you will need to connect to the correct IBM i using the 1.2.1 Connect/Disconnect command on the Options menu.

To set your Web Server options, select the Tools menu, choose Configure System and then the Web Server System command.

You will only be able to set these options if you are signed on as QSECOFR or the partition security officer.

The options are set using these three tabs:

Miscellaneous (IBM i Web Server)

File Location (IBM i Web Server)

If your host is not an IBM i:

You will not have the equivalent options, as your Web Server will not be on a separate system.

Ý 1.5.2 Configure System (Connected to host)


Transaction Monitor (IBM i Web Server)

Only the options that are applicable to the Web Server are enabled. You do not set these options if you are connected to a host type Other.

Transaction Monitor – Check Interval (minutes)

The Transaction Monitor monitors all the LANSA jobs started by LANSA for the Web. It is responsible for terminating any jobs that have not been active after a defined period. There is only one instance of the Transaction Monitor for a given IBM i system.

Most of the time, the Transaction Monitor is dormant. It will be activated at predefined periods to perform its tasks. This parameter is used to define this time period. For example, if you define this time as 5 minutes, the Transaction Monitor will be activated every 5 minutes to perform its tasks.

The default value is 2 minutes.

Transaction Monitor - Job Priority

Configure the job priority of the Transaction Monitor and reset the Transaction Monitor for this v

alue to be used.

The default value is 20.

Job Queues - Transaction Monitor

Enter the subsystem to run the Transaction Monitor.

The Transaction Monitor is identified as LWEB_MON.

Ý Web Server System (IBM i only)


File Location (IBM i Web Server)

CGI

Enter alias name used for the location of the CGI files used by the Web Server software.

The default value is CGI-BIN.

Image Files

Enter the alias name used for the location of the image files used by LANSA for the Web. LANSA for the Web expects to find all image files in a single location.

The default setting is /IMAGES.

Authentication Library

Enter the alias name of the library set up for user authentication.

Refer to Configuring LANSA for the Web Security in the Installing LANSA on IBM i Guide for details of this library and how it is used for user authentication.

The default setting is AUTHLIB.

HomePage

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 Web Server.

Ý Web Server System (IBM i only)


Miscellaneous (IBM i Web Server)

Working Library

The library for LANSA for the Web to create its internal files.

The default value is 'WEBWORK'. The WEBWORK library is created when you install LANSA for the Web.

If you have multiple LANSA systems on a single IBM i, it is strongly recommended that each of these LANSA systems is set up to have a different working library. This allows you to use the cleanup program, W3@P2200, against each individual system without disrupting the other LANSA systems on your IBM i.

Router Job Subsystem

Enter the subsystem to run the LANSA for the Web router jobs.

The LANSA for the Web router jobs are named as LWEB_SERV.

Web Job Priority

Configure the job priority of the Web jobs. New web jobs will now be assigned this job priority.

The default value is 20.

Response timeout

Response time is the given amount of time for which a primary job receives an acknowledgement from the secondary job. When the response time is reached, the primary job stops waiting for secondary job.

For a multi-tiered set up, the data application server has a response default value of 300 seconds and the web server has a response default value of 600 seconds. The response time for the web server must always be set greater to that of the data application server to allow for network traffic.

In a single tier setup, this value has a default value of 300 seconds.

A value of 0 means there is no timeout.

Other options on this tab

None of the other options are used with an IBM i web server.

Ý Web Server System (IBM i only)


Maintain Systems (Connected to host)

This command allows you to define multiple systems and ports on a single IBM i.

When you select the Maintain Systems command from the Tools menu, the Maintain Systems dialog box is displayed. You can only use the Maintain Systems commands if you are signed on as QSECOFR or the partition security officer.

The Maintain Systems dialog box displays a list of LANSA systems already configured for LANSA for the Web. LANSA for the Web uses the system name and port identifier on the URL to determine which LANSA system should handle the request. You must remember to include the port identifier in your URL when issuing the request to LANSA for the Web.

Add... or Change...

When you select the Add or Change button, the relevant Add or Change LANSA System dialog box is opened.

Refer to:

General (IBM i only)

Remote (IBM i only)

Web Server (IBM i only)

Hold System (IBM i only)

Ý 1.5.2 Configure System (Connected to host)


General (IBM i only)

General page

This page allows you to record a system name and port identifier for a LANSA System on the IBM i.

Note: Multi-homing Support
LANSA for the Web can be configured with multiple IP Addresses that point to one LANSA System.
It can be set up using IBM's HTTP Web Server products. To use LANSA for the Web with multi-homing support, you will need to specify the System Name and Port Number when creating a new LANSA system.

Web Server - Name

If you are not using multi-homing support, choose Any as your Web Server Name.

If you are using multi-homing support, enter either the DNS Name (for example: sydaspect.lansa.com) or the DNS's IP Address (for example: 124.54.56.21) in the System Name field.

Web Server - Port

If you are not using multi-homing support, choose Any as your Web Server Port.

If you are using multi-homing support, enter the port number associated with the Web Server Name.

Multi-homing systems are resolved in this order:

Priority | System Name | Port Number
1 | Specified Name | Specified Port
2 | Specified Name | Any
3 | Any | Specified Port
4 | Any | Any

LANSA library

Enter the LANSA library.

When you first install LANSA for the Web, it will check if a LANSA system has already been set up. If no LANSA system has been set up, the library to which LANSA for the Web is being installed will be used as the default LANSA library.

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.

Spool File Access

Select an entry from the drop down list to set the level of user access to view IBM i Spool files via LANSA for the Web.

Possible Spool File Access selections are:

  • No - Spool file access is not allowed for this system
  • Default User - Spool file access is allowed and the user access will be as per the user profile associated with the default user. The default user will be the LANSA for the Web registered user of DFTPRT. If DFTPRT is not a LANSA for the Web registered user, DFTUSR will be used. The IBM i user profile associated with the default user will determine access rights to view spool file data. Refer to 1.4.2 User Registration for details of setting up default users.
  • User Authentication - Spool file access is allowed and the user is required to provide authentication. This requires that the Web Server must be set up to require user authentication and that those users you wish to have access must be set up in the Web Server. The Web Server will not permit you to progress any further unless you provide a valid user profile. If a valid user profile is provided, the LANSA for the Web spool file features are available.
  • When a user logs on to LANSA for the Web, it determines 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 IBM i user profile is used to determine access rights to spool file data. If the Web Server user profile is not registered with LANSA for the Web, the access to spool file data will be determined in the same way as for Default User access.

Secured Sockets Layer (SSL) 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.

Send specified HTTP Header Variable values to the host

Select this option if you want to send the values for the specified HTTP Header Variables to the host, i.e. the Data/Application Server. To specify the HTTP Header Variables to be sent, select the Tools menu and choose the HTTP Header Variables command.

For information about HTTP Header Variables, refer to HTTP Header Variables (Connected to IBM i Web Server) .

Ý Maintain Systems (Connected to host)


Remote (IBM i only)

Use Remote System

If the system you are configuring is for multi-tier deployment, select Use Remote System. The related fields are enabled when this option is selected.

System Name

Specify the name of the IBM i that is acting as your Application/Data Server.

Comms type

The communications protocol can be either TCP/IP or APPC.

User ID and Password

Specify a user profile and its password. A user profile is required to allocate a communications conversation between the Web Serving IBM i and the Application/Data Serving IBM i.

Note: The user profile specified must exist on the Application/Data Serving IBM i and must have sufficient authority to start jobs.

Ý Maintain Systems (Connected to host)


Web Server (IBM i only)

Use this page to configure the Web Server for the port.

Host and Client CCSID

If you are using IBM's HTTP Server for i5/OS as your Web Server, you will need to provide the host and client CCSIDs. These CCSIDs are used for data translation purposes.

Default Technology Service

The technology service to use if no specific technology service is nominated in the user agent request.

Ý Maintain Systems (Connected to host)


Hold System (IBM i only)

If you wish to place the LANSA system on hold, select the Hold System option. A user cannot access a LANSA system that is held.

Hold Message

Enter a message to display when the system is held.

If you are not using an IBM i as the host, you will enter the equivalent data in the Maintain Systems (local) menu item of this Administrator.

Ý Maintain Systems (Connected to host)


HTTP Header Variables (Connected to IBM i Web Server)

For use with:
• IBM i CGI Interface

Each request by a browser to the Web Server sends a set of HTTP Header Variables to the Web Server. HTTP Header Variable support in LANSA for the Web allows you to forward the content of these HTTP Header Variables to the Data/Application Server in the form of function parameters (FUNCPARMS).

If the Send specified HTTP Header Variable values to the host option is selected, the HTTP Header Variables are sent to the Data/Application Server for each incoming request. This option must be enabled for each system. It should only be used if you really want to have access to the content of the specified HTTP Header Variables within your Web Application. The Send specified HTTP Header Variable values to the host option is on the General page of the General (IBM i only) which you can reach by selecting the Tools menu and choosing Maintain Systems, select the system you want to enable, press Add/Change and select Send specified HTTP Header Variable values to the host on dialog Add/Change LANSA System tab General.

If an HTTP request received by the Web Server does not contain the HTTP Header Variable you specified, then the Default Value specified together with the HTTP Header Variable will be sent to the Data/Application Server instead.

To specify HTTP Header Variables, select the Tools menu and choose the HTTP Header Variables command. The HTTP Header Variables dialog box is displayed. You must be signed on as QSECOFR or the partition security officer to use this command.

The HTTP Header Variables dialog box displays a list of HTTP Header Variables already configured for LANSA for the Web.

Add... or Change...

When you select the Add or Change button, the relevant Add or Change HTTP Header Variable dialog box is opened.

Refer to Add/Change HTTP Header Variable (IBM i only) .

Ý 1.5 Tools Menu (All platforms)


Add/Change HTTP Header Variable (IBM i only)

The Add/Change HTTP Header Variable dialog box displays the details to be used with the HTTP Header Variable and allows you to specify the Default Value for the HTTP Header Variable and how the content of the HTTP Header Variable will be sent to the Data/Application Server (Function Parameter).

Web Server - Name

Name of the Web Server that will forward the content of the HTTP Header Variables received from the requesting browser.

If you are not using multi-homing support, choose Any as your Web Server Name.

If you are using multi-homing support, enter either the DNS Name (for example: sydaspect.lansa.com) or the DNS's IP Address (for example: 124.54.56.21) in the System Name field.

Web Server - Port

Port number of the Web Server that will forward the content of the HTTP Header Variables received from the requesting browser.

If you are not using multi-homing support, choose Any as your Web Server Port.

If you are using multi-homing support, enter the port number associated with the Web Server Name.

Name

Name of the HTTP Header Variable for which you want to forward the content. This name will be used as the key to locate the HTTP Header Variable received as part of a browser request. Note that this name might depend on the HTTP Server you are running.

Default Value

The Default value to be sent to the Data/Application Server if the HTTP Header Variable specified cannot be located in the incoming browser request.

Function Parameter

The function parameter defines the LANSA field used on the Data/Application Server to receive the content of the HTTP Header Variable. Note that the field definitions you specify, field name (Field), Type, Length and number of decimals (Dec.) must match the repository information for the field.

The number of function parameters in total is restricted to a maximum of 20 function parameters. This includes those that you might be using as part of your Web Application.

Ý HTTP Header Variables (Connected to IBM i Web Server)


Clean Up Systems

You would normally include the LANSA for the Web CleanUp programs as part of your end of day routine. However, to request an immediate cleanup, select the Tools menu and choose Clean Up Systems. From the sub menu, select Clean Up Data/Application Server or Clean Up Web Server (Connected to IBM i Web Server), as appropriate.

This command is only available if you are signed on as QSECOFR or the partition security officer.

If your host is an IBM i:

and

there is no separate IBM i as a Web Server, then only Clean Up Data/Application Server will be available for selection.

If your host is an IBM i:

and

the Web Server system is on a different IBM i to the Data/Application Server, then you will need to connect to the relevant IBM i and select the appropriate sub menu:

Clean Up Data/Application Server

or

Clean Up Web Server (Connected to IBM i Web Server).

If your host is not a IBM i (host type of Other):

then you will have only one LANSA system to clean up. As soon as you select this command, a confirmation message is displayed showing the job you are about to submit. Press Cancel if you do not wish to continue.

Ý 1.5 Tools Menu (All platforms)


Clean Up Data/Application Server

This command is only available if you are signed on as QSECOFR or the partition security officer.

Select the system you want to clean up and press the Clean Up button. A confirmation message is displayed showing the job you are about to submit. Press Cancel if you do not wish to continue.

Ý Clean Up Systems


Clean Up Web Server (Connected to IBM i Web Server)

This command is only available if you are signed on as QSECOFR or the partition security officer.

A confirmation message is displayed showing the job about to be submitted. Press Cancel if you do not wish to continue.

This option is not necessary if you are connected to host type Other.

Ý Clean Up Systems


Clean Up Event Logging (Connected to host only)

To clean up the Event Logging files enter the date in the pop-up window in the format YYYYMMDD. Where YYYY is the four-digit year, MM is the two-digit month, and DD is the two-digit day.

Last page date

Enter the date in the format shown on the dialog box. All Event Logging records created on or before the date entered will be deleted.

Ý 1.5.2 Configure System (Connected to host)


1.5.4 Tools Menu (Local Configuration)

Tools menu with a local configuration:

  • Web Server (Local Configuration)
  • General (Local Configuration)
  • Maintain Systems (Local Configuration)
  • Web Server (Local Configuration only)
  • Data/Application Server (Local Configuration only)
  • Advanced (Local Configuration only)
  • Hold System (Local Configuration)
  • Reusable Sessions (Local Configuration)
  • Legacy (Local Configuration)
  • HTTP Header Variables (Local Configuration)
  • Alias Definitions (Local Configuration, IIS Plug-In only)
  • CSS Filters (Local Configuration, IIS Plug-In only)


Web Server (Local Configuration)

Web Server configuration parameters defined in this section (to be saved/updated in a configuration file) are used by the Web Server running the IIS Plug-in, that is, their settings will impact on all connections to the Data/Application server and on all functionality of the LANSA for the Web IIS Plug-in.

Ý 1.5.2 Configure System (Connected to host)


General (Local Configuration)

Home Page

Enter the URL to be called when the user selects the 'Home' button in LANSA functions.

By default, this parameter is set to '/' pointing to the default home page of the Web Server.

Post Data Size Limit

Use this option to limit the amount of posted data to be accepted by the Web Server. HTTP POST requests with posted data exceeding the limit will be rejected.

You can enter the limit either as a number of bytes or a number suffixed with one of the following units: KB (1,000 bytes), KiB (2^10 = 1024 bytes),MB (1,000,000 bytes) or MiB (2^20 = 1048576 bytes).

Explicitly discard excess data when over size limit

Enabling this option will send error pages for rejected requests to the browser once all posted data has been received. This will make sure the browser receives the error pages properly but it does impose overheads to deal with the excessive volume of posted data.

Not enabling this option will send error pages for rejected requests to the browser as soon as the data size limit has been reached.

For normal operations, it is recommended that you do not to enable this option.

Development Support

Selecting this option will enable you to run the IIS Plug-in in Development Support mode. This is not recommended for the Production Web Server. If enabled, it exposes internal settings, which can compromise security.

The WAM Editor in the LANSA Development Environment can rely on this setting being enabled to retrieve the name of the physical folder of the virtual folder used for images. This is then used by the WAM Editor to browse for images on the Web Server. If the WAM Editor is unable to retrieve the name of the physical folder, browsing for images might result in unexpected behavior.

By default, this parameter is set to disable.

Ý Web Server (Local Configuration)


Trace (Local Configuration)

Enable Tracing

Selecting this option will enable you to enter the Trace Options. If Enable Trace is not selected then tracing will be switched off.

By default, tracing is switched off. Before you switch tracing on please be aware of the impact tracing will have on your system (see WARNING on dialog).

Trace File

Enter the full file name, including path information, of the trace file. IIS Plug-in will append any new message to the trace file if the file already exists. To create a completely new trace file, you may need to delete/rename the existing trace file or use a different trace file name.

The default setting is %TEMP%\lansaweb.log where %TEMP% is your system temporary directory.

Notes
  • You may need to grant sufficient rights to "Everyone" (that is, a standard user group on Windows) for all the underlying directories of the trace file. Otherwise, the trace file may not be able to be created/updated. Alternatively, if you know what NT logon (normally IUSR_<machinename>) is used by IIS to run the IIS Plug-in, you may grant rights to that account only.
  • IIS Plug-in will always generate a few messages when IIS Plug-in is being started or stopped and in case of a serious problem even tracing is turned off by the option above. So it is expected that a trace file is always created when IIS Plug-in is running. To stop the trace file from being created, you may simply use "NUL" as the trace file name.

Other Trace options

Use the other options to select the areas you want to trace.

Ý Web Server (Local Configuration)


Reusable Sessions (Local Configuration) (For IIS Plug-in Only)

For Visual LANSA, a pool of currently running LANSA Open sessions is used to route data back and forth between the web server (using the IIS Plug-in) and the LANSA system. During normal operation, a LANSA Open session can complete each web request (after sending a complete generated html page to the web server) in a short period of time and will immediately be ready for the next web request. So, the number of running LANSA Open sessions is usually much smaller than the total number of users concurrently accessing the web server and the LANSA system.

Under very busy conditions, there can be many simultaneous web requests, which all need to be processed. In this case, the number of currently running LANSA Open sessions may not be enough to serve all requests so the system will start more LANSA Open sessions to satisfy the requirement. However, because of the process and resources (a special kind of system heap memory in particular) management of Windows, there is a limit to the total number (see section for Windows Desktop Heap Management) of LANSA Open sessions and other LANSA system programs, e.g. W3_P1200.EXE, which can be run simultaneously. If the limit is reached, serious problems may occur, e.g. system may hang and not respond to any further web requests. In order to prevent such a potential problem, the IIS Plug-in can limit the number of running LANSA Open sessions by not immediately submitting further web requests so no more LANSA Open sessions will be started when all the running LANSA Open sessions are busy serving other requests. All excess web requests will be placed in a queue maintained by the IIS Plug-in and will be processed when one or more of the running LANSA Open sessions are ready to process a new web request. Eventually, all web requests will be processed but they may appear to need more time to be processed than in a normal situation.

The following configuration options are used to enable the IIS Plug-in to limit the number of running LANSA Open sessions.

For fine-tuning a LANSA system, which may run under very busy conditions (even occasionally), you may also need to change those parameters for Windows Desktop Heap Management. Please refer to the corresponding section for further information.

Max Reusable Sessions:

Enter the maximum number of reusable sessions. Acceptable range of values is from 0 to 9999. A value of 0 means using the current default of 100 reusable sessions.

The default value is 0.

Keep Alive Sessions:

Enter the maximum number of idle sessions. Acceptable range of values is from 0 to the value of Max Reusable Sessions. A value of 0 means that all reusable sessions are kept alive.

The default value is 0.

In case of the value is set to value other than 0, when the system becomes relatively idle, any excessive sessions over this limit will be closed gradually in about 30 minutes.

Connection Check:

Choose the number of checks to be performed to detect a dead session. The higher value, the longer possible delay for each Web request. It is therefore recommended that you use a lower value, if possible.

To detect a dead session against an IBM i backend, a higher value may be required. For Windows or Linux backends, once is normally enough.

The default value is once.

Default:

Will change the settings to reflect their defaults.

Windows Failsafe:

Will change the settings to reflect their defaults, except for Max Connections, which is set to 10. Note that this setting is intended for a Windows system only.

Ý Web Server (Local Configuration)


Maintain Systems (Local Configuration)

This command allows you to define multiple systems and ports for your local configuration.

When you select the Maintain Systems command from the Tools menu, the Maintain Systems (local) dialog box is displayed.

The Maintain Systems (local) dialog box displays a list of LANSA systems already configured for LANSA for the Web. LANSA for the Web uses the Web Server Name and Port identifier on the URL to determine which LANSA system (connection to Data/Application Server) should be used to handle the request.

Add... or Change...

When you select the Add or Change button, the relevant Add or Change LANSA System dialog box is opened. This dialog contains these Tabs:

  • Web Server (Local Configuration only)
  • Data/Application Server (Local Configuration only)
  • Advanced (Local Configuration only)
  • Hold System (Local Configuration)
  • Reusable Sessions (Local Configuration)
  • Legacy (Local Configuration)

Ý 1.5 Tools Menu (All platforms)


Web Server (Local Configuration only)

When you select the Add or Change button on the Maintain Systems dialog box, the Add or Change LANSA System (as appropriate) is displayed. Add or change the Web Server options as required.

Web Server - Name

Name of the Web Server that will forward the content of the HTTP Header Variables received from the requesting browser.

If you are not using multi-homing support, choose Any as your Web Server Name.

If you are using multi-homing support, enter either the DNS Name (for example: sydaspect.lansa.com) or the DNS's IP Address (for example: 124.54.56.21) in the System Name field.

Web Server - Port

Port number of the Web Server that will forward the content of the HTTP Header Variables received from the requesting browser.

If you are not using multi-homing support, choose Any as your Web Server Port.

If you are using multi-homing support, enter the port number associated with the Web Server Name.

The Web Server Name together with the Port number is then used as the key to locate the connection parameters for the Data/Application Server that will handle the request.

Default Technology Service

The technology service to use if no specific technology service is nominated in the user agent request.

Server Side Includes (SSI)

This group of options can only be used with a Data/Application Server running LANSA Version 11 SP5 or later.

Parsing and Processing

Select Always Done to indicate that SSI Parsing and Processing is always to be done. Select Controlled by Data/Application Server to indicate that the Data/Application Server determines if SSI Parsing and Processing is to be done.

There is a time overhead if you select Always Done, so think carefully before you choose this option.

For WAMs, select Always Done.

Default is Controlled by the Data/Application Server.

Allow Files to be Retrieved from Data/Application Server

If this option is selected, an SSI #include file instruction (for example, <!--#include file="/some/file"-->) included in a web page will be replaced with the requested file if it can be found.

If the attempt fails (because this option is not enabled on the Data/Application Server or the requested file does not exist), the IIS Plug-in/Apache Module will look for local files on the Web Server to replace the SSI #include file instruction unless the Use Files from Data/Application Server Only is selected.

Default is not selected.

Use Files from Data/Application Server Only

If you select this option, only files found on the data/application server will replace an SSI #include file request.

Default is Not Selected.

Note that you must also set the corresponding Data/Application options. The corresponding File Serving options are set in the Data/Application Server's Miscellaneous tab.

Transform XSLT on Web Server

Select this option if you wish to perform all WAM XSLT Transformations on the Web Server, instead of the Application Server. By default, this option is ON to distribute the WAM processing load between the Web Server and the Application Server so that the Data/Application Server executes the LANSA webroutine and the Web Server transforms XSLT.

Ý Maintain Systems (Local Configuration)


Data/Application Server (Local Configuration only)

When you select the Add or Change button on the Maintain Systems dialog box, the Add or Change LANSA System (as appropriate) is displayed. Add or change the Data/Application Server options as required.

LANSA System

Enter the name of the host that is acting as your Data/Application Server. This name must be known to the LANSA Communications Extensions. You must not leave this parameter blank.

Kerberos

This setting indicates that the connection to the server will be made using Kerberos. This means that the user's Windows profile and password is used to sign on to the server. The server must have been configured for Single Sign On, and the user enrolled, before this can be done.

User, Password and Confirm Password

Specify a user profile and its password. A user profile is required to allocate a communications conversation between the Web Server and the Data/Application Server. Confirm password must match the password.

Note: The user profile specified must exist on the Data/Application Server and must have sufficient authority. If the Data/Application Server uses a trusted connection to connect the database, the user profile (by default it is usually PCXUSER) must have sufficient authority to access the database.

Test Connection

Use Test Connection to try to establish a communication connection with the Data/Application Server with the user profile and system specified.

LANSA Library (IBM i only)

Enter the name of the LANSA Library.

The LANSA Library is required when you connect to a Data/Application Server on IBM i.

Code Page (IBM i only)

Enter the parameter to specify the Code Page translations to be applied for communications between the Web Server and the Data/Application Server.

For LANSA for the Web IIS Plug-In configurations:

if left blank, no code page translations will be performed.

otherwise:

the value specified defines the name of the LANSA Code Page mapping table. This Code Page mapping table must be located in the LANSA for the Web IIS Plug-In code page directory (by default c:\Program Files\LANSA\WebServer\IISPlugin\codepage).

  • For a deployment with a Windows host, leave this field blank.
  • For a deployment with an IBM i host, enter the name of the relevant EBCDIC translation table shipped.
  • If you wish to use your own customized code page files you need to add them to the code page directory. Note that if the specified file cannot be found, a file with the same name but prefixed with wpi_ will be used. This is to ensure backward compatibility. For example, if you enter cp037, the IIS Plug-in will look for cp037.dat in the code page directory and if that file is not found it will then look for wpi_cp037.dat in the code page directory.

    • Partition

    Specify the partition if you want to have all the requests for this Web Server/Port to use a particular LANSA partition or if you want to use a default partition. If no partition is specified, you must specify the partition parameter in your URL.

    Always use this partition

    If this option is selected, the specified partition will override any partition specified in the URL.

    If this option is not selected, the specified partition will be used as a default partition if none is specified in the URL.

    Ý Maintain Systems (Local Configuration)


Advanced (Local Configuration only)

When you select the Add or Change button on the Maintain Systems dialog box, the Add or Change LANSA System dialog box (as appropriate) is displayed. Add or change the Advanced options as required.

Spool File Access

Select an entry from the drop down list to set the level of user access to view IBM i Spool files via LANSA for the Web. This setting will only be relevant if you connect to an IBM i Data/Application Server and retrieve HTML.

Possible Spool File Access selections are:

  • No - Spool file access is not allowed for this system
  • Default User - Spool file access is allowed and the user access will be as per the user profile associated with the default user. The default user will be the LANSA for the Web registered user of DFTPRT. If DFTPRT is not a LANSA for the Web registered user, DFTUSR will be used. The IBM i user profile associated with the default user will determine access rights to view spool file data. Refer to 1.4.2 User Registration for details of setting up default users.
  • User Authentication - Spool file access is allowed and the user is required to provide authentication. This requires that the Web Server must be set up to require user authentication and that those users you wish to have access must be set up in the Web Server. The Web Server will not permit you to progress any further unless you provide a valid user profile. If a valid user profile is provided, the LANSA for the Web spool file features are available.
  • When a user logs on to LANSA for the Web, it determines 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 IBM i user profile is used to determine access rights to spool file data. If the Web Server user profile is not registered with LANSA for the Web, the access to spool file data will be determined in the same way as for Default User access.

Refer to LANSA for the Web Spool File Facility in the LANSA for the Web Guide to find out how to view spool files.

Enable File Fetch Request

Enable File Fetch Request to allow the IIS Plug-in or Apache Module for Linux to handle URLs like

http://server/cgi-bin/lansaweb?fetch=/some/file

to retrieve files from the Data/Application Server. If this option is disabled, any such request returns HTTP error code 404 (File Not Found). If this option is enabled and the corresponding option on the Data/Application Server is disabled or if the requested file path does not exist in the file fetch directory, HTTP error code 404 (File Not Found) is returned.

By default this option is disabled.

Expired Generated Page Immediately

If this option is checked, the following additional HTTP header will be added to every web response produced by the Web Plug-in.

Expires: {time}

The expire time can be set to either the time when the web response is generated by the Data/Application Server or specified seconds before/after the generation time.

This HTTP header is used to expire the generated page at the specified time.

See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.21 for more information.

Default is not selected.

Prevent Generated Page From Being Cached

If this option is checked, the following additional HTTP header will be added to every web response produced by the Web Plug-in.

Pragma: no-cache

This HTTP header is used to control caching behavior of web browsers and proxies.

See http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.32 for more information.

Default is not selected.

Business Objects Support

Enable support for Business Object. Not yet documented.

HTTP POST Request Guard

You can either use the settings defined at the Web Server level or you can override those settings for this

LANSA System. See Post Data Size Limit in General (Local Configuration) for information.

Ý Maintain Systems (Local Configuration)


Hold System (Local Configuration)

If you wish to place the LANSA system on hold, select the Hold System option. A user is not able to access a LANSA system that is held.

Hold System

Select this option to stop users accessing the Data/Application Server.

If Hold System is selected the message defined in Hold Message will be displayed.

Hold Message

Enter a message to display when the system is held.

Ý Maintain Systems (Local Configuration)


Reusable Sessions (Local Configuration)

When you select the Add or Change button on the Maintain Systems dialog box, the Add or Change LANSA System (as appropriate) is displayed. Add or change the Reusable Sessions options as required.

Override System Default

By default, the settings from the Web Server's Reusable Sessions (Local Configuration) (For IIS Plug-in Only) are used for all LANSA systems. If you wish to have specific settings for this LANSA system, select this option and change the appropriate settings. For more information on these settings, please refer to the Web Server's Reusable Sessions (Local Configuration) (For IIS Plug-in Only).

Ý Maintain Systems (Local Configuration)


Legacy (Local Configuration)

If you need to configure the LANSA for the Web plug-in to communicate with a pre V13 Data/Application server you might need to fill in these details.

Code Page

Enter the parameter to specify the Code Page translations to be applied for communications between the Web Server and the Data/Application Server.

For LANSA for the Web IIS Plug-In configurations:

if left blank, no code page translations will be performed.

otherwise:

the value specified defines the name of the LANSA Code Page mapping table. This Code Page mapping table must be located in the LANSA for the Web IIS Plug-In code page directory (by default c:\Program Files\LANSA\WebServer\IISPlugin\codepage).

  • For a deployment with a Windows host, leave this field blank.
  • For a deployment with an IBM i host, enter the name of the relevant EBCDIC translation table shipped.

If you wish to use your own customized code page files you need to add them to the code page directory. Note that if the specified file cannot be found a file with the same name but prefixed with wpi_ will be used. This is to ensure backwards compatibility. If you for example enter cp037 the IIS Plug-in will look for cp037.dat in the code page directory and if that file is not found it will look for wpi_cp037.dat in the code page directory.

Web Server Character Set

Specify the IANA character set to be used for the following operations:

  • Transform XSLT on Web Server
  • Transform XSLT on Data/Application Server which is not IBM i

For example, to generate UTF-8 web responses for these operations, select Custom and set the character set to "utf-8".

Default is the "Web Server Default" option.


HTTP Header Variables (Local Configuration)

For use with:

  • Windows using IIS Plug-in

Each request by a browser to the Web Server sends a set of HTTP Header Variables to the Web Server. HTTP Header Variable support in LANSA for the Web allows you to forward the content of these HTTP Header Variables to the Data/Application Server in the form of function parameters (FUNCPARMS).

If you specify HTTP Header Variables, then these HTTP Header Variables are sent to the Data/Application Server for each incoming request. You should only define Http Header Variables if you really want access to the content of the specified HTTP Header Variables within your Web Application.

If an HTTP request received by the Web Server does not contain the HTTP Header Variable you specified, then the Default Value specified together with the HTTP Header Variable will be sent to the Data/Application Server instead.

To specify HTTP Header Variables, select the Tools menu and choose the HTTP Header Variables command. The HTTP Header Variables dialog box is displayed.

The HTTP Header Variables dialog box displays a list of HTTP Header Variables already configured for LANSA for the Web.

Add... or Change...

When you14 select the Add or Change button, the relevant Add or Change HTTP Header Variable dialog box is opened.

Refer to Add/Change HTTP Header Variable (IBM i only) .

Ý 1.5 Tools Menu (All platforms)


Add/Change HTTP Header Variable (Local configuration)

The Add/Change HTTP Header Variable dialog box displays the details to be used with the HTTP Header Variable. It allows you to specify the Default Value for the HTTP Header Variable and how the content of the HTTP Header Variable will be sent to the Data/Application Server (Function Parameter).

Web Server – Name and Port

For a new Http Header Variable, from the drop down list, select the Web Server Name and Port that will forward the content of the HTTP Header Variables received from the requesting browser.

When you modify an existing Http Header Variable, the Web Server Name and the related Port are displayed in read only mode.

Name

Name of the HTTP Header Variable for which you want to forward the content. This name will be used as the key to locate the HTTP Header Variable received as part of a browser request. Note that this name might depend on the HTTP Server you are running.

Default Value

The Default value to be sent to the Data/Application Server if the HTTP Header Variable specified cannot be located in the incoming browser request.

Function Parameter

The function parameter defines the LANSA field used on the Data/Application Server to receive the content of the HTTP Header Variable. Note that the field definitions you specify, field name (Field), Type, Length and number of decimals (Dec.) must match the repository information for the field.

The number of function parameters is restricted to a maximum of 20. This includes those that you might be using as part of your Web Application.

Ý HTTP Header Variables (Local Configuration)


Alias Definitions (Local Configuration, IIS Plug-In only)

This command allows you to define the mapping between the Alias used as part of the URL and the Virtual directory used by the LANSA for the Web IIS Plug-In.

When you select the Alias Definition command from the Tools menu, the Alias Definitions dialog box is displayed.

The Alias Definitions dialog box displays a list of alias definitions.

Add... or Change...

When you select the Add or Change button, the Configure Alias Definition dialog box is opened. Refer to Configure Alias Definition (Local Configuration, IIS Plug-In only).

Ý 1.5 Tools Menu (All platforms)


Configure Alias Definition (Local Configuration, IIS Plug-In only)

Alias / Virtual Directory

Enter the values for the Alias and the related Virtual Directory, if any.

Ý Alias Definitions (Local Configuration, IIS Plug-In only)


CSS Filters (Local Configuration, IIS Plug-In only)

This command allows you to define which CSS (Cascading Style Sheet) files will have their @import statements resolved by the LANSA for the Web IIS Plug-In. This is useful when designing WAMs in the WAM Editor. Adding the CSS Path in this dialog will resolve all CSS files under that CSS Path. Note that CSS files will only be resolved in the WAM Editor when working in the Design mode.

Under some circumstances, such as after applying Microsoft's Internet Explorer security patch 916281, the styles that are imported using an @import directive are lost in the WAM Editor's Design view. Using the ?expand=yes option addresses this issue.

By default, the /images/style CSS Path will be used by the LANSA for the Web IIS Plug-In. This is the default location of LANSA's CSS files. If you add more CSS Paths, note that /images/style will no longer be used unless it is also listed.

There are some important limitations:

  • It is assumed that all CSS files involved, both the top level and all referenced via @import, are in encoding ASCII or ISO8859-1.
  • Only @imports at the beginning of the CSS file are resolved, as per the CSS standard.
  • Only local CSS files are imported. For example http://webserver/images/style/mystyle.css is not imported, but /images/style/mystyle.css is.

When you select the CSS Filter command from the Tools menu, the CSS Filters dialog box is displayed.

The CSS Filters dialog box displays a list of CSS Filters.

Add... or Change...

When you select the Add or Change buttons, the Configure CSS Filter dialog box is opened. Refer to Configure CSS Filter (Local Configuration, IIS Plug-In only).

Ý 1.5 Tools Menu (All platforms)


Configure CSS Filter (Local Configuration, IIS Plug-In only)

CSS Path & Virtual Directory

Enter the values for the CSS Path and the related Virtual Directory, if any.

Ý CSS Filters (Local Configuration, IIS Plug-In only)


1.6 Help Menu

The Help menu includes the following options:

1.6.1 Contents

1.6.2 About


1.6.1 Contents

Help is available from any dialog or menu item when you press the F1 key. This is context help, where the help displayed is just for the item with the focus. From there, you can open the full help file by pressing the blue book [image] icon at the top of the Help page.

You can also open the full help file by selecting the Content command from the Help menu.

From the full LANSA for the Web Administrator's help you can find a topic of interest by using the:

  • Search features, such as simple or boolean search, search on headings or text, and so on, in the Search tab
  • Contents list.

Ý 1.6 Help Menu


1.6.2 About

Use this command to obtain the version number of this version of the LANSA for the Web's Administrator.

Ý 1.6 Help Menu


2. Configuration Tasks

Following is some general and housekeeping information for application development and maintenance with LANSA for the Web Applications:

  • 2.1 HTTP Header Variables
  • 2.2 Security Considerations
  • 2.3 Storing Application Images
  • 2.4 Pre-Start Ready to Use IBM i Web Jobs


2.1 HTTP Header Variables

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 (FUNCPARMS) to the Web application.

HTTP Header Variable support is enabled on a per system basis using the LANSA for the Web Administrator. The HTTP Header Variables for which you want to retrieve the values are specified via the LANSA for the Web Administrator as described in HTTP Header Variables. The Header Variables that you specify and their corresponding default values are stored in the Configuration file L4W3Serv.cfg.

Function parameters used as part of the URL take priority over the function parameters used to pass on the values for HTTP Header Variables.

There is a maximum limit of twenty function parameters that may be passed on to the Web application per URL requested.

How HTTP Header Variables work

1. The Configuration file (L4W3Serv.cfg) is loaded during the first time the LANSA for the Web IIS Plug-in or Java Servlet is started. During this load, the values of the HTTP Header Variables will be sent to the host LANSA system.
If you are using the Java Servlet, the Configuration is re-loaded the first time the Java Servlet is called after LANSAWebReset.

2. If there are no HTTP Header Variables specified, no additional information will be sent to the host LANSA system.

3. If there are HTTP Header Variables specified for the related system, then for each URL requested by the Browser, the IIS Plug-in or the Java Servlet will retrieve the specified HTTP Header Variable value(s) and send them as FUNCPARMS to the host LANSA system.

4. If the URL already contains other FUNCPARMS, then the HTTP Header Variable related FUNCPARMS will be added at the end of the list.

5. If a value for a specified HTTP Header Variable cannot be retrieved, then the Default Value specified for the Variable will be sent instead.

Verifying that the HTTP Header Variables are sent

To verify that HTTP Header Variables are sent, test using the User-Agent Header Variable. The HTTP Header Variable field should reflect the agent that is used. Otherwise this field will contain the default value.

Tips and Techniques

  • Values of header variables that are longer than the length specified by funcpar will be truncated.
  • If the value for a Header Variable cannot be retrieved, the default value will be sent.
  • The number following _HTTP must be in the range of 1-20 (definitions with numbers outside of this range will not be processed).
  • The values for the HTTP Header Variables will be received in UPPERCASE.
  • The default value must be specified (at least one space must be entered between the separators).
  • The function must be set to *ALL (future releases may make use of this).


2.2 Security Considerations

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.
  • 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 decide not to use the anonymous user access option, refer to the security information in the Installing LANSA on IBM i Guide.
  • 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 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. Partial or process level authentication is not available for WAMs.
  • You may choose to implement the full user authentication model. 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.

Also see

2.2.1 Web and IBM i User Profiles

Task: Configure LANSA for the Web Security in the Installing LANSA on IBM i Guide.


2.2.1 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 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.


2.3 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.


2.4 Pre-Start Ready to Use IBM i Web Jobs

LANSA for the Web starts a job on the Data/Application Server for each LANSA request. 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.

To counter this delay, you can pre-start a defined number of LANSA for the Web jobs. These pre-started jobs form a pool of Web jobs that are then ready to use 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 reassigns the job 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.

Also see

Transaction Monitor

2.4.1 Pre-start the IBM i Transaction Monitor


2.4.1 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 could mean that the first LANSA request will have a performance impact since there are no pre-started jobs available to handle this initial request.

To overcome this problem, simply 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.


3. Maintenance Tasks

Web Clean ups

  • 3.1 Running out of WEB seat licenses
  • 3.2 WAM Session Clean Up
  • 3.3 IBM i Clean Up
  • 3.4 Windows Web Jobs and Clean Up
  • 3.5 Hold/Release LANSA for the WEB Systems


3.1 Running out of WEB seat licenses

If a Web Job crashes when using seated Web licenses, for example W05, the license will not be released. After all licenses have been used up in this manner, no other Web Jobs can be started. To "refresh" the system:

1. Run Clean Up Systems from the Web Administrator.

2. Restart the Listener.

If you wish, you can create a batch file to do these two steps in one go. Following is an example of such a batch file with the Name: resetw05lic.bat

@echo off
rem Change to the drive LANSA is installed on
C:
rem Change to Execute folder
cd C:\Program Files\LANSA\X_WIN95\X_LANSA\Execute
echo Perform Clean Up Systems
w3_p2200
rem Change to Connect folder
cd C:\Program Files\LANSA\Connect
echo Restart the Listener
lcolist -sstop
lcolist -sstart

Typically the locations of

w3_p2200.exe is C:\Program Files\LANSA\X_WIN95\X_LANSA\Execute.

lcolist.exe is C:\Program Files\LANSA\Connect

  • If your installation is different to the typical installation, please update the batch file example accordingly.


3.2 WAM Session Clean Up

Following are some considerations if you are using WAM Session Management:

  • All WAM sessions are created and managed in a database with any session state that is maintained by the session. For more information refer to WAM Session Management in the WAM Guide.
  • The session timeout determines if a session in the database is invalid or active. All invalid sessions are subject to session clean up performed by the Clean Up Program. The default setting is to clean up invalid sessions every 60 minutes. You can change this default via the Web Administrator by setting Cleanup (minutes) time on the WAM Components page of the Web Administrator.
  • It is also possible to disable this periodic clean up and instead perform clean up at scheduled times. This may be desirable, because high volume WAM Applications may create a lot of sessions at peak times. In these cases, it may be preferable to perform the clean up at off-peak times, at midnight for example, to avoid adding load to the database that may occur during clean up. To do this you should disable the automatic periodic clean up by setting to 0 (zero) the Cleanup(minutes) in the WAM Components page of the Web Administrator. You can then schedule the Clean Up Program to run with the argument "*WAMONLY", which will perform immediate session clean up and terminate.
    On Windows, the Clean Up Program command line is:

w3_p2200 *WAMONLY

and on IBM i, the command is:

CALL PGM(W3@P2200) PARM('*WAMONLY')

  • If you want to clean up all WAM session data (both expired and non-expired session data) run the Clean Up Program with the argument "*WAMCLEAR".
    On Windows, the Clean Up Program command line is:

w3_p2200 *WAMCLEAR

and on IBM i, the command is:

CALL PGM(W3@P2200) PARM('*WAMCLEAR')

  • You can use arguments *WAMONLY and *WAMCLEAR in the same Clean Up:
    On Windows, the Clean Up Program command line is:

w3_p2200 *WAMONLY *WAMCLEAR

and on IBM i, the command is:

CALL PGM(W3@P2200) PARM('*WAMONLY' '*WAMCLEAR')

Also see

3.3 IBM i Clean Up

3.4 Windows Web Jobs and Clean Up


3.3 IBM i Clean Up

The LANSA for the Web 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.


3.4 Windows Web Jobs and Clean Up

To halt all Web jobs and to clean up the system, do the following:

Step 1. Halt Web Jobs

1. On the Web Server, open Microsoft Management Console.

2. Select your Web site in the left hand pane (this will be the Default Web Site if you have followed the installation procedure in this document).

3. Right click the mouse and select the Stop option. Once stopped, any attempt to use the web site will respond with a 404 error and the request will never get to the Plug-in or Visual LANSA.

Step 2. Start Clean up

1. Open the LANSA for the Web Administrator.

2. Select the Tools menu, and choose the Clean Up Systems sub menu item.

3. All active Web jobs and their associated resources will have been cleaned up.


3.5 Hold/Release LANSA for the WEB Systems

To prevent users accessing a LANSA for the Web system, you can place the system on "Hold". One on "Hold", the Web Administrator will allow IIS to continue to handle requests and pass them on to the Plug-in which displays the Hold message (that you have specified) as an HTML page. That is IIS is still serving the request passing it on to the Plug-in.

Normally you use the Hold System option in 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')

Also see

Hold System (IBM i only)

Hold System (Local Configuration)


4. Occasional Tasks

LANSA for the Web supports features that are common to both WAM or Web Function Applications. If you are using LANSA for the Web, you may wish to review the following:

In addition, you should be aware of the following LANSA features that may be beneficial when building Web applications:

4.1 Web-enable the Partition

4.2 Set up Users on Windows Data/Application Server

4.3 Locate IP Address of Data/Application Server

4.4 Set Up Listener on the Data/Application Server

4.5 Verify Listener is Active on the Data/Application Server


4.1 Web-enable the Partition

Start the Visual LANSA development environment.

Enter your User ID and Password, AND BEFORE YOU PRESS OK, select the Partition and click the Partition Initialization button.

If the partition is already enabled, the Enable LANSA for the Web option will be checked (that is, the check box will be coloured [image]). If this is the case, simply press Cancel.

If the partition is not Web enabled, click on the Enable LANSA for the Web option. A tick will be displayed in the check box. Press OK. The response will be a message for each language in the partition. When the process has finished successfully, you will be returned to the Login dialog.

If the Web enabling process fails, you will get a message that a number of imports have failed and the partition initialization dialog will be displayed again. Press the Show Last Log button for further information.

Ý 4. Occasional Tasks.


4.2 Set up Users on Windows Data/Application Server

A Windows User is needed to:

  • allow the LANSA for the Web Administrator to communicate with the Data/Application Server.
  • allow the LANSA IIS Plug-in on the Web Server to communicate with the Data/Application Server.

A Windows User is created for this purpose during the LANSA install process and it is added to the Windows LANSA Users group. In this documentation this user is referred to as PCXUSER.

Note: If a workstation belongs to a Windows domain and a Windows User exists on both the Domain and the Local (on the workstation), the Local User logon takes precedence. This is especially important as the User created during the install may conflict with the Domain User.

If you wish to create a different user for Web access, then you can do so in these steps:

  • Step 1. Create User for Default Web Access
  • Step 2. Add User to LANSA User group
  • Step 3. Register New User with Windows Server

Step 1. Create User for Default Web Access

If you use the Windows User that was created during the LANSA Install you do not need to perform this step.

Note: The following steps describe the Windows XP procedures. These may not be exactly the same in all versions of Windows.

1. From the Start menu, select Settings, then open the Control Panel folder.

2. From the Control Panel, select the Administrative Tools, then select Computer Management.

3. Select Local Users and Groups.

4. Right click on the Users folder and select New User... from the pop-up menu.

Enter these details in the New User dialog box:

User Name: Full Name: | e.g. WEBUSER (This must be a valid LANSA User. To be valid, it must be assigned to a LANSA task.)
Description | Web User Account for LANSA
Password: | e.g.password (Remember: passwords are case sensitive!)
Check (select) these options: | Password never expires and User cannot change password.

If you intend to use the trace facilities of the Listener, then you must give this Windows User Administrator rights temporarily, otherwise the Listener job may terminate with an exception in kernel32.dll.

Press Create to create the new User and then Close to return to Computer Management.

Step 2. Add User to LANSA User group

For each user you wish to use to connect to the Data/Application Server using the Web Administrator, you need to add that user to a LANSA User group. Every user in the group will have the permissions granted to the group.

To add a User to the LANSA Users group:

1. While still in Computer Management, select Local Users and Groups and then Groups.

2. Right click on LANSA Users and select Properties from the pop-up menu to open the LANSA Users Properties dialog.

3. In the LANSA Users Properties dialog, press the Add button to open the Select Users, Computers, or Groups dialog.

4. Choose the location of the new WEBUSER, then enters the name WEBUSER in the Enter the object names to select entry box.

5. Press OK and your new user will be added to the LANSA User Group dialog box.

6. Press OK and then exit Windows User Management.

Step 3. Register New User with Windows Server

From your Windows PC running the Administrator, connect to your Windows host and register your user.

1. Choose the Security menu and select the User Registration command.

The User Registration window is displayed.

To register a new user, you can press the Add button or you can right click on the Web User ID column and select Add from the pop-up menu displayed.

Ý 4. Occasional Tasks.


4.3 Locate IP Address of Data/Application Server

You will need to know the IP address of the Data/Application Server for the steps in this task. The IP address can be found using the ipconfig command in the Start/Run dialog box.

Ý 4. Occasional Tasks.


4.4 Set Up Listener on the Data/Application Server

A Windows service called the Listener (LCONNECT) provides the Data/Application Server's side of the TCP/IP link to the Web Server. The Listener must be set up before it can be linked to the Web Server.

In this task, you will start the Listener on the Windows Data/Application Server preferably using the Windows User created during the install.

If you are using an IBM i Data/Application Server, a default listener is configured on IBM i as part of the LANSA installation. For details, refer to LANSA for the Web Configuration and Set Up on IBM i in the Installing LANSA on IBM iGuide.

Step 1. Start the LANSA Communications Administrator

1. On the Windows Data/Application Server, start the LANSA Communications Administrator:

a. Open the LANSA folder from the Start menu.

b. Select the Settings and Administration folder.

c. Select LANSA Communications Administrator from the list and click it to start.

In the LANSA Communications Administrator, the Host Routes will be displayed:

2. Select the Advanced menu and choose the Listener command (or use Ctrl+I) to open the Listener Information dialog box.

If the Listener menu item item is not available, it means that it is not installed.
To install a listener, start a command prompt and run this command from the LANSA Connect directory (for example, <drive>:\Program Files\LANSA\Connect):

lcolist -i

Once this has been completed, select the Advanced menu again and choose the Listener command to open the Listener Information dialog box.

2. In the Listener Information dialog box:

a. Ensure that Socket is selected as the Communications Method.

b. Set Number of Threads to Listen on to 4.

3. Press the Start Listener button. The listener service will be started.

4. Press OK to update the Listener Information.

5. Exit from the LANSA Communications Administrator.

Step 2. Is Listener Service set to Start Automatically?

It is recommended that the listener is set to start up automatically.

The Server install sets automatic start-up by default. If you are not sure whether this default is in use, from the LANSA Connect directory (for example, <drive>:\Program Files\LANSA\Connect) start a command prompt and execute this command:

lcolist -iauto

-iauto will stop the listener and change the start mode to automatic, but it will not start the listener.

Start the listener again using this command:

lcolist -s

Ý 4. Occasional Tasks.


4.5 Verify Listener is Active on the Data/Application Server

IBM i Data/Application Server

From an OS/400 command entry (CALL QCMD), use the WRKACTJOB command to verify that the LANSA Listener subsystem is active.

If the subsystem is not active, start the subsystem.

If there are no jobs in the subsystem, then the Listener is not configured properly.

Windows Data/Application Server

From the Control Panel, Administrative Tools folder, use the Services icon to start the Microsoft Management Console to display the list of services.

If the listener (LCONNECT Services) is not started, use the right click context menu to start the service.


5. Interactive Debugging

The Visual LANSA Development Environment has extensive interactive debugging facilities to debug applications developed with various Visual LANSA Technologies including:

  • Visual LANSA Components
  • WAMs
  • LANSA SuperServer Functions
  • RDML Functions executable as batch jobs using X_RUN

Note: For IBM i, only RDMLX applications can be debugged using the Visual LANSA Editor. RDML applications can only be debugged using a IBM i display device (that is, the green screen).

Interactive debugging allows LANSA applications to be debugged at the RDML source code level. You can single-step through RDML commands, set breakpoints at individual RDML commands, and examine and change field values whenever execution is paused.

There are two modes of interactive debugging:

  • Local debugging
  • Remote debugging

From the setup point of view, there is no difference between local and remote debugging. The Visual LANSA Debug Service supports debugging in the Visual LANSA development environment for various scenarios.

Refer to Debug in the LANSA Settings in the Visual LANSA User Guide for more information about setting up the development environment for interactive debugging.

Local debugging

In local debugging mode, the LANSA application being developed is running alongside Visual LANSA on the same computer.

This is also the case even if the LANSA application being developed and the Visual LANSA for debugging belong to two different Visual LANSA installations on the same computer although that is not that a common scenario.

While Visual LANSA runs only on Windows, the LANSA application being developed must also be running on Windows in this mode.

Remote debugging

In remote debugging mode, the LANSA application being developed is running on a data/application server that is different to the computer where Visual LANSA is running.

If the LANSA application being developed is running on a non-Windows platform, this is the only debugging mode available.

Ý 5. Interactive Debugging


5.1 Additional Setup for Debugging Web Applications

To debug WAMs, the following additional set up is required for these configurations:

5.1.1 Data/Application Server (All Platforms)

5.1.2 Web Client (Internet Browser)


5.1.1 Data/Application Server (All Platforms)

You must enable debugging and extend the web job timeouts on the data/application server.

For security reasons, Web application debugging is disabled by default. It is strongly recommended that you disable debugging when it is no longer required, especially for production servers.

1. Enable debugging

To enable debugging, select the Allow Interactive Debugging option for the data/application server. To do this:

a. Start the Web Administrator.

b. Connect to the data/application server.

c. Select the Tools Menu.

d. Select the menu item Configure System.

e. Select the sub-menu item Data/Application Server.

f. Select the Miscellaneous tab in the Configure Data/Application Server dialog.

g. Check (tick) the Allow Interactive Debugging option (as shown below):

2. Extend the Web Job timeout for Web Functions

It is recommended that you extend the Web Job timeout, which is 2 minutes by default for Web Functions, so that the Transaction Monitor does not interfere with the Web Function running in debug mode.

If the Web Function running in debug mode uses browse lists, you may also need to extend the Web Function data timeout, which is 1 hour by default, so that the browse list data can be kept as long as required for the debug session.

To extend the Web Job timeouts, perform the following steps.

a. Start the Web Administrator.

b. Connect to the data/application server.

c. Select the Tools Menu.

d. Select the menu item Configure System.

e. Select the sub-menu item Data/Application Server.

f. Select the Web Functions tab in the Configure Data/Application Server dialog.

g. Change the timeouts to the desired values.

Refer to the dialog's Help for information about these settings.

Close the Web Administrator.

Ý 5.1 Additional Setup for Debugging Web Applications


5.1.2 Web Client (Internet Browser)

Extending Timeout

If you are using Internet Explorer, you may need to extend the timeout so that the page can still be displayed after a long debug session.

To extend the Internet Explorer time out:

Add or Change the Registry:

HKEY_CURRENT_USER
\Software\Microsoft\Windows\CurrentVersion
\Internet Settings\ReceiveTimeOut

The registry is a DWORD value and is specified in terms of milliseconds for the timeout, that is, a value of 3,600,000 means 3,600 seconds (1 hour).

If you are using another browser, please refer to the browser's documentation for instructions about changing similar settings.

Caution
Do not interact with the page shown on the browser while the underlying LANSA web application in debug mode is paused in the Visual LANSA Editor. If you do so, in most cases the application will behave incorrectly and system clean up may be required to return the application to normal.

Ý 5.1 Additional Setup for Debugging Web Applications


6. Multi-Tier Web System Set up

6.1 Overview

6.2 Before you Begin Checklist

On a Windows Data/Application Server:

1. 6.4 Task: Register User on the Data/Application Server

2. 6.3 Task: Define Data/Application Server Name

On an IBM i Data/Application Server, the above two tasks are completed as part of the LANSA for iSeries installation.

On the Web Server:

Complete the following tasks for either a Windows or IBM i Data/Application Server:

2. 6.5 Task: Configure IIS Plug-in Communications with Data/Application Server

On the Data/Application Server:

Complete the 6.6 Task: Test LANSA for the Web.

If you encounter any problems, refer to Troubleshooting .


6.1 Overview

A Multi-Tier installation involves the installation of LANSA software on a Windows Data/Application Server and a Windows Web Server.

A Mixed Multi-Tier installation involves the installation of LANSA software on an IBM i Data/Application Server and a Windows Web Server.

The link between your IIS based Web Server and your Data/Application Server (where the LANSA system runs) is provided by the LANSA for the Web IIS Plug-in, giving you a platform-independent solution for the multi-tier deployment model.

The LANSA for the Web IIS Plug-in extends Microsoft's Internet Information Services (IIS) Web server using the ISAPI technology.

The data transfer between the Web Server and the Data/Application Server is implemented as a Communications Extension connection using a LANSA Listener Job running on the Data/Application Server.

The components of a multi tier system are:

Browser

Builds the client side front-end to display the generated Web Pages.

Web Server

Runs the Web Server services. Must support the ISAPI technology (e.g. Microsoft Internet Information Server).

LANSA for the Web IIS Plug-in

The LANSA for the Web IIS Plug-in is the component used to build the link between the Web Server and the Data/Application Server.

LANSA for the Web Administrator (Local Configuration) is used for the connection to the Data/Application Server.

LANSA Communications Administrator is used for the TCP/IP settings for the communications layer.

Data/Application Server

The Data/Application Server is the back-end system hosting LANSA for iSeries or Visual LANSA with LANSA for the Web enabled.


6.2 Before you Begin Checklist

Before you start the linking of the Web Server and Data/Application Server, there are a few things that you should check first.

On the Web Server On the Data/Application Server

Is Visual LANSA installed?
If not, refer to the Installing LANSA on Windows Guide:

  • Install LANSA.
  • select the IBM i Slave as the system type if an IBM i is the master system
    otherwise
    select the Custom install.
  • Select the LANSA for the Web as the Setup Type.

A full Visual LANSA system is not required on the Web Server.

 Is Visual LANSA installed?

For a Windows Data/Application Server:
Refer to the Installing LANSA on Windows Guide: Custom Visual LANSA development environment.

  • Select Custom Visual LANSA development environment
  • Select Server install in the Setup Type.

This install will provide some specific database connections for LANSA for the Web
Is correct LANSA license applied?

Refer to LANSA Windows License Code in the Installing.LANSA on Windows Guide for information.

 Is LANSA for iSeries installed?

For an IBM i Data/Application Server:
Install a LANSA for iSeries System (including LANSA for the Web). Go to the Installing LANSA on IBM i Guide for details. You should perform a Custom installation and select both LANSA for iSeries and LANSA for the Web to be installed on the IBM i Server.
Is the Web Administrator installed?

Refer to Task: Install Other Features if this software needs to be installed.

 Do you know the User ID you will use?

The recommended User ID is the name nominated during the install process.
If you don't wish to use this user, you can create a new one. Refer to Set up Users on Windows Data/Application Server to create a new user.)
Note: This User must be the LANSA security officer or product owner.

Is the Listener running?

Listener is installed with Visual LANSA with Automatic start as the default.
Is partition web enabled?

Refer to Web-enable the Partition in the Installing LANSA on Windows Guide.
Is the correct LANSA license applied?

Refer to LANSA Windows License Code in the Installing LANSA on Windows Guide.


6.3 Task: Define Data/Application Server Name

On the web server, you must record the names of the data/application server(s) that it will need to connect to.

Step 1. Add a New Host Route

1. On the web server, start the LANSA Communications Administrator:

a. Open the LANSA folder from the Start menu.

b. Select the Settings and Administration folder.

c. Select LANSA Communications Administrator from the list and click it to start.

2. A list of all existing host routes for the current configuration is displayed in the LANSA Communications Administrator. This is a list of the servers to which your PC will be able to connect.

3. Click the New button to create a new host route to your Data/Application Server.

4. Enter the Host Route information to configure the TCP/IP connection to the Listener on the Data/Application Server:

Partner LU Name

A name that you nominate to identify the system you are connecting to. This name is referred to as the LANSA system name elsewhere in these procedures. The name must be unique.

You will use this name to test in Step 3 of this task.
Fully Qualified Name of the Host

The name of the host or alternatively, the IP address of your Data/Application Server expressed in nnn.nnn.nnn.nnn or Ipv6 fomat.

IBM i: Enter the host name or IP address of the IBM i server.
Windows: Enter the host name IP address. To locate it refer to Locate IP Address of Data/Application Server.

Communications Method

Select Socket.
Connection Identifier

You may leave this field blank. The default port number used is 4545.

IBM i: If you entered a different Connection ID when you configured the LANSA Communications Extensions on the IBM i, then enter the Connection ID number used.

Communications Module

This field should be left blank for TCP/IP Sockets (default is Winsock).
Maxl_Field (Packet Size)

It is recommended that this parameter is left with the default, but it may be set by a networking specialist configuring for special circumstances.
Enable TCP_NODELAY TCP/IP socket option

The TCP_NODELAY socket option disables the Nagle algorithm to allow small data packets to be delivered to the remote host without delay.

The Nagle algorithm combines multiple send calls in a small data buffer and delays sending it until an acknowledgement for the previous data packet sent is received from the remote host. It is enabled as the default in TCP/IP socket. As the LANSA Communication Extension implements its own data buffering, the Nagle algorithm is not needed.
Enable Ipv6 Support

Select this option to enable Internet Protocol version 6 support. This option enables the application to work on both the IPv4 and IPv6 network.

5. Press OK to continue.

6. Exit the LANSA Communications Administrator.

Step 2. Test the new Host Route

1. Start the LANSA for the Web Administrator by opening the LANSA folder from the LANSA icon on your desktop, selecting the Setting and Administration folder and choosing the Web Administrator from the list.

2. From the Options menu, select Connect... or press Ctrl +T to open the Connection Details dialog.

3. Enter the required details in the Connection Details dialog:

LANSA System name | This is the same name that was used as the Partner LU name in Step 1of this task. If you press the Ellipsis button beside this entry, it will open the LANSA Communication Adminstrator so that you can copy and paste the name into this field.
Host Type | From the drop down list select IBM i, or Other if using Windows or Linux.
Partition | Enter a partition.
Language | Enter ENG if the partition is multilingual. If this is a non-multilingual partition, leave this field blank. For information, refer to Multilingual Support in the LANSA Open Guide.
LANSA system owner Userid and Password | IBM i: The user profile must have the LANSA program library in its library list. Windows: Use the User Name that you nominated during the install.

4. Press OK to connect to the Data/Application Server.

If you are not able to connect, refer to LANSA for the Web Troubleshooting in the Installing LANSA on Windows Guide.

You have now completed the 6.3 Task: Define Data/Application Server Name.

5. Exit from the Web Administrator.


6.4 Task: Register User on the Data/Application Server

The user to be registered is the user that you nominated during the LANSA installation. To register that user on the Data/Application Server, perform the following steps.

1. Start the LANSA for the Web Administrator.

a. Open the LANSA folder from the Start menu.

b. Select the Settings and Administration folder.

c. Select Web Administrator from the list and click it to start.

The LANSA Web Administrator main window will open:

2. From the Options menu, select Connect... or press Ctrl +T to open the Connection Details dialog.

3. Enter the following information:

LANSA System | Enter the LANSA system you created in the 6.3 Task: Define Data/Application Server Name.
Host Type | Select Other from the drop down list.
Partition identifier & Language | Set your Partition identifier and Language.
Userid | Enter the User Name you created in during the install.
Password | Enter corresponding password. (Note that the password is case sensitive.)
Save Password | Optional: Select option as required.

4. Select the Save As... button and enter a Profile name to save these entries. (The Profile name can be any name you wish to use but it must be unique.)

5. Now go to the Security Menu> Register User in the Web Administrator to register the user that will run the web job on the Data Application server.

Note: If the Web Administrator is connecting to a Data/Application Server that it is not compatible with, such as an earlier version, an error message will be issued. You will need to update your versions before continuing.


6.5 Task: Configure IIS Plug-in Communications with Data/Application Server

Now you will create the links from the Web server to the Data/Application Server.

The Data/Application Server may be a Windows or IBM i Server.

Before you begin the Configuring IIS Plug-in Communications with Data/Application Server task, you must have completed the preceding steps:

  • 6.4 Task: Register User on the Data/Application Server
  • 6.3 Task: Define Data/Application Server Name

Step 1. Define Connection from Web Server to Data/Application Server

1. On the Web Server, start the LANSA for the Web Administrator:

2. From the Options menu choose Local Configuration and then Open Active from the sub-menu.

The default configuration created by the install will now be loaded for you to adapt to your environment or you could create a new one.

3. Choose the Tools menu and select the Maintain Systems command.

4. The pre-set system created during the install is displayed. Press the Add button to add a new one.

Step 2. Specify the Web Server Connection

You will now be able to set the values that connect the selected LANSA System using the Web Server and Data/Application Server tabs as shown in the following steps.

Web Server

For Name and Port, select Any unless you are using multi-homing support.

If you are using multi-homing support, select the Specific option and enter either the DNS Name (for example: www.xyzzy.com) or the IP Address (for example: 124.54.56.21) in the Web Server Name field.

Note: The values you enter for Name and Port must match the System Name and Port defined for the default user in the LANSA for the Web Administrator. DFTUSR is the default user when Anonymous User for all partitions is selected. If these values are not the same, when you run a LANSA function from your browser, it will return a Dealloc Abend message.
Default Technology Service

The technology service to use if no specific technology service is nominated in the browser's request.
Transform XSLT on Web Server

By default, this option is ON.

Select this option if you wish to perform all WAM XSLT Transformations on the Web Server, instead of the Application Server. When this option is ON, the WAM processing load is distributed between the Web Server and the Application Server so that the Data/Application Server executes the LANSA webroutine and the Web Server transforms XSLT.

For details about the other options on this dialog, refer to Web Server (Local Configuration only).

Step 3. Specify Data/Application Server Connection

1. Select the Data/Application Server tab.

2. Enter the following information:

LANSA Sytem Name

Enter the name of the host that is acting as your Data/Application Server. This name must match the Partner LU Name specified for the LANSA Communications Administrator.
User, Password and Confirm

Specify a user name and password for the Data/Application Server. A user profile is required to allocate a communications conversation between the Web Server and the Data/Application Server.

IBM I server: You may enter the user password of the default user profile you defined during the LANSA for the Web install.

Windows server: This user/password will be the user/password specified in the Web Server tab.
Test Connection

Use the Test Connection button to verify the User and Password.
LANSA Library

If you are using an IBM i Data/Application Server, enter the name of the LANSA program library.

If you are using a Windows Data/Application Server, leave this field blank.
Code Page

Page translations to be applied for communications between the Web Server and the Data/Application Server.
IBM i Data/Application Server, enter a value of 'WPI_Cp037'. This is the name of the default EBCDIC translation table shipped.

Windows/Linux - Leave blank.
If blank, no code page translations will be performed.
Partition

You may specify the default partition used for all the requests for this Web Server/Port. If a partition is specified, it will override any partition specified in the URL.

If no partition is specified here, you must specify the partition parameter in your URL.

3. Press OK to save your settings (or select the Options menu and choose the Save file).
If you do not save your settings, the changes you have made will not be applied.

4. Exit from the LANSA for the Web Administrator.

Step 4. Restart IIS and Verify the Web Server is ready to use

1. Restart IIS to ensure the new settings take effect.

2. To test IIS, start your Web browser and type the following URL:

http://localhost

or

http://localhost:8080

A welcome page for IIS should be displayed.

3. Check that the IIS Plug-in is working by running from Internet Browser using this Web address:

http://localhost/cgi-bin/about

or

http://localhost:8080/cgi-bin/about

A message with the version of IIS Plug-in will appear with the details of the IIS Plug-in loaded.

4. Check that the IIS Plug-in can connect to the Data/Application Server by running from an Internet Browser using this Web address:

http://localhost/cgi-bin/lansaweb?about

or

http://localhost:8080/cgi-bin/lansaweb?about

A message with the version of IIS Plug-in will appear with the details of the IIS Plug-in loaded.

If you encounter any problems, refer to LANSA for the Web Troubleshooting Checklist.


6.6 Task: Test LANSA for the Web

After you have installed and configured LANSA for the Web installation, you can execute the following URL as a simple test of your web configuration.

Execute the following URL as a simple test of your web configuration:

http://<your path>/cgi-bin/lansaweb?wam=xabout&webrtn=show&ml=LANSA:XHTML&part=<your RDMLX partition>

The following page should be displayed:

If this image does not appear, check that the specified Images directory exists and that the specified images exist.

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.


7. Troubleshooting

7.1 LANSA User Group and Local Users created/verified by Install

7.2 Local Users versus Domain Users


7.1 LANSA User Group and Local Users created/verified by Install

The install can create a user account or it verifies an existing user. It will update the configuration file for the LANSA for the Web Plug-in and/or the User Registration for the Data/Application Server to use the specified user. This created or verified user will be added to the LANSA User group, which is created by the install. Every user in this group, LANSA Users, will have permissions to update the User Registration for the Data/Application Server. If a different user is selected for logging into the backend using the Web Administrator, it is advisable that this new user is added to the LANSA Users group.

Ý 7. Troubleshooting


7.2 Local Users versus Domain Users

If a workstation belongs to a Windows domain and a Windows user exists on both the Domain and the Local (on the workstation), the Domain user logon takes precedence. This is especially important as the install can optionally create a user account. It will update the configuration file for the LANSA for the Web Plug-in and/or the User Registration for the Data/Application Server to use the specified user.

Ý 7. Troubleshooting


Appendix A. LANSA for Web Platform Differences

Some of the features you are familiar with if you are using LANSA for the Web on IBM i may not be available when you are using LANSA for the Web on a Windows platform.

The following list includes the specific platform differences as well as answers to some of the common questions about development with LANSA for the Web.

Item

 IBM i Windows

Locking of DLLs

N/A

When developing and testing RDML functions at the same time, the RDML compilation may fail because the LWEB_JOB (W3_P1200) has the related DLL in use. To allow concurrent development and execution of Web applications, set Maximum reuse to 1 (in the Administrator, menu Tools, sub-menu Configure System, Tab Transaction monitor). With Maximum reuse set to 1, the LWEB_JOB will be terminated. This unloads any DLLs in use.

Web Skeletons

Default skeleton is member WEBSKEL in file DC@F28 in the LANSA data library.

Overrides are members in file DC@W22.

Default skeleton is webskel.s in the LANSA source directory.

Overrides are named <filename>.s in the LANSA partition source directory.

EMAIL BIFs

Supported

These BIFs cannot be used in functions that are invoked on remote Windows server systems so therefore cannot be used in Web applications.

WEB_STATIC_ PAGE Built-In Function

Yes

Yes, with these restrictions:

  • Only the first page (corresponding to the first DISPLAY/REQUEST command) will be created no matter whether the function is running as BATCH jobs or from a browser.
  • If running in a Web context, that is, called from within a browser, Java Servlets MUST be used at the Web server. If IIS Plugin is used, the corresponding page will be displayed instead of saving to disk.
  • See the documentation of the BIF for more information.

Data Area

Data Area DC@LWEB

Values are stored in registry with this key:
\HKEY_LOCAL_MACHINE\SOFTWARE\LANSA\<encoded-root-path>\LANSAWEB\*

Spool File Access

Supported

Not supported

Location of DC@W08
Web User information

In a database.

In DC_W08.DAT file in the Visual LANSA Execute directory.

Implementation of:
DC@W05
DC@W19
DC@W21

In a database.

In a 'memory-file'. There are no related tables in the database.

Model A (Single Tier) -
Both Web Server and data/application servers on a single system.

Yes

No, only multi-tier supported.

Multi panel displays

Yes

If the screen format is larger than one page it can be displayed in a Web browser window but NOT in a PC window.
If a process containing multi-page data is compiled, a warning will be issued if the process is WEB/XML enabled. If the process is NOT Web/XML enabled, a Full Function Check fatal error will be issued.

Field spanning lines

Not supported.
When a field is longer than one line on the screen only a single line will be displayed. No error or warning is issued.

LANSA for the Web Programs

All used on IBM i

Refer to Appendix B. LANSA for the Web Programs

Exchange List

OS400 users can specify (in the web administrator) whether to use regular exchange (2K byte limit) or the extended exchange.

LANSA for the Web on Windows does not differentiate between types of Exchange list. The memory available is the only limit to the size of the Exchange Lists on Windows

Printing

Supported

Supported with these restrictions:

  • Printer mapped to LPT1 cannot be a network printer.
  • Alternatively you could use PRTR=*PATH and print to a local file.

File Components

Uses I5/OS physical files

Uses simple text file

Library Lists

Supported

No such concept on Windows

Highlighting of fields with errors

No plans at this stage for HTML.

No plans at this stage for HTML.

Cursor positioning

No plans at this stage.

No plans at this stage.

LANSA processes with an Action Bar style

No

No.

Process and function level help

No

No.

Field conditioning (e.g. IOCOND)

No.

No.

LANSA Repository based GUI constructs (except drop downs)

No

No

Column headings on flat panel will appear to the left of the field on the same line.

No change planned.

No change planned.

Browse lists do not fold if the length is greater than 80 characters.

No change planned.

No change planned.

When recompiling a function, does LANSA for the Web check to see if I have made any manual changes to the HTML or XML.

As for Windows.

No.
You can choose to:

  • not to generate the HTML or XML when you compile the function.
  • enable backup, so that your page(s) are saved before they are overwritten when your function is compiled.

You can compare two versions of a page Using the LANSA Editor - provided backup was enabled and the original version of the page was saved.

Fields with values of Hex '00' (*LOVAL) or Hex 'FF' (*HIVAL) cannot be sent to the browser.

As for Windows.

Hex '00' and Hex 'FF' are conventionally used for string delimiting and end markers. This is also the case with LANSA for the Web. Consequently, if these values are used they will be misinterpreted and result in unpredictable results if sent to the browser.

3GL programs with screen displays.

No

No

Browse commands

No

No

Message types *STATUS, *WINDOW and *WINDOWBUZ

No

No


Appendix B. LANSA for the Web Programs

You will find details of these programs and when you will use them in other LANSA Online Guides. To locate, simply search on the Program name, enclosing it in double brackets.

Program | IBM i | Windows
LCOLIST |  | LANSA Listener program
LCOTP |  | LANSA Listener transaction program
W3_P1200 |  | LANSA for the web transaction jobs.
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? in the Installing LANSA on IBM i Guide. | W3_P2000 - Transaction Monitor - Windows
W3@P2001 | Start the Transaction Monitor for the IBM i Web Server. This program is only used for a Multi-tier deployment. | N/A
W3@P2200 | Clean up program for an IBM i Data/Application Server. For details, refer to IBM i Clean Up System. | W3_P2200 - Cleanup Data/Application Server - Windows
W3@P2210iSeries | Event logging (click tracking) cleanup | W3_P2210 -Event logging (click tracking) cleanup
W3@P2300 | Web user maintenance program. For details, refer to Modifying Multi-tier IBM i LANSA for the Web User Information. | N/A
W3@P2301 | i5/OS validation list maintenance program. For details, refer to Modifying IBM i Validation Lists in the Installing LANSA on IBM i Guide. | N/A
W3@P2500 | L4Web Partition Initialization | N/A
W3@P2600 | Use triggers to generate Visual Web Components | N/A
W3@P2800 | Clean up program for an IBM i Web Server. For details, refer to IBM i Clean Up System. | N/A
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 in the Installing LANSA on IBM i Guide This program is used instead of the LANSA for the Web Administrator when LANSA is not installed on the Web Server. | N/A
W3@P2903 | Hold/Release LANSA for the Web systems | N/A


Disclaimer

While every effort has been made to ensure that the information in the LANSA documentation is accurate. In no event shall LANSA be liable for any damages arising from its use.

LANSA MAKES NO WARRANTIES, EXPRESSED OR IMPLIED.

Copyright and trademark information

© LANSA. "LANSA" is a trade name and registered trademark of LANSA in the United States of America, Australia, the United Kingdom and other countries. All rights reserved.

The following are some companies which require attribution:

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Microsoft, Windows, .NET and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Other company, product, and service names may be trademarks or service marks of others.

This material may contain other proprietary notices and copyright information, the terms of which must be observed and followed.