Skip Headers

Oracle® Forms Migrating Forms Applications From Forms 6i 10g (10.1.2.0.2) for Windows and UNIX B15572-01 |
| Library | Product | Contents | Index

Previous | Next |

# 14 Integrating Reports and Graphics

This chapter contains the following:

- Chapter14, "Overview"

- Chapter14, "Oracle Graphics6i"

- Chapter14, "About Integration with Oracle Reports"

## Overview

Oracle Graphics6i is no longer shipped with Oracle Forms versions 9.0.2 and higher. In addition, the Charting wizard has been removed from Forms. This chapter describes how you can call existing Graphics6i and Reports applications from a form.

## Oracle Graphics6i

You cannot create new chart modules because Oracle Graphics6i is no longer shipped with Oracle Forms. However, you can display existing charts in Forms and Reports applications that have been migrated.

The following whitepapers at http://www.oracle.com//technology/products/forms provide additional information:

- Deploying Oracle Graphics in Oracle Forms Services 10g: Best practices for integrating Oracle Graphics in Forms on the Web

- Deploying Interactive Charts on the Web: Migrating from the Graphics Cartridge

- Integrating OracleAS Reports in OracleAS Forms

### Displaying Existing Charts in Oracle Forms

If your form contains embedded Oracle Graphics6i displays, you can still display them in Oracle Forms by doing the following:

- Use the Oracle Graphics (OG) package wrappers

- Be sure that Oracle Graphics6i is installed on the same machine as Forms Services, but in a separate ORACLE_HOME, for example, OG6I_HOME.

- On Windows, set the registry variable ORACLE_GRAPHICS6I_HOME to the ORACLE_HOME directory where Graphics6i is installed. This variable must be set in the registry key that contains other Oracle Forms registry variables. The version of Graphics6i must include Developer 6i Patch 8 or higher.

- On UNIX, set the environment variable ORACLE_GRAPHICS6I_HOME to the ORACLE_HOME directory where Graphics6i is installed. The version of Graphics6i must include Developer 6i Patch 8 or higher.

- If you use OG.PLL to run Graphics6i, then you must open and compile OG.PLL in Forms Developer before you can use it. OG.PLL also needs to be included in FORMS_PATH.

- Set the path definition in the Oracle Forms (not Forms 6i) servlet environment to include Graphics in the default.env file as follows:

      PATH=%FORMS_HOME%\bin;%ORACLE_GRAPHICS6I_HOME%\bin;

Note: You must also add the ORACLE_GRAPHICS6I_HOME and GRAPHICS60_PATH variables to the default.env file in Oracle Forms. You can add these variables with Enterprise Manager Application Server Control. For information on how to do this, see Chapter 4 of the Oracle Application Server Forms Services Deployment Guide part number B14032-01.

Note: The following registry entries are read directly from the Graphics 6i ORACLE_HOME registry: GRAPHICS60 = %ORACLE_HOME%\TOOLS\DBTAB60\GRAPH60 DE60 = %OG6I_HOME%\TOOLS\COMMON60 GRAPHOGD60 = %ORACLE_HOME%\TOOLS\DBTAB60\GRAPH60\GWIZ_OGD MM60 = %OG6I_HOME%\TOOLS\COMMON60 TK60 = %OG6I_HOME%\TOOLS\COMMON60 UI60 = %OG6I_HOME%\TOOLS\COMMON60 VGS60 = %OG6I_HOME%\TOOLS\COMMON60 OCL60 = %ORACLE_HOME%\TOOLS\DBTAB60\GRAPH60

### Editing Existing Chart Items

You can edit the properties of existing Oracle Forms chart items, create new Oracle Forms chart items in Forms Developer, and populate an Oracle Forms chart item with an OGD file that was created in Oracle Graphics6i Developer. However, future releases of Forms may further restrict Graphics6i functionality.

Since Oracle Graphics was not originally conceived for Web deployment, issues may arise when forms with embedded charts are re-deployed from a client-server environment to the Web, particularly more complex charts with more complex character sets. In some cases, text dimensions may alter, causing text items to overlap or to extend over the edge of a display. These issues, particularly concerning scaling, are akin to the side effects that can occur when porting applications from one platform to another. Recommendations on how to deal with these issues can be found in Deploying Oracle Graphics in Oracle Forms Services 10g at http://www.oracle.com/technology/products/forms/.

