Communications Setup

LANSA Communications Setup Guide
for
LANSA Workstation Products

  • Introduction
  • PC Workstation Configuration
  • IBM i Configuration
  • Linux Configuration
  • Communications Error Codes
  • Running Multiple Listener Jobs
  • Troubleshooting

Edition Date May 30, 2014

© LANSA


1. Introduction

1.1 What are LANSA Communication Extensions?

1.2 Software Prerequisites

1.3 Using Encryption

1.4 Components

1.5 Setup Overview

Note: Existing LANSA functions and I/O modules do not need to be changed to use the LANSA Communications facilities.


1.1 What are LANSA Communication Extensions?

LANSA Communication Extensions provide access to TCP/IP (Sockets) as a communications method to an IBM i, Windows or Linux host. These extensions provide native TCP/IP sockets support to LANSA workstation products by exposing the sockets interface via an APPC interface.

On the host, these extensions provide a "Listener" to handle client requests for a connection by invoking the requested transaction program (TP) and ensuring the invoked TP runs in the context of the user name and password supplied by the client. On the host, each transaction program runs in its own job or process which is known as a session job.

The Listener can also determine whether the communication line is to be secure or not by enabling the encryption. By default, the setting is no encryption. This setting may be changed by selecting one of the available cryptographic algorithms as described in Security Setting.


1.2 Software Prerequisites

IBM i

TCP/IP support is provided by i5/OS. You need to configure TCP/IP following the instructions provided by the IBM documentation and then start TCP using the command STRTCP.

Windows Client and Host

TCP/IP support is provided by all supported versions of Windows.

Linux

TCP/IP support is provided by all supported versions of Linux.


1.3 Using Encryption

LANSA Communication Extensions allow you to select a cryptographic algorithm to encrypt the data transmitted between clients and hosts.

The selection of the cryptographic algorithm is done in the listener's record configuration. Refer to LANSA Communication Extensions Listener Records in the LANSA for iSeries User Guide for details.

Note: If a cryptographic algorithm is selected, the listener job will only accept connection requests from clients that support the selected cryptographic algorithm.

If you have clients that are on an earlier version of LANSA Communication Extensions (versions 1.x) which doesn't support encryption, then you can only accept connection requests from them if you select *NONE.

Encrypting data has an impact in speed and use of processing resources. Depending on your security requirements, you will need to make the trade-off decision between speed and security.

If you need to enable both encrypted and unencrypted connections to your host, you will need to configure two listener jobs. Refer to Running Multiple Listener Jobs for instructions on how to do this.

Version Compatibility

When you use the encryption facility, both the client and host must be running the same version of LANSA's Communication Extensions. This is Version 9.0 or later.

Clients running with a pre-encryption version can connect to an encryption-enabled host (Version 9.0 or later) provided the host has encryption disabled.

If a client running a version earlier than Version 9.0 attempts to connect to a host with encryption enabled, the connection request will be refused and a diagnostic message will be logged on the host.

If a client running an encryption-enabled version (Version 9.0 or later) attempts to connect to a host running a version earlier than Version 9.0, the host will reject the request. The client will then request a connection using a pre-version 9.0 request. Job logs for the unsuccessful connection requests will be produced on the IBM i host. To avoid this, you must upgrade the host to version 9.0.


1.4 Components

Host Components

The main programs that support these extensions on the host are:

 | IBM i | Visual LANSA | Linux
Listener | LCOLIST | LCOLIST.EXE | lcolist program
Transaction Program Entry | LCOTP | LCOTP.EXE | lcotp program
CPIC Manager | LCOMGR40 | LCOMGR32.DLL | liblcomgr.so shared library
Sockets IPC | LCOSCK40 | LCOSCK32.DLL | liblcosck.so shared library
Communications Routing Support | LCOCROUT | N/A | liblcocrout.so shared library
Administration | LANSA CONFIGURE | LCOADM32.EXE | N/A
DES | LCOEDES | LCOEDES.DLL | liblcoedes.so shared library
TWOFISH | LCOETWF | LCOETWF.DLL | liblcoetwf.so shared library

These programs are used by the LANSA programs which service remote session requests. Existing LANSA functions and I/O modules need no change to run over these connections.

The Listener program (LCOLIST) is the component that waits for connection requests from remote sessions at a nominated port number or pipe. When the Listener receives a connection request, it transfers the connection to a Session Job, whose entry point is the Transaction Program Entry (LCOTP). The communications layer is provided by the CPIC Manager, the IPC Modules and on an IBM i, the Communications Routing Support (LCOCROUT).

Workstation Components

The components on the client workstation consist of an Administration Utility, an APPC interface DLL (known as the CPIC Manager), a Windows Sockets (Winsock) interface DLL (known as an IPC Module). These modules are installed during the LANSA setup.

The file names for these modules on Windows are:

Administration Utility | LCOADM32.EXE
CPIC Manager | LCOMGR32.DLL
Sockets IPC Module | LCOSCK32.DLL
DES Encryption Algorithm Module | LCOEDES.DLL
TwoFish Encryption Algorithm Module | LCOETWF.DLL


1.5 Setup Overview

TCP/IP with an IBM i host

1. Configure the IBM i TCP/IP Software.

2. Install and configure the Workstation TCP/IP Software.

3. Specify the IBM i TCP/IP parameters.

4. Specify the Workstation communication extensions paths and options.

TCP/IP with a Visual LANSA host

1. Install and configure the Workstation TCP/IP Software on both the client and host.

2. Specify the Workstation communication extensions Listener options on the host.

3. Specify the Workstation communication extensions paths and options on both the client and host.

TCP/IP with a Linux host

1. Configure TCP/IP on the Linux Server.

2. Install and configure the Workstation TCP/IP Software.

3. Specify the Communication Extensions Listener options on the host.

4. Specify the Workstation communication extensions paths and options on the client.


2. PC Workstation Configuration

The LANSA Communications Administrator is used to specify your workstation configuration and to set logging and tracing on and off as required.

