Running the Client¶
- Running the Client
- JVM command line parameters
- Command line syntax and options
- Client logging and output
- ChUI drivers
- Accessing environment variables
- Connecting to server application
- Job Control and FWD 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:
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.ClientDriveris the application's main class,
app_arguments- arguments passed to the
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]
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:
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
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:
||Displays the help screen (including syntax and a brief description).
If present, it must always be the first and any other argument is ignored.
||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.
||The password to use to decrypt the first bootstrap configuration if file is encrypted. Use '
||The (relative or absolute) file path to second bootstrap configuration file if using a split bootstrap configuration.
||The password to use to decrypt the second bootstrap configuration if file is encrypted. Use '?' to force an interactive password prompt.
||An integer value that specifies the logging level that should be used before server's main configuration (in the directory) can be read
||Configuration values that add to or replace values that can be specified in the bootstrap configuration; the override must take one of three forms:
The shorter forms will use the most recently specified category and/or group as needed. See the “Bootstrap Configuration” chapter for details.
||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
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
The sample shell script
$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.
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:
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.
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
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
$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
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:
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.
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 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
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.