Migration to the Web of forms with embedded Oracle Graphics displays may well entail modifications to modules. Allow time to check the behavior of each embedded chart on the Web, and decide if any of the suggestions in the white paper need to be implemented. See how the chart looks with the largest set of data it is likely to be passed, not just a small set of test data (good practice whether running in a client-server environment or on the Web). Consider whether reports deployment may be preferable in some cases. Review the charts to see if there are any items that can be removed, particularly redundant axes labels or legends. If you are migrating forms with embedded OGDs from client-server deployment to Oracle Application Server on the Web, it would be best to break this down into two stages. First migrate to Forms Services 6i Web deployment and then upgrade to Oracle Application Server. In this way, you can deal with any Oracle Graphics Web-migration issues in the 6i environment in which you still have Graphics Builder and the Chart Wizard. Nevertheless, in the second stage, the upgrade to this release, check out the appearance of your charts once again.

## About Integration with Oracle Reports

You can embed new and existing Reports applications in forms that have been migrated to Oracle Forms.

You can no longer use the Reports client runtime engine to output Reports in the Web. From Forms5.0 forward, the RUN_REPORT_OBJECT Built-in is available in Forms Developer to run integrated reporting in Forms. The RUN_PRODUCT Built-in is obsolete in Oracle Forms for running Oracle Reports applications from Oracle Forms.

Oracle Forms and Oracle Reports versions 9.0.2 and higher are now Web-based only, and do not have client/server runtime engines. Therefore, integrated reports in Oracle Forms applications must be recoded to use the RUN_REPORT_OBJECT Built-in and Oracle Application Server Reports Services.

For additional information about integrating Oracle Forms with Reports, see Integrating OracleAS Reports in OracleAS Forms at the Oracle Technology Network at http://www.oracle.com/technology/products/forms/.

### Displaying Reports in Oracle Forms

If your form contains embedded Oracle Reports applications, you can migrate the form to Oracle Forms by changing the integrated call to Oracle Reports to use:

- RUN_REPORT_OBJECT Built-in (Do not use the RUN_PRODUCT Built-in to call Reports.)

- WEB.SHOW_DOCUMENTBuilt-in

Using RUN_PRODUCT in Oracle Forms to run integrated Oracle Reports is no longer supported in this release. The Migration Assistant is provided to help you migrate your applications to use RUN_REPORT_OBJECT. See Chapter 2, "Using the Oracle Forms Migration Assistant" for more information.

### Example

The following example runs a report using the RUN_REPORT_OBJECT Built-in. The report_object node defined in Oracle Forms is assumed to be "report_node1". A user-defined Reports parameter "p_deptno" is passed by Forms using the value in the "dept.deptno" field. The Reports parameter form is suppressed. For additional details about the logic used in this example, see Notes About the Example.

    /* The following example runs a report using the RUN_REPORT_OBJECT Built-in. The report_object node defined in Forms Developer is assumed to be "report_node1". A user-defined Reports parameter "p_deptno" is passed by Forms using the value in the "dept.deptno" field. The Reports parameter form is suppressed */

     DECLARE
     v_report_id 		Report_Object;
     vc_report_job_id  		VARCHAR2(100); 	/* unique id for each Report 	 request */
     vc_rep_status      		VARCHAR2(100);		 /* status of the Report job */

     BEGIN
     	/* Get a handle to the Report Object itself. */
     	v_report_id:= FIND_REPORT_OBJECT('report_node1');
     	SET_REPORT_OBJECT_PROPERTY(v_report_id,REPORT_COMM_MODE, SYNCHRONOUS);
     	SET_REPORT_OBJECT_PROPERTY(v_report_id,REPORT_DESTYPE,CACHE);

     /* Define the Report output format and the name of the Reports Server as well as a user-defined parameter, passing the department number from Forms to the Report. The Reports parameter form is suppressed by setting  paramform  to "no". */
     	SET_REPORT_OBJECT_PROPERTY(v_report_id,REPORT_DESFORMAT, '<HTML|HTMLCSS|PDF|RTF|XML|DELIMITED>');
     	/* replace <ReportServerTnsName> with the name of the Reports Services as defined in your tnsnames.ora file */
     	SET_REPORT_OBJECT_PROPERTY(v_report_id,REPORT_SERVER, '<ReportServerTnsName>');
     	SET_REPORT_OBJECT_PROPERTY(v_report_id,REPORT_OTHER, 'p_deptno='||:dept.deptno||'paramform=no');
      	/* finally, run the report and retrieve the Reports job_id as a handle to the Reports process */
     	vc_report_job_id:=RUN_REPORT_OBJECT(report_id);

     /*The report output is not delivered automatically to the client, which is okay because the Web is a request model. Thus the next step is to check if the report finished. */

     	vc_rep_status := REPORT_OBJECT_STATUS(vc_report_job_id);
     	IF vc_rep_status='FINISHED' THEN
     /* Call the Report output to be displayed in a separate browser window. The URL for relative addressing is only valid when the Reports Server is on the same host as the Forms Server. For accessing a Remote Reports Server on a different machine, you must use the prefix http://hostname:port/ */
     web.show_document ('/<virtual path>/<reports cgi or servlet name>/getjobid='|| vc_report_job_id ||'?server='|| '<ReportServerTnsName>','_blank');
     	ELSE
     	message ('Report failed with error message '||rep_status);
     	END IF;
    END;