The LANSA Communications Administrator is installed when you select the LANSA Communication Extensions option during the LANSA Open or Visual LANSA installation. If you did not select this option when you first installed LANSA, you can do so by repeating the installation steps.

The Communications Administrator is used for both client systems and Visual LANSA host systems.


2.1 Start the LANSA Communications Administrator

To start the LANSA Communications Administrator, select the Communications Administrator icon from the LANSA Program Group.

To use LANSA Communication Extensions, it is necessary to define the route of each of the host or hosts to which you wish to be connected. This information is stored in a Route Table file (lroute.dat). You start this task from the Administrator's main window.

Host Routes

The Administrator's main window lists the Host Routes that have been set up or, if this is a new LANSA installation, the default Host Route.

To add a new Host Route or to modify an existing Host Route press the appropriate button as described below:

Communications Route Table Name

This is the name of the Route table used.

New button

To open the Host Route Information window to add a new host or route as described in 2.2 Add or Change a Host Route.

Edit button

Highlight the route to be changed and press the Edit button. Go to 2.2 Add or Change a Host Route for details.

Delete button

Highlight the host or route you wish to delete and press the Delete button.

Log and Trace...

How you instigate logging and tracing will depend on the element you wish to log or trace. It will be either a:

  • Host Route - highlight the route in the list and press the Log and Trace button to go to 2.7 Set Logging and Tracing Options.

or:

  • Module - select Module Log and Trace ... from the Advanced menu to go to 2.4 Module to Log and Trace to select the module to be monitored.


2.2 Add or Change a Host Route

If you have selected the New or Edit buttons on the main window, the Host Route Information dialog box is displayed.

The route record created using the Host Route Information dialog is not required if you are using the default TCP host name/port pair format.

The default setting for host name is localhost, and the port is 4560. (When calling the host name, just set it to localhost:4560.)

If you are not using the default host route, please continue with the options on this dialog:

Use TCP/IP Host Name (or IP Address) and Port pair notation as System Name

Select this option to use a generated LU name for TCP host name/port pair format.

System Name

Enter the name of a host to which you want to connect.
For LANSA Open, this is the name used in a call to LceUseSystem.

Tip

When defining an IBM i system, it may save you time if you define it twice with different Partner LU Names. For example, if your IBM i LU Name was MYHOST, then you could define it under the LU Names MYHOST and APPN.MYHOST. The two entries should be identical in all other respects. Using this approach allows your applications to use either the short name MYHOST, or the more formal name APPN.MYHOST. For example, the Visual LANSA Host Monitor always uses the formal name APPN.MYHOST, so unless you specify the formal name the host monitor will fail to start. However, the ability to also use the shorter name MYHOST is simpler and easier to remember for other applications.

TCP Host Name (or IP Address)

The address of the host may be a simple host name for a host in the same domain, a fully qualified host.domain name, or an IP address in nnn.nnn.nnn.nnn format. Note that when a name is supplied, name resolution (to an IP address) is provided by the underlying TCP/IP protocol stack, with which you should be familiar.

TCP Port

The default port number is 4545.
If used, the Listener component on the host must also be configured to listen on this port number.

Options

If you leave any of these options blank, the default will be used.

Maximum Packet Size

Simulates APPC packet sizes by determining the size of the send buffer used internally. The default is 1024 plus the size of a header. It is recommended that this parameter is left with the default, but it may be set by a networking specialist configuring for special circumstances.

Default to zero (0) to use the system default.

Enable Ipv6

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

Enable TCP_NODELAY TCP/IP socket option

Select this option to disable 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 Extensions implements its own data buffering, the Nagle algorithm is not needed.

Logon Timeout

Reserved for future use.

Receive Timeout

If no data is returned from the application server in the specified time in seconds, the connection is automatically closed and an error is returned to the client application.

The default of 0 second that means no timeout at all. That is, the client application would wait indefinitely until application server replies.

It is recommended that this parameter is left with the default, but it may be set by a networking specialist configuring for special circumstances.

When you have completed your entries, press OK. This will generate the lroute.dat file to be used.

DO NOT manually alter the lroute.dat file. If further changes are required, use this dialog to enter them.


2.3 Visual LANSA Listener Configuration

The Visual LANSA installation procedure will install (as a Windows service) the Communication Extensions listener named LConnect Services when you elect to install a Visual LANSA server system and select TCP/IP as the communications method. When this service is installed on a system, an additional sub-menu item: Listener... is added to LANSA Communications Administrator's Advanced menu.

You use the Listener Information dialog box to Start and Stop the Listener service on your Visual LANSA system. The Listener must be running for client workstations to connect.

Select Listener… from the main window's Advanced menu, to display the Listener Information dialog box.

Start / Stop Listener button

Highlight the communications method, then press this button to start or stop the Listener running as a Windows service (LConnect Services). The title bar of the window indicates whether the service is currently running or stopped.

Log and Trace button

Select this button to enable or disable tracing and/or logging, commencing with 2.4 Module to Log and Trace and as described in 2.7 Set Logging and Tracing Options.

Security button

Select this button to enable, disable or select encryption as described in 2.5 Security Setting.

WDTM setting... button

Select this button to access the Windows Desktop Heap Management settings (2.6 WDTM settings... ) which control the number of web jobs and/or LANSA Open sessions that can be run on your Windows server

Number of Threads

This number determines how many threads the Listener will start, to support connection requests. One (default) or two will normally be adequate but in heavy load situations, you may wish to increase this.

TCP Port

May be used with TCP/IP Sockets to provide a non-standard port number that will be listened on. If used, the client component must also be configured to connect to this port number. The default port number is 4545.

Application Mode

32-Bit or 64-Bit

Select to run 32-bit or 64-bit version of your application.

64-bit support is only available on 64-bit Windows platforms.

Note: Some Visual LANSA features, such as Web Functions, are not available in 64-bit mode.

Options

The default will be used if the following options are left blank.

Enable IPv6 Support

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

Enable TCP_NODELAY TCP/IP socket option

Select this option to disable 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 Extensions implements its own data buffering, the Nagle algorithm is not needed.

Enable SO_KEEPALIVE TCP/IP socket option

