Client Installation¶

• Client Installation
  • System Requirements
    • Hardware
    • Operating System
    • Networking
      • Network Path to the Application Server
      • Network Path to the User's Web Browser
  • Choosing the Appropriate JVM
  • Choosing the Client Implementation
    • FWD Console Client
    • FWD ChUI Swing Client
    • FWD ChUI Web Client
    • Batch Client Driver
    • FWD GUI Swing Client
    • FWD GUI Web Client
    • FWD GUI Embedded Client
  • Installation Process
    • Install the Java Virtual Machine
    • Patch NCURSES - Linux Only
    • Patch TERMINFO - Linux Only
    • Install libffi
    • Create the FWD Client Directories
    • Create the FWD User Accounts
    • Install FWD Application Client
    • Setup the Spawner
    • Client Startup Script
    • Setup Client Configuration Files
    • Copy the Security Related Configuration Files
    • Firewall Setup
    • Update CLASSPATH
    • Application-Specific Platform Dependencies
      • Set Operating System Environment Values
      • Install Configuration or Data Files
      • Install Programs or Libraries
      • Setup Application-Level Environment Variables
      • Create Necessary Directories
      • Setup Printers
    • Set File System Permissions
  • First Time Java Usage - Windows only
  • File System Structure

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 database access of ANY kind is executed on the FWD Client. The client process is often called the "thin client". It 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 “primitives“ - this allows the client code to be completely generic (not application specific) as well as reasonably small in working set (memory and code). Examples of primitives:

• user interfaces primitives, to manipulate the widgets and windows (the UI)
• OS-related primitives, to manipulate file system access and process launching
• memory-related primitives, to manipulate memptr addressing
• library call primitives, to manipulate calls into native libraries

For more details on the thin nature of the FWD Client and the contrast with the Progress OpenEdge runtime, please see the Progress ABL is Inherently a Single Threaded Fat Client and the Client Platform Delegate documents.

System Requirements¶

Hardware¶

Please see the Client System Requirements for details on the FWD Client hardware requirements.

Operating System¶

Java processes are normally platform neutral. When applications or tools are written in pure Java, it is possible for such processing to be run on any operating system or hardware platform that supports the proper level of J2SE (Java 2 Standard Edition) required. From the software point of view, you can install the client on any operating system as long as there is a JVM implementation for it.

At this time, while the vast majority of the client FWD code is written in pure Java, there is a small amount of platform-specific code (written in C) used for character mode user interface processing, process launching, native memory access and native library calls. That platform-specific code is implemented using the Java Native Interface (JNI) and is often referred to as “native” code. A customized version of that native code is included in the FWD project. This code is currently compiled as a 32-bit or 64-bit shared library for Linux (libp2j.so) or Windows (p2j.dll).

The ChUI Native Client (based on NCURSES) can be run without an installed graphics environment. For the Web clients (ChUI Web Client, GUI Web Client and GUI Embedded Client), the client will be spawned automatically, with no required graphics environment. A desktop environment is required only if you want to use the ChUI Swing Client or the GUI Swing Client. Also, for the legacy ABL AppServer Agent support or the batch clients, the FWD clients will run in a headless mode, with no associated UI.

Choosing to run one of the clients that use a Swing display driver will allow running the application on any operating system with a graphical system on which a Java distribution exists, including Linux, Windows and MacOS. The only issue here is that there must be a native port of the FWD JNI code and its native dependencies (libffi and in some cases NCURSES). At this time, only Linux, Solaris and Windows have such ports. MacOS is not yet supported.

Networking¶

Network Path to the Application Server¶

Unless all the clients are on the same system as the application server there will be more network traffic with a FWD implementation than with Progress OpenEdge implementation because of the design of the FWD runtime.

There is one client per ABL client program that is running. This means each interactive user, batch process and Appserver/WebSpeed agent will have a matching client process. There is one socket opened between the application server and each of these client instances. That per-client socket is kept open for the duration of the client's session with the application server. If there are non-ABL applications and/or batch programs that connect to the FWD server, then there is at least one socket open for each of them. Hand coded applications can create more than one session with the server, if they do that, there is 1 socket per session.

If the clients and application server reside on the same system, then there is typically nothing to do to enable connectivity. However, if any clients run on a separate system, then the firewall setup on both the client and the server must be configured to properly support the port(s) in use.

At this time, there isn't a specific equation that can be used to estimate the network traffic, since there are many variable factors. Although the exact amount of traffic is application-specific, ensure high performance for the network connection between the clients and the application server in order to achieve optimal performance.

