The PC Integration API allows you to integrate your browser screens with PC applications. For example, you may have the need to call up your PC-based imaging or document management application to view an invoice, part image, etc., based on a user action in the browser screen. The PC Integration API also allows you to copy data to the PC's clipboard. Genie's
STRPCCMD command support also makes use of the PC Integration API.
For obvious security reasons, the browser vendors have made it so that Web-based applications cannot call programs on the PC under normal security settings. This makes it challenging to integrate your browser-based screens with other applications in your environment. The PC Integration API solves this challenge by running the PC commands in either a separately installed PC program (PC Command Listener or PC Command Launcher) a Java applet (PC Integration Applet).
One of the following alternatives must be configured on the end user PC's before the PC Integration API can be used.
If your RPG program is calling STRPCCMD only to load web pages (some URL starting with http or https) in a browser and you can use Rich Display Files with the RPG program, then you do not need the PC Integration API. In this environment the simplest approach is to use Profound UI widgets or APIs to load the URL in a new tab or window in the user's browser. This avoids the need to install or configure additional software on each user's PC.
There are at least three ways to use this approach, and each involves binding a field in the Rich Display File, changing the RPG program to write the URL to that field instead of calling STRPCCMD, and letting some client-side code handle the bound field data.
- Bind a Hyperlink widget's "hyperlink reference" property to a field, and change the RPG program to write the URL to the field. Then, the user can click on the hyperlink to load the URL. Set the hyperlink widget's "target" property to "_blank" to open in a new browser tab/window.
- Bind an IFrame widget's "iframe url" property to a field, and change the RPG program to write to the field. This make a page inside a page. You may need to re-arrange the Rich Display File so that there is space to show the IFrame.
The widgets can be hidden conditionally until ready by binding the "visibility" property.
Note: when writing a URL to a field, you omit commands like "START IEXPLORE.EXE"; just write the URL. which is the part beginning with "http://" or "https://".
PC Command Listener
The PC Command Listener runs on any Windows Vista, 8, 7, or 10 PC.
Installing and Configuring the PC Command Listener on the PC
This is a standard Windows program installer that works in the typical way. The program is installed for all PC users and registers itself to run on Windows startup. The program runs in the System Tray. The tray icon has a context menu that can be used to start/stop the listener and to configure the port number.
PC Command Listener Command-line Installation
The MSI installation package can also be run from a command prompt or script using the Windows 'msiexec' command. When installing using 'msiexec' the configuration data can be passed on the command line using the --CONFIG parameter. The configuration will be written to the PC's program data directory, which is shared by all PC users. For example, to set the listen port to 8100, disable notification messages, and disable logging:
PC Command Listener Logging
By default, PC Command Listener does not log any information regarding the commands it receives. As of Launcher version 1.0.10, the Listener can be configured to log the commands received. Logging can be enabled via the Listener's System Tray context menu under "Configure...". Alternately, the "log commands" property can be passed in an argument to the "msiexec" command as indicated in the section above.
The log file will either be located here:
Configuring the Server for the PC Command Listener
In Profound UI versions Release 6 Fix Pack 6.0 and earlier, the default mode of operation for the PC Integration API is to use the Java applet. In those versions the configuration option pui["use pc listener"] must be set in order to use the Listener. With all versions, optionally pui["pc listener port"] must be set in order to use the Listener, depending on which TCP port your Profound UI instance expects the listener on. Options to configure the PC Command Listener are also provided in the Genie Administrator. If specified, these will take precedence.
(Profound UI Version 5, Fix Pack 12.0 and earlier)
PC Command Listener on HTTPS (SSL) Servers
To enable a Rich Display session running on HTTPS to send commands to the Listener, the configuration option pui["pc listener mode"] must be set. Genie automatically detects the site is using HTTPS, so that option isn't necessary for Genie.
PC Command Launcher
The PC Command Launcher is an alternative to the Command Listener and the applet. The Launcher enables the PC Integration API to function in any web browser, in HTTP or HTTPS (SSL) pages, and in browsers running in Terminal Services sessions. However, as with the Listener, a program must be installed separately on end user PCs. Another disadvantage is that the Integration API gets no feedback about the command's status. If the command fails to run, then the API doesn't know. Consequently, the command "wait" is not implemented. Each command is executed as soon as it is received, and no commands can wait until the previous command finished.
Once the PC Command Launcher program is installed on a PC, the Launcher will handle any requests to a custom protocol. The Integration API will open a custom URL containing some encrypted information with the command, and the browser will attempt to run the Launcher. There is no interface to the PC Command Launcher. However, the first time a PC Command is sent via the Launcher mode, the browser will prompt the user before running the launcher:
If your web browser supports it, the user can check the "Always open these types of links in the associate app" checkbox and then click the "Open..." option, so that they will no longer be prompted before the command runs.
PC Command Launcher works with Profound UI Version 5, Fix Pack 13.0 and later.
Installing and Configuring the PC Command Launcher on the PC
The download is a standard Windows program installer that works in the typical way. The program is installed for all PC users.
PC Command Launcher Command-line Installation
The installer package can be installed from a Windows command line without displaying an interface. For example, do an install with no UI:
The installer needs administrative privileges.
Configuring the Server for the PC Command Launcher
The default mode of operation for the PC Integration API is to use the PC Command Listener. To use the PC Command Launcher, pui["pc command mode"] must be set to "launcher". Options to configure the PC Command Listener are also provided in the Genie Administrator. If specified, PC Command Mode will override "pc listener mode" and "pc listener" options.
Enable Logging for PC Command Launcher
By default, the Launcher does not track any information about the commands it receives. As of Launcher version 1.0.2, the Launcher can be configured to log the commands received. A log may assist in debugging commands sent from the IBM i, or logs can be reviewed for security auditing.
To enable logging, a Windows Registry key must be modified: Computer\HKEY_CLASSES_ROOT\puilaunch\Shell\Open\Command. A flag, "/logtofile", must be added to the end of the (default) entry in that key.
The log is saved to the Windows "All Users" folder, %ProgramData%, which is usually c:\ProgramData and hidden from most users. The log file is %ProgramData%\Profound UI\Logs\pccommand-launcher.txt. The date and the PC user's username appear first, then the unencrypted command or filename received. If the command fails, then an error code is also recorded.
Uninstalling the PC Command Launcher from the PC
The launcher can be uninstalled like any other program, using Windows' Add/Remove Programs:
Or the Windows Control Panel:
PC Integration Applet
The PC Integration applet runs in the Java Virtual Machine's browser plug-in on the end user's PC. The only current browser that supports the Java plug-in is Internet Explorer. Chrome, Firefox, and Edge do not support the Java plug-in.
Installing PC Java Plug-in and Verifying Version
As mentioned above, the Sun plug-in is required. The user can verify the version and install it if necessary at this URL: http://www.java.com.
- Click on the "Do I have Java?" hyperlink to test the version.
- This brings up the verification page. If the latest version of Sun Java is installed, a "congratulations" message will appear.