Executing a Windows Program From a Classic Page

This document describes how to launch a process from the browser on a local Windows workstation. This can be useful in some cases, although it can create security flaws.

Description

A dedicated feature allows you to launch applications (as long as they are in the registry) on the local workstation from a classic page session using the 4GL Callui statement, relayed by Asynchronous Pluggable Protocols stack (or APP). Unlike the 4GL System statement, this implementation does not support I/O flow control on the process called. It is just a "Launch and forget" mode, used in an asynchronous way.

Make sure you update the Windows registry on a local workstation to register the application you want to launch, based on APP specifications. Refer to Registering an Application to a URI Scheme for more information.

Every application that can be launched is identified by a unique name (the APP protocol name). For example, if you want to launch notepad.exe, you can call the component "SageX3ProtocolTest". The APP protocol must be registered for "SageX3ProtocolTest" by adding this Windows registry branch: 

[HKEY_CLASSES_ROOT\SageX3ProtocolTest]
@="URL:SageX3ProtocolTest"
"URL Protocol"=""
[HKEY_CLASSES_ROOT\SageX3ProtocolTest\shell]
[HKEY_CLASSES_ROOT\SageX3ProtocolTest\shell\open]
[HKEY_CLASSES_ROOT\SageX3ProtocolTest\shell\open\command]
@="notepad.exe"

The corresponding 4GL script is as follows: 

Local Char RETOUR(250)
Callui RETOUR="" With     "UIAction="+chr$(1)+"OpenFile",
&                         "UILocalDir="+ chr$(1) +"APP",
&                         "UIWindowTimeOut="+ chr$(1) +"10000",
&                         "UIWindowName="+ chr$(1) +"My window App  ID",
&                         "UIWindowFeatures="+ chr$(1) +"width=300,height=300",
&                         "UILocalFile="+ chr$(1) +"SageX3ProtocolTest:
  • The UILocalDir parameter is mandatory. It is a constant and must be set to "APP".
  • The UILocalFile parameter is mandatory. It contains the APP protocol name, and optionally, the command line.
    Caution: The maximum length for UILocalFile is 200 characters. If the parameter value is greater than 200 characters, the parameter must be split in several occurrences, each one prefixed by the occurrence index (chr$(i)).
  • The UIWindowFeatures parameter is optional. It allows you to set the Windows size of the browser window used by "APP".
  • The UIWindowName parameter is optional. It allows you to set the browser window name bound to the "APP" application. If this paramter is not set or if it is empty, "_blank" is used by default.
  • The UIWindowTimeOut parameter is optional. It allows you to automatically close the browser window used by "APP" after a timeout (in milliseconds).

The last two optional parameters allow you to control the behavior of the "APP" browser window to offer a more user-friendly experience.

Workaround

The command line propagated to the process called contains the APP protocol name (SageX3ProtocolTest in our example). If the process to call requires command line arguments, it must be able to correctly parse the command line in order to skip or ignore the protocol name.

If the process called cannot handle this constraint, it is possible to call the process via a DOS script instead. In this case, both 4GL script and Windows registry data must be adapted accordingly.

Registry

[HKEY_CLASSES_ROOT\SageX3ProtocolTest]
@="URL:SageX3ProtocolTest"
"URL Protocol"=""
[HKEY_CLASSES_ROOT\SageX3ProtocolTest\shell]
[HKEY_CLASSES_ROOT\SageX3ProtocolTest\shell\open]
[HKEY_CLASSES_ROOT\SageX3ProtocolTest\shell\open\command]
@="c:\\temp\\test_app_notepad.bat \"%1\""

4GL script

Local Char RETOUR(250)
Callui RETOUR="" With     "UIAction="+chr$(1)+"OpenFile",
&                         "UILocalDir="+ chr$(1) +"APP",
&                         "UIWindowTimeOut="+ chr$(1) +"10000",
&                         "UIWindowFeatures="+ chr$(1) +"width=300,height=300",
&                         "UILocalFile="+ chr$(1) +"SageX3ProtocolTest:~C:\Tem",
&                         "UILocalFile="+ chr$(2) +"p\test_app.txt"

DOS script

The script is called test_app_notepad.bat.

The command line relayed by APP is split (as shown by the "~" character) in order to retrieve the end application startup arguments.

@echo off
for /f "delims=~ tokens=1,2" %%a in (%1) do set param=%%b
start notepad %param%