Network Path to the User's Web Browser¶

When connecting to the FWD Application Server via the browser (using a FWD Web Client), then there are two ports in use: the port to access the FWD login page (for non-embedded clients) and the port on which the FWD Client's embedded web server will start (for all clients), after launching the associated FWD Client JVM.

If the browser accessing the web client and the associated Web Client JVM are on the same network (or on the same machine), then here is typically nothing to do to enable connectivity. However, if this is done from separate systems, then the firewall on the client must be configured to properly support the port(s) in use.

The FWD Web Client will rely on a websocket connection between the Browser and the embedded web server running in its associated FWD Client JVM; the communication protocol over this websocket allows passing input from the user (key-presses, mouse events) to the FWD Client and the FWD Client passing drawing primitives (and other commands) to the FWD Web Client. The performance of the FWD Web Client running in the browser will depend on the network latency between the systems where the browser and the actual FWD Web Client JVM are running.

Choosing the Appropriate JVM¶

The core requirement for the JVM is that it must be compatible with Java 8.

Each FWD component (conversion, application server, client, user-defined functions running at the database) can use a different JVM. These can run on the same system or different systems. They can even run on a different operating system platform. There is no dependency between JVMs of different components, since they are separate operating system processes.

The following JVM versions have been well tested:

• Oracle JDK 1.8 on Linux
• Oracle JDK 1.8 on Windows
• OpenJDK 1.8 on Linux
• OpenJDK 1.8 on Windows

The specific versions of Oracle JDK 1.8.0_101 and OpenJDK 1.8.0_111 have both been tested and have been found to work well. Generally, it is safe to use any later version of the Java 1.8 platform.

• The thin client does not need large amount of memory to run, this means that the heap can (and should) be limited in size.
• The client does not process any data except for the displaying primitives received from server and any file-system or other OS related calls (which map to ABL features). The improved performance of a x64 built JVM is insignificant.
• All things being equal, the memory footprint is greater on a 64-bit JVM as the pointers are twice as long as the pointers in a 32-bit JVM. Java uses pointers intensively as all references to objects (except for the scalars) are in fact pointers. This leads to the fact that a 64-bit JVM takes between 40% and 50% more memory on average than a 32-bit JVM.

Using the 32-bit version will greatly reduce the memory footprint and overhead of each JVM instance. On client systems where there will be large numbers of JVM instances (often at least one per user), this can accumulate into a significant savings.

From a heap perpective, the FWD Client needs enough memory to handle its windows, frames, widgets, streams and other ABL resources (and their contained data). These can be used in a deeply nested manner, which means that some programs can create many such resources simultaneously. However, even in such a case the memory requirements of the client tend to be quite limited.

For the above reasons, there is no strong requirement for the 64-bit JVM. Using a 32-bit JVM for this purpose will be faster and will use less memory. Use a 32-bit JVM if possible. Even applications with deeply nested UI processing can usually be run with max heaps of 16MB to 32MB.

Choosing the Client Implementation¶

Depending on your application, FWD provides a variety of clients which can be used to access your application deployed via the FWD Application Server. If your application is a ChUI application, you can use console, Swing or Web clients. If your application is a GUI application, you can use Swing, Web or Embedded clients. Also, legacy ABL AppServer agents can be spawned as FWD Clients.

If you are using any of the web clients, you will need to have the FWD client spawner installed. Also, when spawning clients for appserver agents, optionally you can configure and start a FWD client to act as a broker, so that it will spawn FWD clients on behave of a FWD server, on a machine different than the one where the FWD application server runs.

FWD also provides support for ABL non-interactive batch clients - these are called FWD batch clients.

For any client running in a browser (ChUI Web Client, GUI Web Client or GUI Embedded Client), the supported browsers are latest versions of Google Chrome, Mozilla Firefox, Internet Explorer 11 and Microsoft Edge browser. In all cases, the web client can be accessed from any machine (even from the Internet), with the only constraint that the FWD Application Server is setup so the access host/port and the redirection host/port are reachable by that machine - see the Firewall Setup section for details.

Mobile support for the FWD Web Clients is not tested at this time; if the mobile browser is able to run JavaScript code, then this might work (or it can be made to work with minimal effort). Also, the Web Clients have no inherent touch support - the UI is supposed to be accessed via mouse, and access via touch commands might not work. Another limitation is automated scaling of the UI for small screens: if the GUI window has a size larger than the browser's native resolution, then it may not fit the screen.

