Client "Host()" Command Executor Pluggable Java Component

The Host() Pluggable Java Component (PJC) is a JavaBean designed to extend the capabilities of the Forms Java Client to add the capability to execute operating system commands, much as the conventional Host() built-in does, but rather than executing these commands on the application server machine, the command is executed on the machine that is running the Forms Java client in a browser.

Version Compatibility

The Host() PJC as provided is compiled using Java 1.3 and has been tested with Oracle Forms and JInitiator 1.3.1.9. The Java code supplied can be recompiled to operate with JInitiator 1.1.n or native Internet Explorer with Forms 6i. However, in this situation you will have to re-sign the host.jar file using the procedures for Java 1.1 or create a signed .cab file respectively.

How should I use this demo?

Here is an example of what you can do in this demo.  It is assumed the client is running on Microsoft Windows.

  1. Enter "notepad" in the field.  Choose Blocking from the poplist.  Press the Host button.

    Note that Notepad appears.  Without closing Notepad, go back to the Forms application.  Notice that you can't interact with it?  That's because it's blocked, waiting for the Notepad process to close.
     
  2. Close Notepad and you'll be able to go back to the demo.
     
  3. Select Non-Blocking from the polist, and press Host.

    As expected, Notepad appears.  Leave it running and go back to the Form.  This time you can keep using the Form, because it's non-blocking.
     
  4. Press the Host button.

    You now have two Notepad windows!  Leave them both running and return to the demo screen.
     
  5. Press the Kill last button.

    This will kill the newest Notepad window.  Pressing Kill last won't kill the first Notepad window.  There's no reason why this can't be done, though.  It's just that this demo only remembers the id of the last process it launched.  You could build your own application to store all of the process ids launched and stop any of them.
     
  6. Close the Notepad window and return to the Form.
     
  7. Select Async Callback from the poplist and press the Host button.

    Notepad appears.  Close it and return to the demo form.  See how you received an alert?  With Async Callback, Forms can be notified when the process is finished.

    The Return Code says 0, which means there were no errors.

Preparing the Host() PJC for use

You can use the Host() PJC as supplied – as it stands the PJC is signed using a temporary demonstration certificate generated by Oracle. In your own systems that use this PJC you should re-sign the host.jar file with your own certificate (whether self generated or purchased from a certificate authority).

For JInitiator 1.3 use the JarSigner utility from the Java SDK for signing.

Using the Host() PJC

To install and use the Host PJC into a form follow these steps:

  1. Create a block to hold the PJC (or you can re-use an existing control block). This block should have the “Single Record” Property set to “Yes”
  2. Create a bean area in your form. This bean area must be on a canvas that is visible to the user, as the PJC will not be instantiated until it’s canvas is displayed. The Bean Area can be sized at 1x1 with no bevel and no foreground or background color, in order to render it invisible to the user. The Visible property of the Bean should be set to Yes.
  3. Set the Implementation Class property of the Bean Area to “oracle.forms.demos.host.Host” (without the quotes and with no leading or trailing spaces). Note that this class name is case sensitive.
  4. In your formsweb.cfg file, edit the profile for the application that will be calling the Form that you have just added the Host() functionality to. You need to add the host.jar file to the list of jars for the client to download. The list of downloaded jar files are defined by the various values that can be specified for the archive tags (archive_jini, archive_ie and archive) e.g. for an application using JInitiator set archive_jini=frmall_jinit.jar,host.jar
  5. The Host() PJC is now ready to use in the Form.

The PL/SQL API for Client Side Host commands

The host PJC can be directly manipulated with calls to Get and Set_Custom_Property from within PL/SQL, however, for convenience, a PL/SQL package ClientHost is provided in the file host90.pll. This PL/SQL library can be directly attached to your form, or you can simply copy the ClientHost package spec and body into the form or your own library.

To use the ClientHost package, you should first register the name of the Bean Area that you have created to hold the Host PJC. This allows all of the subsequent host related commands to be automatically sent to that bean. Use the ClientHost.registerHostBean() procedure to do this. Once the bean is registered you can that use the various execute commands to call a client side program.
The full list of available functions within the ClientHost package is detailed in the table below.

