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.
- 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.
- Close Notepad and you'll be able to go back to the demo.
- 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.
- Press the Host button.
You now have two Notepad windows! Leave them both running and return to
the demo screen.
- 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.
- Close the Notepad window and return to the Form.
- 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:
- 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
- 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 its
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.
- 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.
- 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
- 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:
- There is only one Host PJC in the Form.
- The ClientHost package has been placed in a Non-Shared library (or is in
the Form itself)., If the package is placed into a shared library and more
than one Form has a Host Bean, then the package will not work consistently
as it only stores a reference to a single BeanArea. (The last one to be registered).
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
- Copy the supplied hostforms/java and host90.pll to your existing forms\demos\lib
directory.
- Copy the host.html file to your forms\demos\doc directory
- Copy the host.jar file to your forms\demos\jars directory
- 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.
- Open Internet Explorer or Netscape.
- Enter the URL for the PJC demo.
http://<yourmachine>:8888/forms/frmservlet?config=pjc_demos
- Hit the exit button in that demo but do not close the browser
- Now issue the following URL in the same browser window:
http://<yourmachine>:8888/forms/frmservlet?config=pjc_host
- When prompted by JInitiator to trust the certificate by Product Management
do so.
- 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.