4 Upgrading the Middle Tier

4.5.1.1 Resolving Common Errors

Under certain conditions, the OracleAS Upgrade Assistant cannot perform an upgrade. Among these are that the starting configuration is unsupported, processes are running in the Oracle homes, the Infrastructure services are unavailable, or there is insufficient memory for a large-scale OC4J application upgrade.

This section identifies each condition and its cause(s), and explains how to resolve it.

http://www.oracle.com/technology/documentation/database10g.html

4.5.1.2 Examining the Log File

You can use the OracleAS Upgrade Assistant log file to determine the cause of examination and upgrade failures.

The OracleAS Upgrade Assistant log file is located at:

DESTINATION_ORACLE_HOME\upgrade\log\iasua.log

4.5.1.3 Reasons for Oracle Application Server Containers for J2EE Upgrade and Deployment Failures

The following sections discuss reasons for which an Oracle Application Server Containers for J2EE upgrade may fail and ways you can address the issues:

DESTINATION_ORACLE_HOME\upgrade\log\iasua.log

DESTINATION_ORACLE_HOME\dcm\bin\dcmctl validateEarFile -f
full_path_and_filename_for_ear_file

DESTINATION_ORACLE_HOME\dcm\bin\dcmctl validateEarFile -f 
full_path_and_filename_for_ear_file -noproxy

dcmctl validateEarFile -v -f simple.ear
No J2EE XML/DTD validation errors were found

dcmctl validateEarFile -v -f petstore.ear
Warning: J2EE/DTD validation errors were found
ADMN-906001   {0}   Base Exception:
oracle.ias.sysmgmt.deployment.j2ee.exception.J2eeDeploymentException:
Cannot get xml document by parsing /var/tmp/jar50152.tmp: Invalid element
'servlet' in content of 'web-app',   expected elements '[servlet-mapping,
session-config, mime-mapping, welcome-file-list,error-page, taglib,
resource-ref, security-constraint, login-config, security-role, env-entry,
ejb-ref]'.

set ORACLE_DCM_JVM_ARGS=-Dhttp.Proxyhost=www-proxy.hostname.com -Dhttp.Proxyport=9999

4.6.1.1 About the portlist.ini File

Note that the portlist.ini file does not reflect the upgraded port settings; instead, it lists the port values assigned by the installer when the destination instance was initially installed. The portlist.ini file can be found in the following location in the destination Oracle home:

DESTINATION_ORACLE_HOME\install\portlist.ini

4.6.1.2 Using the Ports Page in the Application Server Control Console to Identity Port Assignments

Another way to review the current port settings for the upgraded middle tier, is to use the Ports page on the Application Server Home page in the Application Server Control Console. The Ports page lists all the ports in use by the Oracle Application Server instance.

To display the Application Server Control Console, enter the following URL in your browser:

http://appserver_host_name:app_server_control_port_number

If you do not know the Application Server Control Console port, you can locate the port number by checking the StandaloneConsoleURL entry in the following configuration file in the application server Oracle home:

DESTINATION_ORACLE_HOME\sysman\emd\targets.xml









See Also:
"Managing Ports" in the Oracle Application Server Administrator's Guide

4.6.1.3 About the Application Server Control Console Ports Before and After Upgrade

If you are upgrading from Release 2 (9.0.2), the OracleAS Upgrade Assistant cannot reset the port for the Application Server Control Console to its original port. This is because the port used to access the console may or not be defined within the upgraded Oracle home.

However, if you are upgrading from 10g (9.0.4), the port number for the Application Server Control Console is automatically reset by the OracleAS Upgrade Assistant so it uses the original port number from the source Oracle home.

Note that after you upgrade from 10g (9.0.4) the 10g Release 2 (10.1.2) Welcome pages will continue to link to the Application Server Control Console port number assigned during the 10g Release 2 (10.1.2) installation. As a result, the link from the 10g Release 2 (10.1.2) Welcome pages to the Application Server Control Console will not work after you upgrade from 10g (9.0.4).

4.6.1.4 Examples of Port Assignments Before and After Upgrade

To illustrate how ports are initially assigned to the new 10g Release 2 (10.1.2) Oracle home and then modified by the OracleAS Upgrade Assistant, Table 4-5 lists examples of pre- and post-upgrade values for Oracle HTTP Server, Oracle Enterprise Manager 10g Application Server Control Console, and Oracle Application Server Web Cache.

4.6.3.1 Verifying the Secure Sockets Layer (SSL) Configuration After Upgrade

If you enabled SSL in the source Oracle home, verify that the component is still configured for secure communications after you have used the OracleAS Upgrade Assistant.

To verify the proper configuration of your secure Oracle HTTP Server, use the following procedure to check the required values in the opmn.xml and httpd.conf configuration files. Unless both of these files are configured as described in this procedure, you could encounter problems with your SSL configuration:

1. Use a text editor to open the following OPMN configuration file:

   DESTINATION_ORACLE_HOME\opmn\conf\opmn.xml

2. Locate the following ias-component entry in the opmn.xml file:

   <ias-component id="HTTP_Server">
      <process-type id="HTTP_Server" module-id="OHS">
          <module-data>
              <category id="start-parameters">
                  <data id="start-mode" value="ssl-enabled"/>
              </category>
          </module-data>
   
   

3. Within the start-parameters category tag, verify that the start-mode parameter is set to ssl-enabled.

   This ensures that OPMN starts Oracle HTTP Server in SSL mode.

4. Use a text editor to open the following Oracle HTTP Server configuration file:

   DESTINATION_ORACLE_HOME\Apache\Apache\conf\httpd.conf
   
   

5. Locate the following entry in the httpd.conf file:

   <IfDefine SSL>
       LoadModule ossl_module libexec/mod_ossl.so
   </IfDefine>
   
   

   In particular, be sure that the LoadModule ossl_module command is surrounded by the <IfDefine SSL> tag. This ensures that Oracle HTTP Server will be started in SSL mode if and only if OPMN directs it to start in SSL mode. Without the surrounding <IfDefine SSL> tag, Oracle HTTP Server starts in SSL mode regardless of whether OPMN has been configured to do so.

   In 10g Release 2 (10.1.2), the SSL configuration is controlled by OPMN so it is important that the settings in both the opmn.xml file and httpd.conf file be consistent.

4.6.3.2 Manual Upgrade Tasks You May Need to Perform

The OracleAS Upgrade Assistant upgrades the standard settings for the Oracle HTTP Server. If you have configuration files or documents that are in non-standard locations or referenced in non-standard ways, you must upgrade these manually. These, and other specific cases for manual upgrade, are detailed below.

• If mod_osso was configured: If mod_osso was configured, after upgrade, the osso.conf file continues to use the source Oracle home partner entry in the Single Sign-On server. If the name of the entry in use is obsolete (in that it refers in some way to the source Oracle home), rename it accordingly.

• If there are configuration files in non-default locations: If httpd.conf, mod_oc4j.conf, mod_osso.conf and moddav.conf files are not in the default location, you must upgrade them manually by applying the customizations in the files in the source Oracle home to the files in the destination Oracle home.

• If there are custom files and directories referenced by Oracle HTTP Server configuration files: Because the OracleAS Upgrade Assistant only upgrades the items listed in Section A.1.4.1, "OHS Upgrade Items", there could be files or directories referred to by directives such as Alias, mod_rewrite, and log directives, such as ErrorLog, that are not present after the upgrade. Ensure that all such items are upgraded manually and exist in the locations expected by the directives. If these files or directives are missing after the upgrade, the Oracle HTTP Server may not start. You can identify errors by starting the Oracle HTTP Server individually after the upgrade, and examining the following file for errors associated with these items:

  DESTINATION_ORACLE_HOME\Apache\Apache\logs\error_log
  
  

