| Oracle® Fusion Middleware Application Adapters Installation Guide for Oracle WebLogic Server 11g Release 1 (11.1.1.4.0) E17054-04 |
|
 Previous |
 Next |
| Oracle® Fusion Middleware Application Adapters Installation Guide for Oracle WebLogic Server 11g Release 1 (11.1.1.4.0) E17054-04 |
|
Previous |
Next |
This appendix describes how to migrate to Oracle Fusion Middleware Application Adapter for SAP R/3 (SAP JCo 3.x). It contains the following sections:
A new version of the Oracle Fusion Middleware Application Adapter for SAP R/3 is available that supports SAP Java Connector (SAP JCo) version 3.x. The SAP JCo API has changed by providing a different set of connection parameters to connect with the SAP R/3 server. As a result, the new Oracle Fusion Middleware Application Adapter for SAP R/3 has a different set of connection parameters than the previous version, which supported SAP JCo version 2.x. This introduced a backward compatibility issue by preventing users to reuse adapter targets and channels that were created by the previous version of the SAP R/3 adapter with the new version of the adapter that supports SAP JCo version 3.x. To enable the transition from the previous version of the SAP R/3 adapter, a command line migration utility is available that can be used to migrate the adapter targets and channels from the SAP R/3 adapter (using SAP JCo 2.x) to the SAP R/3 adapter (using SAP JCo 3.x).
This migration utility cannot completely automate the migration of the targets and channels between the SAP R/3 adapters because of the incompatibility between the SAP JCo versions. As a result, some manual operation is required. The scope of the migration utility is to provide adapter target and channel migration capabilities between both versions of the SAP R/3 adapter. The migration utility does not provide any other functionality and cannot be used for any other purposes. In this appendix, the SAP R/3 adapter (using SAP JCo 2.x) is referred to as the sap2 adapter and the SAP R/3 adapter (using SAP JCo 3.x) is referred to as the sap3 adapter.
The following Oracle releases are supported:
10.1.3.4
11g PS1
11g PS2
Only J2CA configurations are supported for migration purpose. BSE configurations are not be supported by the migration utility. The migration utility only supports Oracle database repositories for migration purposes. No other database repositories are supported. The utility works with a file repository, but migrating file repositories is not supported.
The migration utility is located in the following directory:
<ADAPTER_HOME>\etc\util
The contents of the util folder include:
The SAP2_to_SAP3 Migration.docx file, which is a help document for the migration utility.
The iwrepocmd.jar file, which is the required .jar file for the migration utility.
|
Note: Theiwrepocmd.jar file must not be used for any other purpose other than the migration. This file must not be part of the classpath or any other path when the adapter is running for design time or runtime purposes. |
The sapupd.bat file, which is the migration utility .bat file for Windows platforms.
The sapupd.sh file, which is the migration utility .sh file for UNIX/Linux platforms.
This section describes the syntax that must be used with the migration utility.
Syntax for Listing the Targets or Channels
sapupd list config [targets | channels] [sap2 | sap3 | sap2to3] [-jdbc driver url user password | -file file] > [output file]
Table C-1 Syntax for Listing the Targets or Channels
| Syntax | Description |
|---|---|
|
|
Command to list the adapter targets or channels. |
|
|
The name of the J2CA configuration that was specified by the user in Application Explorer. |
|
|
List of targets or channels. |
|
|
List of sap2 objects, sap3 objects, or sap2 objects as mapped to sap3 parameters. |
|
|
Repository to connect to, which can be a file or Oracle database repository. The JDBC URL is used to connect to the Oracle database repository. |
|
|
List of adapter targets or channels are redirected to the output file, which must use the .tab extension. |
Usage considerations:
Use the sapupd list command to list the targets or channels from a file or Oracle database repository (J2CA configuration). The output consists of tab-delimited text with targets or channels as columns and parameters as rows.
The sap2 and sap3 options are provided to allow you to list the respective SAP R/3 objects from the repository.
When you run the migration utility, you can list only the adapter targets or channels. Adapter targets or channels cannot be combined to create a single Excel spreadsheet.
The output file name must use the .tab extension, since that extension is recognized by Excel for the migration. In this appendix, the output file uses the sap2to3.tab naming convention.
To replace sap2 objects with sap3 objects, the sap2to3 option can be used.
In the following examples, the sapupd list command lists all sap2 targets mapped to sap3 parameters into the sap2to3.tab file.
File Repository Example
sapupd listjcatargets sap2to3 -file $ADAPTER_HOME\config\jca_sample\repository.xml > sap2to3.tab
In this example:
ADAPTER_HOME is the location where the adapters are installed.
jca represents the name of the J2CA configuration that was specified in Application Explorer.
Database Repository Example
sapupd list jca targets sap2to3 -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott scott1 > sap2to3.tab
For UNIX/Linux platforms, execute the sapupd.sh file. For example, the following command lists all sap2 channels mapped to sap3 parameters into the dbchn.tab file for a database repository:
./sapupd.sh list jca_sample channels sap2to3 -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@172.19.20.242:1521:orcl system welcome1 > dbchn.tab
Syntax for Updating the Targets or Channels
sapupd update config [targets | channels] sap2to3[source file] [-jdbc driver url user password | -file file]
Table C-2 Syntax for Updating the Targets or Channels
| Syntax | Description |
|---|---|
|
|
Command to update the adapter targets or channels. |
|
|
The name of the J2CA configuration that was specified in Application Explorer. |
|
|
List of targets or channels to update. |
|
|
The source Excel file that contains the mappings between sap2 and sap3 parameters. |
|
|
Repository to connect to, which can be a file or Oracle database repository. The JDBC URL is used to connect to the Oracle database repository. |
Use the sapupd update command to update the targets or channels in a file or Oracle database repository (J2CA configuration).
File Repository Example
sapupd update jca targets sap2to3 sap2to3.tab -file $ADPTER_HOME\config\jca_sample\repository.xml
Database Repository Example
sapupd update jca targets sap2to3 sap2to3.tab -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott scott1
For UNIX/Linux platforms, run the sapupd.sh file. For example:
./sapupd.sh update jca targets sap2to3 sap2to3.tab -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@172.19.20.242:1521:orcl system welcome1
A manual step must be performed before you create the list and update the J2CA repository. This is the process of mapping the values between sap2 and sap3 adapter targets and channels. At this stage, you must take a look at the values underneath each adapter target/channel column and update the output file that has been created accordingly. While editing, do not remove or add rows and columns to the file. Also, do not change the SAP R/3 connection parameters in the file. The only action allowed is to update the parameter values.
Figure C-1 shows sample output from a J2CA repository with two SAP R/3 application server targets, "asserver2" and "isdsrv2", and one SAP R/3 message server target, "msgsrvr", as opened in an Excel spreadsheet. The SAP R/3 parameters have been pre-populated with the matching sap2 parameter values. If no matching value was present in the sap2 target, then the sap3 parameter default is used.
You can add or modify parameter values as required, then save the file and use it to replace existing sap2 objects with sap3 objects.
The update command can be used only to replace existing sap2 targets or channels with their sap3 equivalents. It cannot be used to create new targets or channels or to edit the parameter values of existing targets and channels. Also, you cannot change the adapter target or channel names in the file.
This section provides a use case scenario for the migration utility.
Close Application Explorer. Ensure that no instance of Application Explorer is running and that no updates are being made in the J2CA repository.
Use the sapupd list command to list the connection parameters into an Excel spreadsheet. This command inserts the sap2 targets or channels into the spreadsheet. Running this command only extracts targets or channels. As a result, first run the command to list the adapter targets and then repeat the command to list the channels. Ensure to save the contents in separate files for adapter targets and channels.
Make an required updates to the Excel spreadsheet. This is the step where the Excel spreadsheet is updated with the sap3 targets and channels.
Stop Oracle WebLogic Server if it is running. Remove the SAP R/3 adapter (using SAP JCo 2.x) files and any SAP JCo 2.x library files from the adapter environment.
Install the SAP R/3 adapter (using SAP JCo 3.x) in the environment. This adapter is delivered as a patch for 10.1.3.4 and 11g PS1 releases. It is a part of the application adapters in the 11g PS2 release.
If you are using a 10.1.3.4 adapter environment, then check the installation documentation when making any changes to configuration files (for example, server.xml).
Use the sapupd update command to update the connection parameters for sap3 targets or channels. Running this command only updates adapter targets or channels from different files. As a result, repeat the steps accordingly with the correct input file. As a best practice, first update the adapter targets and then update the adapter channels.
Start Application Explorer and connect to an SAP R/3 adapter (using SAP JCo 3.x) target and channel to ensure that the design time is working.
Restart the Oracle WebLogic Server and execute runtime test cases to verify successfully functionality.
This section includes useful considerations for the migration utility.
The following is list of actions that are recommended:
Close Application Explorer before executing the update command. The target or channel parameters are not updated if Application Explorer is open.
If you are using an Oracle database as a database repository and if it is running in more than one system, more than one instance, or part of a cluster, then the migration utility must be executed in each of the environments separately. The migration utility updates details in one database repository at any given point of time. It does not update into multiple databases repository instances.
The following is list of actions that must be avoided:
Do not add, delete or change the rows in the Excel spreadsheet that was created by the upgrade utility.
Do not rename the targets or channels in the Excel spreadsheet that was created by the upgrade utility.
Do not add or delete the column in the Excel spreadsheet that was created by the upgrade utility.
This utility cannot be used to migrate the adapter targets and channels from one environment to another environment. For example, migration between development, testing, and production environments cannot be performed. You must use the migration utility in each of the environments separately.
This section describes best practices for the migration utility.
Create a backup of the Oracle database which contains the J2CA repository. This applies irrespective of development, testing, and production environments. In case of a file repository, create a backup of the file repository. This also applies irrespective of development, testing, and production environments. The file repository is located in the adapter folder structure. For example:
$ADAPTER_HOME\applicationadapters\config\jca
When the migration utility extracts information into the Excel spreadsheet, the Excel spreadsheet takes 00 as 0 for the system number parameter value for the sap2 target. When the sap2 target values are mapped to sap3 from the Excel spreadsheet, the adapter target has the system number parameter value set to 0 in Application Explorer.
There is no issue with the adapter to work with this target in design and run time. However, it is recommended that you to manually update the target for the correct value. For example, replace "0" with "00".
There is no command to migrate both targets and channels. This must be done separately
When performing the upgrade in a production environment, consider the following guidelines:
Extract the sap2 adapter targets and channels well in advance of the production migration date. Perhaps two to four weeks earlier. This date is just an approximation.
Make changes to the Excel spreadsheet with the new parameter values for the sap3 adapter.
Upload the details from the Excel spreadsheet into the environment which should be an exact replica of the production environment. Ensure that the design time (Application Explorer), run time (BPEL, ESB, Mediator) is working. Note that if there is a change in the environment, then the runtime scenarios based on BPEL, ESB, and Mediator process flows would not work.
If everything is working accordingly, then keep the Excel spreadsheet intact until the production migration.
Do not make any changes to the adapter targets and channels in the production environment after extracting the details. If you make any changes, then repeat steps 1 through 4.
On the day of the production environment migration, use the Excel spreadsheet to update the sap3 adapter targets and channels.
This approach minimizes the downtime during the production migration.
If your production environment is high availability (cluster), then perform this procedure for all of the nodes that are part of the cluster.
This section provides troubleshooting information for the migration utility.
Executing the spaupd update command to update the adapter targets with the sap2to3.tab file, which contains the adapter channel parameters, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample targets sap2to3 sap2to3chn.tab -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott scott1Exception in thread "main" com.iwaysoftware.iwrepository.PrimaryKeyNotExsistsException: Primary key does not exist: xpath = //AF_CONFIG[cfg_adapter='MySAP' and cfg_name='jca_sample' and cfg_target='service_mysap_isdsrv2_ch2'] at com.iwaysoftware.iwrepository.xml.file.FileDataObjectFactory.getDataObject (FileDataObjectFactory.java:86)
Executing the spaupd update command to update the adapter channels with the sap2to3tgt.tab file, which contains the adapter target parameters, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample channels sap2to3 sap2to3tgt.tab -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott scott1
Exception in thread "main" com.iwaysoftware.iwrepository.PrimaryKeyNotExsistsException: Primary key does not exist: xpath = //AF_CONFIG[cfg_adapter='MySAP' and cfg_name='jca_sample' and cfg_channel='service_mysap_isdsrv2_tgt'] at com.iwaysoftware.iwrepository.xml.file.FileDataObjectFactory.getDataObject (FileDataObjectFactory.java:86)
After the connection parameters are updated successfully for the Oracle Fusion Middleware Application Adapter for SAP R/3 (SAP JCo 3.x), if you try to connect to the J2CA configuration using the SAPJCO 2.x libraries, the following exception is generated:
Jca could not initialize
Executing the sapupd list command to list the targets when no targets are available results in the creation of an empty output file (0 KB in size).
Executing the sapupd list command to list the channels when no channels are available results in the creation of an empty output file (0 KB in size).
Executing the sapupd update command without specifying a file name generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample targets sap2to3 -file C:\soadp1\adapters\application\config\jca_sample\repository.xml
Exception in thread "main" java.lang.Exception: File -file does not exist. at com.iwaysoftware.iwrepocmd.sap.Script.update(Script.java:67) at com.iwaysoftware.iwrepocmd.sap.Script.run(Script.java:83) at com.iwaysoftware.iwrepocmd.CommandBase.run(CommandBase.java:86) at com.iwaysoftware.iwrepocmd.sap.Command.main(Command.java:8)
Executing the sapupd update command to update the targets in a repository where no targets are available in the J2CA configuration (for example, empty repository.xml), generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample targets sap2to3 sap2to3tgt.tab -file C:\soadp1\adapters\application\config\jca_sample\repository.xml
Exception in thread "main" com.iwaysoftware.iwrepository.PrimaryKeyNotExsistsException: Primary key does not exist: xpath = //AF_CONFIG[cfg_adapter='MySAP' and cfg_name='jca_sample' and cfg_target='service_isdsrv2_tgt'] at com.iwaysoftware.iwrepository.xml.file.FileDataObjectFactory.getDataObject(FileDataObjectFactory.java:86) at com.iwaysoftware.iwrepocmd.sap.Sap2to3.updateDescriptor(Sap2to3.java:273) at com.iwaysoftware.iwrepocmd.sap.Sap2to3.updateTargets(Sap2to3.java:303)
Executing the sapupd update command to update the channels in a repository where no channels are available in the J2CA configuration (for example, empty repository.xml), generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample channels sap2to3 sap2to3chn.tab -file C:\soadp1\adapters\application\config\jca_sample\repository.xml
Exception in thread "main" com.iwaysoftware.iwrepository.PrimaryKeyNotExsistsException: Primary key does not exist: xpath = //AF_CONFIG[cfg_adapter='MySAP' and cfg_name='jca_sample' and cfg_channel='channel_isdsrv2_chn1'] at com.iwaysoftware.iwrepository.xml.file.FileDataObjectFactory.getDataObject(FileDataObjectFactory.java:86) at com.iwaysoftware.iwrepocmd.sap.Sap2to3.updateDescriptor(Sap2to3.java:273) at com.iwaysoftware.iwrepocmd.sap.Sap2to3.updateChannels(Sap2to3.java:325)
Executing the sapupd list command using the incorrect user name to the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd list jca_sample channels sap2to3 -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl sct scott1 > sap2to3.tabjava.sql.SQLException: ORA-01017: invalid username/password; logon denied at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.java:112) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331)
Executing the sapupd list command using the incorrect password to the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd list jca_sample channels sap2to3 -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott ott > sap2to3.tabjava.sql.SQLException: ORA-01017: invalid username/password; logon denied at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.ja:112) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:283) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:278)
Executing the sapupd list command using the incorrect URL to the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd list jca_sample channels sap2to3 -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:rl scott scott1 > sapt.tabjava.sql.SQLException: Listener refused the connection with the following error:ORA-12505, TNS:listener does not currently know of SID given in connect descriptorThe Connection descriptor used by the client was:192.168.128.164:1521:rl
Executing the sapupd list command using the incorrect driver to the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd list jca_sample channels sap2to3 -jdbc oracle.jdbc.driverr jdbc:oracle:thin:@192.168.128.164:1521:orcl scott scott1 > sapt.tabjava.lang.ClassNotFoundException: oracle.jdbc.driverr at java.net.URLClassLoader$1.run(URLClassLoader.java:200) at java.security.AccessController.doPrivileged(Native Method)
Executing the sapupd list command without specifying a driver to the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd list jca_sample channels sap2to3 -jdbc jdbc:oracle:thin:@192.168.128.164:1521:orcl scott scott1 > sapt.tabException in thread "main" java.lang.NullPointerException at com.iwaysoftware.iwrepository.IWRepositoryFactory.getRepositoryClassName(IWRepositoryFactory.java:196) at com.iwaysoftware.iwrepository.IWRepositoryFactory.getRepository(IWRepositoryFactory.java:163) at com.iwaysoftware.iwrepocmd.CommandBase.readOptions(CommandBase.java:67)
Executing the sapupd list command without specifying a user name to list sap2 / sap3 in the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd list jca_sample channels sap2to3 -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott1 > sap2to3.tabjava.lang.NullPointerException at java.util.Hashtable.put(Hashtable.java:394) at com.iwaysoftware.iwrepository.rdbms.oracle.OracleRepository.open(OracleRepository.java:144)
Executing the sapupd list command without specifying a password to list sap2 / sap3 in the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd list jca_sample channels sap2to3 -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott > sapt.tabjava.lang.NullPointerException at java.util.Hashtable.put(Hashtable.java:394) at com.iwaysoftware.iwrepository.rdbms.oracle.OracleRepository.open(OracleRepository.java:144) at com.iwaysoftware.iwrepository.IWRepositoryFactory.getRepo(IWRepositoryFactory.java:286)
Executing the sapupd update command with an incorrect user name to update sap2 to sap3 in the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample targets sap2to3 saptgt.tab -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl sco scott1java.sql.SQLException: ORA-01017: invalid username/password; logon denied at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.ja:112) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:283) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:278)
Executing the sapupd update command with an incorrect password to update sap2 to sap3 in the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample targets sap2to3 saptgt.tab -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott scpt1java.sql.SQLException: ORA-01017: invalid username/password; logon denied at oracle.jdbc.driver.DatabaseError.throwSqlException(DatabaseError.ja:112) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:331) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:283) at oracle.jdbc.driver.T4CTTIoer.processError(T4CTTIoer.java:278
Executing the sapupd update command without specifying a user name to update sap2 to sap3 in the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample channels sap2to3 saptch.tab -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott1 java.lang.NullPointerException at java.util.Hashtable.put(Hashtable.java:394) at com.iwaysoftware.iwrepository.rdbms.oracle.OracleRepository.open(OracleRepository.java:144)
Executing the sapupd update command without specifying a file name to update sap2 to sap3 in the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample targets sap2to3 -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott scott1Exception in thread "main" java.lang.Exception: File -jdbc does not exist. at com.iwaysoftware.iwrepocmd.sap.Script.update(Script.java:67) at com.iwaysoftware.iwrepocmd.sap.Script.run(Script.java:83) at com.iwaysoftware.iwrepocmd.CommandBase.run(CommandBase.java:86) at com.iwaysoftware.iwrepocmd.sap.Command.main(Command.java:8)
Executing the sapupd update command without specifying a password to update sap2 to sap3 in the database repository, generates the following exception:
C:\soadp1\adapters\application\etc\util>sapupd update jca_sample channels sap2to3 sapch.tab -jdbc oracle.jdbc.driver.OracleDriver jdbc:oracle:thin:@192.168.128.164:1521:orcl scott java.lang.NullPointerException at java.util.Hashtable.put(Hashtable.java:394) at com.iwaysoftware.iwrepository.rdbms.oracle.OracleRepository.open(OracleRepository.java:144) at com.iwaysoftware.iwrepository.IWRepositoryFactory.getRepo(IWRepositoryFactory.java:286)
|
 Copyright © 2010, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
