6
Migrating Business Intelligence Components

This chapter explains how to change the necessary configuration files, application deployment files, and metadata schema in order to migrate Business Intelligence components. It contains these major sections:

Migrating Oracle9iAS Forms Services

Migrating Oracle9iAS Reports Services

Migrating Oracle9iAS Discoverer

Migrating Oracle9iAS Personalization

Migrating Oracle9iAS Forms Services

Oracle9iAS Release 2 (9.0.2) Enterprise Edition contains Oracle9iAS Forms Services Release 9i. Oracle9iAS Release 1 (1.0.2.2.x) contains Oracle9iAS Forms Services Release 6i. This section explains how to migrate Oracle9iAS Forms Services Release 6i deployments to Oracle9i Forms Services in Oracle9iAS Release 2 (9.0.2).

Oracle9iAS Release 1 (1.0.2.2.x) contains Oracle9iAS Forms Services Release 6i, which supports the following deployment options:

Web Interfaces

• Static HTML files

• Common Gateway Interface (CGI)

• Forms Servlet

Forms Servlet Request dispatcher types (Listeners)

• Forms Listener

• Forms Listener Servlet

In Oracle9iAS Release 2 (9.0.2), not all of these options are supported. In Oracle Forms Services 9i, the Common Gateway Interface (CGI) is no longer a Web Interface option, and the Forms Listener is no longer an option for Forms Web requests. The Oracle9i Forms Services architecture supports the following Forms Services deployment options:

Web Interfaces

• Forms Servlet

Request Dispatcher (Listener)

• Forms Listener Servlet

This section details the steps necessary to migrate Forms Services from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2).

This section contains the following sub-sections:

• Migrating from Oracle9iAS Forms Services Release 6i Common Gateway Interface (CGI) to Forms 9i Servlet

  This section explains the changes required to migrate to the Forms Servlet from the Forms CGI. Follow these steps if you are using the Forms Services Common Gateway Interface to dynamically render the Forms Applet start HTML file for your application.

• Migrating Forms 6i Static HTML Start Files to Forms 9i Generic Application HTML Start Files

  If you are using static HTML deployment files in Oracle Forms Services 6i, follow these steps. Static HTML deployment files are not recommended for use in Oracle9iDS Forms Services 9i, because the Forms Servlet provides functionality that makes administration and application deployment easier.

• Migrating from Forms 6i Listener to the Forms Listener Servlet

  If you are using the Forms Listener to start a Web Forms runtime process, follow these steps. The Forms Listener is a C program that routes Web requests for Forms applications to a runtime process started by the listener. The Forms Listener Servlet does the same, but is completely written in Java. This section explains the differences between the listener types, and how to migrate your applications from Forms Listener to the Forms Listener Servlet.

• Migrating the Forms 6i Listener Servlet Architecture to Oracle9iAS Forms Services Release 9i

  This section explains the differences between the deployment in Oracle9iAS Forms Services Release 9i and the deployment in Oracle9iAS Forms Services Release 6i.

• Migrating Load Balancing

  Read this if you are using load balancing with Oracle9iAS Forms Services Release 6i (the Forms Services Metrics Server or the JServ engine load balancing method).

• Usage Notes

  This section contains instructions for configuration and deployment of Oracle9iAS Forms Services Release 9i when migrating from Oracle9iAS Forms Services Release 6i. The sections are:

  • "Deploying Icon Images with the Forms Servlet"

  • "Migrating Integrated Calls to Oracle9i Reports to use Reports Services"

  • "Creating Forms Listener Servlet Alias Names in OC4J"

  • "Accessing the Listener Servlet Administration Page"

• Best Practices For Migrating to Oracle9iAS Forms Services Release 9i

  This section provides a check list for migrating Oracle Forms Services 6i to Oracle9i Forms Services 9i. Note that at this time your Forms application source modules should already be upgraded to Forms 9i.

Migrating from Oracle9iAS Forms Services Release 6i Common Gateway Interface (CGI) to Forms 9i Servlet

The CGI was introduced in Oracle9iAS Forms Services Release 6i to allow the Forms Applet start HTML file to be rendered dynamically. The Forms CGI uses the formsweb.cfg configuration file and a HTML template to create the application specific start HTML file. The CGI Interface is configured by an entry in the Oracle HTTP Server httpd.conf file, which defines a ScriptAlias dev60cgi for the directory structure containing the ifcgi60.exe file.

The Forms Servlet renders the HTML in the same manner as the CGI, but also provides an automatic browser type detection, supporting Internet Explorer native VM. The Oracle9iAS Forms Services Release 9i servlet is configured when you install Oracle9iAS Release 2 (9.0.2) Enterprise Edition, and is named f90servlet.

To access the Forms Servlet, request the following URL:

http://<hostname>:port/forms90/f90servlet

This URL is similar to the URL used with the CGI Interface in Oracle9iAS Forms Services Release 6i. To call an application configured as myapp in the custom configuration section of the formsweb.cfg file, located in the Forms90/Server directory, request the following URL:

http://<hostname>:port/forms90/f90servlet?config=myapp

Configuration is automatic upon installation. The installer creates a virtual path /forms90/ pointing to the Oracle9iAS Forms Services Release 9i configuration, forms90app and forms90web, in the Oracle9iAS Containers for J2EE (OC4J) home (ORACLE_HOME/j2ee/home).

To migrate an Oracle9iAS Forms Services Release 6i CGI environment to an Oracle9iAS Forms Services Release 9i servlet environment in Oracle9iAS Release 2 (9.0.2), perform the following steps:

1. Copy all of the application specific configurations from ORACLE_HOME_1 in Forms60/Server/formsweb.cfg and append them to the Forms90/Server/formsweb.cfg file in ORACLE_HOME_2.

   Note: It is not safe to replace the 9i formsweb.cfg file in ORACLE_HOME_2 with the 6i formsweb.cfg file from ORACLE_HOME_1, because the 9i file is different from the 6i file. You must copy the application configuration lines from the 6i file to the 9i file.

2. Configure Forms90_Path in the default.env file in Forms90/Server to point to your migrated Oracle9iAS Forms Services Release 9i application modules.

   Note: You can create your own environment file by copying default.env, modifying it for use with a particular application, and adding envFile=your created environment file to the custom application section in the formsweb.cfg file.

3. If you changed the Forms 6i HTML template files, then make the same changes to the Oracle9iAS Forms Services Release 9i HTML template files.

   Note: You must make the changes in all three files: basejini.htm, basejpi.htm and baseie.htm, because the servlet supports JInitiator, Java Plugin and Internet Explorer native VM.

Migrating Forms 6i Static HTML Start Files to Forms 9i Generic Application HTML Start Files

Every application deployed by Oracle9iAS Forms Services has a custom application definition, configured in the formsweb.cfg configuration file. It automatically inherits the general system settings, such as the JInitiator version used or the names and locations of the base HTML template files.

The name of the custom application definition becomes a part of the Forms URL. The following custom settings define two different applications:

[MyHR_app]
IE=Jinit 
serverURL=/forms90/l90servlet 
Form = hr_main.fmx 
lookAndFeel=oracle 
Otherparams=myParam1=12 
Userid=scott/tiger@orcl

The following URL invokes this application:

http://<hostname>:<port>/forms90/f90servlet?config=MyHR_app

Another custom application definition might look like this:

[booking_app]
IE=native 
ServerURL=/forms90/l90servlet 
Form = book.fmx 
lookAndFeel=oracle 
Otherparams= Userid=

The following URL invokes this application:

http://<hostname>:<port>/ forms90/f90servlet?config=booking_app 

For each static HTML file, you must create a custom application definition. Part of the static HTML file is the archive parameter holding at least f90all.jar in Oracle9iAS Forms Services Release 9i. If you added a custom archive file, then the archive parameter directive looks similar to Archive=f90all.jar, custom.jar. Using the Forms servlet and the formsweb.cfg file, the archive settings are defined under the User Parameter section. All custom application settings inherit these values, so you don't have to explicitly set this parameter, unless you add your own custom.jar file required by one of your applications.

If custom.jar was added, then you add the following lines to the custom application definition (the example assumes that you are using Jinitiator or another VM but not IE native).

[booking_app] 
archive_jini=f90all_jinit.jar, custom.jar 
archive=f90all.jar, custom.jar 
ServerURL=/forms90/l90servlet 
Form = book.fmx 
lookAndFeel=oracle 
Otherparams= 
Userid=

To migrate, perform these steps:

1. Edit the default.env file in Forms90/Server, adding the location of the Forms9i application modules to the Forms90_Path.

2. Edit the Forms90/Server/formsweb.cfg file and append a custom application section for each static HTML application file that you want to replace.

3. Give each custom application section a name, containing no spaces and enclosed in square brackets [ ] (as shown in the examples above).

4. Start the application using:

   http://<hostname>:<port>/forms90/f90servlet?config=name
   
   

Using Static HTML Files with FormsOracle9iAS Forms Services Release 9i

If you need to, you can continue to use static HTML files in Oracle9iAS Release 2 (9.0.2). However, with static HTML files, some Release 2 functionality, such as Single Sign-On support, is unavailable to your Forms applications.

The Forms Listener Servlet is automatically set up to /forms90/l90servlet after installation. To use static HTML files in Release 2, you must modify each static start HTML file to include a value for the serverURL parameter. The serverPort and serverHost parameters are no longer used, and can be left undefined. Oracle9iAS Forms Services Release 9i uses JInitiator version 1.3.x, so you must also change those settings. The required values are found in the /forms90/server/formsweb.cfg file.

The migration steps for this configuration are:

1. Configure Forms90_Path in the forms90/server/default.env file to point to the migrated Oracle9iAS Forms Services Release 9i application modules.

2. Create virtual directories in the ORACLE_HOME_2/Apache/Apache/conf/httpd.conf file to point to the location of the static HTML start files.

3. Modify the application start HTML files as follows:
   1. Add the serverURL value /forms90/l90servlet.

   2. Change the Jinitiator version number.

4. Change the codebase parameter to forms90/java.

5. Go to ORACLE_HOME_2/j2ee/OC4J_BI_Forms/applications/forms90app/form90web/WEB-INF and edit the web.xml file.

6. Set the envFile initialization parameter for the LIstenerServlet to point to the environment file (usually ORACLE_HOME_2/forms90/server/default.env).

After editing, the entry in the web.xml file for the Forms listener servlet should resemble that shown in Example 6-1.

Example 6-1 Forms listener entry in web.xml

<!--Forms 9i listener servlet-->
<servlet>
  <servlet-name>l90servlet</servlet-name>
     <servlet-class>oracle.forms.servlet.ListenerServlet</servlet-class>
  <init-param>
    <param-name>envFile</param-name>
    <param-value>ORACLE_HOME_2/forms90/server/default.env</param-value>
  </init-param>
</servlet>

Migrating from Forms 6i Listener to the Forms Listener Servlet

The Forms 6i Listener is a C program that starts a Forms runtime process on behalf of an incoming Forms Web request. The Forms Web runtime process then is directly accessed by the Forms client Applet, using either a direct socket or a HTTP socket connection. The Forms Listener is then no longer involved in the application Web client-server communication process, and free to handle other incoming Web requests.