• If there are Dynamic Monitoring Service (DMS) configuration elements in the httpd.conf and mod_oc4j.conf files: You must relocate these configuration elements into the dms.conf file.

• If Oracle Application Server Web Cache is the first listener: If OracleAS Web Cache is configured as the first listener, ensure that the Oracle HTTP Server directives listed in Table 4-6 have the same values as the corresponding OracleAS Web Cache elements. In particular, note that the Oracle HTTP Server Port directive specifies the port number of a front-end load balancer or reverse proxy. Thus, if Oracle Application Server Web Cache is used, then the Oracle HTTP Server Port directive should have the value of the port on which OracleAS Web Cache is listening.

  Table 4-6 Oracle HTTP Server and Oracle Application Server Web Cache Port Settings

  Oracle HTTP Server Directive	Oracle Application Server Web Cache Element
  VirtualHost	Site definitions
  Listen	Origin server ports
  VirtualHost, Listen	Site-to-server mappings
  Port	Listen

  
  

• If you have static documents in the default DocumentRoot directory that you want to upgrade: The OracleAS Upgrade Assistant locates static document files and directories for upgrade in the location specified in the DocumentRoot directive. The DocumentRoot directive defines the location for static documents and related directories. The base server has a document root location, and each virtual host has one. The OracleAS Upgrade Assistant copies files under these directories to the destination Oracle home. The default DocumentRoot directory contains demonstration programs and release notes placed there by the installer, so the OracleAS Upgrade Assistant does not upgrade this directory. You must upgrade this directory manually:

  SOURCE_ORACLE_HOME\Apache\Apache\htdocs 
  

4.6.4.1 Upgrading Oracle Application Server Java Authentication and Authorization Service (JAAS) Provider (JAZN) Security Settings

During upgrade, the OC4J upgrade assistant redeploys your J2EE applications in an OC4J instance in the new 10g Release 2 (10.1.2) Oracle home. Thus, changes made to the jazn-data.xml and jazn.xml files packaged within an application's EAR file will be migrated automatically.

However, manual steps are needed for the following cases, which are not common.

• In orion-application.xml, the application can specify the location of jazn-data.xml; for example:

  <jazn provider="XML" location="SOURCE_ORACLE_HOME\j2ee\jazn-data.xml">
  
  

  When jazn-data.xml is not packaged within the application's EAR file, then jazn-data.xml needs to be copied manually to the new 10g Release 2 (10.1.2) environment. The location of the file may need to be updated accordingly in the orion-application.xml file.

• In orion-application.xml, the application can point to jazn.xml using the following syntax:

  <jazn config="path_to_jazn.xml" /> 
  
  

  When jazn.xml is not packaged within the application's EAR file, then it needs to be copied manually to the new install environment. The location of the file may need to be updated accordingly in the orion-application.xml file.

4.6.4.2 Upgrading JAZN Library Path Entries After Upgrading From Release 2 (9.0.2)

If you are upgrading OC4J instances in a Release 2 (9.0.2) Oracle home, note that in Oracle Application Server 10g (9.0.4) and 10g Release 2 (10.1.2) the jazn.jar file is split into two JAR files: jazn.jar and jazncore.jar.

For this reason, after upgrading OC4J applications that use JAZN and require dynamic compilation (for example, JSP), both JAR file names should be added to the library path entries in the application.xml file.

Ensure that the application.xml file contains both of the entries below:

<library path="DESTINATION_J2EE_HOME\jazn.jar"/> 
<library path="DESTINATION_J2EE_HOME\jazncore.jar"/>

In this example, replace DESTINATION_J2EE_HOME with the following directory path:

DESTINATION_ORACLE_HOME\j2ee\home

4.6.4.3 Reviewing the Default OC4J Instances After Upgrade

Default OC4J instances are installed automatically by the Oracle Universal Installer and are used by Oracle Application Server components.

During upgrade, the OracleAS Upgrade Assistant does not upgrade default OC4J instances. These default OC4J instances are replaced by new default instances that are installed by the 10g Release 2 (10.1.2) installation procedure in the destination Oracle home. In most cases, these default instances are designed for specific use by the Oracle Application Server components. These default instances include:

• OC4J_SECURITY

• OC4J_PORTAL

• OC4J_WIRELESS

4.6.4.4 Completing the Upgrade of User-Created OC4J Instances

User-created OC4J instances are created or modified by the user; this category includes the home instance.

The OracleAS Upgrade Assistant upgrades most of the properties and attributes of user-created OC4J instances, including the home instance. However, not all the properties and attributes of a user-created OC4J instance are upgraded automatically.

For example, the OracleAS Upgrade Assistant adds any properties defined in oc4j.properties to the corresponding java-options section (for both start and stop parameters) in opmn.xml. However, the OracleAS Upgrade Assistant does not upgrade the process-set properties that define the number Java Virtual Machines (JVMs) defined for the instance.

The following sections describe the rules used by the OracleAS Upgrade Assistant to determine which attributes and properties in the opmn.xml file can be upgraded automatically for each user-created OC4J instance:

• About the java-options Parameters in the opmn.xml File

• Upgrading java-options Other Than -D Options for OC4J Instances Defined in the OPMN.XML File

• Upgrading -D java-options for OC4J Instances Defined in the OPMN.XML File

• About the start-parameters and stop-parameters Sections of the OPMN.XML File

<ias-component id="OC4J">
   <process-type id="home" module-id="OC4J" status="enabled">
      <module-data>
         <category id="start-parameters">
            <data id="java-options" value="-server -Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy -Djava.awt.headless=true"/>
         </category>
         <category id="stop-parameters">
            <data id="java-options" value="-Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy -Djava.awt.headless=true"/>
         </category>
      </module-data>
      <start timeout="600" retry="2"/>
      <stop timeout="120"/>
      <restart timeout="720" retry="2"/>
      <port id="ajp" range="3301-3400"/>
      <port id="rmi" range="3201-3300"/>
      <port id="jms" range="3701-3800"/>
      <process-set id="default_island" numprocs="1"/>
   </process-type>
</ias-component>

<data id="java-options" value="-server -Djava.security.policy=$ORACLE_HOME\j2ee\home\config\java2.policy -Djava.awt.headless=true" -Xmx512m -Xmx256m />

<data id="java-options" value="-server -Djava.security.policy=$ORACLE_HOME/j2ee/home/config/java2.policy -Djava.awt.headless=true"

4.6.4.5 Upgrading application.xml Entries

If you have customized entries in the application.xml file, such as library paths, Java options, and OC4J options, you must upgrade them manually.

4.6.4.6 Using the Compatibility Test Suite (CTS) Compatibility Flag for Backward Compatibility

In Oracle Application Server 10g Release 2 (10.1.2), OC4J by default complies with the J2EE 1.3 specification. In some cases, this results in behavior that differs from that seen with previous OC4J implementations. To allow for backward compatibility, OC4J supports a CTS compliance flag that you can set to false to revert to previous OC4J behavior in the following components:

• Oracle JMS

• Oracle JDBC

• Oracle XML parser for JAXP/XDK

The compliance behavior of OC4J is determined by the flag oracle.cts.useCtsFlags, with a default value of true. If any of the upgrade issues are critical in a particular application, you can disable CTS compliance and revert to old behavior for an OC4J instance by setting the flag value to false in an OC4J properties file, and providing the location of the properties file to OC4J.

For example, consider the following configuration file:

DESTINATION_ORACLE_HOME\j2ee\home\config\oc4j.properties 

This file might contain the flag:

oracle.cts.useCtsFlags=false

Supply the name and location of a properties file to OC4J through an <oc4j-option> element in the opmn.xml file. The opmn.xml file is located in the following directory:

DESTINATION_ORACLE_HOME\opmn\conf\opmn.xml

The <oc4j-option> element should appear as in the following example:

<oc4j>
...
<oc4j-option value="-p DESTINATION_ORACLE_HOME\j2ee\home\config\oc4j.properties"/>
...
</oc4j>

