Web Deploying Forms and Reports

Audience:

• Forms Developer
• Support Engineer
• Business Intelligence Developer
• Technical Consultant
• Reports Developer

Suggested Prerequisites:

• Develop Forms applications with Oracle Developer Suite 6i
• Use a Web browser

Benefits of Deploying Forms Applications to the Web

• Improving Productivity
• Reducing Costs
• Increasing Accessibility
• Maintaining Support
• Leveraging Current Knowledge
• Providing a Rich User Interface
• Employing the Latest Technologies
• Utilizing New Product Features

Streamlining of Oracle Forms

• Elimination of Character Mode and Client-Server Run-time Executables
• Elimination of Item Types and Built-Ins That Are OS-Specific or Related to Character Mode
• Elimination of Obsolete Features from Older Forms Versions

Migrating Forms Applications

• Considering Pre-Upgrade Issues
• Using the Correct Migration Path
• Using Forms Builder to Migrate
• Using Forms Compiler to Migrate
• Using Forms Migration Assistant
• Considering Post-Upgrade Issues

Utilizing Forms Services

• Forms Servlet
• Forms Listener Servlet
• Forms Runtime Engine
• Forms Client
• Starting a Run-Time Session
• Selecting a Java Runtime Environment

Testing and Deploying Forms Applications

• Testing Applications
• Generating Applications
• Deploying Applications
• Constructing a URL to Run the Application

Configuring Run-Time Behavior

• Configuring the Forms Servlet
• Configuring the Environment
• Customizing the User Interface
• Using Configuration Files

Adapting Features That Work Differently on the Web

• Adjusting Fonts
• Key Mapping
• Integrating Oracle Graphics
• Calling Reports from Forms
• Displaying Images
• Displaying Icons

Adapting Features with Performance Implications

• The SYNCHRONIZE Built-In
• Timers
• Tabbed Canvases
• Mouse Event Triggers

Adapting Client-Server Specific Features

• When-Mouse-Move|Enter|Leave Triggers
• GET_FILE_NAME Built-In
• Image Control Palette
• Dialog Window Style
• VBX, ActiveX (OCX)
• OLE Containers
• Sound Items

Adapting Platform-Specific Features

• Built-Ins Work on Middle Tier
• OLE Automation
• User Exits
• Case Sensitivity
• D2kwutil

Enhancing Forms Applications with Web Technologies

• Using JavaBeans to Extend Functionality
• Using PJCs to Extend the User Interface
• Launching a Web Page from Forms
• Integrating Web Services
• Integrating Forms Applications with Oracle Application Server Portal

Using WebUtil to Interact with the Client

• Configuring WebUtil
• Integrating WebUtil into a Form
• Opening a File Dialog on the Client
• Reading an Image File from the Client
• Writing Text Files on the Client
• Executing Operating System Commands on the Client
• Performing OLE Automation on the Client
• Obtaining Environment Information about the Client

Using New Integration Features of Forms 10g

• Configuring JVM Pooling
• Managing Forms Services with Oracle Enterprise Manager
• Implementing Single Sign-On

Using Other Web-Related Features of Forms 10g

• Implementing Run-Time Pooling
• Performing Remote Debugging
• Enabling Browser Language Detection
• Restricting Parameters That Can Be Passed in the URL

Integrating Forms and Reports Applications

• Using RUN_REPORT_OBJECT to Run a Report with the Reports Multi-Tier Server
• Displaying a Report from Forms
• Calling a Report with the WEB.SHOW_DOCUMENT Built-In

Why Move Reports Applications to the Web?

• Reducing Costs
• Improving Productivity
• Increasing Accessibility
• Maintaining Support
• Publishing Enterprise Data
• Leveraging a Standards-Based Architecture
• Utilizing New Features

Migrating Reports Applications

• Deprecated and Obsolete Functionality
• Migrating a Report Application
• Reports Builder User Interface Changes
• Formatting with the SRW Built-in Package
• Replacing OLE2 Objects
• Migrating Charts
• Replacing Buttons
• Referencing System Parameters

Developing Reports for the Web

• What is JSP Technology?
• Building a Web Report
• JSP Tags
• Generating Output
• Adding Dynamic Content
• Customizing Reports JSPs
• Creating a Web Layout Template
• Creating a Parameter Form

Using New Features in Oracle Reports: Development

• Accessing Data with Pluggable Data Sources
• Bursting on a Repeating Group
• Adding a Table of Contents
• Using PDF in Oracle Reports
• Inline Formatting Using HTML Tags
• Using External Style Sheets
• Adding a Graph to a Web Report
• Integrating with Oracle JDeveloper

Deploying Reports Using OracleAS Reports Services