The Forms Listener Servlet, a Java program, also takes incoming Web requests for a Forms application and starts the Forms server-side Web runtime process. But, unlike the Forms Listener, the Forms Listener Servlet remains between the Forms application Applet-server communication.

While the Forms 6i Listener listens on a specific port (by default 9000), the Forms Servlet doesn't need an extra port and is accessed by the HTTP listener port. The Forms Listener Servlet was introduced in Forms 6i patch 4 and is the only listener supported in Forms 9i Services.

The Forms Listener Servlet is configured during installation.

The installer creates a virtual path /forms90/ that points to the Oracle9iAS Forms Services Release 9i Services. Oracle9iAS Containers for J2EE (OC4J) is the servlet environment.

Request the Forms Listener Test page with the following URL:

http://<hostname>:<port>/forms90/f90servlet/admin

This page indicates that the Forms Listener Servlet is configured and ready for you to use. f90servlet is the access name configured for the Forms Servlet during installation. The name of the Listener Servlet is l90servlet.

If the Forms Listener Servlet is accessed with the Forms Servlet, then only the custom application settings from the Forms60/server/formsweb.cfg file need to be appended to the Forms90/server/formsweb.cfg file. All application configurations automatically inherit the serverURL parameter value /forms90/l90servlet from the global system parameter settings.

Note: It is not safe to replace the 9i formsweb.cfg file in ORACLE_HOME_2 with the 6i formsweb.cfg file from ORACLE_HOME_1, because the 9i file is different from the 6i file. You must copy the application configuration lines from the 6i file to the 9i file.

To change a Forms application deployment from the Forms Listener architecture to the Listener Servlet architecture, you need only to supply a value for the serverURL parameter in the formsweb.cfg file. During installation, this parameter is set to /forms90/l90servlet.

To migrate, perform these steps:

1. Copy your Forms application files to a new directory and migrate them to Oracle9iAS Forms Services Release 9i modules.

2. Edit the file in the Forms90/server/default.env directory, adding the location of the migrated Oracle9iAS Forms Services Release 9i application modules to the Forms90_Path variable.

3. Copy the custom application settings from the Oracle9iAS Forms Services Release 6i formsweb.cfg file to the Oracle9iAS Forms Services Release 9i formsweb.cfg file.

   Note: It is not safe to replace the 9i formsweb.cfg file in ORACLE_HOME_2 with the 6i formsweb.cfg file from ORACLE_HOME_1, because the 9i file is different from the 6i file. You must copy the application configuration lines from the 6i file to the 9i file.

4. If an applications requires its own environment file, then instead of defining a Servlet alias for the Listener Servlet, you add this information into the custom application definition section of the application. For example:

   envFile=myEnvFile.env
   
   

   where the myEnvFile.env is located in the Forms90/server directory

5. If you changed the Oracle9iAS Forms Services Release 6i HTML template files, then make the same changes to the Oracle9iAS Forms Services Release 9i HTML template files.

   Note: If you need to change the underlying base HTML files, you should make a copy of the provided template files before editing them. Save the edited HTML files under a different name and leave the default templates that were provided with the installation unchanged. This prevents overwriting of your custom HTML template files when patch sets are applied to your application. To use your own template files with applications, use these parameters in the system section, or one of your custom application definitions: baseHTML=your base template.htm baseHTMLJinitiator=your base jinit.htm baseHTMLie=your base ie.htm

6. Start the application using:

   http://hostname:port/forms90/ 90servlet?config=application 
   
   

Migrating the Forms 6i Listener Servlet Architecture to Oracle9iAS Forms Services Release 9i

In Oracle9iAS Forms Services Release 6i the Listener Servlet, if not aliased, is accessed by oracle.forms.servlet.ListenerServlet. The Listener Servlet configuration exists in the jserv.properties and the zone.properties files.

In Oracle9iAS Forms Services Release 9i, the Forms Listener Servlet is the same except for the servlet names: f90servlet and l90servlet, and the servlet container, which is now Oracle9iAS Containers for J2EE (OC4J). As in Release 1, the configuration is performed during installation. The Listener Servlet configuration in OC4J is stored in Forms_OC4J_Home\applications\forms90app\forms90web\web-inf\web.xml. Some initialization parameters, like the envFile parameter, need no longer be configured with the servlet engine because they are moved into the formsweb.cfg file.

Installing Oracle9iAS Release 2 (9.0.2) configures the Forms Listener servlet.

The installer creates a virtual path /forms90/ that points to the Oracle9iAS Forms Services. Oracle9iAS Containers for J2EE (OC4J) is the servlet environment.

After installation, the following URL invokes the Forms Listener test page:

http://<hostname>:<port>/forms90/f90servlet/admin

This page indicates that the Forms Listener Servlet is configured. f90servlet is the access name configured for the Forms Servlet during installation; the name of the Listener Servlet is l90servlet.

To migrate, perform these steps:

1. Copy your Forms application files to a new directory and migrate them to Forms 9i modules

2. Edit the default.env file in the Forms90\server directory, adding the location of the migrated Forms9i application modules to the Forms90_Path variable.

3. Copy the custom application settings in the Oracle9iAS Forms Services 6i formsweb.cfg file and add them to the Forms9i formsweb.cfg file.

   Note: It is not safe to replace the 9i formsweb.cfg file in ORACLE_HOME_2 with the 6i formsweb.cfg file from ORACLE_HOME_1, because the 9i file is different from the 6i file. You must copy the application configuration lines from the 6i file to the 9i file.