This is equivalent to starting OC4J as follows in standalone mode:

java -jar oc4j.jar -p DESTINATION_ORACLE_HOME\j2ee\home\config\oc4j.properties 

4.6.4.7 Upgrade Considerations for Enterprise Java Beans

Beginning with Oracle9iAS Release 2 (9.0.3), Oracle Application Server Containers for J2EE complies with the J2EE 1.3 specification and implements the Enterprise Java Beans (EJB) 2.0 specification in entirety. Therefore, if you are upgrading from Release 2 (9.0.2) to 10g Release 2 (10.1.2), applications using EJB features in the areas of container-managed persistence and container-managed relationships will require modification.

4.6.4.8 Upgrade Considerations for the OC4J Java Server Pages (JSP) Container

The following sections describes JSP settings that are affected by the upgrade:

• Enabling Extra Imports

• Setting Additional JSP Flags for Backward Compatibility

<servlet>
   <servlet-name>jsp</servlet-name>
   <servlet-class>oracle.jsp.runtimev2.JspServlet</servlet-class>
   <init-param>
      <param-name>check_page_scope</param-name>
      <param-value>true</param-value>
   </init-param>
   ...
</servlet>

4.6.4.9 Considering JDK 1.4 Issues: Cannot Invoke Classes Not in Packages

Among the migration considerations in moving to a Sun Microsystems JDK 1.4 environment, which is the environment that is shipped with Oracle Application Server 10g Release 2 (10.1.2), there is one of particular importance to servlet and JSP developers.

As stated by Sun Microsystems, "The compiler now rejects import statements that import a type from the unnamed namespace." (This was to address security concerns and ambiguities with previous JDK versions.) Essentially, this means that you cannot invoke a class (a method of a class) that is not within a package. Any attempt to do so will result in a fatal error at compilation time.

This especially affects JSP developers who invoke JavaBeans from their JSP pages, as such beans are often outside of any package (although the JSP 2.0 specification now requires beans to be within packages, in order to satisfy the new compiler requirements). Where JavaBeans outside of packages are invoked, JSP applications that were built and executed in an OC4J 9.0.3 / JDK 1.3.1 or prior environment will no longer work in an OC4J 9.0.4 / JDK 1.4 environment.

Until you update your application so that all JavaBeans and other invoked classes are within packages, you have the alternative of reverting back to a JDK 1.3.1 environment to avoid this issue.

For more information about the "classes not in packages" issue and other JDK 1.4 compatibility issues, refer to the following Web site:

http://java.sun.com/j2se/1.4/compatibility.html

In particular, click the link "Incompatibilities Between Java 2 Platform, Standard Edition, v1.4.0 and v1.3".

4.6.4.10 Considering Modified Servlet APIs and Behavior

When upgrading to Oracle Application Server 10g Release 2 (10.1.2) and using servlets, consider the following changes in servlet APIs and behavior:

• Changes relating to getRequestURI()

• Changes regarding filtering of servlets that are forward or include targets

4.6.4.11 Deploying Oracle Business Components for Java (BC4J) Applications After Upgrade

After you upgrade to Oracle Application Server 10g Release 2 (10.1.2), you will want to redeploy your J2EE applications using the OC4J component of your newly upgrade 10g Release 2 (10.1.2) instance.

However, before you redeploy any applications that use the capabilities of Oracle Business Components for Java (BC4J), you must repackage the application .EAR file. Specifically, you must be sure to package the 10g Release 2 (10.1.2) version of the bc4jhtml.jar file into the WEB-INF/lib directory of your application .EAR file.

4.6.5.1 Using Multiple Versions of OracleAS Web Cache within an OracleAS Web Cache Cluster

When upgrading an OracleAS Web Cache cluster, you can upgrade one cache cluster member at a time. The caches will continue to function, but because the other cluster members have a different version of the configuration, the caches will not forward requests to cache cluster members operating with a different version.

For example, if you upgrade Cache_A to the current version, but have not yet upgraded Cache_B and Cache_C, Cache_A will not forward requests to the cache cluster members Cache_B and Cache_C.

In this situation, the Operations page in Web Cache Manager indicates that the Operation Needed is Incompatible software version.

4.6.5.2 Synchronizing the Upgraded OracleAS Web Cache Cluster Configuration

After you upgrade each cache cluster member to 10g Release 2 (10.1.2), you must perform the following additional steps to synchronize the configuration for the members of the cluster:

1. If the caches have not been started, for each upgraded cache, start OracleAS Web Cache and OracleAS Web Cache Manager. On the command line, enter:

   opmnctl startproc ias-component=WebCache
   
   

   This command starts the OracleAS Web Cache cache server process and admin server process.

2. In a browser, enter the URL for the OracleAS Web Cache Manager for one of the upgraded caches, and, when prompted, enter the username and password for the ias_admin or administrator user.

   Note that after you upgrade an OracleAS Web Cache instance, you log into the OracleAS Web Cache Manager using the Administrator password defined when you installed and configured OracleAS Web Cache source Oracle home.

   
   

   See Also: Section 4.6.2, "About Administration Passwords After Upgrade"

   
   

3. In the navigator frame, select Administration -> Operations.

   The Operations page appears.

4. In the Operations page, click Retrieve Configuration.

   Web Cache retrieves the cache-specific configuration information from the remote cache cluster members. Then, Web Cache Manager indicates that the Operation Needed is Propagate Configuration.

5. To propagate the configuration to all cache cluster members, select All caches and an Interval of Immediate. Then, click Propagate.

6. Restart the caches by selecting All caches and an Interval. Then, click Restart. (Note that you can perform this operation as you upgrade each cache, or you can perform this operation after all of the cache cluster members have been upgraded.)

4.6.5.3 Upgrading an OracleAS Web Cache Cluster from Release 2 (9.0.2.x) to 10g Release 2 (10.1.2)

A Release 2 (9.0.2) cache cannot accept invalidation messages from a 10g Release 2 (10.1.2) cache. In a configuration that uses a OracleAS Web Cache cluster with a mixture of Release 2 (9.0.2) and 10g Release 2 (10.1.2) cluster members, you must configure the Load Balancer to send invalidation messages only to the Release 2 (9.0.2.x) members.

When upgrading a cache cluster from Release 2 (9.0.2) to 10g Release 2 (10.1.2), remove cluster members one at a time from the invalidation pool for the Load Balancer prior and upgrade them. Once all the cluster members are upgraded, add them back to the invalidation pool. As an example, assume a configuration with a Load Balancer in front of a cache cluster that is comprised of four members, webche1-host, webche2-host, webche3-host, and webche4-host, all running Release 2 (9.0.2.x). To upgrade this cache cluster:

1. In the Load Balancer configuration, remove webche1-host from the pool that is responsible for invalidation.

2. Upgrade webche1-host from Release 2 (9.0.2) to 10g Release 2 (10.1.2).

3. In the Load Balancer configuration, remove webche2-host from the pool that is responsible for invalidation.

4. Upgrade webche2-host from Release 2 (9.0.2) to 10g Release 2 (10.1.2).

5. In the Load Balancer configuration, remove webche3-host from the pool that is responsible for invalidation.

6. Upgrade webche3-host from Release 2 (9.0.2) to 10g Release 2 (10.1.2).

7. Upgrade webche4-host from Release 2 (9.0.2) to 10g Release 2 (10.1.2). As this is the last cache member in the Load Balancer configuration, it is not necessary to remove it from the invalidation pool.

8. In the Load Balancer configuration, add webche1-host, webche2-host, and webche3-host back into the pool that is responsible for invalidation.

4.6.5.4 About Linking to the Application Server Control From the OracleAS Web Cache Welcome Page