### Notes About the Example

- Calling a report synchronously makes the user wait while the report gets processed on the server. For long-running Reports, it is recommended that you start the report asynchronously, by setting the REPORT_COMM_MODE property to asynchronous and the REPORT_EXECUTION_ MODE to batch.

      SET_REPORT_OBJECT_PROPERTY(report_id,REPORT_EXECUTION_MODE,BATCH);
      SET_REPORT_OBJECT_PROPERTY(report_id,REPORT_COMM_MODE,ASYNCHRONOUS);

- After calling the RUN_REPORT_OBJECT Built-in, you must create a timer to run frequent checks on the current REPORT_OBJECT_STATUS using a When-Timer-Expired trigger. For performance reasons, the timer should not fire more than four times a minute. After the report is generated, the When-Timer-Expired trigger calls the WEB.SHOW_DOCUMENT Built-in to load the Reports output file, identified by a unique job_id, to the client's browser.

  Note: Do not forget to delete the timer when it is no longer needed.

  The following example shows the When-Timer-Expired trigger that checks for the Report_Object_Status.

      (...)
       /* :global.vc_report_job_id needs to be global because the information about the Report job_id is shared between the trigger code that starts the Report and the When-Trigger-Expired trigger that checks the current Report status. */
       vc_rep_status:= REPORT_OBJECT_STATUS(:global.vc_report_job_id);
       IF vc_rep_status='FINISHED' THEN
       web.show_document ('/<virtual path>/<reports cgi or servlet name>/getjobid='|| vc_report_job_id ||'?server='|| '<ReportServerTnsName>','_blank');
       ELSIF vc_rep_status not in ('RUNNING','OPENING_REPORT','ENQUEUED') THEN
       	message (vc_rep_status||'  Report output aborted');
        END IF;
      (...)

### Using Parameter Lists in RUN_REPORT_OBJECT

Parameter lists that were used with RUN_PRODUCT in client-server mode can also be used with RUN_REPORT_OBJECT calling Oracle Application Server Reports Services. System parameters must be set by the Set_Report_Object_Property. The syntax for using parameter lists in RUN_REPORT_OBJECT is as follows:

    report_job_id:=run_report_object(report_id,paramlist_id);

where paramlist_id is the same id used with RUN_PRODUCT.

Parameter settings can be any of the following:

- REPORT_COMM_MODE: Batch, Runtime

- REPORT_EXECUTION_MODE: Synchronous, Asynchronous

- REPORT_DESTYPE: FILE, PRINTER, MAIL, CACHE, PREVIEW, FTP, FAX, WEBDAV, ORACLEPORTAL, ORACLEWIRELESS, SECUREPDF, BLOBDESTINATION

- REPORT_FILENAME: The report filename (not used with CACHE)

- REPORT_DESNAME: The report destination name (not used with Cache)

- REPORT_DESFORMAT: The report destination format

- REPORT_SERVER: The report server name

Other settings are as follows:

- Reports CGI name is "rwcgi.sh" (UNIX) and "rwcgi.exe" (Windows)

- Reports Servlet default name is "rwservlet"

- Reports Servlet virtual path is /reports/

### Migration Steps

You can use the Forms Migration Assistant described in Chapter 2, "Using the Oracle Forms Migration Assistant" to change integrated Reports calls in your Oracle Forms modules. The Migration Assistant adds code to your application modules that redirects Run_Product calls to Reports and uses the Run_Report_Object Built-in and Reports Services. The resulting conversion is of the same quality as using Run_Product and the runtime engine in Forms 6i.

To manually migrate Reports in Oracle Forms, do the following:

1. Find all occurrences of Run_Product.

2. Identify and locate the parameter lists used with these calls.

3. Remove all of the Reports system parameter settings like desname and destype from the parameter lists.

4. Find the Reports node ID for the Reports node name defined in Oracle Forms or the Forms 6i Builder.

5. Create Set_Report_Object_Property codes for DESNAME, REPORT_SERVER, DESFORMAT, DESTYPE, COMM_MODE, and EXECUTION_MODE in your PL/SQL.

6. Use Run_Report_Object(report_node_id, paramlist_id) to reuse your parameter lists that had been created for Run_Product.

   Note: Detailed information about how to change calls to Oracle Reports in Forms 6i to use Run_Report_Object are provided in a whitepaper on `http://www.oracle.com/technology/products/forms/`.