Project

General

Profile

Running the Client

The client can be launched from command line in the installation directory using a command as simple as:

TBD: missing command line.

assumming that java binary directory is added to PATH operating system environment variable, all client binaries reside into current directory and the server is running on standard port on local machine. However, because of the multitude of application options and JVM parameters usually the client application is launched by a shell script names client.sh that automates the client's startup. It handles all JVM command-line parameters detailed below and also the application arguments. It assume that all binaries (java and any native code is located into bin subdirectory of the installation root).

JVM command line parameters

The JVM can be customized to load and fit the needs of the running client application. The general syntax for launching the client application is:

where:

  • jvm_options - command line options given to the JVM to define the parameters in which the JVM will function and additional features,
  • com.goldencode.p2j.main.ClientDriver is the application's main class,
  • app_arguments - arguments passed to the ClientDriver class, main() method.

CLASSPATH setup

First, to be able to load the application JVM needs to know what is the application composed of. The client code of the client is packaged in the p2j.jar file. This archive MUST be added to JVM's class path in order to be loaded:

Native library location setup

As the client loads native compiled code using JNI, it must have access and be informed where [CA] remove libTerminal.so reference [CA] libp2j.so (or p2j.dll on Windows) binaries are located. Java environment variable java.library.path that it's used to specify the location is by default uninitialized so it must be explicitly added to command line using -D parameter. This is not necessary if the client is running with swing ChUI display driver:

Heapsize

In order to load the application JVM has to know how much memory to reserve. The default heap size in JVM 6 is 25% of the amount of free physical memory in the system. A good size is 32 MB which is large enough to fit the application and a larger heap will cause garbage collection pauses to increase because there is more heap to scan. Also it seems to be a good practice to enable java server optimizations with the penalties of using a little more memory and a small startup delay:

If the JVM runs out of memory you can increase the heap size and, optionally, dump heap content to a file for later analyzing and debugging purpose using -XX:+HeapDumpOnOutOfMemoryError and -XX:OnOutOfMemoryError='./stack_dump.sh %p'.

Debugging the application

For debugging purpose alter the command line like:

Now you can use now a local/remote debugger to attach to the running process on port 4444.

Command line syntax and options

The syntax accepted by the client is the following:

Each line is optional and is detailed in the next table:

Parameter Description
-? Displays the help screen (including syntax and a brief description).
If present, it must always be the first and any other argument is ignored.
config_1 The (relative or absolute) file path to first bootstrap configuration file. May be in xml/plain text format or encrypted for advanced security. Please see the “Bootstrap Configuration” chapter for details.
config_1_file_password The password to use to decrypt the first bootstrap configuration if file is encrypted. Use '?' to force an interactive password prompt.
config_2 The (relative or absolute) file path to second bootstrap configuration file if using a split bootstrap configuration.
config_2_file_password The password to use to decrypt the second bootstrap configuration if file is encrypted. Use '?' to force an interactive password prompt.
initial_debug_level An integer value that specifies the logging level that should be used before server's main configuration (in the directory) can be read
parameter_overrides Configuration values that add to or replace values that can be specified in the bootstrap configuration; the override must take one of three forms:
     category:group:key=value
     group:key=value
     key=value
The shorter forms will use the most recently specified category and/or group as needed. See the “Bootstrap Configuration” chapter for details.
application_arguments a list of application-specific strings which will be passed to the server class arguments() method. See the “Server configuration” chapter for more details.
If present it must always appear last.

Client logging and output

When running in application mode, the output of the client application can be captured and redirected to a log file. The devices STDIN or STDOUT cannot be used for redirection because the output will interfere with the [CA] console CHUI [CA] driver. So the proper way of capturing the application log to a file is using STDERR.

The sample shell script client.sh uses $P2J_LOG_DIR environment variable to locate the destination where log files will be placed. The name of an individual file 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:

The log output is enabled by application's configuration boolean item logging:debug:enable, the verbosity level is found on server and until retrieving it the value of -d application value is used. Enable this settings only for debugging sessions as it is very verbose and this can slow down a production installation.

ChUI drivers

As mentioned earlier in the “Client installation” chapter, the client can be started using:

  • native ChUI terminal emulator, as an application
  • Swing ChUI driver as an application or
  • Swing ChUI driver as an applet.

Selecting the appropriate driver can be done in the client's bootstrap configuration file.