• Running the Web Layout
• Running the Paper Layout
• Deploying a Report
• Using a Key Map File
• Extending Oracle Reports Functionality Using Plug-ins
• Managing and Monitoring OracleAS Reports Services
• Implementing Single Sign-On

DEPLOYING FORMS ON THE WEB

Companies are now making a move from the client-server model of Forms to the 9i/10g Application Server Web-based architecture. Now the questions that are appearing with greater frequency on Oracle-related websites, including Oracle's own MetaLink site.

As an Oracle DBA, people could find themselves in the position of being told to resurrect old Forms 6.0 or 6i forms and reports and making them available on your company's intranet So, with these two Oracle users in mind (the developer and the DBA), let's look at a deployment framework that simplifies and explains what it takes to deploy forms on the Web.

How to get from Forms 6i to 9i/10g

First of all ensure to have a backup copy of Forms source code. This includes fmb's, mmb's, and pll files. After doing this you are now ready to start converting your 6i forms into a 9i/10g state. Which Oracle product are you going to use to perform this conversion? This answer is the Form Builder found in Forms 6i.

If a form compiles under 9i, it will compile under 6i. The reverse is not necessarily true, but you can make it that way. Two commonly used built-in's in Forms 6i (change_alert_message and enable_menu_item/disable_menu_item) are obsolete in 9i. These have become set_alert_property and set_menu_item_property under 9i. These built-in's work in 6i, so to make the appropriate changes using the 6i Form Builder, your 6i fmb will successfully compile itself. Checking the execution of revised fmx file can be done by running it in the client-server mode. The specifications for these built-in's are shown in the 6i Form Builder Using the 9i version of Form Builder (or the 10g version, which is really release 9.0.4), open the 6i fmb and compile the module, BUT DO NOT SAVE IT. If you save your 6i fmb as a 9i fmb, you cannot go back to a 6i state. Yes, the 6i fmb will open, but you will find that much of your code has disappeared. That is why you have a backup of everything. If there is a compilation error under 9i, fix it (and save it) using 6i Form Builder, then re-compile under both Form Builder versions. This approach allows you to keep one source code repository and be able to generate fmx's for two different versions of Forms. Additionally, running the fmx from Form Builder is a lot quicker than running its 9i counterpart on the Web. If the form runs fine in 6i, it will most likely run fine on the Web.

Oracle included a migration utility to take a 6i fmb to a 9i state, but it is found that it does not work that well. If you have a lot of forms to migrate, you can open several at a time and use the Find and Replace function in the PL/SQL editor to make your changes. It is actually easy to perform this step while using Form Builder because you will quickly develop a pattern in how you make the edits. If the two aforementioned built-in's are biggest changes, you can easily convert around 100 forms in an hour. If any of these forms call reports, you have some extra work ahead of you.

By using the f90genm executable to compile your 6i fmb's into a 9i state. This process can be tied into a shell script, but remember to pipe the output into a log file so to see if there were any compilation errors.

Finally, don't forget to compile the attached library files and menu files, All of these 9i-enabled fmx's, mmx's and plx's can be placed in one or more directories as specified by the FORMS90_PATH environment variable found in the default.env file.

How to view your new 9i forms on the Web

How did users call the 6i forms in the client-server environment? If anybody who has used a master form that calls other forms (and reports), you can use the same form in 9i. The master form has everything listed in drop-down menu lists. This master form can be specified in the formsweb.cfg file on the "form=" line. This simplifies the URL your users will use to launch your forms. Using "http://server:port/forms90/f90servlet" will cause an Oracle logon window to appear. After a successful logon, the master form appears, and from there, all forms can be called. The unstated tip here is that if you did not have a master form in 6i, think about making or using one in 9i. Your users will appreciate the point and click approach to call a form as opposed to entering URL after URL.

While testing new 9i forms on the Web, use Application Server to call/view them. There is no need to "turn on" the Developer Suite version of Application Server. By this way, there is no configuration needed in Developer Suite by just doing it once in Application Server have a configured Application Server.

One another area to be looked is viewing a 9i form concerns the appearance of a form on the Web. Some text and display items may be truncated when the form is viewed in a browser. For example, if you have a "Save" button on a form, the "Save" text may appear as "Sa..." if the button is disabled. By adding some extra width to the button the text will appear. The same thing applies for text alignment and justification.

Quick tip about Oracle JInitiator

It is the first time a form on the Web, will be prompted to download and install Oracle JInitiator. 99% of the time, this does not gives any problem. Some users will receive errors during the installation process (messages about not being able to install 16-bit Windows applications, a temp directory not being found, etc.). Do not waste time trying figure out why the user's computer is looking for some nonexistent temp directory. Copy the jinit.exe file to the problem PC. Right-click the file and extract it locally. Once that is accomplished, the setup.exe file can be run.

In closing