API Purpose
procedure registerHostBean(hostBean in VARCHAR2) RegisterHostBean (procedure) defines the name of the Bean Area that is using the Host PJC.
You must call this procedure before doing any host calls but it only needs to be done once.
If the Bean Area registered does not exist, the exception NO_DATA_FOUND will be raised.
procedure execute(hostCommand in VARCHAR2, executionMode in PLS_INTEGER )

Execute (procedure) executes the specified hostCommand using one of the following execution modes:

  • ClientHost. BLOCKING - The Forms client will wait until the HOST process finishes before control returns to the user Note: This means that the Forms Client will not re-draw if occluded. If the host command will take any time to execute consider using ASYNCHRONOUS mode.
  • ClientHost.NON_BLOCKING - The Forms client will execute the host command and control immediately returns to the user. The return code and console output are not guaranteed to be available in NON_BLOCKING mode. NON_BLOCKING is best used to launch interactive host programs such as a word processor which, once launched, Forms has no further interest in.
  • ClientHost. ASYNCHRONOUS - The Forms client will execute the host command and immediately returns control to the user. When the Host process completes, an event (HOST_CALLBACK) will be raised in the When-Custom-Item-Event trigger on the PJC Bean Area.


The procedure returns no value but the return code from the host command and any console output can be retrieved
using getHostReturnCode() and getHostConsoleOutput() respectively (note these values may not always have a value depending on the command exec uted and the mode)

function execute(HostCommand in VARCHAR2) return NUMBER Execute (Function) executes the specified hostCommand using one of the execution modes defined above.
The function returns the return code set by the host process So is always run in BLOCKING mode.
As with the procedure version of execute, the return code and console output can be retrieved asynchronously using
getHostReturnCode() and getHostConsoleOutput()
procedure terminate Terminate kills the last host process started. Only has an effect if that command was started in ASYNCHRONOUS
or NON_BLOCKING mode
function getHostReturnCode return NUMBER

GetHostReturnCode. Returns the return code generated by the last command executed.

A return code of -1 may indicate that the command has not yet completed.

function getHostConsoleOutput return VARCHAR2

GetHostConsoleOutput returns the console output (stdout) of the last command executed.
A null return code indicates that the command has not yet completed

Note: This value is not guaranteed to capture all of the console output from the host command and should be used with caution as a result.


Note: When using the ClientHost convenience package the following is assumed:

Demonstration Form

The utility is provided with a small demonstration form which shows the functionality of the ClientHost package. This demo form requires that the Oracle Forms Demos have already been installed into your iDS instance.

To run this demonstration form, follow these steps

  1. Copy the supplied hostforms/java and host90.pll to your existing forms\demos\lib directory.
  2. Copy the host.html file to your forms\demos\doc directory
  3. Copy the host.jar file to your forms\demos\jars directory
  4. Create the following profile entry in the forms\server\formsweb.cfg file

[pjc_host]
pageTitle=OracleAS Forms Services - Client Side HOST()
form=hostforms/java
archive=frmall.jar,/formsdemo/jars/demo.jar,/formsdemo/jars/host.jar
archive_jini=frmall_jinit.jar,/formsdemo/jars/demo.jar,/formsdemo/jars/host.jar

Special Notes

Due to a problem with certificate importing, the very first time you want to run the Host demo you will have to carry out the following steps.  These are only required the very first time you run this demo.

  1. Open Internet Explorer or Netscape.
  2. Enter the URL for the PJC demo.
    http://<yourmachine>:8888/forms/frmservlet?config=pjc_demos
  3. Hit the exit button in that demo but do not close the browser
  4. Now issue the following URL in the same browser window:
    http://<yourmachine>:8888/forms/frmservlet?config=pjc_host
  5. When prompted by JInitiator to trust the certificate by Product Management do so.
  6. The demo will then run successfully

Once you have trusted the certificate you will be able to run th e pjc_host configuration directly in future.