FWD

Client Installation¶

• Client Installation
  • System Requirements
  • Choosing the Appropriate JVM
  • Choosing the CHUI Implementation
    • Console Driver
    • Swing ChUI Driver
    • [CA]Web Client Driver[/CA]
    • [CA]Batch Client Driver[/CA]
  • Installation Process
  • File System Structure

This chapter is out of date and is no longer being maintained. It is only being retained for historical purposes. The replacement chapter can be found in Client Installation.

This chapter documents how to install the runtime code that allows the FWD client to execute. Configuration and execution of the client is documented in the Bootstrap Configuration and Running the Client chapters.

The converted application runs entirely on the FWD Server, and unlike the Progress client, no business logic or data access of ANY kind is executed on the FWD thin Client. The client process is “thin” from the perspective that it does nothing except connect to the server, authenticate and then invoke an entry point (the business logic) on the server side. The server drives all client activities using a set of user interface “primitives“. This allows the client code to be completely generic (not application specific) as well as reasonably thin.

System Requirements¶

Since the client process is thin the hardware resources needed for running it are relatively low. The following hardware requirements needed to support Java runtime usually should suffice:

Feature	Requirement
CPU	Any recent Intel compatible CPU will work. It is recommended to stay with a 32bit x86 processor since it greatly simplifies the installation of the runtime components. FWD has been tested to work on systems which can run 64bit code. The FWD runtime is highly threaded, so a multi-core CPU environment will be of great benefit for this purpose. Both AMD and Intel CPUs have been tested and have been found to work well. If the JVM being used works well on a given CPU, then that CPU is OK. Modern CPUs such as the Intel Core2 Duo have been found to be quite suitable for runtime performance.
Memory	The client memory footprint is rather low as it needs memory just to process the interface primitives from server. The client only stores the current screen and active frame configuration. As JREs usually no not require more than 128 MB, there is enough room for client application as modern computers came with gigabyte-size memory.
Disk space	The most disk space is taken by the JRE environment - about 100 MB, while the client application's jars only take about 5 MB, a fraction of that. If file logging is enabled then space must be reserved. Depending on the complexity of the logs generated, few tens of megabytes should be plenty. However, if the FWD application save streams locally enough space should be reserved on the disk.
Network	The communication between client and the server is very interactive so a low-latency network should be preferred.

Operating System

From the software point of view, you can install the client on any operating systems as long as there is a JVM implementation for it. *[CA]*However, you will be limited by the FWD's support of the native code for this operating syste. At the time of this writing, the native code on Linux/UNIX is fully supported (although dependent on NCURSES) and a port for the Windows operating system exists too (although not fully tested at this time). In both cases, this platform specific code is implemented using the Java Native Interface (JNI) and is often referred to as “native” code. This code is currently compiled as both 32bit and 64bit shared libraries for either Linux or Windows. The application has been successfully run on a variety of recent Linux distributions from Ubuntu, SuSE, Red Hat and CentOS. There are no specific dependencies on any particular distribution. It is expected that any UNIX compatible system would work properly. Testing for Windows operating system is not finished yet.[/CA]

Choosing to run the client with Swing display driver will allow to run the application on any Linux distribution and other operating systems like Windows and MacOS with a graphical system on which a Java distribution exists, [CA]keeping in mind the limitations needed for the native code to build.[/CA]

Java Virtual Machine

[CA] TODO: java 7

The Sun JRE 1.6 on Linux is a well tested option. Various versions from 1.6.0_04b12 through 1.6.0_16b01 have been tested and have been found to work well. Either the 32bit or 64bit version may be used. Even if at the time of the writing of this document Oracle's JVM 7 is rather mature it did not passed yet out tests, so we recommend to stick to Java 6.

Choosing the Appropriate JVM¶

At this moment there is a clear trend towards 64 bit architecture. The new x64 hardware is able to support very large amounts of memory and thanks to larger and increased number of 64bit registers the application's performance is improved. It's up to the already installed OS if the applications will benefit of these enhancements.

If of your operating system is a 64 bit built you may use the 32 bit or the 64 bit one. We recommend using for the client-side application the 32-bit JVM for the following reasons:

• the thin client does not need large amount of memory to run, as mentioned in previous paragraph, the needed memory is rather low.
• the client does not process any data except for the displaying primitives received from server. The improved performance of a x64 built JVM is insignificant.
• the memory footprint is usually greater on 64 bit as the pointers are twice as long as the 32 bit ones. Java uses pointers intensively as all references to objects (except for the scalars) are in fact pointers. This leads to the fact that the 64 bit version takes between 40% - 50% more memory on average than either 32-bit JVM.
• Running the client with native display driver need additional JNI and libp2j@.so@ libraries that must be re-compiled for the 64 bit version.