4. If an applications requires its own environment file, then instead of defining a servlet alias for the Listener Servlet, you add this information into the custom application definition section of the application. For example:

   envFile=myEnvFile.env
   
   

   where the myEnvFile.env is located in the Forms90/server directory

5. If you changed the Oracle9iAS Forms Services Release 6i HTML template files, then make the same changes to the Oracle9iAS Forms Services Release 9i HTML template files.

6. Start the application using:

   http://hostname:port/forms90/f90servlet?config=application 
   
   

Migrating Load Balancing

The method of load balancing in Oracle9iAS Forms Services Release 6i depends on the deployment type used.

• With the Forms 6i listener, the Metrics Server (a separate process) performs load balancing.

• With the Forms 6i servlet, load balancing is configured with the JServ servlet engine using a round robin load balancing among JServ engines.

In Oracle9iAS Forms Services Release 9i in Oracle9iAS Release 2 (9.0.2), the load balancing is performed by mod_oc4j. mod_oc4j binds Web requests to the servlet container processing the Forms Servlet and the Forms Listener Servlet.

For information on setting up clusters for load balancing, see the Oracle9i Application Server Administrator's Guide.

Usage Notes

This section contains instructions for configuration and deployment of Oracle9iAS Forms Services Release 9i migrated from Oracle9iAS Forms Services Release 6i.

Deploying Icon Images with the Forms Servlet

Using static HTML start files in Oracle9iAS Forms Services Release 6i allowed storage of images used by an application in a location relative to the start HTML file. The Forms Servlet in Oracle9iAS Forms Services Release 9i does not support this.

The alternative is to use the imagebase parameter with a value of codebase as the location for the icon images for applications. The codebase value refers to the Forms90/java directory, which contains all the Forms client java archive files. For performance reasons, it is not a good idea to store images here.

Instead, Oracle recommends bundling icons into a separate archive file, which improves performance because archives are cached permanently on the client. The instructions below explain how to create the archive file and place the images there.

1. Verify that the jar command succeeds. If it doesn't, then you need to make sure that there is a JDK installed in your system with the appropriate path environment variable entry (pointing to the /bin directory).

2. Navigate to the directory containing the application images and issue the command:

   jar -cfv application_images.jar *.extension 
   
   

   where application is the name of the application and extension is the extension of the image file (e.g., .gif).

   A jar file, application_images.jar is created in the current directory.

3. Copy the application_images.jar file to the Forms90/Java directory.

4. Edit the formsweb.cfg file, adding the imageBase=codebase to the custom application section defined for the application.

5. Add the application_images.jar file to the archive path used by the application by adding the following lines to the custom application section:

   archive_jini=f90all_jinit.jar,<application>_images.jar 
   archive=f90all.jar,<application>_images.jar 
   archive_ie=f90all.jar,<application>_images.jar
   
   

   Note: archive_ie should contain f90all.cab, which is the better archive format when using IE5 native VM. Because you can't mix archives and cab files, you must either create cab file for the images or use f90all.jar for Forms applications (the former is recommended).

See Deploying Oracle Forms Applications (Deploying Forms to the Web chapter) in the Oracle9iAS documentation library for more information on deploying custom icon files with Forms Services.

Migrating Integrated Calls to Oracle9i Reports to use Reports Services

In Oracle9iAS Release 2 (9.0.2), integrated calls to Oracle Reports in Forms are no longer handled by a client-side background engine. Oracle9iAS Forms Services Release 9i requires that applications use the Run_Report_Object built-in, calling Reports 9i Services to process integrated Reports. The Reports Services are set up on your system. To migrate the call, follow the steps below.

1. Change all occurrences of Run_Product(Reports,...) to the equivalent call using Run_Report_Object().

2. Add the location of the application's Reports modules to the Reports90_Path of the Reports Services.

3. Change Run_Report_Object to reference Reports Services.

   See Also: Run_Report_Object() built-in and Reports Services white paper at http://otn.oracle.com

Creating Forms Listener Servlet Alias Names in OC4J

In Oracle9iAS Forms Services Release 6i, before patch 8, it was necessary to create alias names for the Forms servlet in the ORACLE_HOME/Apache/JServ/conf/zone.properties file in order to use individual environment files for different applications. The Forms servlet in Oracle9iAS Forms Services Release 9i does not require this. You can set the environment file name in the formsweb.cfg file using the envFile parameter, shown below.

EnvFile=myApp.env

Alias names for the Forms servlet in Forms 9i are no longer created in

ORACLE_HOME/Apache/JServ/conf/jserv.properties. 

Instead, they are created in

ORACLE_HOME/Forms_OC4J_Home/applications/forms90app/forms90web/web-inf/web.xml

Simply copy the content between the <servlet> and </servlet> tags and change the servlet's name. To create a URL mapping for the new servlet alias name add the following to the file.

<servlet-mapping>
<servlet-name>New_Servlet_Name</servlet-name>
<url-pattern>/New_URL_Name*</url-pattern>
</servlet-mapping>

Accessing the Listener Servlet Administration Page

You can display a test page for the Listener Servlet in Oracle9iAS Forms Services Release 6i with the following URL:

http://hostname:port/servlet/oracle.forms.servlet.ListenerServlet 

The information displayed depends on the value of the initialization parameter TestMode. This is set in the ORACLE_HOME/Apache/JServ/conf/zone.properties configuration file.

You can display the test page for Forms 9i Services with the following URL:

http://hostname:port/forms90/f90servlet/admin 

The information displayed depends on the value of the initialization parameter TestMode. This is set in the ORACLE_HOME/Forms_OC4J_Home/applications/forms90app/forms90web/web-inf/web.xml configuration file. An example is shown below.

<init-param>          
<!-- Display sensitive options on the /admin page ? -->
   <param-name>testMode</param-name>
   <param-value>true</param-value>