If self-signed certificates are used for the HTTPS connections, the browser will require you to accept the certificate before accessing the FWD Web Client page for the first time; this message will vary from message to message, but the common approach will be to add an exception for this certificate or to trust it always.

FWD Console Client¶

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

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

FWD ChUI Swing Client¶

The Swing driver is an alternative to using the console-based client. This is the first example of a non-native client "driver". It is fully functional with only minor limitations. For Swing clients to work, the OS must support a graphics environment.

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.

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.

FWD ChUI Web Client¶

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.

Batch Client Driver¶

The batch driver is a special driver used to run batch processes or Appserver Agents. In these 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.

Although the Progress OpenEdge acts differently when the OS process associated with the ABL batch program is run in the background, FWD does not automatically detect this fact at this time. FWD allows configuring such background mode clients explicitly, to allow full compatibility with the legacy system.

FWD GUI Swing Client¶

The Swing GUI driver is a dedicated driver for GUI clients. There are no OS dependencies; the only requirement is that your JVM must be able to execute Swing code and the OS must support a graphics environment.

Using this is a fat client install of FWD and the GUI is run locally on the system. Since it is a "fat client", the FWD code must be installed on that system. However, the converted application does not run in the FWD client, so the deployment is easier than in Progress OpenEdge.

FWD GUI Web Client¶

The GUI Web Client is fully OS-independent, and runs in your browser, in a virtual desktop. Supported browser are Google Chrome, Mozilla Firefox, Internet Explorer 11 and Microsoft Edge browser. The browser will establish 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.

FWD GUI Embedded Client¶

FWD provides a mechanism to integrate a customer web application with legacy FWD GUI screens. In this mode, the FWD client will run in an embedded iframe, and all the windows will be shown without chrome (title bar, border, status area, message area), to integrate with the other components of the web application. In this mode, clients are spawned and connect in the same way as the FWD GUI Web Client.

This mode allows up-calling from Javascript into the converted ABL code, providing an appserver-like functionality directly from Java.

Installation Process¶

We will assume that the operating system is already installed and up-to-date, and there exists a build FWD version which has its FWD native library and spawn utility built to match the OS and CPU architecture on which the FWD client will be installed.

If one of the web clients is in use 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 for details about how to setup and configure the spawner.

To allow FWD Agents (for the legacy appserver support) to be started on different machines, see the Remote Launchers chapter for details on how to setup a FWD client to act as a Broker.

Install the Java Virtual Machine¶

Please check previous paragraphs for details on what JVM to download and install. Although it is possible to use a JRE for the client installation, the following instructions describe installation of the JDK. Use of a JRE is beyond the scope of these instructions.

sudo apt-get install openjdk-8-jdk openjdk-8-source
cd /usr/lib/jvm
sudo rm default-java
sudo ln -s java-8-openjdk-amd64 default-java
sudo rm /usr/lib/libjvm.so
sudo ln -s /usr/lib/jvm/default-java/jre/lib/amd64/server/libjvm.so /usr/lib/libjvm.so

export CLASSPATH=.

Patch NCURSES - Linux Only¶

If the FWD's libp2j.so library was built on the same machine were the FWD clients will run, then NCURSES patching was already done as a prerequisite for building this library. Otherwise, this step is only needed if you choose to run the client with native (console) driver, and you should already have a built libp2j.so library.

Please see Patching NCURSES for the details.

Patch TERMINFO - Linux Only¶

This step is only needed if you choose to run the client with the native (console) driver.

Please see Patching TERMINFO for the details.

Install libffi¶

In order to support the calling of native library calls from Java code, FWD depends on Portable Foreign Function Interface Library (also known as libffi). The FWD JNI library is dependent upon libffi.

If the FWD client system will also be used to build FWD, you MUST install the development version of libffi.

The following instructions are valid only if the system is being used for running the FWD Client, but NOT for building FWD.

In all cases, the bitness of this library must match the OS architecture and also the bitness of the JVM used by the FWD clients.

Create the FWD Client Directories¶

See the File System Structure for a recommended directory structure. These directories should be created so that the FWD code can be placed there.

If the standard client startup script will be used for launching the FWD clients and the P2J_LOG_DIR environment variable is defined, create the folder that matches the P2J_LOG_DIR value. This is where all client logs will be located. This is the only place where FWD code itself will need write access (of course, the converted application code itself may have requirements for write access).