Choosing the CHUI Implementation¶

[CA]The native-based driver operates on both Linux and Windows systems.[/CA] Also, the swing-based driver should be usable on any system where the JVM supports swing applications (any graphical system such as Linux with X11, Windows or MAC OS) [CA], with the constraint that the FWD's native dependencies are ported for that OS.[/CA]

Console Driver¶

The console driver (based on NCURSES in Linux/UNIX) was the first implemented and it is fully compliant with original Progress 4GL user interface. However, choosing this driver you will need additional effort when installing the client as some patches (NCURSES and TERMINFO) have to be done and additional libraries installed, including native code (libp2j.so) accessed by Java code using JNI. The main advantage of this ChUI driver is that it is the only solution for customers that still use hardware terminals AND there are still other good reasons to be able to run the console client (e.g. the certification harness will only work with the NCURSES client).

[CA]On Windows, the console driver and FWD runtime was built to emulate the 4GL functionalities specific to this OS.[/CA]

Swing ChUI Driver¶

The Swing driver is an alternative to using the [CA]console[/CA]-based client [CA](based on NCURSES on Linux)[/CA]. This is the first example of a non-[CA]native[/CA] client "driver". It is fully functional with only minor limitations. [CA]remove this paragraph: The main advantage of this ChUI driver is that the client application does not need to load native libraries (libp2j.so) and no NCURSES patches and TERMINFO patches are needed for a basic environment, so it can be run on virtually any platform for which a Java Swing implementation exists.[/CA] [CA] The main advantage of this ChUI driver is that the client application can be ran on any platform for which a Java Swing implementation exists and which is supported by the FWD's native dependencies.[/CA]