When you install the 10g Release 2 (10.1.2) destination Oracle home, the OracleAS Web Cache Welcome page is configured to link to the 10g Release 2 (10.1.2) Application Server Control Console URL. However, during the upgrade of the middle tier, the OracleAS Upgrade Assistant configures Application Server Control so you can access it from the original port number assigned when you installed the source 10g (9.0.4) Oracle home.

As a result, after you upgrade from OracleAS Web Cache 10g (9.0.4) to 10g Release 2 (10.1.2), the link to the Oracle Enterprise Manager Application Server Control Console on the OracleAS Web Cache Welcome page does not work. To access the Application Server Control Console, use the 10g (9.0.4) Application Server Control URL.

4.6.5.5 Verifying the Location of OracleAS Web Cache Wallets

If you configured OracleAS Web Cache for HTTPS requests, then you defined a wallet that OracleAS Web Cache must use to support the HTTPS protocol.

The OracleAS Upgrade Assistant automatically upgrades your destination Oracle home with the location of the OracleAS Web Cache wallet as long as the wallet is stored in the Oracle home directory.

However, in some cases, if you did not use the same case when specifying the path to the wallet, the OracleAS Upgrade Assistant incorrectly identifies the wallet as being located outside of the Oracle home. In those cases, the path to the wallet is not updated correctly in the destination Oracle home.

As a result, after you upgrade OracleAS Web Cache, verify that OracleAS Web Cache is configured to locate your wallets in the destination Oracle home and not the source Oracle home.

4.6.6.1 Verifying Oracle Internet Directory Properties for Custom Portals in the OracleAS Portal Dependency File

In cases where a Portal instance accessed through the middle-tier is not using the same Oracle Internet Directory that the middle-tier is registered with, some additional steps need to be carried out after upgrade of the middle tier. These steps validate that the Oracle Internet Directory details stored in the OracleAS Portal Dependency Settings File are correct. When you perform an upgrade, not all of the values are available to the upgrade tool and are simply set to a default value.

To verify the Oracle Internet Directory properties:

1. Open the following file in a text editor:

   DESTINATION_ORACLE_HOME\portal\conf\iasconfig.xml
   
   

2. Review the contents of the file for entries that apply to OracleAS Portal.

   In particular, note each occurrence of the PortalInstance element within the file. Example 4-8 shows the contents of a typical iasconfig.xml file.

3. For each PortalInstance element that refers to an Oracle Internet Directory other than the one with which the middle tier is registered, do the following:

   1. Set the LDAPSSLPort property in the OIDDependency element to the SSL port for the Oracle Internet Directory.

   2. Verify that the AdminDN property of the corresponding OIDComponent element is set to the Administration DN of the Oracle Internet Directory.

   3. Verify that the AdminPassword property of the corresponding OIDComponent element is correctly set to the password of the Oracle Internet Directory.

4. Save your changes and close the iasconfig.xml file.

5. Encrypt all manually entered password properties using the following command:

   DESTINATION_ORACLE_HOME\portal\conf\ptlconfig -encrypt
   
   

   Refer to the Oracle Application Server Portal Configuration Guide for more information about the iasconfig.xml and the ptlconfig tool.

<IASInstance Name="midtier.abc.company.com" Host="abc.company.com">
         <WebCacheComponent AdminPort="4000" ListenPort="80"
             InvalidationPort="4001" InvalidationUsername="invalidator"
             InvalidationPassword="@BdS/zVGJHrElbOMohqLzurxsPR1au77peA=="
             SSLEnabled="false"/>
         <EMComponent ConsoleHTTPPort="1811" SSLEnabled="false"/>
       </IASInstance>
       <IASInstance Name="infra.xyz.company.com" Host="xyz.company.com">
         <OIDComponent AdminPassword="welcome1"
            AdminDN="cn=orcladmin" SSLEnabled="false" LDAPPort="389"/>
       </IASInstance>
       <PortalInstance DADLocation="/pls/portal30" SchemaUsername="portal30"
          SchemaPassword="welcome1"
                connectString="dbserver.company.com:1521:orcl">
             <WebCacheDependency ContainerType="IASInstance"
                 Name="midtier.abc.company.com"/>
             <OIDDependency ContainerType="IASInstance" LDAPSSLPort="4339"
                 Name="infra.xyz.company.com"/>
             <EMDependency ContainerType="IASInstance"
               Name="midtier.abc.company.com"/>
       </PortalInstance>

4.6.6.2 Updating Deployment Properties for Portal Development Kit Services for Java (JPDK) Web Providers

Any new deployment property files added in the source Oracle home will be copied to the destination Oracle home. However, any property file that is modified from its original installation time values will not be copied. Any changes in those files must be manually applied to the destination Oracle home.

The location of the property file will vary among web providers, and can be located using the service identifier of the web provider. The service identifier identifies a provider within an application. The deployment property files are named according to the following convention:

SOURCE_ORACLE_HOME\j2ee\OC4J_Portal\applications\application_name\
web_application_name\WEB-INF\deployment\service_identifier.properties

For example, the deployment properties for the JPDK sample web provider, whose identifier is sample, reside in:

SOURCE_ORACLE_HOME\j2ee\OC4J_Portal\applications\jpdk\jpdk\WEB-INF\
deployment\sample.properties

To migrate modified deployment properties from the source to the destination Oracle home:

1. Identify all customized property files (files in which new properties were added or whose default property values were changed) in the source Oracle home.

2. Copy the customized properties from these property files in the source Oracle home to the corresponding files in the destination Oracle home.

4.6.8.1 Upgrading OracleAS Reports Services Customizations

The OracleAS Upgrade Assistant performs most of the Oracle Application Server Reports Services upgrade. However, it does not process the following:

• The .bat script files in the following source Oracle home location:

  SOURCE_ORACLE_HOME\reports\samples\scripts\rw*.bat
  SOURCE_ORACLE_HOME\reports\samples\scripts\reports.bat
  
  

• The template file in the following source Oracle home location:

  SOURCE_ORACLE_HOME\reports\conf\rwserver.template
  
  

• The jdbcpds.conf configuration file in the following source Oracle home location:

  SOURCE_ORACLE_HOME\reports\conf\jdbcpds.conf
  
  

If you have customized any of these files, you must apply the customizations to the corresponding files in the destination Oracle home.

In addition, to preserve the cache files and the cache directory from source Oracle home, copy the reports server cache directory from the source Oracle home to the destination Oracle home.

4.6.8.2 Enabling Management of OracleAS Reports Services from the Application Server Control Console

After you upgrade OracleAS Reports Services in the middle tier, make the following changes to the targets.xml configuration file to manage the upgraded OracleAS Reports Services server from the Application Server Control Console. These changes are necessary in order for the EM integration to work with the upgraded OracleAS Reports Services in-process server:

1. Use a text editor to open the following configuration file in the destination Oracle home:

   DESTINATION_ORACLE_HOME\sysman\emd\targets.xml
   
   

2. Locate the following entry in the targets.xml file for the Reports in-process server:

   TYPE="oracle_repserv" and DISPLAY_NAME="Reports Server: new_server_name
   
   

   Note that new_server_name will be in the following format:

   rep_hostname_newOracleHome
   
   

   In this example, hostname is the name of host computer without the domain name and newOracleHome is the destination Oracle home.

3. For the oracle_repserv entry, replace all occurrences of new_server_name with the original server name that was used in the source Oracle home before you performed the middle-tier upgrade.

   Example 4-9 uses boldface type to identify the typical occurrences of new server name in the oracle_repserv entry in the targets.xml file.

   Note that the original server name can be found in the following OracleAS Reports Services configuration file:

   DESTINATION_ORACLE_HOME\reports\conf\rwservlet.properties
   
   

4. Use the Services control panel to restart the Application Server Control service for the changes to take effect.