With a small amount of planning and prior preparation, migrating 6i forms to a 9i state is a fairly painless process. An application that currently uses the client-server architecture to port your forms on the Web, all supporting client-server environment, you will use and maintain one source code repository. In addition to the ease of testing for compilation purposes, using Form Builder 6i is a sensible solution for preventing the problem of maintaining two sets of source code.

DEPLOYING REPORTS ON THE WEB

The steps to get your Reports on the Web

The steps to use Reports-related built-in's in your forms, how to "tell" your forms the name of your report server, how to toss in some JavaScript so an "Exit" button will exit a form and close the browser window, and how to use and configure the in-process report server. As in the Forms on the Web article, we will not discuss Reports development.

Establishing a baseline example

Because there are so many variations of how to configure various components, the following assumptions are made for Forms and Reports development-to-deployment environment.

• Your 6i forms have been successfully migrated to a 9i/10g state
• If using Application Server 10g Forms and Reports Services (the steps here work for the full scale version as well) and everything will be on one server
• When Reports were used in your 6i client-server environment, the reports were called via a "Run Report" button on a form or via a report filter type of form (it also uses a "Run Report" button after the user inputs parameter type of information)
• Reports on the Web will appear in a new browser window, and that browser window has its "normal" buttons removed (when the user is finished viewing, saving, or printing the report, the user closes the browser window and returns to the report-calling browser window)
• If a user wants to save a report, he has to click on the Save button (reports appear as PDF documents), and reports cached or saved on the Application Server machine are not intended to be directly accessed by users

The code to make a report run on the web

Difference between parameters and data

Parameters tell the report how it is supposed to run or display. Data is what the report shows. How you provide the data to make a report run is up to you. How you provide the parameters falls into two categories: those required by Oracle, and those you want or need. Further, several items that you used to pass in as parameters under 6i are now required to be used as a built-in with 10g. The best way to describe the code is to show an example. Some of what is shown below comes from an example Oracle has in a note on MetaLink. The code below is what you can put behind a "Run Report" button.

PROCEDURE RUN_REPORT IS
 
-- Some variable you use to populate a report table named REPORT,
-- Or call some procedure to generate data for a report
 
v_report_uui    REPORT.report_uui%TYPE;
 
-- Parameter List used in call to Oracle Report "rpt_name"
 
p_rpt_param_list  paramlist;
 
report_id       REPORT_OBJECT;
ReportServerJob VARCHAR2(100);
v_jobID         VARCHAR2(100);
rep_status      VARCHAR2(20);
reportserver    VARCHAR2(30);
v_url           VARCHAR2(200);
v_url2          VARCHAR2(200);
 
-- However you keep track of reports; this is just one way
 
usr_sessionid   NUMBER;
 
report_not_generated EXCEPTION;
 
BEGIN
 
--Get the user session ID
 
SELECT USERENV('sessionid') into usr_sessionid FROM DUAL;
 
-- Execute database stored package.procedure "some_package.some_procedure"
-- that populates a REPORT table
 
some_package.some_procedure
(
to_char(:block.some_item),      -- IN
v_report_uui                    -- OUT
);
 
-- Destroy the parameter list if it already exists
 
IF NOT Id_Null(p_rpt_param_list) then
Destroy_Parameter_List(p_rpt_param_list);
END IF;
 
-- Create a Parameter List
 
p_rpt_param_list := Create_Parameter_List ('tmp');
 
-- Generate report - on the Web
-- You can add an ELSE clause to this to re-use your 6i code
 
IF (get_application_property(user_interface)='WEB') THEN
 
-- You need to provide the name of the report server
-- The "rpt_name" is a report object you create in the Form Builder Object
-- Navigator
 
reportserver := :parameter.reportserver;
report_id := find_report_object('rpt_name');
 
-- These five calls to the built-in cover what 10g requires
 
SET_REPORT_OBJECT_PROPERTY(report_id, REPORT_COMM_MODE, SYNCHRONOUS);
SET_REPORT_OBJECT_PROPERTY(report_id, REPORT_EXECUTION_MODE, BATCH);
SET_REPORT_OBJECT_PROPERTY(report_id, REPORT_DESTYPE, FILE);
SET_REPORT_OBJECT_PROPERTY(report_id, REPORT_DESFORMAT, 'pdf');
SET_REPORT_OBJECT_PROPERTY(report_id, REPORT_SERVER, reportserver);
 
-- Here is where you can add your own parameters to the report
 
Add_Parameter(p_rpt_param_list,'paramform',TEXT_PARAMETER,'no');
 
Add_Parameter(p_rpt_param_list,'p_report_uui',TEXT_PARAMETER, to_char(v_report_uui));
 
Add_Parameter(p_rpt_param_list,'PRINTJOB',TEXT_PARAMETER,'NO');
 