</init-param>

Best Practices For Migrating to Oracle9iAS Forms Services Release 9i

This section provides general recommendations and considerations for migrating Forms applications to Oracle9iAS Release 2 (9.0.2).

• Keep your Oracle9iAS Release 1 (1.0.2.2.x) installation until you successfully deploy your applications on Oracle9iAS Release 2 (9.0.2).

• Deploy Oracle9iAS Forms Services Release 6i using the new Listener Servlet architecture.

• Use the Forms servlet rather than the Forms CGI.

• Replace Run_Product calls to integrated Reports with Run_Report_Object calls to Reports Services (or use the PL/SQL conversion utility later in Forms9i).

• Install Oracle9iAS Release 2 (9.0.2) and configure the formsweb.cfg file in the Forms90/server directory with the information used by your applications. Copy the environment files used by your Forms applications to the same directory. Copy the migrated Forms application module files to the machine running Oracle9iAS Release 2 (9.0.2) if it is not the same machine.

• After starting Oracle9iAS Release 2 (9.0.2), access the Forms 9i Services Listener Servlet test page with the following URL:

  http://hostname:port/forms90/f90servlet/admin 
  
  

• Verify that the application setting is added to the formsweb.cfg file and that the environment variable Forms90_Path contains the directory of the application modules.

• Verify that the database is accessible from using a SQL*Plus connect.

• Type http://hostname:port/forms90/f90servlet?config=your app to invoke your application.

• Test applications deployed on Forms9i Services before decommissioning Oracle9iAS Release 1 (1.0.2.2.x).

• Migrate source files first, and completely back up and secure application files.

Migrating Oracle9iAS Reports Services

This section explains how to migrate a 6i Reports Server configuration from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2). It contains the following sections:

Migrating Reports Configuration Files

Using Oracle9iAS Portal with Oracle9iAS Reports Services

Oracle Graphics Migration

Deprecated Features in Oracle9iAS Reports Services

Migrating Reports Configuration Files

If you want to reuse the 6i Reports server persistent file and server configuration file, copy the file

ORACLE_HOME_1/reports60/server/report server name.ora

to:

ORACLE_HOME_2/reports/conf/report server name.ora

and, if present, copy this file

ORACLE_HOME_1/reports60/server/report server name.dat

to:

ORACLE_HOME_2/reports/server/report server name.dat

If you want to reuse the 6i Reports server cgicmd.dat file, copy it from:

ORACLE_HOME_1/reports60/server/cgicmd.dat

to

ORACLE_HOME_2/reports/conf/cgicmd.dat

Security features have been improved for Oracle9iAS Reports Services. With Oracle 6iReports, you may have placed connect string information in the cgicmd.dat file. For improved security in Oracle9iAS Reports Services, you should consider moving this connect string information into the Oracle Internet Directory (OID).

See Also: Oracle9iAS Reports Services Publishing Reports to the Web

Using Oracle9iAS Portal with Oracle9iAS Reports Services

To facilitate a smooth transition to Oracle9i, your Oracle9iAS Reports Server can use Oracle9iAS Portal 9.0 or 3.0.9 as its security repository and the destination for report content you are pushing into a page group or content area. This compatibility is extremely useful if you are currently using Oracle9iAS Portal 3.0.9 and Oracle Reports 6i integration in Oracle9iAS Release 1 (1.0.2.2.x) and want to continue to use Oracle9iAS Portal 3.0.9 while upgrading to Oracle9i Reports.

To configure Oracle9i Reports in this way, the Reports Server needs to be able to use an Oracle9iAS Portal 3.0.9 connection as its security and destination for reports. When the Reports Server detects that the security system is an Oracle9iAS Portal 3.0.9 instance instead of an Oracle9iAS Portal 9.0 instance, it will run in 6i security compatible mode. The Reports Servlet also uses this mode and behaves appropriately for any report request that utilizes the Oracle9iAS Portal 3.0.9 integration.

Simultaneously, you can have another Oracle9iAS Reports Server that uses Oracle9iAS Portal 9.0 for its security and destination element. This Oracle9iAS Reports Server runs with all of the latest functionality, including support for Single Sign-on and OID for authentication. The Reports Servlet also uses this mode and behaves appropriately for any report request that utilizes the Oracle9iAS Portal 9.0 integration. The servlet will also use Single Sign-on if configured to do so.

Note: You only need one instance of the Oracle9iAS Reports Servlet to service your Oracle9iAS Reports Servers, regardless of whether they are operating with an Oracle9iAS Portal 3.0.9 instance or an Oracle9iAS Portal 9.0 instance. The servlet will switch between 6i and 9i modes as necessary depending upon the Reports Server to which it is sending the request.

To ensure that your Oracle9iAS Reports Server operates correctly, do the following:

• To set up the Oracle9iAS Reports Server to work with Oracle9iAS Portal 3.0.9, enter the 3.0.9 Portal's database username/password@tnsname for the securityUserid property under the security element and portalUserid property under the destination element in the Reports Server configuration file servername.conf. For example:

  <security id="rwSec" class="oracle.reports.server.RWSecurity">
  

  <property name="securityUserid" value="portal309_id/portal309_
  password@portal_schema" confidential="yes" encrypted="no"/>
  

  </security>
  
  
  

• To set up the Oracle9iAS Reports Server to work with Oracle9iAS Portal 9.0, enter the 9.0 Portal's database username/password@tnsname for the securityUserid property under the security element and portalUserid property under the destination element in the Reports Server configuration file servername.conf. For example:

  <security id="rwSec" class="oracle.reports.server.RWSecurity">
     <property name="securityUserid" value="portal90_id/portal90_
     password@portal_schema" confidential="yes" encrypted="no"/>
  </security>
  

  See Also: Oracle9iAS Reports Services Publishing Reports to the Web