<Target TYPE="oracle_repserv"
     NAME="appserv1.acme.com_Reports_Server: new_server_name"
     DISPLAY_NAME="Reports Server: new_server_name" 
     VERSION="1.0"
     ON_HOST="appserv1.acme.com">
            <Property NAME="IASInternalName" VALUE="new_server_name"/>
            <Property NAME="Password" VALUE="77c1ed41793a5ce6"  ENCRYPTED="TRUE"/>
            <Property NAME="Server" VALUE="new_server_name"/>
            <Property NAME="Servlet"
                      VALUE="http://appserv1.acme.com:port/reports/rwservlet"/>
     ...
     ...
</Target>

4.6.8.3 Registering Standalone Reports Servers with OPMN and Oracle Enterprise Manager

The OracleAS Upgrade Assistant does not upgrade OracleAS Reports Services standalone servers. As a result, if you are using any standalone OracleAS Reports Services servers, you must manually register those servers with Oracle Process Manager and Notification Server (OPMN) and with Oracle Enterprise Manager 10g Application Server Control.

Registering the standalone servers with OPMN and Application Server Control involves updating the opmn.xml and targets.xml configuration files. Oracle Application Server provides a script you can use to automatically perform the updates.

To register your OracleAS Reports Services standalone servers, run the following command once for each standalone server you want to register:

DESTINATION_ORACLE_HOME\bin\addNewServerTarget.bat standalone-server-name

In this example, replace standalone-server-name with the name of the OracleAS Reports Services standalone server you want to register with OPMN and Oracle Enterprise Manager.

4.6.8.4 Upgrading User-Defined OC4J Instances With OracleAS Reports Services Deployments

The OracleAS Upgrade Assistant upgrades your Release 2 (9.0.2) or 10g (9.0.4) Business Intelligence & Forms configuration to an Oracle Application Server 10g Release 2 (10.1.2) Business Intelligence & Forms configuration. The OracleAS Upgrade Assistant is not aware of OC4J instances outside of these configurations that may contain deployed reports, or of customizations made to those instances in order to enable the deployed reports to run.

Therefore, if you are using OC4J instances other than the standard Business Intelligence and Forms OC4J instance, you must apply any manual deployment steps that you performed on those instances to the equivalent instances in Oracle Application Server 10g Release 2 (10.1.2).

4.6.8.5 Configuring OracleAS Reports Services After Upgrading from Business Intelligence & Forms to Forms and Reports Services

This section applies only if you are upgrading from the Release 2 (9.0.2) or 10g (9.0.4) Business Intelligence & Forms installation type to the 10g Release 2 (10.1.2.0.2) Forms and Reports Services installation type.

After upgrading to the 10g Release 2 (10.1.2.0.2) Forms and Reports Services installation type, perform the following steps to make all Reports Servers (in-process and standalone servers) unsecure and enable them to work properly:

1. Modify the server_name.conf file, as follows:

   1. Locate and open the server_name.conf configuration file:

      DESTINATION_ORACLE_HOME\reports\conf\server_name.conf
      
      

   2. Locate the following element in the file:

      <security id="rwSec" class="oracle.reports.server.RWSecurity">
      <!--property name="securityUserid" value="portal_db_username/portal_db_
      password@%portal_db_tnsname" confidential="yes" encrypted="no"/-->
      <property name="oidEntity" value="reports_oid_entity"/>
      </security>
      
      

   3. Comment the security element as shown in the following example.

      Be sure to remove any existing comment characters (<!-- and -->) within the security element:

      <!--security id="rwSec" class="oracle.reports.server.RWSecurity">
      <property name="securityUserid" value="portal_db_username/portal_db_
      password@%portal_db_tnsname" confidential="yes" encrypted="no"/>
      <property name="oidEntity" value="reports_oid_entity"/>
      </security-->
      
      

   4. Save and close the server_name.conf file.

2. Modify the rwservlet.properties file:

   1. Open the rwservlet.properties configuration file:

      DESTINATION_ORACLE_HOME\reports\conf\rwservlet.properties
      
      

   2. Locate the OID_ENTITY entry in the rwservlet.properties file.

      For example:

      OID_ENTITY=reportsApp.acme.com_FD502C79FB3F660CE0340003BA182918
      
      

   3. Comment the OID_ENTITY entry as follows:

      #OID_ENTITY=reportsApp.acme.com_FD502C79FB3F660CE0340003BA182918
      
      

   4. Save and close the rwservlet.properties file.

4.6.9.1 Using the Oracle Application Server Wireless Notification Service Upgrade Script

This section explains how to upgrade notifications created by the Oracle Application Server Wireless Release 2 (9.0.2) Notification Engine in the Oracle Application Server Wireless System Manager. The architecture and functionality of the Notification Engine are not described here.

This procedure is not necessary if you are upgrading from 10g (9.0.4).

You can upgrade notifications from Release 2 (9.0.2) to 10g Release 2 (10.1.2) with the migrateNotifications.bat script. To execute the script:

1. Navigate to DESTINATION_ORACLE_HOME\wireless\bin.

2. Set the ORACLE_HOME environment variable to the 10g Release 2 (10.1.2) Oracle home.

3. Issue one of the commands below:

   • migrateNotifications.bat -name deprecated master alert name(s) -owner owner user name

   • migrateNotifications.bat -oid deprecated master alert oid -owner owner user name

   
   

   Notes: The name parameter enables you to upgrade alerts by name. The oid parameter enables you to upgrade a specific alert by object ID. You can use the % wildcard character to specify deprecated master alert names. All 9.0.4.x notification objects (master alert service, master service, link, and so on) will be owned by the user name specified.

   
   

   The script does the following:

   • Creates a new master alert service named old master alert name_New. (This process involves converting the message template to a valid mobile xml, if necessary.)

   • Creates the folder \master\notifications, if it does not exist.

   • Creates the master service old master alert name_MS.

   • Creates a mapping for the new master alert and the new master service based on the message template for the old master alert.

   • Creates the folder \Users Home\username\notifications, if it does not exist.

   • Discovers all associated 9.0.2.x AlertService objects and converts them to link objects. (The top-level authorization is flattened to link level authorization during this process.)

   • Transforms all subscriptions for alert services converted.

The following command upgrades all 9.0.2.x master alert services whose name starts with StockAlert (for example, StockAlertNews, StockAlertWarning, and so on). All new objects will be owned by the orcladmin user.

migrateNotifications.bat -name StockAlert% -owner orcladmin

The following command upgrades the 9.0.2.x master alert service with the name StockAlert, and assigns all new objects to the systemadmin user.

migrateNotifications.bat -name StockAlert -owner systemadmin

The following command upgrades the 9.0.2.x master alert service with the object ID 1973, and assigns all new objects to the systemadmin user.

migrateNotifications.bat -oid 1973 -owner systemadmin

4.6.9.2 Operating OracleAS Wireless Release 2 (9.0.2), 10g (9.0.4), and 10g Release 2 (10.1.2) Middle Tiers Together

You can operate an environment with Oracle9iAS Wireless Release 2 (9.0.2) and Oracle Application Server Wireless 10g Release 2 (10.1.2) middle tiers using the same Infrastructure services. However, this configuration is subject to some restrictions, as described below.

• J2ME download and XHTML/XForms based applications should not be used in a mixed environment. These features are new in Oracle Application Server Wireless 10g Release 2 (10.1.2), and would cause errors when attempting to access them from any of the Oracle9iAS Wireless Release 2 (9.0.2) middle tiers. If you wish to use these features, then it is necessary to upgrade all middle tiers to Oracle Application Server Wireless 10g Release 2 (10.1.2).

• The Notification Engine cannot be used in a mixed environment. Instead, you should use the Alert Engine.

• Service access point (service-level address) should be created through an Oracle Application Server Wireless 10g Release 2 (10.1.2) middle tier, in order for them to be visible to both the Oracle Application Server Wireless 10g Release 2 (10.1.2) middle tiers and Oracle9iAS Wireless Release 2 (9.0.2) middle tiers.