sudo mkdir /opt/fwd/
sudo mkdir /opt/fwd/lib
sudo mkdir /opt/fwd/client
sudo mkdir /opt/fwd/client/cfg
sudo mkdir /opt/fwd/client/security
sudo mkdir /opt/fwd/client/tmp
sudo mkdir /opt/fwd/client/log

mkdir c:\opt\fwd/
mkdir c:\opt\fwd\lib
mkdir c:\opt\fwd\client
mkdir c:\opt\fwd\client\cfg
mkdir c:\opt\fwd\client\security
mkdir c:\opt\fwd\client\tmp
mkdir c:\opt\fwd\client\log

Above is assumed that the /opt/fwd/client (or c:\opt\fwd\client) will be the current (or working) directory for the process which will launch the FWD client. For the legacy AppServer Agents or web clients, the working directory will be specified in the server's directory.xml configuration. In this case, there will be no explicit script to launch the FWD client (as the it will spawned by the FWD Application Server), and all any logs, file system access, etc will be done relative to this working directory. There will be no need to keep cfg, security or log folders for these clients, just ensure all Application Specific Platform Dependecies are installed properly for these clients.

Create the FWD User Accounts¶

On the client system under which context the FWD client will run, there must be an account for each end user that will be running a client process. The users may be included in the same group (so that they can access the same FWD client binaries).

In addition, if there are batch processes, they will need to be started in the context of some appropriate user account, since they run as a full, non-interactive, 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.

sudo groupadd fwd-users
sudo adduser fwd-user fwd-users

net localgroup fwd-users /add
net user fwd-user /add
net localgroup fwd-users fwd-user /add