Oracle Graphics Migration

Oracle9iAS Reports Services has a new graphing engine that replaces Oracle Graphics from earlier releases. You cannot migrate Oracle Graphics graphs to the new graphing engine, but Oracle9iAS Reports Services can use the Oracle Graphics engine for backward compatibility.

To make the Oracle Graphics engine backward-compatible on Windows, all you need to do is ensure that the Oracle Graphics 6i home is in the system path.

On UNIX, you just need to ensure that the environment variable ORACLE_GRAPHICS6I_HOME is set to the Oracle Graphics 6i home in g90runm.sh. Refer to the comments in g90runm.sh for additional information about setting ORACLE_GRAPHICS6I_HOME.

The following restrictions apply to the use of Oracle Graphics in Oracle9iAS Reports Services:

• You can only use Oracle Graphics graphs in paper layouts. They will not work in the new JSP Web layouts. If you want to put an Oracle Graphics graph into a Web format, you must run the paper layout to a Web destination format (e.g., HTML or HTMLCSS).

• Reports that use Oracle Graphics must be saved in the Reports Definition File (RDF) format. They cannot be saved in any of the other formats, such as XML.

• You cannot add new Oracle Graphics charts in Oracle9iAS Reports Services. You can only run existing Oracle Graphics charts. All new charts will use the new charting engine that comes with Oracle9iAS Reports Services.

Deprecated Features in Oracle9iAS Reports Services

Deprecated features in Oracle9iAS Reports Services are listed below. Existing reports using these features will continue to function without modification, but these features are no longer documented and further use is discouraged.

• User exits

• rwcgi web executable

• Command line options: CURRENCY, THOUSANDS, DECIMAL, PROFILE, ERRFILE, LOGFILE, BACKGROUND, KEYIN, KEYOUT

• SRW.SET_ATTR built-in

• OLE2 object support

The following features are removed entirely:

• rwrunc character mode runtime

• client/server GUI report previewer in rwrun

• rwrbe60 background engine

• rwows60 OAS cartridge

• obe60 query builder

• obs60 schema builder

  See Also: http://otn.oracle.com for more information about deprecated and obsolete features and alternatives to their use.

Migrating Oracle9iAS Discoverer

This section explains how to migrate Oracle9iAS Discoverer from Oracle9iAS Release 1 (1.0.2.2.x) to Oracle9iAS Release 2 (9.0.2). This process involves the following tasks:

• Migrating Preferences

• Updating the End User Layer

• Updating URL References

• Configuring Session Timeout

• Migrating Viewer Customizations

Before you begin the migration process:

1. Confirm that the Oracle9iAS Release 2 (9.0.2) Discoverer installation was successful. Run the Discoverer demonstrations with the links available from:

   http://hostname:port/discoverer/intro/html/disc_demo_intro.htm
   
   

Migrating Preferences

This section explains how to migrate default user and user-level preferences.

Migrating Default User Preferences

To migrate default user preferences, follow these steps:

1. Compare the original version 4.1 file

   ORACLE_HOME_1/discwb4/util/pref.txt

   to

   ORACLE_HOME_2/discoverer902/util/pref.txt

2. If changes were made to the ORACLE_HOME_1/../pref.txt file, edit the ORACLE_HOME_2../pref.txt file, so that it contains the same changes as the original version 4.1 file.

3. To apply the default preferences, issue the following command:

   dis51pr -apply -nopause
   

Migrating User Level Preferences From Discoverer 4.1 to Discoverer 9.0.2

To migrate user level preferences from Discoverer 4.1:

1. (UNIX only) Copy the .reg_key.dc file (that the DC_REG environment variable points to) to the location specified by the DC902_REG environment variable.

2. Issue the following command:

   dis51pr -migrate
   
   

Updating the End User Layer