-- A common error message has to do with not being able to find the report object.
-- No report object means no report_id, and you'll get lots of errors.
 
ReportServerJob := run_report_object(report_id, p_rpt_param_list);
v_jobID := substr(ReportServerJob,length(reportserver)+2,length(ReportServerJob));
 
IF ReportServerJob is NOT NULL THEN
rep_status := report_object_status(ReportServerJob);
 
WHILE rep_status in ('RUNNING', 'OPENING_REPORT','ENQUEUED') LOOP
rep_status := report_object_status(ReportServerJob);
END LOOP;
IF rep_status != 'FINISHED' THEN
raise report_not_generated;
END IF;
 
-- The JavaScript command/string can be used to show a basic browser window
 
v_url := '/reports/rwservlet/getjobid'||v_jobID||'?server='||reportserver;
 
-- The following is one long string, carriage returns used for formatting
 
v_url2 := 'javascript:window.open("'||v_url ||'", "", "fullscreen=no,
titlebar=no, location=no, toolbar=no, menubar=no, status=no, resizable=yes");
 
-- "self.close" shown below is continued from the line above, carriage return
-- here for formatting, but it is really one long string
 
self.close()';
 
-- This is the built-in that calls a new browser window
 
Web.Show_Document(v_url2,'_blank');
ELSE
raise report_not_generated;
END IF;
 
 
END IF;
 
-- Destroy the parameter list. Report has been generated - it's no longer needed
 
Destroy_Parameter_List(p_rpt_param_list);
 
EXCEPTION
WHEN report_not_generated THEN
 
-- "am" is a shortcut to call an alert message. If you are raising a lot of alert messages in
-- your forms, add a procedure in Program Units. It takes the string you pass in and will
-- save you lots of time by not having to keep writing set_alert_property(...).
 
am('There was an error in running the report.'||chr(10)||
'Contact the Application Server administrator for assistance.');
WHEN OTHERS THEN
user_show_error;
 
END;

To standardize your Forms and Reports development environment, all that needs to be changed is the name of the report, and even then, you can pass that in to the procedure via the code behind when-button-clicked for the "Run Report" button. Calling a Form needs to have a report object added to it (that's covered in Oracle's documentation) in addition to having a "reportserver" parameter (the name of the report server).

Deploying Reports on the Web

Naming the report server and passing it to a form

One way to pass the name of the report server is to hard code it in the parent menu-type form. Hard coding is generally bad, but at least it's contained in one place (the calling form). Another way is to pass in the report server name via the URL you use to call your menu form in the first place. Use the "otherparams" line in the formsweb.cfg file. Hard code the name of the report server, by using a configuration.

Which report server to use?

Assuming that Application Server is installed, and server's host name is prod. Navigating to the ORACLE_HOME/reports/conf directory, a file named rep_prod.conf is seen. Copy that file and name it prod.conf. Technically, there is no need to copy the file, as Application Server will create it for you the first time you use the in-process report server, but is easy for ahead of time so it can be configured prior to first use.

Open the prod.conf file. It's an XML file. The good news is that only this has to be edited (around line 15, use sourceDir to tell Application Server where your reports are located). The features and options configured via this file are too numerous to be discussed here, but the sourceDir property is required.

Edit the reports.sh (UNIX) file in the ORACLE_HOME/bin directory. Around line 62, add your reports location to the REPORTS_PATH variable.

To start the in-process report server on UNIX, for example, issue the following command at the command prompt (as the owner of the 10g installation):

ias@prod: rwserver.sh server=prod batch=yes &

This starts another process that should be persistent. The report server itself, however, will be idle after 15 minutes of non-use (see idleTimeOut at line 48 if you want to change the default value to something else). If the report server has idled out (gone to sleep, so to speak), the report "waking up" the report server will take a bit longer than normal to appear.

If you use the Enterprise Manager console, you will see references to the rep_prod (rep_name-of-your-server) report server, which is the stand-alone report server. You can ignore it because you're using the in-process report server.

At this point, anyone should be able to call reports. Test this via the Application Server "home" page at http://server_name:port_number.

Closing your Forms main menu page

Oracle left out a feature for Web forms, one that will close the browser window for you. Currently, if you just exit the main form, you're left with a dull-colored applet window. Thanks, what do we do with that? Add an "Exit" button to the main form, and add this to a post-form trigger:

web.show_document('close.html','_self');

In the ORACLE_HOME/Apache/Apache/htdocs directory on the Application Server machine, create a file called close.html and add this to the file:

<html>
   <body onload="closeit()">
      <script>
         function closeit() {
         win = top;
         win.opener = top;
         win.close (); }
      </script>
   </body>
</html>

Clicking on "Exit" will send the browser to the close.html file and the JavaScript "closeit" function will close the browser window.