How Do I Debug Oracle9 i Forms Developer Pluggable Java Components?

An Oracle9 i Forms Developer How-To Document
Version 1
February 11, 2003

Contents

• Introduction
• Setting up and Debugging your projects
  • Prerequisites
  • Step 1 - Prepare your JDeveloper project
  • Step 2 - Create a debug_pjc.html file
  • Step 3 - Add the debug_pjc.html file to your project
  • Step 4 - Set your breakpoints
  • Step 5 - Debug your Form
• Additional Information

Introduction

Pluggable Java Components (PJCs) provide a powerful mechanism for extending the Forms Java Client with custom functionality. However, PJCs have to be written in Java and the process of debugging such components when embedded in the Forms runtime using print statements alone, is time consuming. This How-To takes you through the steps required to set up your Oracle9 i Forms Developer installation and Oracle9 i JDeveloper 9.0.2 to debug your PJC code live inside of a running Forms application. These instructions also equally apply to Oracle9 i JDeveloper 9.0.3 (although the screen layouts may be slightly different).

This How-To does not cover the basic steps of building a PJC. For more information on creating PJCs see:

• "Developing PJCs Quickstart" For a step by step guide to PJC creation on the OTN forms Upgrade Center: /products/forms/htdocs/upgrade/pjc/index.html
• A viewlet of the the Pluggable Java Components Wizard in Oracle9 i JDeveloper at: /sample_code/products/forms/index.html
• The Forms help system.

Setting up and Debugging your PJC Project

Prerequisites

These instructions assume that you have already set up and are successfully running both Oracle9 i Forms Developer and Oracle9 i JDeveloper, that you have an existing PJC project in JDeveloper that you wish to debug, and an existing test Form which uses that PJC. The locations of any Forms, Menus or Libraries that you are using as part of the test should be defined in your FORMS90_PATH environment variable.

Furthermore the instructions assume that you are developing using a standard Oracle9 i Forms Developer OC4J installation listening on port 8888 on your development machine. If this is not the case, you will have to make some slight changes to the instructions below to conform to your actual configuration.

Step 1 - Prepare your JDeveloper project

If you are creating a PJC you will already have the f90all.jar file associated as a library in your project. However, if you have patched your Oracle9iDS install you may have several versions of the f90all.jar file available. When debugging through JDeveloper you need to ensure that the library being used in JDeveloper is the same version as that being used by your Form install. The simplest way to do this is to ensure that the f90all.jar that is being used is the one from your %ids_home%/forms90/java directory.

To confirm this, select your project and choose Project Settings and select the Libraries node in the navigator. You should see a library entry for Oracle Forms in the Selected Libraries list. Select this and click the Edit button to confirm that you are indeed using the version of f90all.jar from your forms90/Java directory. For example:

Fig 1- Editing the location of the f90all.jar file

If you do not use the correct version of f90all.jar you may get a runtime error "Client too Old" if that happens, edit the library location as described above.

Step 2 - Create a debug_pjc.html file

The key part of setting up PJC debugging is the creation of an HTML file to launch your test Form in a way that can be used for debugging. The following file provides a basic template.

Fig 2- Template Debugging HTML file

Note that the Archive attribute of the <APPLET/> tag only contains the f90all.jar. It does not contain a jar file with your PJC code in it. This code will be picked up from your JDeveloper project.

In this basic html template, the only value you will have to change to match your project is the value of the serverArgs parameter which will need to be updated to name a suitable test form to launch, and any other Forms parameters such as the logon information that are required.

This html file should be called something suitable such as "debug_pjc.html" and should be saved into the %ids_home%/forms90/Java directory.

Step 3 - Add the debug_pjc.html file to your project

To debug your PJC you will be running the html file that you have just created. Select your project and click the Add to Project button select the debug_pjc.html file that you have just created from the %ids_home%/forms90/Java directory.

Step 4 - Set your breakpoints

You are just about ready to run and debug your Form and PJC from within JDeveloper. All you have to do now is to set up suitable breakpoints in your PJC code. With most PJCs all of the calls come through the setProperty() and getProperty() methods so those are a good place to start.

Step 5 - Debug your Form

To debug your PJC, ensure that your OC4J engine is started, right mouse click on the debug_pjc,html file to get the context menu, and choose "Debug debug_pjc.html".

JDeveloper will start an AppletViewer process (the size of this AppletViewer window is controlled by the HEIGHT and WIDTH attributes in your html file) and your Form will run within the AppletViewer frame. When your PJC breakpoint is encountered as you run the Form, control will return to JDeveloper where you can inspect variables and step through and debug your custom code.

Additional Information

1. You can see an on-line viewlet of this process at /sample_code/products/forms/index.html - choose the Debugging PJCs link.
2. If when running or debugging from JDeveloper you get an error about Registry.dat not being found substitute your machine name or real IP address into the html file in place of 127.0.0.1 in the CODEBASE  value in the debug_pjc.html. On Windows NT as a further step you may have to remove the http:// prefix before your machine name in the CODEBASE. e.g. CODEBASE="my-dev-machine:8888/forms90/Java"
3. If the Form or pl/sql library cannot be found when running through the html file ensure that your FORMS90_PATH is not too long.  A FORMS90_PATH defined in the Window registry cannot exceed 255 characters.  If the path is too long it will be ignored not truncated.
4. The technique described here is defined solely for the purpose of debugging PJCs. When running in this mode, the Forms Servlet has limited functionality and cannot use facilities such as environment files that would normally be configured through the formsweb.cfg. As such it is important that your base operating system environment has the correct variables defined to allow your forms to run without additional information having to be defined in a .env file.
5. The use of the AppletViewer as a container for running Forms applications is restricted to debugging use and it is not a supported client deployment method.