Select this option to enable the TCP/IP socket option KeepAlive.

An application can request a TCP/IP provider to enable the use of keep-alive packets on TCP connections by turning on the SO_KEEPALIVE socket option. If a connection is dropped, as the result of keep-alive option, the error code WSAENETRESET is returned to any calls in progress on the socket, and any subsequent calls will fail with WSAENOTCONN.

Logon Timeout

The maximum time in seconds allowed for completing the logon negotiation.

It is recommended that this parameter is left with the default, but it may be set by a networking specialist configuring for special circumstances.


2.4 Module to Log and Trace

For a details of the logging and tracing options, refer to 2.7 Set Logging and Tracing Options .

To log or trace a Module, open the Choose Module to Log and Trace dialog box from the Module Log and Trace... menu item in the Advanced menu on the Administrator's main window.

Select the module you wish to log and/or trace from the list. For client workstations, the only valid options are:

  • CPIC MANAGER
  • IPC MODULES
  • ADMIN UTILITY.

The other options in the list are for modules when logging and tracing from a server workstation.

Select Edit to open the Log and Trace Information dialog box, or Close to cancel.

Note: IBM i Logging and Tracing facility is configured on the IBM i as described in LANSA Communication Extensions Configuration Items in the LANSA for iSeries User Guide. It is not related to this facility.


2.5 Security Setting