The version of Discoverer that ships with Oracle9iAS Release 2 (9.0.2) requires an End User Layer created by Discoverer Administrator 9.0.2 (which is shipped with Oracle9i Developer Suite Release 2 (v9.0.2). If you have an existing Discoverer v4.1 End User Layer, you must upgrade the End User Layer from v4.1 to v5.1 using Discoverer Administrator 9.0.2.

See Also: Oracle9i Discoverer Administrator Administration Guide in the Oracle9i Developer Suite Documentation Library.

Updating URL References

All Discoverer Viewer and Discoverer Plus URL references have changed. These include, but are not limited to, links within the Web site and client bookmarks. You must manually replace all occurrences of old URLs with the new URLs, according to the tables below:

Discoverer Plus Release 1 URL	Release 2 URL	Example
http://hostname/Discwb4/html/english/ ms_ie/start_ie.htm or http://hostname/Discwb4/html/english/ netscape/start_nn.htm	http://hostname/discoverer/ plus	Change http://host:port/Discwb4/english... to http://host:port/discoverer/plus

Discoverer Viewer Release 1 URL	Release 2 URL	Example
http://hostname/Discoverer4i/Viewer	http://hostname/discoverer/viewer	Change http://host:port/Discoverer4i/Viewer to http://host:port/discoverer/viewer

Configuring Session Timeout

The session-timeout parameter has moved from

ORACLE_HOME_1/Apache/JServ/servlets/discoverer4i.properties 

to

ORACLE_HOME_2/J2EE/OC4J_BI_Forms/discoverer/web/web/web-inf/web.xml

The session-timeout parameter controls the http session timeout, the number of minutes the Discoverer servlet waits for a browser to make another http or https request before terminating the user's http session.

The session-timeout parameter resides in the web.xml file, directly following the line that reads <web-app>, as shown below:

<session-config>
<session-timeout>15</session-timeout>
</session-config>

Migrating Viewer Customizations

A number of files control the appearance and behavior of Oracle9iAS Discoverer Viewer. Those files might have been modified to customize Discoverer Viewer to meet certain requirements. Installing Oracle9iAS Release 2 (9.0.2) installs new files with different names. Specifically, disco4iv.xml has been renamed configuration.xml and viewer_config.xml has been renamed ui_config.xml. If you have modified the original configuration files and .xsl files, then you must edit the new files and reapply the changes from your original version 4.1 files.

Note: Do not simply replace the new files with the original version 4.1 files (do not simply rename the files). Follow the steps in this section to migrate only the customizations, not all of the differences, from the original version 4.1 files to the new files.

1. For each original version 4.1 file in ORACLE_HOME_1/Apache/Apache/htdocs/discwb4/disco4iv/htm, perform the following tasks:
   1. Use the table below to identify the file that contains the equivalent information.

      Release 1 File	Release 2 File
      disco4iv.xml	web/web-inf/configuration.xml
      viewer_config.xml	web/common/xsl/ui_config.xml

   2. Compare the original version 4.1 file with the equivalent Release 2 file in the ORACLE_HOME_2/J2EE/OC4J_BI_Forms/discoverer/web/directory.

   3. Edit the equivalent Release 2 file to incorporate any customizations found in the original version 4.1 file.

      Note: If you modify configuration.xml, consider using Oracle Enterprise Manager to make the changes. Oracle Enterprise Manager provides a user interface for editing configuration.xml and includes useful information about each setting.

Upgrading JInitiator

You must use Oracle9iAS Release 2 (9.0.2) Discoverer with the supplied version of JInitiator (1.3.x) or a later version. The version of JInitiator is specified by the jvm element in the

ORACLE_HOME_2/j2ee/OC4J_BI_Forms/discoverer/webplus/xsl/plus_config.xml

file. Do not attempt to run Oracle9iAS Release 2 (9.0.2) Discoverer with the version of JInitiator supplied with Oracle9iAS Release 1 (1.0.2.2.x).

Migrating Oracle9iAS Personalization

This section describes how to migrate from Oracle9iAS Personalization (OP) release 1 (version 9.0.1) to OP release 2 (version 9.0.2). There are two ways to perform the migration: extract-load-and-transform (ELT) and in-place.

Migration requires stopping and starting certain OP components. For information about how to perform these tasks, see the online help for the OP Administrative UI, the Oracle9iAS Personalization User's Guide, and the Oracle9iAS Personalization Administrator's Guide. The Oracle9iAS Personalization User's Guide contains information about the OP components and how they work together.

Migration Overview

There are two ways to migrate (upgrade) from OP Release 1 to OP Release 2:

• Extract, load, and transform (ELT) migration

• In place

Both approaches migrate the OP 9.0.1 Mining Table Repository (MTR) to the OP 9.0.2 MTR. The MTR contains all of the data required to build packages plus all information collected by OP applications. Therefore, migrating the MTR preserves critical data.

The Mining Object Repository (MOR), Recommendation Engines, and configuration settings for the Administrative UI and the REAPI Demo are not migrated using the provided scripts. After you migrate the MTR, you must reenter the OP metadata stored in the MOR to the 9.0.2 MTR (use the OP administrator user interface to do this) and you must also rebuild and deploy all packages.

Both types of migration have advantages and disadvantages:

• ELT migration keeps the OP 9.0.1 installation intact. With ELT migration, you install OP 9.0.2 on a different machine (or machines), and copy the 9.0.1 MTR data to the 9.0.2 MTR. After migration is complete, you can run the 9.0.2 version of OP. However, ELT migration requires that you maintain two MTRs, and these can be large.

• Migration in place changes the existing OP 9.0.1 MTR to an OP 9.0.2 MTR. Since the 9.0.1 MTR no longer exists after migration is complete, you can no longer run the 9.0.1 version of OP unless you have an additional 9.0.1 MTR available. You can, however, reload the 9.0.1 from a backup or downgrade the 9.0.2 MTR to a 9.0.1 MTR, as described in "Downgrading a Migrated MTR" below.

Location of Migration Scripts

All of the scripts described in this section are located in

ORACLE_HOME/dmt/admin

Migrating With Extract, Load, and Transform

ELT migration keeps the OP 9.0.1 intact. ELT migration involves these steps:

1. Install OP 9.0.2.

2. Migrate from 9.0.1.

3. Restart OP 9.0.1, if you wish, and start OP 9.0.2.

Install OP 9.0.2

Install OP 9.0.2 as described in Oracle9i Application Server Installation Guide. Do not overwrite any OP 9.0.1 files. After the installation completes, configure one MOR, one MTR, and at least one RE.

Migrate the OP 9.0.1 MTR Using ELT

These steps all take place on the system where OP 9.0.1 is installed. Migration consists of stopping OP 9.0.1 and then copying the 9.0.1 MTR to the 9.0.2 MTR that you created when you installed OP 9.0.2. Follow these steps to perform the migration:

1. Stop all package builds, package deployments, and reports that reference the 9.0.1 MTR.
   1. Use the OP administrator user interface to ensure that all package builds, package deployments, and reports are stopped. If any of these are running, you can cancel them, or wait until they complete. You must also change the schedule for any builds, deployments, and reports to make sure that they do not take place.

   2. Verify that nothing is running.

2. Stop all Recommendation Engines using the script ORACLE_HOME/dmt/admin/remaint.sh.

   remaint.sh stops all REs known to the MOR and forces the REs to save any cached information to the MTR. After the script completes, any application that attempts to use any of the stopped REs receives an RE_OFFLINE exception.

3. Back up the 9.0.1 MTR.

4. Generate a list of the REs by running the following script on the 9.0.1 MTR:

   Select ID, name, description from mor_re_farmj

5. Copy the OP 9.0.1 MTR to the OP 9.0.2 MTR as follows:
   1. Export the 9.0.1 MTR:

      mtrexp.sh MTRUsername, MTRpassword, TnsAlias
      
      

   2. Import the 9.0.1 MTR into the 9.0.2 MTR

      mtrimp.sh SYSTEMPasswd oldMTRUname, NewMTRUname, NewMTRUname, 
      NewTableSpaceName, NewDataFileName, TnsAlias
      
      

      The existing 9.0.1 MTR is copied to the new OP 9.0.2 MTR.

Start OP 9.01 and OP 9.0.2

Once migration is complete, you can use the OP 9.0.1 Administrative UI to start the 9.0.1 REs. Any applications that connect to one of these REs will no longer receive an exception.

To start OP 9.0.2, first verify that you have created all required REs. Next use the 9.0.2 Administrative UI to build and deploy new packages based on the migrated MTR to 9.0.2 REs.

Any application that uses the 9.0.2 MTR must have access to the 9.0.2 REAPI.jar file. You do not need to recompile the code.

Migrating In Place

Migration in place copies the 9.0.1 MTR to the 9.0.2 MTR. (The 9.0.1 MTR does not exist after migration is done.) Migration in place consists of the following major steps:

1. Install OP 9.0.2.

2. Migrate the MTR from 9.0.1.

3. Start OP 9.0.2. (You cannot restart OP 9.0.1 unless you have a 9.0.1 MTR in addition to the one that you migrated.

   Note: You can downgrade the migrated MTR back to an 9.0.1 MTR, if necessary.

Install OP 9.0.2

Install OP 9.0.2 MOR and RE only as described in Oracle9i Application Server Installation Guide. Do not overwrite any OP 9.0.1 files. After the installation completes, configure an MOR, an MTR, and as many REs as required by the 9.0.1 applications.

Migrate the OP 9.0.1 MTR in Place

Perform these steps all take place on the system on which OP 9.0.1 is installed. Migration consists of stopping OP 9.0.1 and then copying the 9.0.1 MTR to the 9.0.2 MTR that you created when you installed OP 9.0.2. Follow these steps to perform the migration:

1. Stop all package builds, package deployments, and reports that reference the 9.0.1 MTR.
   1. Use the OP administrator user interface to ensure that all package builds, package deployments, and reports are stopped. If any of these are running, you can cancel them, or wait until they complete. You must also change the schedule for any builds, deployments, and reports to make sure that they do not take place.

   2. Verify that nothing is running.

2. Stop all Recommendation Engines using the script remaint.sh.

   remaint.sh stops all REs known to the MOR and forces the REs to save any cached information to the MTR. After the script completes, any application that attempts to use any of the stopped REs receives an RE_OFFLINE exception.

3. Back up the 9.0.1 MTR.

4. Generate a list of the REs by running the following script on the 9.0.1 MTR:

   Select ID, name, description from mor_re_farmj

5. Upgrade the OP 9.0.1 MTR with the following script:

   opupgrd.sql MTRUsername, MTRpassword, TnsAlias
   
   

   The existing 9.0.1 MTR is copied to the new OP 9.0.2 MTR.

Start OP 9.0.2

You can no longer start OP 9.0.1, because the MTR no longer exists (unless you have a 9.0.1 MTR in addition to the one that you migrated).

To start OP 9.0.2, first verify that you have created all required REs. Next use the 9.0.2 Administrative UI to build and deploy new packages based on the migrated MTR to 9.0.2 REs.

Any application that uses the 9.0.2 MTR must have access to the 9.0.2 REAPI.jar file. You do not need to recompile the code.

Downgrading a Migrated MTR

If necessary, you can downgrade a 9.0.2 MTR, that is, convert it to a 9.0.1 MTR. You downgrade by doing a migration in place from a 9.0.2 MTR to a 9.0.1 MTR.

Follow these steps to downgrade:

1. Stop all package builds, package deployments, and reports that reference the 9.0.1 MTR.
   1. Use the OP Administrative UI to ensure that all package builds, package deployments, and reports are stopped. If any of these are running, you can cancel them, or wait until they complete. You must also change the schedule for any builds, deployments, and reports to make sure that they do not take place.

   2. Verify that nothing is running.

      Note: Do not delete any scheduled tasks or the MTR connection.

2. Stop all Recommendation Engines using the script remaint.sh.

   remaint.sh stops all REs known to the MOR and forces the REs to save any cached information to the MTR. After the script completes, any application that attempts to use any of the stopped REs receives an RE_OFFLINE exception.

3. Downgrade the OP 9.0.2 MTR to a 9.0.1 MTR with the following script:

   opdowngrd.sql MTRUsername, MTRpassword, TnsAlias
   
   

4. To restart OP 9.0.1, create the 9.0.1 MTR connection if it no longer exists, build and deploy new packages based on the downgraded MTR, and reschedule any reports.

   Any application that uses the 9.0.1 MTR must have access to the 9.0.1 REAPI.jar file. You do not need to recompile the code.

Deinstall OP 9.0.1

You should not deinstall OP 9.0.1 until you are certain that the migration was successful. This is particularly important if you are migrating in place.

When you are certain that you no longer need OP 9.0.1, stop it and deinstall it as described in the Oracle9iAS Personalization Administrator's Guide, version 9.0.1.