• Oracle Application Server Wireless 10g Release 2 (10.1.2) supports user name case sensitivity. However, this requires that you upgrade the Oracle Internet Directory to Oracle Application Server 10g Release 2 (10.1.2).

• If you change (add, delete, or update) a 10g Release 2 (10.1.2) ASK Access point, the changes you make will not be reflected in the Release 2 (9.0.2) Enterprise Manager Web site until the Release 2 (9.0.2) Enterprise Manager Web site and the OC4J_Wireless OC4J instance is restarted.

  Specifically, a driver account (for example, an e-mail account for an e-mail driver) that is removed from an instance and subsequently added to another instance that is a different release version (for example, from Release 2 (9.0.2) to 10g Release 2 (10.1.2)) may cause messages to be lost. Restarting the OC4J_Wireless OC4J instance resolves this problem.

• The Notification Engine introduced in Oracle Application Server Wireless 10g Release 2 (10.1.2) replaces the Alert Engine, which was part of Oracle9iAS Wireless Release 2 (9.0.2). Although the Alert Engine is still available in Oracle Application Server Wireless 10g Release 2 (10.1.2), Oracle Corporation recommends that after all middle tiers have been upgraded to Oracle Application Server Wireless 10g Release 2 (10.1.2), you switch to the Notification Engine, as the Alert Engine may not be available in future versions of Oracle Application Server Wireless.

  Upgrade scripts are available to help you with this task. See the Oracle Application Server Wireless Developer's Guide for details. The Oracle9iAS Wireless Release 2 (9.0.2) Alert APIs have been deprecated, and you must upgrade your applications to use the Oracle Application Server Wireless 10g Release 2 (10.1.2) APIs instead.

• Oracle Sensor EdgeServer processes will not operate in a mixed environment of Release 2 (9.0.2), 10g (9.0.4), or 10g Release 2 (10.1.2) middle tiers. To use these features, you must upgrade all middle tiers to 10g Release 2 (10.1.2) and upgrade the OracleAS Metadata Repository to 10g Release 2 (10.1.2).

4.6.9.3 Configuring Site-Level Drivers in a Mixed Mode Environment

In a mixed mode environment, Oracle9iAS Wireless Release 2 (9.0.2) and Oracle Application Server Wireless 10g Release 2 (10.1.2) may have transport drivers configured to receive incoming messages. The two sets of entry points, Oracle9iAS Wireless Release 2 (9.0.2) and Oracle Application Server Wireless 10g Release 2 (10.1.2), should not be exposed to a device at the same time. A user issuing a request to the Release 2 (9.0.2) instance should not subsequently send another request, within an 3 hour period, to the entry point defined in the transport driver of the Oracle Application Server Wireless 10g Release 2 (10.1.2) instance. The same user may not receive any response for requests addressed to the latter entry point, if it is violated.

Since the driver configuration is different in Release 2 (9.0.2) and 10g Release 2 (10.1.2), when a Oracle9iAS Wireless Release 2 (9.0.2) instance is upgraded to Oracle Application Server Wireless 10g Release 2 (10.1.2), the transport drivers must be managed such that requests are processed as expected.

In 10g Release 2 (10.1.2), a site level driver can be enabled or disabled. By default, it is enabled. If a driver is disabled, it is not recognized by the routing algorithm, and therefore is not used by the messaging system. However, in Release 2 (9.0.2), all site level drivers are recognized by the routing algorithm.

If a Release 2 (9.0.2) instance has two middle tiers, after one of the middle tiers and the Infrastructure are upgraded to 10g Release 2 (10.1.2), the upgraded middle tier may enable or disable a site level driver. However, middle tiers that are not yet upgraded recognize all drivers as enabled. For this reason, it is prudent to remove, rather than disable, a driver in this type of environment.

InRelease 2 (9.0.2), the transport mechanism can route a message to only one driver, and it does not matter whether there is an instance configured for it. This means that a message will not be delivered if it is indeed routed to a driver that has no instance configured. For this reason, the best practice is to remove all drivers that do not have an instance configured in any Release 2 (9.0.2) environment, including a Release 2 (9.0.2) and 10g Release 2 (10.1.2) mixed environment.

4.6.9.4 Restoring the OracleAS Wireless Release 2 (9.0.2) Schema

If, after installing the Oracle Application Server Wireless 10g Release 2 (10.1.2), you decide that you do not want to use it and want to use OracleAS Wireless Release 2 (9.0.2), you can restore the 9.0.2 WIRELESS schema:

1. Remove all objects from the WIRELESS schema, which is now at version 9.0.4, in the 9.0.2 metadata repository.

   To do this, run the wirelessrm.sql script. The Oracle home refers to the Oracle home for the 9.0.4 middle tier.

   cd %ORACLE_HOME%\wireless\repository\sql
   sqlplus system/password@service_name @wirelessrm.sql
   
   

2. Restore the 9.0.2 WIRELESS schema by importing the database export file created in step 2 of the previous procedure.

   imp system/password@service_name file=iasw902.dmp
      fromuser=wireless touser=wireless
   

4.6.9.5 Manually Creating Oracle Sensor Edge Server Processes After the OracleAS Metadata Repository Upgrade

When you upgrade to 10g Release 2 (10.1.2), Oracle Sensor EdgeServer Processes will not be created automatically. Instead, you must create these processes manually after you run the OracleAS Upgrade Assistant and after you have upgraded the OracleAS Metadata Repository to 10g Release 2 (10.1.2).

Note, however, that you cannot create Oracle Sensor Edge Server processes until after you upgrade the OracleAS Metadata Repository to 10g Release 2 (10.1.2).

4.6.9.6 OracleAS Wireless Middle Tier Applications Require Upgrade of the OracleAS Metadata Repository

After you upgrade an OracleAS Wireless middle tier to 10g Release 2 (10.1.2), some of the applications provided by Oracle Application Server Wireless, such as Commerce, Location, PIM, and Examples will generate errors when accessed from your 10g Release 2 (10.1.2) middle tier. To prevent these errors from occurring, upgrade the OracleAS Metadata Repository to 10g Release 2 (10.1.2).

4.6.10.1 New Names for OracleAS Forms Services Files, Directories, URLs, and Environment Variables

For Oracle Application Server 10g Release 2 (10.1.2.0.2), the names of many OracleAS Forms Services files, directories, URLs, and environment variables have changed. The OracleAS Upgrade Assistant converts your OracleAS Forms Services configuration to the new names automatically.

4.6.10.2 Upgrading Forms *.fmx Files

If the OracleAS Forms Services executable files (.fmx files) exist in a directory within the source Oracle home, then manually copy these files to a relative path in the destination Oracle home. However, if these files are not in the source Oracle Home (for example, in a separate directory referenced by the FORMS_PATH environment variable), then this manual step is not required.

4.6.10.3 Upgrading OracleAS Forms Services EAR File Deployed in User-defined OC4J Instances

In the source Oracle home, the OracleAS Forms Services EAR file (forms90app.ear) is deployed by default into the OC4J_BI_Forms OC4J instance as forms90app. If you have re-deployed this ear file in a customized configuration in the OC4J_BI_Forms OC4J instance, then the OracleAS Upgrade Assistant automatically upgrades this deployment to the destination Oracle home.

However, if you have deployed the ear in any other default OC4J instance (home, OC4J_Portal, OC4J_Wireless) or in any user-defined OC4J instances, then this configuration will not be upgraded. In that case, redeploy the OracleAS Forms Services EAR file to the corresponding OC4J instance in the destination Oracle home.

The OracleAS Forms Services 10g Release 2 (10.1.2.0.2) formsapp.ear file is located in the folowing directory:

DESTINATION_ORACLE_HOME\forms\j2ee

4.8.3.1 Resetting the OracleAS Portal Service Monitoring Link In the Source Oracle Home