Native CHUI client application

The native CHUI driver is fully compliant with original P4GL user interface. The main advantage of this ChUI driver is that it is the only solution for customers that still use hardware terminals. This is the default settins. If you want to explicitly configure the client application set the client:driver:type = chui_native into the to bootstrap configuration file. Launch the client application using the shell script.

Running the Swing CHUI Driver

It provides a swing-based CHUI client as an alternative to using the native CHUI client. This is the first example of a non-native client "driver". It is fully functional with only minor limitations. It works great for FWD testcases and even works well for larger applications! The swing client has 2 personalities: as a standalone Java application (as started by our own ClientDriver.java) or as an applet. You must not use it on servers accessed via ssh since you can't start an X session for Swing there! But it will work great on your local system.

Swing client application

For the application mode launch the shell script and having client:driver:type=swing_chui_frame set in bootstrap configuration file or as a command line argument. Adding the other settings from client:chui group is recommended, too:

Swing client applet

For starting the swing CHUI client as an applet the server's embedded Jetty environment has been modified to optionally serve this swing applet. Please note that there are more serious limitations when running as an applet, due to the inherent limitations of the applet security environment. As a consequence the applet is useful mostly for development purposes as long as they don't access the file system, launch child processes or otherwise try to access things that trip security limits.

The server's embedded Jetty environment has been modified to optionally serve this swing applet in addition to the administration client that it already supports. The adminPort node still determines the web server's port. We still only support HTTPS. However, the chuiApplet section can be enabled independently of the adminEnabled value (as shown above). The web server only listens on one port regardless of which applet(s) are enabled. To launch the client applet use:

https://localhost:7443/chui

Of course, you will have to accept the certificate exception just as you would do for the admin console as jetty module is only activated on secured connections.

The server's directory.xml was updated to include the section needed to enable applet support:

Web ChUI Client

The character mode (ChUI) web client can be accessed from any browser supporting HTML5, Web Sockets and AJAX requests. Details about these clients (setup, configuration, installation) can be found in the dedicated Web Client Setup chapter of this book.

Batch Process Clients

The batch process clients are FWD clients which mimic the legacy batch program behavior. These clients are allowed to be started in the same way as the legacy batch program was started; this includes:

  • runtime awareness if the standard INPUT/OUTPUT was redirected
  • configuration to set the client in “background” mode, via the client:driver:background@=true@ bootstrap configuration. This setting will allow a FWD client to act the same way as a legacy batch program for which its associated system process is in background.

For all batch programs, it is needed to set the client:mode:batch=true configuration and the client's driver also needs to always be set to client:driver:type=chui_batch.

A batch process can also be ran via the ServerDriver's -b <process-id> argument, with a command like:

java com.goldencode.p2j.main.ClientDriver -b <process-id>

In this case, the runtime will take care of automatically setting the batch mode and the driver type, to the appropriate values. For the setup needed to use this feature, see the Spawner Setup and Configuration chapter of this book.

Accessing environment variables

Some P4GL programs read environment variables and act accordingly. The FWD converts the system environments reads to java properties. This means that in order that the converted application to have access to original environment variables they must be known in advance and should be coded as properties to the JVM using -D parameter:

Here the $TOOL_PRINTER variable is 'passed' from the operating system environment to Java virtual machine in order to be accessible by the converted application.

Connecting to server application

The client is only a 'thin' application, it does not contain any code converted from original Progress application. To execute the code, the client have to connect to the server application, where the converted 4GL code truly runs. As usually in a multi-tier system, to connect to a server the client side needs to know the host on which the server application is running and the port it has open to accept connections. Another important thing in communication is the protocol, in this case we have two cases: insecure and SSL-secured connections.

On the client side there are two ways to specify the connectivity data. The first one is to add in the bootstrap configuration file the net:server group with port and host keys.

Another way to specify the host/port combination and eventually override the settings from bootstrap files is to use the corresponding command-line arguments with the needed values:

By default the host would default to localhost, but that can be overridden with -h <host> argument. With these options properly specified, the startup script will ensure that the command line is modified as needed for connectivity.

The secure/insecure port numbers can be specified either inside the bootstrap configuration xml or as arguments in the java command line. When specified on the command line it would look something like this: net:server:port=3333 net:server:insecure_port=3334.