This dialog box opens when you press the Security.. button on the Listener Information dialog. (To reach the Listener Information dialog, you select Listener from the main window's Advanced menu.) The server side of LANSA Communication Extensions will determine whether the communication line is to be a secure or a non secure line.

Cryptographic Algorithm

Select the cryptographic algorithm you require from the drop down list.
Options are:

  • None - No encryption applied. This applies to releases prior to LANSA Communication Extensions V10.0.
  • DES - Data Encryption Standard. This standard was adopted by ANSI in 1981. DES is a block cipher, it encrypts data in 64 bit blocks. The key length is 64 bits.
  • TWOFISH - Twofish is a 128 bit block cipher. The key length can be 128, 192 or 256 bits, however, due to US restrictions, LANSA only uses a key length of 128 bits.
    Twofish is one of the five finalists for the Advanced Encryption Standard(AES). This standard was introduced by NIST(National Institute of Standards and Technology).
  • SSL – Secure Socket Layer. SSL and its successor TLS v1 are today the most widely used protocols providing end-to-end encryption of network communications.This is the recommended option for best data encryption protection. The current implementation is based on OpenSSL on all platforms. See http://www.openssl.org for more information about OpenSSL. Our use of OpenSSL does not require certificates for server authentication.

Compression

Select this option to enable and disable compression during connection.

The use of encryption and/or compression algorithms cause more CPU cycles to be consumed during communication sessions.

This option is not used when SSL is used. SSL has data compression integrated into the protocol.


2.6 WDTM settings...

The Windows Desktop Heap Management (WDTM) settings control the efficiency of your Windows server's operation and can be used to fine-tune server system behavior under heavy loads. These settings affect your entire Windows system and are only available when connected to a Windows data/application server.

You should not need to amend these settings. If you do, your Windows performance or stability may be affected.
Changes should only be performed by an authorized Window's Administrator and only after the notes following have been read and understood.

Windows Desktop Heap Management Important Notes:

Remember: The Windows Desktop Heap Management parameters affect the entire Windows system and you should not need to change them.

The shipped default values allow approximately 800 Web Jobs and/or LANSA Open sessions (for V10.0 or later installations) to be run simultaneously on the same Windows system. In most circumstances you should not need to run more than this number of Web Jobs and/or LANSA Open sessions. If changes are necessary, they should only be made by a Windows administrator with a logon account belonging to the Administrators group. Contact your local LANSA distributor before continuing.

These parameters do not impose any hard limit (unlike the Maximum concurrent users setting in the LANSA for the Web Administrator) on the number of Web Jobs and/or LANSA Open sessions running on the same Windows system. To limit the number of Web Jobs to less than 800, you should use the Web Administrator's Maximum concurrent users setting.

The Desktop Heap parameters are designed to improve the stability of the system when the number of running Web Jobs and/or LANSA Open sessions is below the implied limit, which, using the default values, is a Windows system running 800 Web Jobs and/or LANSA Open sessions simultaneously. This should not seriously affect the stability of the system, assuming the Windows system is dedicated mainly to running Web Jobs and/or LANSA Open sessions. When that number of Web Jobs and/or LANSA Open sessions has been reached and more requests are made, Visual LANSA (version 10.0 or later) will still attempt to process the requests and create more Web Jobs (as allowed by the Maximum concurrent users setting) and/or LANSA Open sessions. This situation has the potential to cause system instability as system resources become low.

If a Windows system has the capacity to run more Web Jobs and/or LANSA Open sessions (as determined by calculating the load limit as described below) than the default implied limit , then changing these parameters can improve the stability of the system. If the Windows system is only able to marginally handle the default 800 or less Web Jobs and/or LANSA Open sessions, increasing the implied limit will not help the system to reliably run more Web Jobs and/or LANSA Open sessions. Conversely, in this case, decreasing the implied limit and the Maximum concurrent users setting would improve the stability of the system.

Calculating the load limit

The actual number of Web Jobs and/or LANSA Open sessions that can be run simultaneously is dependant on the hardware configuration and the application. Before you change the parameters, you will need to first calculate the most suitable load limit for your Windows system.

External factors also should be taken into account when determining the practical and estimated load limits. For example, if you will be running Windows batch jobs on this Windows system, these should be active when performing the limit test.

To calculate the practical load limit:

1. Change the Number of Window Desktops setting to allow a large number of Web Jobs and/or LANSA Open sessions. For example, 3000. In this case, you will need multiple Visual LANSA installations for the test, as each Visual LANSA installation supports a maximum of 1500 Web Jobs.

2. Stress the system to load more and more Web Jobs and/or LANSA Open sessions until the system starts to display signs of instability such as slow response times, hanging jobs, etc. Take a note the number of running Web Jobs and/or LANSA Open sessions. This number becomes the practical load limit of the Windows system.

3. Estimate the suitable load limit based on (and under) the practical load limit.

4. Change the Advanced Window Desktop Options parameters according to your estimated limit.

Important notes:
  • These parameters are used and shared by all Visual LANSA systems (version 10.0 or later) running simultaneously on the same Windows system.
  • These parameters are also used and shared by all LANSA Open sessions (version 10.0 or later) running simultaneously on the same Windows system. For your convenience, when using LANSA Open, these settings can be accessed from within the LANSA for the Web Administrator.
  • If there is any LANSA system process or listener service (version 10.0 or later), for example, W3_P1200 or LCOTP, running on the Windows system, these parameters will NOT be effective for the Windows system until all system processes and listener services are cleaned up and restarted. You must clean up ALL system processes and stop ALL listener services before restarting any one of these processes or services.

Procedure for Activating the Changed Parameters

1. Use LANSA for the Web Administrator to clean up all LANSA Web Jobs for all LANSA systems (version 10.0 or later) running simultaneously on the same Windows system.

2. Close down all LANSA Open sessions (version 10.0 or later) running simultaneously on the same Windows system. Note that LANSA for the Web Administrator, LANSA Web Function Editor, IIS Plug-in use LANSA Open sessions so you need to close LANSA for the Web Administrator and Web Function Editor applications that are running and stop all Web Servers using IIS Plug-in which are connected to the same Windows system.

3. Stop all Web Servers which are connecting to the same Windows system.

4. Stop all listener services (version 10.0 or later) running on the same Windows system.

5. Restart all listener services (version 10.0 or later) running on the same Windows system.

6. Restart all Web Servers which connect to the same Windows system.

7. Restart Web Jobs or LANSA Open sessions required by end users.


2.7 Set Logging and Tracing Options

The Log and Trace Information dialog box is opened when you select Edit from the 2.1 Start the LANSA Communications Administrator dialog.

Logging enables the recording of normal events which you may wish to track.

Tracing provides a means of recording detailed information for troubleshooting purposes.

You can set options for either or both the logging and tracing actions, as required.

When you set any trace or log option on, it will have an impact on performance. This impact may be minimal but that will depend on the workstation's hardware and software configuration.

You can set logging and/or tracing can be set for a particular:

  • Host Route, identified by its Partner LU Name and selected from the Host Route list on the Communication Administrator's main window.
  • Software module, for example the CPIC Manager, selected from the Module to Log and Trace dialog via the Advanced menu on the Communication Administrator's main window.

The Route or Module selected is displayed in the Log and Trace Information dialog's title bar.

Log

Connect In

Reserved for future use.

Outgoing Connection Requests

Select this option to record details of outgoing connection requests.

Trace

The number in brackets following each item in the Trace area is the value that will be automatically added to the setting to trace that item in the Route Table file.

Errors (1)

Traces error information. This consists of errors which may be considered normal during communications as well as any fatal errors encountered. Fatal errors are also always written to the log file regardless of this setting.

Debug Listener (8)

Reserved for future use.

CPIC Data (1024)

Traces data sent and received at the point where the Communication Extensions are called.

External IPC Calls (512)

Traces API calls made to the underlying communications and some calls to the operating system.

Calls to CPIC (4096)

Traces API (CPI-C) calls to the Communication Extensions CPI-C manager.

System Info (2)

Traces some basic information such as DLL loading and unloading events.

IPC Data (2048)

Traces data sent and received at the point where the underlying communications (e.g. TCP/IP sockets) is called.

Internal IPC Calls (8192)

Traces API calls to the Communication Extensions IPC Module.

Cryptographic Info (16384)

Traces encryption API calls where the encryption communications module is being used.

Trace Host (32768)

Trace flags will be sent to the host during the connection of this route record. The host will use the trace flag for this communication session.

Press the Select Basic button to restore the basic options.

Press the Select All button to turn all options On.

Press the Clear All to clear all the options.

Log and Trace Files

These Log and Trace File settings are global and are not specific to a particular route or module.

Use Default path

Use Default path to create separate trace files for multiple configurations. This is for Windows platform use only.

Log File Path & Log File Maximum Size

Enter the name of the file in which the logged entries are to be recorded, and the maximum size (in bytes). If you leave the file size as 0 (zero), there will be no limit placed on the file size.

Trace File Path & Trace File Maximum Size

Enter the file name for the trace file entries and the maximum size of the file (in bytes). The Maximum File Size default is 0, which indicates an unlimited file size.


2.8 Example Windows Workstation Setup for LANSA Open

Following is a brief guide to the steps required to configure a Windows client running a 32 bit application over LANSA Open using the TCP/IP Communication Extensions.

In this example, the client is communicating with an IBM i system named AS400PC1.

1. Ensure that TCP/IP and the LANSA Communication Extensions are running on the IBM i.

2. Install Windows TCP/IP Software from Control Screen / Network. Configure this software following the vendor's instructions and information provided by your network administrator.

3. Once you have TCP/IP installed and configured on both your workstation and host, test your configuration by running "ping" from your workstation to the host.

4. Install LANSA Open, including the LANSA Communication Extensions option.

5. Start the LANSA Communications Administrator to define the route of the host as described in the following steps.

6. In the LANSA Communications Administrator's main window, select the New button to open the Host Routes Information dialog box and enter the details as shown here:

Partner LU Name | AS400PC1
Fully Qualified Name | The address of the host. This may be: - a simple host name for a host (AS400PC1) in the same domain; - a fully qualified host.domain name; - an IP address in nnn.nnn.nnn.nnn format supplied by your network administrator.
Communications Method | Socket
All other fields | Leave blank.

7. Press the OK button when complete.

Your Windows 32 bit LANSA Open application will now use TCP/IP Socket communications with the host AS400PC1.


3. IBM i Configuration

This section describes setting up TCP/IP on the IBM i.

3.1 Working with Configuration Items

3.2 Open System Utilities Considerations

3.3 Running the Listener Job on the IBM i


3.1 Working with Configuration Items

How to set up the IBM i Configuration Items is described in the LANSA for iSeries User Guide. Refer to LANSA Communications Extensions Configuration Items (COMMS_EXTENSIONS) in the LANSA for iSeries User Guide for how to access and use the Configuration Items which include:

  • Communications Definitions,
  • Communication Extensions Facility Tracing Records, and
  • Communication Extensions Listener Records.


3.2 Open System Utilities Considerations

On the IBM i, session jobs are pre-started with the user profile of the user who started the listener job. They are changed to the user profile requesting a session when a connection request is received. If you are using program UD@CALL1 to invoke LANSA functions, then use the updated source member provided in file DC@F28 to load the current user into data structure DC@IDS.


3.3 Running the Listener Job on the IBM i

3.3.1 Starting the Listener Job

3.3.2 Ending the Listener Job

Sub-System Settings

Use the parameters of the job description you entered in the LANSA Communication Extensions definitions to determine the subsystem in which the session jobs will run. The subsystem where the session jobs will run must allow for as many active jobs as you expect. Otherwise session jobs submitted by the Listener will be queued and unable to receive connection requests.

Security Considerations

The session job starts running with the same user profile as the listener job. When a connection request is received, the session job performs a "sign-on" of the user requesting the remote session. After the new user is signed on, the job will run under the new user profile (The library list is changed to the initial library list of the new user).

To perform the user sign-on, the session job uses APIs QSYGETPH, QWTSETP, and QSYRLSPH which are supplied by IBM. The user profile which owns program LCOTP must have authority to use these APIs.

Note that although the session job runs under the signed on user profile, the initial job name doesn't change. You must not rely on the user component of the job name to identify the user who is running the session job. Instead, you should retrieve the current user attribute of the session job. This is handled by LANSA but you should be aware of it when using non LANSA programs.


3.3.1 Starting the Listener Job

Before remote sessions can connect to the IBM i using TCP/IP, the listener job must be started on the IBM i. The listener job will wait for connection requests on the port number nominated in the Listener record of the Routing Table. TCP/IP must be active before you start the listener job.

To start the listener job, submit the following LANSA request:

SBMJOB CMD(LANSA REQUEST(STRLISTEN)) JOB(aaaaaaaaaa)

where aaaaaaaaaa is the job name of your choice.

If you want to minimize the dependency of the Listener Job on the LANSA system from which it is started, then use the optional parameter PARM01(*UNLOCK). When this option is requested, the Listener job will not place a lock on data area DC@A01 nor will it keep open any files from the LANSA system data library. With this option the submit command should look like the following request:

SBMJOB CMD(LANSA REQUEST(STRLISTEN) PARM01(*UNLOCK)) JOB(aaaaaaaaaa)


3.3.2 Ending the Listener Job

To end the listener job just issue an ENDJOB command with OPTION(*IMMED) against the listener job. The listener job will end any unused pre-started session jobs and then shut down.


4. Linux Communications Configuration

This chapter describes how to configure the Listener and the Communications Route Table on a Linux server, and how to start or stop the Listener and check the status of the Listener.

4.1 Linux Communications Configuration Files

4.2 Running the Listener Job on the Linux Server


4.1 Linux Communications Configuration Files

LANSA for Linux use the following three configuration files to configure various communication requirements:

  • lansa.ini
    This is the main configuration file which is used to change default file locations of other configuration files and provide common logging and tracing parameters.
    listen.dat
    This is the configuration file for the Listener which contains, among other settings, the TCP port number to be used and various logging and tracing parameters.
  • lroute.dat
    This is the Communications Route Table which contains, amoug other settings, host routes and various route specific logging and tracing parameters.

LANSA for Linux Installer creates all these files upon installation and places the files inside the installation root directory.

If the environment variable LANSAXROOT is defined, LANSA Communications checks first in the directory specified by LANSAXROOT for lansa.ini, listen.dat and lroute.dat. If LANSAXROOT is not defined, or the files are not found, the /etc directory is checked next.

Note: The installer creates a shell script {install_root}/x_lansa/bin/setenv.sh to help advanced user to set up environment variables required for using LANSA for Linux in a shell command prompt. For instance, setenv.sh sets LANSAXROOT to {install_root} as default.

4.1.1 Using lansa.ini to Change Default File Locations

4.1.3 Configuring the Communications Route Table


4.1.1 Using lansa.ini to Change Default File Locations

If you need to change any of the default file locations or other parameters, e.g. maximum log file size, you need to edit {lansa_root}/lansa.ini with a text editor.

For example, if you install LANSA for Linux to the directory /lansa, the file /lansa/lansa.ini will be created with the following content:

[Communications]
LicenceTable=/lansa/x_lansa/x_lickey.dat
ProcInfoFile=/lansa/lcoproc.ini
RouteTable=/lansa/lroute.dat
TraceFile=/lansa/log/lroute.trc
LogFile=/lansa/log/lroute.log
;TraceMaximum=65536
;LogMaximum=65536
;LogStateCheck=N

The file lists all the file locations and other parameters that you may customize.

Lines starting with a semicolon are remarks and so the semicolons can be used handily as a way to disable/enable a parameter. In the example, for instance, default value for TraceMaximum will be used as the line is remarked out.


4.1.2 Configuring the Listener

LANSA for Linux Installer creates the configuration file {lansa_root}/listen.dat for the Listener during installation. If you do not specify a port number for the installer, port number 4545 is used.

For example, if you install LANSA for Linux to the directory /lansa, the file /lansa/listen.dat will be created with the following content if you do not use the port option for the installer:

* LANSA Communication Listener Record File
* Comma Delimited, positional parameters.
* Empty parameters must have at least one space.
* Record Types (first character)
* L listener information
*L,Threads,NotUsed,NotUsed,Trace,TCPPort,Compression,Algorithm,Mode,Options,Features,LogonTimeout,AppMode
L,1,-,-,0,4545,1,NON,0,1,0,10,0

If you use the port option for the installer, the port number you provided will be written to the configuration file instead. See the installation guide for Linux for more information about the installer and its options.

If you need to customize any settings for the Listener after installation, you can edit the configuration file with a text editor. Most of the settings are simple to change by following the remarks in the configuration file.

For advanced users, alternatively, you may copy the configuration file to Windows and use the LANSA Communications Administrator to modify it. After the modification, you can then copy the configuration file back to the Linux server. Reminded you may need to preserve your current listen.dat for the LANSA for Windows installation and replace it back after modifying the configuration file for Linux.


4.1.3 Configuring the Communications Route Table

LANSA for Linux Installer creates a basic Communications Route Table {lansa_root}/lroute.dat during installation. The table contains only one entry of LU Name *LOCAL which can be used to access the Listener of the same installation. The port number of the entry simply uses the same port number for the Listener.

For example, if you install LANSA for Linux to the directory /lansa, the file /lansa/lroute.dat will be created with the following content if you do not use the port option for the installer:

* LANSA Communication Routing Table File
* Comma Delimited, positional parameters.
* Empty parameters must have at least one space.
* Record Types (first character)
* R routing information
* T module trace information
*R,SystemName,TCPHost,NotUsed,NotUsed,Trace,TCPPort,MaxPacketSize,Options,LogonTimeout,ReceiveTimeout
*T,Module,Trace
*
R,*LOCAL,127.0.0.1,Socket, ,0,4545,0,1,0,0

If you need to customize any settings for the entry after installation, you can edit the route table with a text editor. Most of the settings are simple to change by following the remarks in the route table.

If you need to add entries to the route table, you can modify the route table by copy existing entries and then customize the copied entries.

Alternatively, if you need to make extensive changes to the route table, the LANSA Communications Administrator on Windows offers some nice GUI editing capability.

You can use the LANSA Communications Administrator to create or maintain the Communications Route Table (lroute.dat) for use on the Linux Server. You must run the Administrator on a Windows Server that has the LANSA Listener installed, so that the Listener options appear in the Advanced menu.

1. Decide on a location for the Linux Route Table. (For example, c:\lroute.dat)

2. Open the Administrator and choose Create Route Table for Deployment from the Advanced pull-down menu. Any Host Routes you had defined for your default Route Table should disappear when you click on the Host Routes window.

3. Configure the Communications Route Table as described in the Workstation Configuration chapter. Keep the following points in mind:

  • The Start Listener and Stop Listener button should not be used as it will attempt to start or stop the listener on the Windows Server, not the Linux Server.
  • The Log and Trace Files settings should not be changed. These only affect the Windows Server trace files. If you wish to change the location on Linux, refer to 4.1.1 Using lansa.ini to Change Default File Locations.
  • The Number of Threads parameter should be 0 or 1. Anything else is treated as 1.

4. Copy the new lroute.dat file to the appropriate directory on the Linux Server, usually {lansa_root}/listen.dat.

Note: The filename lroute.dat must be specified in lower case.


4.2 Running the Listener Job on the Linux Server

The Linux Server has a listener control utility named lcolctl. The utility allows you to start or stop the Listener and to check if the Listener is running.

Before you can use the utility, you need to start a shell command prompt and load the setup script {lansa_root}/x_lansa/bin/setenv.sh. The setup script is targeted for standard shells sh and bash, if you are using other shells, you may need to adapt setenv.sh for the shell that you use.

If you are using standard shells sh or bash, you can set up the command prompt environment for running LANSA for Linux with the following command:

. {lansa_root}/x_lansa/bin/setenv.sh

You need to replace {lansa_root} with the directory for your LANSA for Linux installation, e.g. /lansa. The setup script will set a few environment variables, including LANSAXROOT and X_RUN, which are crucial to using LANSA forLinux in a command prompt. The setup script will also updates the command path and shared library path.

To start or stop the listener, you need to use a shell command prompt logged in as root. For other operations, you may log in as any user belongs to the group that owns the installation directory.
To start the Listener, you use the command (must be running as root):

lcolctl start {port}

where {port} is the Listener port number. If you do not specify a port number for the installer, the default port number is 4545. In case you forget what the current port number should be, you can check the configuration file for the Listener listen.dat.

For example:

lcolctl start 4444

if 4444 is the port number of your Listener.

To stop the Listener, you use the similar command (must be running as root):

lcolctl stop {port}

For example:

lcolctl stop 4444

To check if the Listener is running, you use the command:

lcolctl show

If the Listener for the installation is running, for example, you will see something like:

Port PID SID
4545 15489

which shows that the Listener is running and listening on port number 4545 and its process id is 15489. Note that the SID column is no longer used in this release and should be usually blank.

You can also use the Linux standard ps command to check for all the Listeners (not just the current installation you are using) running on your system, e.g.:

ps -ef | grep lco

If the Listener is running, for example, on a Linux server, you will see something like:

root 15489 1 0 Jul01 ? 00:00:00 /lansa/connect/lcolist: [monitor]
root 15490 15489 0 Jul01 ? 00:00:00 /lansa/connect/lcolist: listening on port 4545

If there are more than one Listeners running on your system, you will see more entries like these.

If the Listener is stopped but it is not properly stopped with the lcolctl stop command, e.g. explicitly terminated by the system shutdown sequence, lcolctl show command may incorrectly show that the Listener is still running. If you attempt to start the Listener again with the lcolctl start command, the command will fail with a message like this:

Port 4545 already in use

In this case, you can simply run the lcolctl stop command first, and then restart the Listener with the lcolctl start command.


5. Communications Error Codes

If a communications error occurs between the client and the host while using these communication extensions, the error returned from the TCP/IP software is mapped to a standard APPC error code.

The most commonly experience APPC error codes are 20, 6 and 17. This APPC code is often enough to let you know what caused the issue. Refer to the following for simple resolutions:

APPC Error Code | Likely cause
20 | Indicates that the application could not connect to the listener. Check that the listener is running, and that there are no firewall issues for the listener port on the server.
6 | Indicates a login validation error. If you are sure the correct username and password has been used, use LANSA comms tracing on the server to determine the cause of the error.
17 | Indicates an unexpected error on the server, after login validation. Check the joblog/x_err.log on the server for problem.

If this is not enough information, and the problem is reproducible, you should turn on the Errors tracing option to determine what the original error was. For further details refer to Set Logging and Tracing Options. With the Errors tracing option turned on, you will get an entry in the trace file similar to this:

02/06/97 16:12:39 testw32(0xa2:0x9f):LCOSlapi:Error:COMM_Allocate

Native Error:10061 CPIC Error:20 in connect

"Native Error" shows the original error returned by the communications software. In this example; error code10061 (WSAECONNREFUSED) occurred on a "connect" request because the host was not running the Listener, required to listen on sockets port 4545.

Following is a list of possible error codes returned by the WSAGetLastError() (Winsock) call, along with their explanations. These error numbers are consistent across all Windows Sockets-compliant implementations.

Error Code | Windows Sockets Code | Berkeley equivalent | Interpretation
10004 | WSAEINTR | EINTR | As in standard C
10009 | WSAEBADF | EBADF | As in standard C
10013 | WSEACCES | EACCES | As in standard C
10014 | WSAEFAULT | EFAULT | As in standard C
10022 | WSAEINVAL | EINVAL | As in standard C
10024 | WSAEMFILE | EMFILE | As in standard C
10035 | WSAEWOULDBLOCK | EWOULDBLOCK | As in BSD
10036 | WSAEINPROGRESS | EINPROGRESS |
10037 | WSAEALREADY | EALREADY | As in BSD
10038 | WSAENOTSOCK | ENOTSOCK | As in BSD
10039 | WSAEDESTADDRREQ | EDESTADDRREQ | As in BSD
10040 | WSAEMSGSIZE | EMSGSIZE | As in BSD
10041 | WSAEPROTOTYPE | EPROTOTYPE | As in BSD
10042 | WSAENOPROTOOPT | ENOPROTOOPT | As in BSD
10043 | WSAEPROTONOSUPPORT | EPROTONOSUPPORT | As in BSD
10044 | WSAESOCKTNOSUPPORT | ESOCKTNOSUPPORT | As in BSD
10045 | WSAEOPNOTSUPP | EOPNOTSUPP | As in BSD
10046 | WSAEPFNOSUPPORT | EPFNOSUPPORT | As in BSD
10047 | WSAEAFNOSUPPORT | EAFNOSUPPORT | As in BSD
10048 | WSAEADDRINUSE | EADDRINUSE | As in BSD
10049 | WSAEADDRNOTAVAIL | EADDRNOTAVAIL | As in BSD
10050 | WSAENETDOWN | ENETDOWN | As in BSD
10051 | WSAENETUNREACH | ENETUNREACH | As in BSD
10052 | WSAENETRESET | ENETRESET | As in BSD
10053 | WSAECONNABORTED | ECONNABORTED | As in BSD
10054 | WSAECONNRESET | ECONNRESET | As in BSD
10055 | WSAENOBUFS | ENOBUFS | As in BSD
10056 | WSAEISCONN | EISCONN | As in BSD
10057 | WSAENOTCONN | ENOTCONN | As in BSD
10058 | WSAESHUTDOWN | ESHUTDOWN | As in BSD
10059 | WSAETOOMANYREFS | ETOOMANYREFS | As in BSD
10060 | WSAETIMEDOUT | ETIMEDOUT | As in BSD
10061 | WSAECONNREFUSED | ECONNREFUSED | As in BSD
10062 | WSAELOOP | ELOOP | As in BSD
10063 | WSAENAMETOOLONG | ENAMETOOLONG | As in BSD
10064 | WSAEHOSTDOWN | EHOSTDOWN | As in BSD
10065 | WSAEHOSTUNREACH | EHOSTUNREACH | As in BSD
10091 | WSASYSNOTREADY |  | Network subsystem is unusable.
10092 | WSAVERNOTSUPPORTED |  | Windows Sockets DLL cannot support this app.
10093 | WSANOTINITIALISED |  |
11001 | WSAHOST_NOT_FOUND | HOST_NOT_FOUND | As in BSD
11002 | WSATRY_AGAIN | TRY_AGAIN | As in BSD
11003 | WSANO_RECOVERY | NO_RECOVERY | As in BSD
11004 | WSANO_DATA | NO_DATA | As in BSD


6. Running Multiple Listener Jobs

You can run multiple listener jobs on a 6.1 IBM i host, 6.2 Linux host or a 6.3 Windows Host.

The following setup steps are for twin listener jobs but the mechanism can easily be extended to accommodate more listener jobs.


6.1 IBM i host

Set up a Separate Listener

If you install a second LANSA system on the same machine, it will have its own communications configuration. That is, each LANSA system has its own separate listener. To avoid conflicts between this second listener and the listener from the first LANSA system you need to:

  • Edit the LANSA communications definitions (i.e. configuration item COMMS_DEFINITIONS) in your second LANSA system and change the prefix for the session's job name. This is not mandatory but will help you identify session jobs started by this listener instance.

If you change the user queue for session jobs, ensure it is unique and not used by other listeners.

  • Before creating or upgrading an additional listener, check if the following LANSA libraries are in the library list:
  • LANSA program library
  • LANSA communication library

If these libraries are not in the library list, add them by using the IBM i command ADDLIBLE.

The options are:

6.1.1 Create an Additional Listener

6.1.2 Upgrade an Additional Listener


6.1.1 Create an Additional Listener

In the event that you want two listeners (the default plus an additional listener) for the same LANSA system, you need to create a second configuration.

A reason why you may want a second listener is if you want to have some clients connect on an encrypted port while others connect without encryption.

If you do use two listeners, you must upgrade the additional listener manually as described in 6.1.2 Upgrade an Additional Listener.

To have two listeners for the same LANSA system, follow these steps:

1. Create a new configuration library to store the second listener's configuration object (e.g. NEWCFGLIB).

2. Create a copy of data area LCOA01 in the new configuration library.

3. Run the command (shipped in your LANSA program library):

LCOAINST REQUEST(INSTALL) LIB(PPPPPPPPPP)

where PPPPPPPPPP is the name of the new configuration library (for example, NEWCFGLIB).

4. Press the Enter key once and you will be prompted for additional command parameters.

Enter the following required parameters:

Owner of route table: | The owner of the LANSA communications routing table.
IFS path for route table: | The IFS path for the routing table.
Port Number: | The TCP port for the additional listener.
Program Library: | The program library of the LANSA system. (This should be different from the new configuration library.)

If the values prompted are correct, press the Enter key once. If you have changed your LANSA configuration since you installed or upgraded your LANSA system, you may want to enter your current values before you press the Enter key. This command creates a new routing table with default content.

5. Set your new configuration library as the current library for the job you are currently running. Use the i5/OS command CHGCURLIB for this purpose.

6. Edit the LANSA communications definitions (i.e. configuration item COMMS_DEFINITIONS). The message at the bottom of the screen informs you which configuration object is being changed. Confirm that the configuration object locked is the one from your new configuration library.

7. Change the prefix for the session's job name. This is not mandatory but will help you identify session jobs started by this listener instance.

8. Change the user queue for session jobs. This qualified name must be unique for all listeners on the same machine.

9. Change the user profile under which the second listener will run so that the new configuration library is its current library. This will ensure that the LANSA Communication Extensions configuration is retrieved from the new configuration library and not from the LANSA program library.

10.User profiles connecting to the second listener should also have the new configuration library as their current library.

11.Submit the second listener job. Use the USER parameter of the SBMJOB command to nominate the user profile you created in step 9.


6.1.2 Upgrade an Additional Listener

The LANSA system upgrade only upgrades the default listener (whose configuration is stored in the LANSA program library) and not any additional listener.

To upgrade the second (additional) listener in your LANSA system, follow these steps:

1. Run the command (shipped in your LANSA program library):

LCOAINST REQUEST(UPGRADE) LIB(PPPPPPPPPP)

where PPPPPPPPPP is the name of your second listener configuration library.

2. Press the Enter key once and you will be prompted for additional parameters.

Enter the following required parameters:

Owner of route table: | The owner of the LANSA communications routing table.
Port Number: | The TCP port for the additional listener.
Program Library: | The program library of the LANSA system. (This should be different from the second listener configuration library.)

3. If the value prompted is correct, just press the Enter key once more. If you have changed your LANSA configuration since you installed or upgraded your LANSA system, you may want to enter your current owner.

4. Set your second listener's configuration library as your current library.

5. Edit your LANSA communications definitions to review your existing configuration.


6.2 Linux host

The listener job will handle all connection requests from clients connecting to the same LANSA installation.

Note: The environment variables in the root user's shell (LANSAXROOT, ORACLE_SID, etc.) at the time the listener is started are inherited by the listener and all session jobs.

If you have more than one LANSA installation on the same machine, it is possible to run multiple listener jobs, but care must be taken in the setup to ensure the session job will run as expected.

In particular:

  • You must separate the lansa.ini, lroute.dat, trace and log files for each listener. The easiest way to do this is to put them in the LANSAXROOT directory for each LANSA installation. Refer to Using lansa.ini to Change Default File Locations for details.
  • You must use a different port number for each listener. For example, use port 4545 for your production system, and port 4546 for your training system.
  • Create a script to start (and stop) each listener. This will allow appropriate values, such as LANSAXROOT and the listener port number, to be set explicitly in one place. Refer to Running the Listener Job on the Linux Server for details on starting and stopping the listener.

Setup on the Client(s)

On each client you need to change the host route record connection identifier to connect to the appropriate port number.


6.3 Windows Host

Multiple Visual LANSA systems can be installed and configured on single computer preferably running a Windows Server operating system. This is a description of installing multiple Visual LANSA systems on single server.

In this example, each Visual LANSA system will use separate database and a Listener will be configured to run on a specific port number to control communication to each Visual LANSA system.

When installing Visual LANSA as a Slave/Master Server configuration, LANSA Communication software is installed in subdirectory CONNECT.

This example of installing and configuring two Visual LANSA systems uses these names as examples only.

  • First Visual LANSA system name: Visual LANSA1
  • Second Visual LANSA system name: Visual LANSA2

Install First Visual LANSA System

1. Visual LANSA1 system will be installed in directory C:\Visual LANSA1

  • During installation, set up the Listener to start manually *

2. From the LANSA Menu, select Setting and Administration folder, and start the LANSA Communication Administrator.

3. From menu option Advanced/Listener, define Listener port number. For the Visual LANSA1 system, the Listener will be defined on the same port number, for example, 4550.,

4. Define the details of Host Route Information for the VisualLANSA1 system.

5. Test the Listener.

  • Start/Stop Listener, observe the service running in the Services console.
  • The defined LConnect service should be running.

Install Second Visual LANSA System

1. Visual LANSA2 system will be installed in directory C:\Visual LANSA2.

  • During installation, set up the Listener to start manually *

2. From the LANSA Menu, select Setting and Administration folder, and start the LANSA Communication Administrator.

3. From the menu option Advanced/Listener, define the Listener port number. For Visual LANSA2 the system Listener will be defined on the same port number, for example, 4560.

4. Define the details of Host Route Information for the VisualLANSA2 system.

5. Start the Listener manually, the LConnect Service can be observed from Services console.

6. To test the behavior of two Listeners running on the same machine, try to connect to both databases at the same time.

Configure and use LANSA Client or the LANSA Web Administrator/Function Editor if they are installed to connect to Visual LANSA1 and Visual LANSA2 systems.

*If you didn't set the Listener up to start manually during the install, when you change the Listener's port number then you'll need to Stop then Start the listener. If it's set to manual start, then you don't need to Stop the listener before Starting it. However, if it's set to start manually, you'll need to start it every time you want to use it. You can change it to automatic through Windows Services.


7. Troubleshooting

Windows

This error is reported when the Route table can't be found:

Can't find lroute.dat (a Communication Extensions message)

or

Host route record can't be found (a Visual LANSA error)

Restart the LANSA Communication Extensions Administrator to verify that your route records are now correct.


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.