Because of the nature of the java language it may be seen in action in two 'flavors': as an application (as started by our own ClientDriver.java) or as an applet (embedded in a web-page or running in Java's appletviewer). Please note that there are more serious limitations when running as an applet, due to the inherent limitations of the applet security environment. As applets are prohibited to access the file system, launch child processes or otherwise try to access things that trip security limits, it cannot be used for most applications.

[CA]Web Client Driver[/CA]¶

This driver allows FWD clients to be launched and accessed in a browser. The browser establishes a Web socket connection to an embedded web server running within the FWD Client, and the user will have the same experience as if the client was accessed on a physical machine. This requires that the user has an account on the remote system on which the FWD Client is launched, as the user remotely operates a real FWD client with the proper OS security context on that machine. At the time of this writing, clients can be launched only on the same machine as the one on which the FWD Server is running, but in the future is expected to allow the clients to be started on different machines.

[CA]Batch Client Driver[/CA]¶

The batch driver is a special driver used to run batch processes or Application Server Agents. In this modes, UI features are limited/restricted (depending on the type of client being started - appserver Agent or batch process). FWD will be aware of any redirection of the standard input/output streams (at OS process level) and act accordingly. As 4GL acts differently when the OS process associated with the 4GL batch program is ran background, FWD allows configuring such clients explicitly, to allow full compatibility with the legacy system.

TODO: is batch client driver dependent on NCURSES?

Installation Process¶

We will assume that the operation system is already installed and up-to-date. Also assume that the root of the client installation is given by $P2J_CLIENT environment variable. To install the client the following steps should be followed:

1. Install the Java Virtual Machine. Please check previous paragraphs for details on what JVM to download and install.

Make sure the bin directory of the JVM installation is added to PATH variable of the operating system so the application could be executed by using “java” command in a terminal window.

It is also recommended to set the user's CLASSPATH to current folder (“.”). On Unix/Linux use:

export CLASSPATH=.

2. Patch NCURSES. This step is only needed if you choose to run the client with native driver, for swing chui driver [CA]or if installing FWD on Windows[/CA] skip to step 4.

[CA]TODO: on Linux, is it possible to build the native task if NCURSES is not patched???[/CA]

All common Linux distributions have support for and include NCURSES by default but FWD need a customized version of NCURSES v5.5 or higher to be installed and patched. If the currently installed NCURSES version is 5.5 or 5.6 copy

• ncurses_curses_h_in_20060828.patch and
• ncurses_lib_getch_c_20060828.patch

files to a temporary location $P2J_CLIENT/tmp. For version 5.7 use

• ncurses_curses_h_in_20060828.patch and
• ncurses_lib_getch_c_v5.7_20090512.patch.

Follow the next 4 steps to patch NCURSES package (This example will use the version numbers and patch file names for v5.7, adjust filenames for your installed version):

Step 1: Obtain the source code

cd $P2J_CLIENT/tmp
apt-get source ncurses

Step 2: Patch the source

cd ncurses-5.7
patch ncurses/base/lib_getch.c $P2J_CLIENT/tmp/ncurses_lib_getch_c_v5.7_20090512.patch
patch include/curses.h.in $P2J_CLIENT/tmp/ncurses_curses_h_in_20060828.patch

Step 3: Build

./configure --with-shared
make

Step 4: Install

su root
make install
cd /lib/i386-linux-gnu/
cp libncurses.so.5.7 libncurses.so.5.7.ori
cp /usr/lib/libncurses.so.5.7 .
rm libncurses.so.5
ln -s libncurses.so.5.7 libncurses.so.5

3. Patch TERMINFO. This step is only needed if you choose to run the client with the native driver, for swing chui driver [CA]or if installing FWD on Windows[/CA] skip to step 4.

TERMINFO definitions for vt320, vt220 and xterm need to be fixed. Follow the next 3 steps to update the definitions (the example only shows vt320 case):

Step 1: Decompile the TERMINFO Entry into a temporary file:

infocmp vt320 > vt320.tmp

Step 2: Edit and Fix the Definitions. Edit the vt320.tmp file. Notice the TERMINFO location mentioned in the first line. It is typically: /usr/share/terminfo/v/vt320. Apply the specific changes documented in the table below.

Definition	xterm	vt220	vt320
TAB	n/a	n/a	ensure that ht=^I, exists and that knxt=^I, is deleted
HOME	n/a	n/a	add or modify the khome= to be khome=\EOH.
END	n/a	add or modify the kend= to be kend=\E[F	add or modify the kend= to be kend=\EOF
BACKSPACE	add or modify kbs= to be kbs=\177	n/a	n/a
cursor visibility	n/a	add or modify the civis= to be civis=\E[?25l add or modify the cnorm= to be cnorm=\E[?25h	n/a

Save the file.

Step 3: Recompile the TERMINFO Entry using the following command:

sudo tic -o/usr/share/terminfo vt320.tmp

4. Copy the client application binary files. The following files from the FWD production build:

• p2j/build/lib/libp2j.so [CA]on Linux/UNIX or p2j/build/lib/p2j.dll on Windows[/CA]
• p2j/build/lib/p2j.jar

must all be copied to the same target directory $P2J_CLIENT/bin. They are the native library (includes the ChUI terminal code [CA]and some other custom code needed by i.e. running native APIs[/CA]) and the archive that contains the FWD Java code. Both are built when FWD is built. If needed, the libraries must be recompiled in 32-bit or 64-bit to match the “bitness” of the JVM choice

5. Copy security related files. For any interactive or batch client that is using secure sockets, copy the following client configuration and security files into a directory on the client system:

• client bootstrap configuration file(s)
• client key store(s)
• server trust store

6. Set up client configuration files. The client can be customized with one or two bootstrap configuration files. Edit the xml files to reflect the needed security items and network informations needed to connect to FWD server. If needed, adjust the display preferences for the ChUI you have chosen. Check the “Bootstrap Configuration” chapter for details.

7. Ensure there are the proper user accounts on the client system under which context the FWD client will run. In addition, if there are batch processes, they will need to be started in the context of some appropriate user account, since they run [CA]as a full, non-interactive,[/CA] FWD client process. Normally each application user, dedicated program or batch process would run under their own operating system level user account, although that is not absolutely required. The following permissions are needed:

• it must be able to launch a java process with the necessary amount of RAM to provide for the maximum heap size plus some amount of overhead in the JVM itself
• it must be able to read all of the jar files copied from the FWD build
• it must have read access in the directory in which the bootstrap configuration file is stored
• it must have access to create, delete and write its log files to the log file destination (often in the current/working directory but also can be a shared directory)
• it must be able to establish an outbound TCP socket connection (with subsequent 2-way communication) to the FWD Application Server host and port

8. [CA]If using web clients or if the FWD Server is configured to launch batch processes or appserver Agents, then you need to setup a special FWD tool called the spawner. This tool will allow the FWD Server to automatically launch FWD Clients on behalf of a certain user, as the clients need to run using that user's credentials and OS security context. See the _Spawner Setup and Configuration _chapter of this book for details about how to setup and configure the spawner.[/CA]

9. Firewall setup. Any firewall support must be configured to allow an outbound TCP socket connection (with subsequent 2-way communication) to the FWD Application Server host and port.

10. Update CLASSPATH. Add the p2j.jar (full or relative path) to the CLASSPATH environment variable or java command line parameter -classpath (specified as a JVM parameter which means it is positioned before the com.goldencode.p2j.main.ClientDriver argument).

11. Set any application-specific environment values. These are values that are required for the operation of the converted application code and which are only known to the application (they have no relevance to FWD). A common example is to set the path to executables that are run as child processes from the converted application. Often these values must be setup in user-specific scripts or profiles.

12. Install any application-specific configuration files. These are files that are required for the operation of the converted application code and which are only known to the application (they have no relevance to FWD). Make sure to assign the necessary permissions/ownership using the operating system security facilities.

13. Install any application-specific program files or libraries. These are files that are required for the operation of the converted application code and which are only known to the application (they have no relevance to FWD). Make sure to assign the necessary permissions/ownership using the operating system security facilities. A common example is to install executables that are run as child processes from the converted application.

14. Setup environment variables used by application. Determine all environment variables that are read directly from the converted application code. Encode these values as JVM properties in the client command line. For example, if the application uses the HOME environment variable, then the client command line should be passed to the client JVM as a defined property using a -DHOME=value syntax and the construct should appear before the com.goldencode.p2j.main.ClientDriver class name (otherwise it will be considered a parameter to ClientDriver instead of a parameter to the JVM).

15. Create all necessary directories needed by the converted application. Make sure to assign the necessary permissions/ownership using the operating system security facilities. See the 'File System Structure' for a recommended directory structure.

Optionally, if FWD_LOG_DIR environment variable is defined, create the folder that matches its value where all client logs will be located. This is the only place where application need write access.

16. Setup printer. All printing in FWD comes from the FWD clients, not the FWD servers. This is due to the client-centered design of the Progress 4GL. In an interactive Progress application (not on an "appserver" or in Webspeed), printing is done using specific Windows APIs (in GUI applications) or in UNIX or Linux by using child process support. In either case, the processing runs on the client side. In FWD, the system on which the FWD client runs must appropriate printers defined/configured and operations in the operating system. Queues and connectivity for all the printers must be setup and the printers must be turned on, attached to the system/network and ready to accept jobs.

File System Structure¶

The client application need just a few files to run. As a consequence a file system structure is not usually needed, all application files can reside into the root of the installation.

However, for a good organization, here is an example of files and their location in a client installation.

File structure		Details
$P2J_CLIENT		The root of installation
	client.sh	Shell script that automates the startup of the client
$P2J_CLIENT/bin		Subdirectory that contains binary files needed to run the client
	libp2j.so - on Linux/UNIX p2j.dll - on Windows	Native startup library
	p2j.jar	Runtime of FWD client application
$P2J_CLIENT/cfg		Configuration subdirectory
	client_shared.xml	Shared bootstrap configuration file (when used in split configuration mode).
	client_custom.xml	Custom bootstrap configuration file (when used in split configuration mode).
$P2J_CLIENT/log		This subdirectory will hold logs from client The name must fit the value of $P2J_LOG_DIR.
	client_joe_1894.log	Sample log file. The name will be client_<userid>_<pid>.log where the <userid> is found via the program whoami and the pid is the process ID of the shell process.
$P2J_CLIENT/security		Any security files needed by server security will be kept here. For FWD clients that connect to a to FWD server that validate SSL connections, they must have a trust-store file that contains the certificates for the root CA.
	keystore.store	A keystore file containing [CA] client's private-keys.[/CA]
	truststore.store	A truststore file.
$P2J_CLIENT/tmp		Temporary files location.
	ncurses_curses_h_in_20060828.patch	Diff file needed to patch the NCURSES package. (May be removed after install)
	ncurses_lib_getch_c_v5.7_20090512.patch
[CA]$P2J_CLIENT/spawner		The FWD spawn tool. Full details about its setup and configuration are found in the Spawner Setup and Configuration chapter of this book.
	p2j.jar	The FWD jar file. On Linux/UNIX, the permissions need to be set to 0550.
	spawn - on Linux/UNIX spawner.exe - on Windows	The spawn tool. On Linux/UNIX, the permissions need to be set to 4755.
	srv-certs.store	The server trust-store. On Linux/UNIX, the permissions need to be set to 0550.
	spawn.ini	Spawner configuration file (only on Windows).[/CA]

---

© 2004-2017 Golden Code Development Corporation. ALL RIGHTS RESERVED.