If this machine is shared between both clients and servers, make sure the FWD server/ folder (where the server's directory, configuration, startup script, etc - see FWD Application Server File System Structure) is not accessible by the FWD clients. This means you must never use the FWD Application Server OS account for any FWD Client session. Otherwise FWD clients would have the ability to modify the directory, access private keys and generally do anything they want.

Install FWD Application Client¶

The following files from the FWD production build must all be copied to the same target directory. They are the native library (includes the ChUI terminal code and some other custom code needed by i.e. running native APIs or native memory access), the archive that contains the FWD Java code and other dependencies. The FWD native library and the FWD jar 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.

Make sure to run the FWD build process using the distribution target. After this, the client distribution binaries will be found in the fwd/dist/client folder; the compiled FWD binary will be found in the fwd/build/lib/p2j.jar location.

The p2j.jar file in turn is dependent upon another jar file or files, which have been specified in file's manifest. This means that as long as the p2j.jar can be found in the Java CLASSPATH and those other jar files exist in the same directory, the client will work properly.

The native library file is built by the same build process that builds p2j.jar and is used with JNI to provide process management services needed by language statements which create child processes, like INPUT THROUGH, INPUT-OUTPUT THROUGH, UNIX, OS-COMMND etc. This file needs to be copied
to the same location as the p2j.jar file, or in a location which exists in the global (or user's) path. This location will be used when launching the client, to specify the java.library.path parameters for the JVM. That will allow the FWD native library to be loaded as a JNI library.

The FWD native library has to match the bitness of the installed JVM. When building, the resulted native library will be built with 32-bit or 64-bit, depending on the development environment in which the FWD project was built.

For more details on each of the jars dependency, see the Software Dependencies chapter.

cd ~/fwd && ./gradlew distribution && cd
sudo install -d /opt/fwd/lib
sudo cp ~/fwd/dist/client/* /opt/fwd/lib/
sudo cp ~/fwd/build/lib/p2j.jar /opt/fwd/lib/
sudo cp ~/fwd/build/lib/libp2j.so /opt/fwd/lib/
sudo chown -R :fwd-users /opt/fwd/lib
sudo chmod 0550 /opt/fwd/ /opt/fwd/lib
sudo chmod 0440 /opt/fwd/lib/*

cd c:\fwd
gradlew.bat distribution
mkdir c:\opt\fwd\lib
copy c:\fwd\dist\client\* c:\opt\fwd\lib\
copy c:\fwd\build\lib\p2j.jar c:\opt\fwd\lib\
copy c:\fwd\build\lib\p2j.dll c:\opt\fwd\lib\
takeown /f /u fwd /p PasswordForUser_fwd_Here c:\opt\fwd\lib /r /d y
icacls c:\opt\fwd\lib /setowner fwd /T /C
cacls c:\opt\fwd /E /P fwd-users,r
cacls c:\opt\fwd\lib /E /P fwd-users,r
cacls c:\opt\fwd\lib\* /E /P fwd-users,r

Setup the Spawner¶

If using web clients or if the FWD Application 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 for details about how to setup and configure the spawner.

On Windows, there is an addition installation dependency for the spawn.exe. It is important to ensure that the Microsoft Visual C++ Runtime Redistributable is installed as documented in MSVCR100.DLL Dependency.

Client Startup Script¶

Full details on how to launch the FWD client can be found in Running the Client.

For web clients, no explicit startup scripts are required, assuming the spawner is installed properly. For Swing or terminal clients, the FWD client uses a script to launch. Assuming that the startup script documented in that chapter is used to start the client, the following scripts need to be copied from your deploy/client folder of the converted application:

cd /opt/fwd/
sudo mkdir /opt/fwd/client
sudo cp /opt/cvt/deploy/client/client.sh client/
sudo chown :fwd-users client/client.sh
sudo chmod 0550 client/client.sh

cd c:\opt\fwd\
mkdir client
copy c:\opt\cvt\deploy\client\client.cmd client\
takeown /f c:\opt\fwd\client /u fwd /p PasswordForUser_fwd_here /r /d y 
icacls c:\opt\fwd\client /setowner fwd /T /C
cacls client\client.cmd /E /P fwd-users,r

The script will setup the FWD Application Server's classpath to include the application jar files (converted and also any other customer-specific jars). These are prepended to the classpath.

Setup Client Configuration Files¶

Most clients are configured with command line parameters or options. Launching the client is usually scripted to make launching easy while still mapping to local configuration variations as needed.

In addition to command line configuration, the client can be customized with one or two bootstrap configuration files. These are XML files that contain hard coded configuration values and which are read at startup.

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 on how to create these files and the values that can be configured there.

The bootstrap configuration files are especially useful in cases where you have a FWD account which needs to authenticate via a certificate. In these cases (FWD batch processes or FWD broker clients), the details about the certificate and private key used by the authentication will need to be specified in the bootstrap configuration file.

To avoid this need for client-side configuration, it is possible for batch processes to be started via:

• Execution of the FWD Application Server startup script with batch mode command-line arguments. This can only be done on the application server system itself and by an operating system account which has the rights to access this script and the associated private key of the server. The batch process will be launched by the target FWD Application Server (locally or remote), in its own context, using the OS account set at the FWD process account.
• Batch processes can be auto-launched by the FWD Application Server at server startup or via the scheduler. This is the recommended approach. It can be used with local or remote spawning.

Full details can be found in the Batch Processes chapter.

For interactive clients which authenticate via a username and password or clients which authenticate via the converted application's business logic, the bootstrap configuration file can be omitted and all details included via the client launch script in the launch command. This is the common case for most clients.

Copy the Security Related Configuration 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

Use the above links to understand how to create the associated files. The Quick Start section will provide details on how to use ChUI and GUI project templates to make it easier to create a working configuration.

Copy each of these files into a directory on the system which will be the current (or working) directory for the FWD client process.

sudo mkdir /opt/fwd/client/cfg
sudo mkdir /opt/fwd/client/security
sudo cp ~/cfg/client_shared.xml /opt/fwd/client/cfg/
sudo cp ~/cfg/client_custom.xml /opt/fwd/client/cfg/
sudo cp ~/cfg/keystore.store /opt/fwd/client/security/
sudo cp ~/cfg/truststore.store /opt/fwd/client/security/
sudo chown :fwd-users -R /opt/fwd/client/
sudo chmod 0440 /opt/fwd/client/cfg/* /opt/fwd/client/security/*

mkdir c:\opt\fwd\client\cfg
mkdir c:\opt\fwd\client\security
copy c:\cfg\client_shared.xml c:\opt\fwd\client\cfg\
copy c:\cfg\client_custom.xml c:\opt\fwd\client\cfg\
copy c:\cfg\keystore.store c:\opt\fwd\client\security\
copy c:\cfg\truststore.store c:\opt\fwd\client\security\
takeown /f c:\opt\fwd\client /u fwd /p PasswordForUser_fwd_here /r /d y
icacls c:\opt\fwd\client /setowner fwd /T /C
cacls c:\opt\fwd\client /E /P fwd-users,c
cacls c:\opt\fwd\client\cfg\* /E /P fwd-users,c
cacls c:\opt\fwd\client\security\* /E /P fwd-users,r

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. If Web clients are used, the firewall must allow an inbound HTTPS server socket connection (with subsequent 2-way communication), used by web or embedded clients.

The FWD Application Server uses both secure and insecure ports to accept incoming connections. These ports are specified when at the server startup, via the net:server:secure_port and net:server:insecure_port bootstrap configuration. In the default server startup script (which can be found in the Hotel demo applications), the port base is 3333 for a secure connection and 3433 for an insecure connection, to which the server's instance number is added. If you don't specify any -i <instance> argument when executing the server startup script, these default ports will be used.

1. the port configured in server/default/adminPort (set to 7443 in the FWD Hotel and Hotel GUI demo applications). This is the port on the server's host where a web client will access the login page. For embedded web clients, this port will not be used.
2. the server/webClient/port setting will specify the port where the FWD Web Client will connect after login, or where the embedded clients will connect: if set to 0, then a random open port will be used; otherwise, this exact port will be used, and only one web client will be able to connect, at a time (useful for testing/debugging purposes).

The FWD Web Client implementation (both ChUI and GUI) will dynamically spawn the client and redirect the initial session from the FWD server to the newly spawned embedded web server on the client. When the web client is being accessed from the Internet or from any situation where the FWD server and clients reside behind a firewall, a reverse proxy will be needed to handle the connectivity. Please see #2683 for details on reverse proxy support.

The converted ABL code may explicitly use network resources on the client. Even though the converted code runs on the application server, when it uses sockets, server sockets or Web Services (SOAP) it will rely on the FWD client to access these remote resources. This means the firewall setup on the machine where the FWD clients will run must allow outbound connections to these hosts/sockets, and also inbound connections, in the case of server sockets usage.

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

Application-Specific Platform Dependencies¶

Progress ABL applications can access a range of platform-specific facilities. The most common of these facilities are file-system access (reading/writing files using streams, manipulating the file-system to move or delete files, accessing file-system meta-data), process launching (running shell/command prompt programs for interactive use, running child processes and reading from/writing to the process via streams) and printing.

All such local system access is done on the FWD client, not the FWD servers. This is due to the client-centered design of the Progress ABL. For example, 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.

The file-system must be setup in the structure, with the permissions and with the resources that are expected by the application. All the necessary processes must be available. Likewise, the appropriate printers must be defined/configured 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.

Set Operating System 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.

Install Configuration or Data 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.

Install Programs 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.

Setup Application-Level Environment Variables¶

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

Create Necessary Directories¶

If the application depends on a specific directory structure, it needs to be created. Make sure to assign the necessary permissions/ownership using the operating system security facilities.

Setup Printers¶

All printing in FWD comes from the FWD clients, not the FWD servers. This is due to the client-centered design of the Progress ABL. 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.

Set File System Permissions¶

• 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
• it must be able to establish an inbound HTTPS server socket (with subsequent 2-way communication) used by web or embedded clients
• it must be able to establish an output TCB socket connection (with subsequent 2-way communication) to any host and port targeted by a client socket or Web Service connection from the legacy application code.
• it must be able to establish an input TCB socket connection (with subsequent 2-way communication) to any host and port targeted by a server socket connection from the legacy application code.

sudo chown -R :fwd-users /opt/fwd/
sudo chmod 0550 /opt/fwd/ /opt/fwd/lib /opt/fwd/client /opt/fwd/client/cfg /opt/fwd/client/security
sudo chmod 0440 /opt/fwd/lib/*
sudo chmod 0770 client/log/ client/tmp/
sudo chmod 0550 client/client.sh
sudo chmod 0440 /opt/fwd/client/cfg/* /opt/fwd/client/security/*

takeown /f c:\opt\fwd /u fwd /p PasswordForUser_fwd_here /r /d y
icacls c:\opt\fwd /setowner fwd /T /C
cacls c:\opt\fwd c:\opt\fwd\lib c:\opt\fwd\client c:\opt\fwd\client\cfg c:\opt\fwd\client\security /E /P fwd-users,r
cacls c:\opt\fwd\lib\* /E /P fwd-users,r
cacls c:\opt\fwd\client\log c:\opt\fwd\client\tmp /E /P fwd-users,f
cacls c:\opt\fwd\client\client.cmd /E /P fwd-users,r
cacls c:\opt\fwd\client\cfg\* c:\opt\fwd\client\security\* /E /P fwd-users,r

First Time Java Usage - Windows only¶

Details can be found here: First Time Java Usage.

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.

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