If you decide to revert to using the source middle tier, you must reset the Portal Service Monitoring link in the Services portlet on the Portal Builder page before you can begin using the Oracle home again.

Oracle Application Server provides the monseed.sql script to automate the process of resetting the Portal Service Monitoring link.

The following instructions describe how to use the script:

1. Set the ORACLE_HOME environment variable to the source middle tier Oracle home.

2. Navigate to the following directory:

   %ORACLE_HOME%\portal\admin\plsql\wwc
   
   

3. Using SQL*Plus, connect to the Portal schema.

4. If you are reverting to a Release 2 (9.0.2) Oracle home, enter the following command to run the monseed.sql script:

   @monseed.sql EM_host EM_port Portal_DAD middle_tier_host middle_tier_port instance_name
   
   

   For example:

   @monseed.sql midtierhost.acme.com 1810 portal midtierhost.acme.com 7777 ias902mid.midtierhost.acme.com
   
   

   Refer to Table 4-7 for a description of the arguments you must provide to the monseed.sql script.

5. If you are reverting to a 10g (9.0.4) Oracle home, then enter the following command to run the monseed.sql script:

   @monseed.sql EM_protocol EM_host EM_port Portal_DAD instance_name
   
   

   For example:

   @monseed.sql http midtierhost.acme.com 1810 portal as904.midtierhost.acme.com
   
   

   Refer to Table 4-7 for a description of the arguments you must provide to the monseed.sql script.

SOURCE_ORACLE_HOME\sysman\emd\targets.xml

4.8.3.2 Resetting the OracleAS Portal Services Monitoring Link When Reverting Back to the Destination Oracle Home

If you upgrade to 10g Release 2 (10.1.2.0.2), revert to the source Oracle home, and later want to revert back to the 10g Release 2 (10.1.2.0.2) Oracle home, consider the following information about the OracleAS Portal Services Monitoring link.

In earlier releases of Oracle Application Server, including Release 2 (9.0.2), 10g (9.0.4), and 10g Release 2 (10.1.2.0.0), clicking the Portal Services Monitoring link displays the OracleAS Portal Monitoring Page in the Application Server Control Console.

Starting with 10g Release 2 (10.1.2.0.2), the behavior of this link has changed. It now displays the Farm page in the Application Server Control Console. You can then access the OracleAS Portal Monitoring Page by selecting the Application Server that is servicing the Portal that you want to monitor, and then selecting the Portal target in the System Components table.

As a result, if you upgrade to 10g Release 2 (10.1.2.0.2), revert to the source Oracle home, and later want to revert back to the 10g Release 2 (10.1.2.0.2) Oracle home, then you must run the monseed.sql script with a slightly different set of arguments than those described in Section 4.8.3.1, "Resetting the OracleAS Portal Service Monitoring Link In the Source Oracle Home".

Otherwise, the Portal Service Monitoring link will not function properly.

To revert back to the 10g Release 2 (10.1.2.0.2) Oracle home, perform steps 1 through 3 as described in Section 4.8.3.1, and then enter the following command to reset the Portal Services Monitoring link for 10g Release 2 (10.1.2.0.2):

monseed.sql EM_protocol EM_host EM_port

In this example:

• EM_protocol is the protocol used to connect to the Application Server Control Console. The value can be http or https. Use https if the the Application Server Control security has been enabled.

• EM_host is the hostname used to connect to the Application Server Control

• EM_port is the port used to connect to the Application Server Control

4.9.4.1 Deinstallation of 9.0.2 or 9.0.3 Instances from a Computer that Also Contains 10g Release 2 (10.1.2) Instances

If you have 9.0.2 or 9.0.3 and 10g Release 2 (10.1.2) instances on the same computer, and you want to deinstall a 9.0.2 or 9.0.3 instance, perform these steps:

1. Apply patch 32346813352263 to your 9.0.2 or 9.0.3 instances. You can download the patch from OracleMetaLink (http://metalink.oracle.com).

   See Section 4.9.4.2, "Issue: 10g Release 2 (10.1.2) Instance Must Not Contain the Active Oracle Enterprise Manager" for details on why you need this patch.

2. Stop all processes associated with the instance you want to deinstall.

3. Run the installer to deinstall the 9.0.2 or 9.0.3 instance. Make sure you run the version of Oracle Universal Installer that was used to install the Release 2 (9.0.2) or Release 2 (9.0.3) instance.

   For example, for Release 2 (9.0.2) and Release 2 (9.0.3) instances, start the installer from the Start menu: Start / Programs / Oracle Installation Products / Universal Installer.

4.9.4.2 Issue: 10g Release 2 (10.1.2) Instance Must Not Contain the Active Oracle Enterprise Manager

If you have multiple 9.0.2 and/or 9.0.3 instances on the same computer, these instances share an Oracle Enterprise Manager. This is the "active Oracle Enterprise Manager". When you deinstall the instance that contains the active Oracle Enterprise Manager using the installer, the installer needs to switch the active Oracle Enterprise Manager to one of the remaining instances. If there is only one remaining instance, then the installer automatically makes it the active Oracle Enterprise Manager. If more than one instance remain, the installer prompts you to select the instance to contain the active Oracle Enterprise Manager.

Unlike 9.0.2 or 9.0.3 instances, Oracle Application Server 10g Release 2 (10.1.2) instances on the same computer do not share an Oracle Enterprise Manager. Each 10g Release 2 (10.1.2) instance has its own Oracle Enterprise Manager.

Because 10g Release 2 (10.1.2) instances do not share an Oracle Enterprise Manager, you must not select a 10g Release 2 (10.1.2) instance to contain the active Oracle Enterprise Manager. You must select a 9.0.2 or 9.0.3 instance to contain the active Oracle Enterprise Manager.

If you select a 10g Release 2 (10.1.2) instance, or if the installer automatically switches the active Oracle Enterprise Manager to a remaining instance that happens to be a 10g Release 2 (10.1.2) instance, the installer overwrites files in the 10g Release 2 (10.1.2) Oracle home with files from the 9.0.2 or 9.0.3 home. This causes Oracle Enterprise Manager to stop working.

The patch described in Section 4.9.4.1, "Deinstallation of 9.0.2 or 9.0.3 Instances from a Computer that Also Contains 10g Release 2 (10.1.2) Instances" prevents the installer from automatically switching the active Oracle Enterprise Manager to a 10g Release 2 (10.1.2) instance in the case where the only remaining instances are 10g Release 2 (10.1.2) instances. It also prevents the installer from displaying 10g Release 2 (10.1.2) instances in the list where you select the instance to contain the active Oracle Enterprise Manager.

4.9.4.3 If a 10g Release 2 (10.1.2) Instance Becomes the Active Oracle Enterprise Manager

If a 10g Release 2 (10.1.2) instance becomes the active Oracle Enterprise Manager, Oracle Enterprise Manager will stop working.

To fix this, perform these steps in the 10g Release 2 (10.1.2) Oracle home:

1. Shut down the Oracle Enterprise Manager Application Server Control:

   DESTINATION_ORACLE_HOME\bin\emctl stop iasconsole
   
   

2. Rename the following files. Do not delete the files, because you might need them in step 5. You can rename them with an "active" suffix (for example, iasadmin.properties.active):

   DESTINATION_ORACLE_HOME\sysman\config\iasadmin.properties
   DESTINATION_ORACLE_HOME\sysman\emd\targets.xml
   DESTINATION_ORACLE_HOME\sysman\j2ee\config\jazn-data.xml
   DESTINATION_ORACLE_HOME\sysman\webapps\emd\WEB-INF\config\consoleConfig.xml
   
   

3. Copy the backup files for the files listed in the preceding step.

   The backup files are in the same directory as the listed files. The names of the backup files are suffixed with a digit (for example, iasadmin.properties.1). Check the timestamp, or check the content, of the backup files to determine the most recent backup file.

4. Start the Oracle Enterprise Manager Application Server Control.

   DESTINATION_ORACLE_HOME\bin\emctl start iasconsole
   
   

5. If you have remaining Release 2 (9.0.2) or Release 2 (9.0.3) instances on the computer, you need to designate one of them to contain the active Oracle Enterprise Manager.

   1. Copy the files listed in step 2 (which you renamed with the active suffix) to the Release 2 (9.0.2) or Release 2 (9.0.3) instance Oracle home. Rename them back to the original names (that is, remove the active suffix).

   2. Update the following key in the Registry to refer to the new active Oracle Enterprise Manager:

      HKEY_LOCAL_MACHINE / SOFTWARE / ORACLE / EM_LOC
      
      

      Steps for updating the key:

      i. Select Start / Run. Enter regedit to start up the Registry Editor.

      ii. In the left frame, expand HKEY_LOCAL_MACHINE / SOFTWARE.

      iii. In the left frame, select ORACLE.

      iv. In the right frame, double-click EM_LOC. Update the path to point to the new active Oracle Enterprise Manager and click OK.

4.10.1.1 Understanding the Components of Oracle Application Server Cluster

If you are using Oracle Application Server Cluster, then you have installed multiple Oracle Application Server middle-tier instances, and two or more of the instances belong to the same farm and to the same OracleAS Cluster.

A farm is a collection of instances that share the same Distributed Configuration Management (DCM) repository. The DCM repository can be one of the following:

• A database-based repository that contains the DCM schema

  The database-based repository can be an OracleAS Metadata Repository installed as part of an Oracle Application Server Infrastructure installation, or it can be an OracleAS Metadata Repository created using the Oracle Application Server Metadata Repository Creation Assistant (OracleAS Metadata Repository Creation Assistant).

  In either case, the database repository contains the DCM schema, as well as schemas used by many other Oracle Application Server components.

• A File-based Repository that does not require an Oracle database.

  The File-based Repository contains only the DCM schema and does not contain other component schemas required for various Oracle Application Server components. As a result, it can be used only as an OracleAS Farm for multiple J2EE and Web Cache installations.

  When you create a cluster in a file-based DCM repository, there is no database, but one of the instances in the cluster becomes the repository host. The file-based repository resides on the repository host.

4.10.1.2 Upgrading Oracle Application Server Cluster in a Database-Based Repository

To upgrade Oracle Application Server Cluster in a database-based repository:

1. Log in to one of the middle tier instances that are part of the cluster and identify the names of all the middle tier instances that are currently in the cluster.

   You can use the DCM command line to identify the members of the cluster, or you can use the Application Server Control Console.

   To use the DCM command line:

   1. Enter the following command to identify the name of the cluster:

      SOURCE_ORACLE_HOME\dcm\bin\dcmctl listclusters
      
      

   2. Enter the following command to list the instances in the cluster:

      SOURCE_ORACLE_HOME\dcm\bin\dcmctl listinstances -cl cluster_name
      
      

   To use the Application Server Control Console, navigate to the Cluster page to see a list of the instances in the cluster.

   
   

   See Also: "About Managing Oracle Application Server Clusters" in the Application Server Control online help

   
   

2. Use the instructions in the remaining sections of this chapter to upgrade each of the middle tiers in the cluster and then start each newly upgraded 10g Release 2 (10.1.2) instance.

3. When all the middle tiers are upgraded and running, make sure the original, source instances are stopped.

4. For each source middle tier, use the following commands to remove the source middle tier from the cluster and then from the database-based farm:

   SOURCE_ORACLE_HOME\dcm\dcmctl leavecluster
   SOURCE_ORACLE_HOME\dcm\dcmctl leavefarm
   
   

5. Add each of the newly upgraded 10g Release 2 (10.1.2) instances to the database-based farm.

   You can add each instance to the farm by using the Application Server Control Console.

   
   

   See Also: "Adding an Instance to an Oracle Application Server Farm" in the Application Server Control online help

   
   

6. After you add the 10g Release 2 (10.1.2) instances to the farm, recreate the cluster and add each of the instances to the new 10g Release 2 (10.1.2) cluster.

   You can recreate the cluster and add each instance to the cluster by using the DCM command line (dcmctl) or by using the Farm page in the Application Server Control Console.

   
   

   See Also: "Farm Creation and Maintenance Tasks" in the Distributed Configuration Management Administrator's Guide for information about using the DCM command line "About Managing Oracle Application Server Clusters" in the Application Server Control online help

   
   

4.10.1.3 Upgrading Oracle Application Server Cluster in a File-Based Repository

To upgrade OracleAS Cluster in a file-based repository:

1. Identify the file-base repository host.

   The repository host is the computer you were logged in to when you created the file-based repository. The file-based repository resides on this host.

2. Log in to the repository host and identify the names of all the middle tier instances that are currently in the cluster.

   You can use the DCM command line to identify the members of the cluster, or you can use the Application Server Control Console.

   To use the DCM command line:

   1. Enter the following command to identify the name of the cluster:

      SOURCE_ORACLE_HOME\dcm\bin\dcmctl listclusters
      
      

   2. Enter the following command to list the instances in the cluster:

      SOURCE_ORACLE_HOME\dcm\bin\dcmctl listinstances -cl cluster_name
      
      

   To use the Application Server Control Console, navigate to the Cluster Home page to see a list of the instances in the cluster.

   
   

   See Also: "About Managing Oracle Application Server Clusters" in the Application Server Control online help

   
   

3. In preparation for upgrading the cluster, install a new 10g Release 2 (10.1.2) J2EE and Web Cache instance in a new Oracle home on the file-based repository host.

   During the installation procedure, create a new file-based repository for the 10g Release 2 (10.1.2) instance. Do not use the OracleAS Upgrade Assistant to upgrade the original source Oracle home to 10g Release 2 (10.1.2) until later in this procedure.

   
   

   See Also: Oracle Application Server Installation Guide for information on creating a new file-based repository as part of the Oracle Application Server installation procedure.

   
   

4. For each of the other cluster members—but not the instance on the repository host—do the following:

   1. Log in to the middle tier host and install a new 10g Release 2 (10.1.2) J2EE and Web Cache instance in a new Oracle home.

      During the installation, join the 10g Release 2 (10.1.2) farm you created when you installed 10g Release 2 (10.1.2) on the repository host.

   2. Use the instructions in Section 4.4, "Task 3: Run the OracleAS Upgrade Assistant" to upgrade the instance to 10g Release 2 (10.1.2).

5. Log in to the file-based repository host and, using the instructions in Section 4.4, "Task 3: Run the OracleAS Upgrade Assistant", upgrade the instance on the repository host to 10g Release 2 (10.1.2).

6. Recreate the cluster and then add each of the instances to the new 10g Release 2 (10.1.2) cluster.

   You can recreate the cluster and add each instance to the cluster by using the DCM command line (dcmctl) or by using the Farm page in the Application Server Control Console.

   
   

   See Also: Distributed Configuration Management Administrator's Guide for information about using the DCM command line "About Managing Oracle Application Server Clusters" in the Application Server Control online help

   
   

4.10.1.4 Updating the mod_oc4j Configuration File for an Upgraded Cluster

Perform the following additional tasks after you upgrade the cluster to preserve your request routing configuration:

1. Use a text editor to open the following file in one of the instances, noting the instance and cluster names in the Oc4jMount directives:

   DESTINATION_ORACLE_HOME\Apache\Apache\conf\mod_oc4j.conf
   
   

2. Change the instance (and, if necessary) cluster names to the instance name of the upgraded instance.

3. Copy the Oc4jMount directives to the mod_oc4.conf file in each instance in the new cluster.

4. Verify that requests that match the URL patterns in the Oc4jMount directives are routed to the correct instances.