In order to use secured connection a certificate is needed by the SSL handshake protocol between the client and server. See the security dedicated chapters (Certificate Authority, Loading Known Certificates, Key-Stores and Trust-Stores, [CA] FWD Cryptography Tool [CA] ) for more informations on this topic. [CA] Depending on how the certificates are configured, this [CA] information needs to be added to the bootstrap configuration file:

For more security the bootstrap configuration file that contains the passwords should be encrypted (see the “Bootstrap Configuration” chapter for this topic).

[CA] Note that any security configuration set in the bootstrap configuration will override the directory's security configuration (related to private keys, trust-store and encryption password for these private keys). [/CA]

Server instance number support

On systems where multiple application server instances will be started, each process will get an “instance number” from 0 to 9. This number is used to assign a different port for each server instance. The startup script use the value for the secure port which would be defined by either a -i<instance_num> parameter or the -p<port> parameter. The -i might calculate the secure port as 3333 + the <instance_number>. The -p might calculate the secure port as equal to <port>. Once the secure port is known the insecure port will be calculated by adding or subtracting some number to the secure port:

See the “Running the Server” chapter for details on this concept.

If server does not request any kind of authentication then the application code begin to be executed and the output will be displayed on the configured terminal emulator. If the server is configured with authentication by password the client will prompt you for your username and password before proceeding with running the actual application:

Entering a correct set of credentials will allow you to continue and run the application while entering a bad combination will quit the process.

Another kind of authentication is based on security certificates. If configured so, the server will only accept clients that have valid certificated and added to bootstrap configuration file(s). As this does not need the user to enter a password, it is well suited for batch programs that run in background periodically (E.g. a daily task that might be scheduled to run each day, at a fixed time using cron daemon). Special care must be taken here as the daemon might run under different credentials and the respective user must have needed needed permissions to read the application's binary files, write logs and other streams and, of course, open two-way communication with the server.

Stopping interactive clients is done using CTRL+C keystroke combination. However, if the 4GL code contains some retry clauses the effect may be different, some loop structures may restart the last iteration or the entire application can be restarted. An alternative way of stopping any kind of clients is by terminating their session from within the administration applet (see the “Accessing the Administration Client” chapter) which will lead to end of the process too. Of course, there is always the option of using unix/linux kill command to stop such a process, and this is also the solution for stopping non-interactive clients that run in background and do not have a “visible” console.

Job Control and FWD Client

In environments where interactive shells provide job control, some special care should be taken when providing custom shell scripts that launch FWD clients. An example of such an environment is the bash shell on Linux. The job control feature makes it possible to stop the client process at an arbitrary (user-specified) time by typing CTRL-Z on the terminal. The operating system suspends the FWD client process and the bash shell regains control, which would differ from a typical Progress environment. Below is the explanation of when and why this may happen and how to avoid it.

When CTRL-Z is typed in the terminal, bash, being the parent of the client JVM process, receives a SIGTSTP signal from the tty driver in the kernel, if the controlling terminal is not in “raw” mode. The kernel sends this signal to all processes in the foreground process group in the bash session. bash itself is in the group.

Under normal conditions, the FWD client will have set the controlling terminal into raw mode. When in raw mode, the SIGTSTP signal is not sent and there is no problem. However, every time the JVM launches an interactive child process, the terminal is restored to the regular “cooked” mode. If the user presses CTRL-Z while interacting with this child process, the kernel will generate the SIGTSTP signal.

In response, the JVM safely ignores the signal. Unfortunately, bash still receives the signal and then performs a "service" for us. It reacts to the signal by sending the SIGSTOP signal to the current processes in the foreground job. This latter signal cannot be caught, blocked or ignored. Thanks to bash, the JVM process stops unconditionally and bash displays the command prompt.

Disengaging the JVM from the parent bash won't help, since bash would display the command prompt immediately and the user would be able to interact with the same terminal in which the JVM is operating. This would create a situation where there is concurrent use of the same terminal, quickly resulting in screen corruption or hangs.

The solution is not to allow bash receive the SIGTSTP. One of the two known ways is the TRAP instruction. Another, more efficient way is to use exec to invoke JVM process instead of eval. This causes the parent bash to go away leaving no parent of the JVM process which can process the job control signals.

This issue only affects the NCURSES-based CHUI driver, since the swing-based driver does not run inside a terminal or shell environment.


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