Oracle Utilities Software

Development Kit V4.4.0.2.x

Installation Guide

Last Modified: October 22, 2019 5:28 PM

Printed On: October 22, 2019
Installation Guide Oracle Utilities Software Development Kit

PROPRIETARY INFORMATION
THIS MATERIAL CONTAINS, AND IS PART OF, A COMPUTER SOFTWARE APPLICATION
WHICH IS PROPRIETARY INFORMATION OWNED BY ORACLE CORPORATION. THE
APPLICATION, INCLUDING THIS MATERIAL, MAY NOT BE DUPLICATED, DISCLOSED OR
REPRODUCED IN WHOLE OR IN PART FOR ANY PURPOSE WITHOUT THE EXPRESSED
WRITTEN AUTHORIZATION OF ORACLE CORPORATION.
This Document is subject to change without notice, and Oracle Corporation does not warrant that
the material contained in this Document is error-free. If you find any problems with this Document,
please report them to Oracle Corporation in writing.
Oracle Corporation and Oracle are registered trademarks of Oracle Corporation or one of its
subsidiaries. All other products or company names mentioned are used for identification purposes
only, and may be trademarks of their respective owners.

2 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Table of Contents
Table of Contents .......................................................................................................................... 3

Quick Start Installation ................................................................................................................. 4

Hardware Requirements ........................................................................................................... 4
Prerequisite Steps ..................................................................................................................... 4
Client Setup ............................................................................................................................... 6
Running Eclipse ........................................................................................................................ 7
Customer Modifications........................................................................................................... 11
Setting up more SDK workspaces .......................................................................................... 13
Running in the Command Prompt ........................................................................................... 14
Viewing SDK Documentation .................................................................................................. 15

Supplementary Guide ................................................................................................................. 16

Components of the Oracle Utilities Software Development Kit............................................... 16
Creating a Project Repository ................................................................................................. 18
Setting Up the Project Development Database ...................................................................... 18
Setting Up Development Workstations ................................................................................... 18
Packaging CM Code ............................................................................................................... 19
Installing a CM Release/Patch Package ................................................................................. 23
Packaging CM Data ................................................................................................................ 24
Service Pack Upgrades........................................................................................................... 25

Appendix ...................................................................................................................................... 27
Where is SPLSDKCommon? .................................................................................................. 27
Remove COBOL References .................................................................................................. 27
Suppressing Java Problems relating to undeclared serialVersionUID ................................... 28
Server does not start; unsupported lookup version ................................................................ 29
Setting up the Oracle Utilities SDK for a new Application Server ........................................... 29
Multiple CM Development and Deployment............................................................................ 30

©2019 Oracle Proprietary and Confidential 3

Installation Guide Oracle Utilities Software Development Kit

Quick Start Installation

Before the SDK can be installed, a fully functioning Oracle Utilities based application server
(e.g. CCB, MDM, MWM, ETM, etc.) for Windows must be installed on the developer’s computer.
If the application is not installed, the SDK setup program will not work.
The SDK installation consists of two basic parts: 1) the ClientSetup.exe program is executed first
to install the primary components and 2) the Eclipse Java IDE is downloaded separately and
configured for Oracle Utilities development.

Hardware Requirements
The following hardware configurations are per workstation.

Recommended
Windows 7
AMD64/x86-64, dual core CPU
8 GB RAM
40 GB hard drive space

Minimum
Windows 7
AMD64/x86-64, dual core CPU
4 GB RAM
20 GB hard drive space

Prerequisite Steps
Ensure that the following is done before continuing with the SDK setup program.
 Create a development database for your application. All developers typically share this
database. Refer to the product installation guide for details.
 Your application server must at least be running on JDK 1.8 (64-bit). The SDK will use
the same JAVA_HOME as your application server.
 Install and configure a Windows application server (e.g. CCB, MDM, ETM, MWM, etc.) on
the developer’s computer. Refer to the product installation guide for details.

Note that this must be an “exploded” environment; the SDK does not update the archive
files (ear/war) for certain types of changes.

4 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

 Perl should already be installed as a result of the application server installation. Check
the Windows executable PATH to make sure that the same Perl is used by the SDK
scripts. Windows commands “where perl” and “perl -version” can be used to verify that.
Perl v5.10.1 was used to certify this version of the SDK.
 This version of the SDK was certified on Luna, which can be downloaded from the
following links. Earlier versions of Eclipse are also supported. The downloaded file will
be unzipped to the correct folder later.

64-bit:
http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release
/luna/SR2/eclipse-java-luna-SR2-win32-x86_64.zip

 Verify that your Windows regional setting is English (USA).

©2019 Oracle Proprietary and Confidential 5

Installation Guide Oracle Utilities Software Development Kit

Client Setup
Run ClientSetup-4.3.0.0.x.exe to install the SDK. The installation wizard will prompt you for the
following information in the first input dialog:
SDK Folder: Specify the folder where you want the SDK will be installed. This is defaulted to
c:\ouafsdk_4_3_0_0_x. The SPLSDKROOT environment variable will hold this value. We
recommend that you keep this default so that you could distinguish between SDK
installations that are already installed in your workstation.
Application Server Folder: This is the folder where the Oracle Utilities Application Server
has been installed. ClientSetup will also obtain database information defaults from this folder.
The Eclipse workspace folder for this application server will also be created.
The installation wizard will obtain the JAVA_HOME and database logon information from the
application server’s ENVIRON.INI file.

Note: While ClientSetup would allow you to specify the SDK Folder to be the same as the
Application Server Folder, it is recommended that you DO NOT specify the same folder for both.
Also, the Oracle Client, Eclipse, Java, and Perl installations must be in 64-bit mode. The Oracle
Utilities Application Framework (v4.3.0) runs only in 64-bit bit mode.

The second input dialog will then prompt you to verify the defaulted database information:
Database Name: This defaults with the database name obtained from the
hibernate.properties file in the application server folders. Change only when if necessary.
Username: This defaults with the user id obtained from the hibernate.properties file in the
application server folders. Change if necessary.
Password: This defaults with the password obtained from the hibernate.properties file in the
application server folders. The password must be in clear text. Change if necessary.
When you have verified the database information, ClientSetup will proceed with the installation
and create a Program Group with shortcuts to the client scripts and Help library.
You may edit the setsplenv.bat file located in the environment specific “etc” folder of the Oracle
Utilities SDK installation folder (e.g. C:\ouafsdk_4_3_0_0_x\%SPLENVIRON%\etc) if you need to
make changes to the database information after the installation.

6 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

The Program Group

ClientSetup creates a program group for Oracle Utilities SDK 4.3.0.0.x that is accessible from the
Windows Start button. In the program group are shortcuts to scripts that you would typically use
during application development.

Running Eclipse
At this point, you should have downloaded Eclipse and hibernate-3.2.5.ga.jar. Have the zip file
name and jar location handy. Running Start Eclipse (from the Oracle Utilities SDK 4.3.0.0.x
Program Group) for the first time will set up the Oracle Utilities SDK for Eclipse for you. You just
need to provide the complete path to the Eclipse zip file and hibernate-3.2.5.ga.jar.
When Eclipse comes up, you should be all set to start an Oracle Utilities project.

Overriding Database Connection Settings

For the class creation wizards to work in Eclipse, the database connect parameters must be
specified in Eclipse. Navigate to Window, Preferences and Select Database Connection under
OUAF Preferences and then check the Override Default box and enter the Connection URL,
Username and Password (must be clear text). Then, click OK.

Note: The URL can be copied from the application server’s hibernate.properties file – i.e.
%SPLEBASE%\splapp\standalone\config\hibernate.properties.

©2019 Oracle Proprietary and Confidential 7

Installation Guide Oracle Utilities Software Development Kit

Create Eclipse Project

To begin Java development, an Eclipse project must be created. The Oracle Utilities plug-in,
accessible via the Oracle Project button, should be used to do that. It will automatically configure
the project with the appropriate build path and create run configurations for the artifact generator
and batch.

Click on the “New OUAF Project” to create a new Oracle Utilities project.

On the New Project dialog, supply a project name. Eclipse will create the project in the default
location. It will be named after the project name you entered. However, you could override this by
removing the check from the “Use default location” checkbox and entering your desired location.
Click Finish.

8 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

You may be prompted to switch to the Oracle Utilities perspective, but for now stay with either the
Java perspective or Java EE perspective.
You will be prompted to “Enter your CM Owner”. This is defaulted to “cm”. Accept this default for
now and click OK.

Note: You only need to change the default CM Owner if you are participating in the development
of a Multiple CM project. If you are, be sure to copy cm.jar (from CM Owner cm) to
%APPSVRDIR%\etc\lib and %APPSVRDIR%\splapp\standalone\lib before clicking Finish. If
you copied cm.jar after the fact, include a reference to it in the –appJars argument in your
project’s Generate Artifacts launch configuration. Multiple CM development is described in more
detail in the Appendix.

Wait for the New Project dialog to disappear and the project should be created similar to this (it
may take a few seconds). Note that the folder names are prefixed by an underscore (_). That is
because they are linked folders to the actual folders in the application server directory structure.

In addition, a set of new Run Configurations should have been created to run artifact generator
and development versions of ThreadPoolWorker and SubmitJob for batch testing. Open the Run
button drop down and click Run Configurations… to bring up the Run Configurations dialog.

©2019 Oracle Proprietary and Confidential 9

Installation Guide Oracle Utilities Software Development Kit

Under Java Applications, you should see configurations to Generate Artifacts, to invoke Submit
Job (for batch programs), and to invoke the ThreadPoolWorker (for batch programs).

Running a configuration will register it in the launch history of the Run button drop down.

Note: When starting a ThreadPoolWorker in Eclipse, the Eclipse Console view might appear to
be stuck or not working. If so, edit the _config/ tpwlog4j.properties and change the rootCategory
property to include A1 (ConsoleAppender) – e.g. “log4j.rootCategory=info, F1, A1”

10 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Customer Modifications
Customers Modifications (or CM) is code that is not shipped with the Oracle Utilities product. CM
is developed by the Oracle customer and is written to meet specific customer requirements. Any
new Oracle Utilities Project is a CM project and is a collection of algorithms, change handlers,
etc. To create these classes and interfaces, navigate to File, New, Other…, and then scroll down
to the Oracle Utilities section. Under Customizations are listed templates for classes and
interfaces. Select the type of object you want to create. Each type of object has its own
specialized wizard that would help you create a skeleton Java class in your workspace.

Deploying CM Code
Open the External Tools button drop-down and click Run Configurations… to bring up the
External Tools Configurations dialog.

©2019 Oracle Proprietary and Confidential 11

Installation Guide Oracle Utilities Software Development Kit

From there, look for the Deploy CM that corresponds to your project under Ant Build. Click it and
then click the Run button at the bottom of the dialog. Eclipse will remember this run configuration
and will register it in the launch history of the External Tools button drop down. The output of the
Ant build will show on the Eclipse console.
Once deployed, reboot your local application server and you should be able to test your custom
code in the online application. If this is the very first deployment of cm.jar, the
cm_jar_structure.xml file may need to be created and the application server rebuilt as described
below.

Create cm_jars_structure.xml
If your application server never had CM code previously deployed to it, you may need to create a
cm_jars_structure.xml file in %APPSVRDIR%\structures. If it does not exist, this template can be
used to create it:

<?xml version="1.0" encoding="UTF-8"?>

<jar_structure>
<cm.jar>
<source_dir_jar>@SPLEBASE@/etc/lib</source_dir_jar>
<dest_folders>
<dest_folder_1>@SPLEBASE@/splapp/applications/XAIApp/WEB-INF/lib</dest_folder_1>
<dest_folder_2>@SPLEBASE@/splapp/applications/root/WEB-INF/lib</dest_folder_2>
<dest_folder_3>@SPLEBASE@/splapp/businessapp/lib</dest_folder_3>
<dest_folder_4>@SPLEBASE@/splapp/standalone/lib</dest_folder_4>
</dest_folders>
<child_jvm_path>@SPLEBASE@/splapp/standalone/lib</child_jvm_path>
</cm.jar>
</jar_structure>

Open up a Command Prompt for your application server environment and run initialSetup. This
will rebuild and redeploy the application server to include your customizations.

Note that the initialSetup script uses this xml file to deploy your cm.jar to the appropriate
locations in the app server. On all subsequent deployments from Eclipse using the Deploy CM
launch configuration, initialSetup is not required as the Eclipse launch configuration will update
the necessary files.

Additional Pointers
 Oracle Utilities SDK 4.3.0.0.x will use the spl-tools jar that is appropriate for your
application server. Ensure that the FW_VERSION_NUM entry in your application server’s
etc\ENVIRON.INI file specifies your Oracle Utilities Framework version.

 Consider it a best practice to stop the instance of Weblogic (that is running your
application server) prior to deployment. This ensures the proper deployment of your
code.

12 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Setting up more SDK workspaces

The ClientSetup installer already sets up the first workspace for the application server you
selected during the initial setup of the SDK. However, if you have another application server in
your workstation that you want to develop on, you would have to use the Create Workspace
shortcut in the Oracle Utilities SDK program group.

The next time your run any of the shortcuts in the program group, the SDK will prompt you to for
an environment context under which the shortcut would run, for example:

©2019 Oracle Proprietary and Confidential 13

Installation Guide Oracle Utilities Software Development Kit

Running in the Command Prompt

To run the SDK scripts in the Command Prompt, you will need to open the Oracle Utilities SDK
Command Prompt:

The Command Prompt will run splenviron on the application server and will also initialize the SDK
environment. The current working folder should be the SDK shortcuts folder
(%SPLSDKROOT%\SDK\shortcuts).
Type “dir” to see all the available scripts.
Follow the prompts of the script you choose to run.

Note: In the SDK\Scripts\bin folder, the following scripts are obsolete: createCMEnv.pl and
switchenvironments.pl. The createCMEnv.pl script has been replaced by the
SDK\shortcuts\createNewEnv.bat script, which is launched using the Create Workspace shortcut
in the Oracle Utilities SDK program group. The switchenvironments.pl script is unnecessary
because the SDK now allows several Command Prompt windows to be opened under the context
of different application servers.

14 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Viewing SDK Documentation

The Oracle Utilities SDK is available in PDF form from the SDK Documentation link in the Oracle
Utilities SDK program group.

From the Eclipse main menu, the SDK documentation is available at Help  Help Contents.

©2019 Oracle Proprietary and Confidential 15

Installation Guide Oracle Utilities Software Development Kit

Supplementary Guide
This guide describes additional setup that may be necessary once the initial installation as
detailed above has been completed.

Components of the Oracle Utilities

Software Development Kit
The following diagram illustrates the typical development environment.

Development Project
Workstation Repository
Sync / Submit Code
Sy
st
em
D
at
a

Project
Dev DB

Development Environment

Development
Client
The following are both Development
Clients:
• Project Repository
• Development Workstation

Development Clients have:

• Development App Server
• SPL SDK Client
• Java IDE

Development Client

16 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Project Repository
The project repository serves the following purposes:
 It is the central storage for all completed, unit-tested code.
 It provides the environment from which to build the latest state of the project.
 It provides the latest state of the project dev app server from which all developers can
synchronize with.
 It is the source for CM Packaging.
To support these purposes:
 It has to be accessible to all developers.
 It is set up as a development client, i.e., similar to a development workstation (see
Development Workstation below).

Project Development Database

Each project has a development database. This is a regular database install of the product that is
being customized. System data for customizations are stored in this database. Development
processes like code generation connect to this database. In addition, development app servers in
development workstations connect to this database.

Development Workstation
Developers write, generate, compile, and test code on development workstations. A development
client is installed for each project that the developer works on.
The main components of a development client are the following:
 Project Dev App Server. Code is developed on and executables built into the project dev
app server.
 Oracle Utilities Software Development Kit Client. This is the primary development tool of
the Oracle Utilities Software Development Kit.
 Eclipse SDK. This is the Java development tool used in the Oracle Utilities Software
Development Kit.

©2019 Oracle Proprietary and Confidential 17

Installation Guide Oracle Utilities Software Development Kit

Creating a Project Repository

Each developer workstation must have a working app server deployment. This individual instance
of the app server is where developed code is deployed and tested.
The Project Repository must at least include the entire application server installation directory
structure because the CM (Customer Modification) Application Packaging Scripts of the Oracle
Utilities SDK expect the new sources in certain places in this directory structure.
Source Control Management (SCM). In a team setting, each developer would have an instance
of the same app server. The Project Repository is a file server where project source code are
stored to ensure that each developer has access to the latest source code, web resources, tools,
and libraries in the project. Third party SCM products – like Subversion or Perforce (among
others) – are best used to manage the Project Repository.
Baseline. The Baseline is a set of files (in the project repository) that corresponds to the code
that is currently released to production. Baselines change once production patches are
incorporated into the next iteration of the baseline.
Syncing. Using the SCM product, a developer would proceed to commit work to the Project
Repository. This might sometimes involve merging work with what was already committed by
other developers, especially those changes that were already deployed t production.
Build Automation. A team may also opt to implement Build Automation on the Project
Repository. Build Automation will automatically handle the building of new code from the Project
Repository, testing the new code, deploying the new build to a common test server, and may
optionally generate documentation.

Setting Up the Project Development

Database
The project development database is a regular database install of the product. The procedure for
creating one is the same as for the product database.

Setting Up Development Workstations

The development workstation is where you develop your custom Oracle Utilities application. It
must at least have Windows 7 running so your hardware must have the recommended hardware
configuration.
 Install an Oracle Utilities -based application server, including the setting up of all software
necessary to run this application server – Oracle database, Oracle Client, and Java SDK.
 Install an Oracle Utilities Software Development Kit Client or configure the app server for
development, including Perl to run the perl scripts in the Oracle Utilities SDK.
 Install and configure an Eclipse SDK for the application server.
 For team development, the Project Repository would be best managed with an SCM (Source
Code Management) software like Subversion or Perforce.

18 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Install the App Server and the Oracle

Utilities SDK
Install an app sever of the product to be customized and point it to the project development
database. This is a regular install of the app server of the product to be customized.
Select the following options during the installation of the app server:
 App server is used for development.
 Web application is deployed in the exploded directory.
 The Oracle Utilities SDK version you install must be compatible with the Oracle Utilities
version used by the application server.
 You could use the createNewEnv.bat script to configure the SDK for another app server.
 The startEclipse shortcut script will set up Eclipse for you so you will need to download the
appropriate Eclipse version for your project.

SCM Plugins for Eclipse

Most SCM software would have plug-ins for Eclipse to facilitate direct access to the SCM from the
Eclipse IDE. Install the SCM plug-in
In order for the Oracle Utilities CM (Customer Modification) Application Packaging Scripts to
work, all CM code may be saved in specific places in the application server directory structure.
This means that all project-related codes that are meant to be deployed to the final target
environment must be saved in the application server directory structure.
The project repository development app server contains the latest state of the project. To create a
development app server for the project, simply synchronize the project development app server to
the development workstation.
Knowing when to sync with the Project Repository is purely an administrative issue. We leave
that responsibility to your respective development teams.

Packaging CM Code
Packaging CM (Customer Modifications) code facilitates the preparing and the deploying of your
CM code to another application server that is different from the one that you are currently working
on.

CM Packaging Scripts are distributed in the same zip file as ClientSetup.exe, under the CM
Packaging Tool Folder.

©2019 Oracle Proprietary and Confidential 19

Installation Guide Oracle Utilities Software Development Kit

 AppServerPackaging.jar – CM Scripts for Unix and Windows. Unpack.

 DBPackaging-Oracle.zip – Oracle CM Data extraction and upload utilities for Windows.

Expand the appropriate archive to your source and target environments – extracting the
CM_Packaging folder (from AppServerPackaging archive) and oracle folders (from DBPackaging-
Oracle.zip).

It is assumed that you have perl installed in both source and target environments.

20 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

An Overview of the Packaging Cycle

The movement of CM code across environments is as follows:

SOURCE  PACKAGING  RELEASE

SOURCE: This is the Source Environment and is typically a Windows-based environment where
developers code and test their code under the Eclipse IDE. Code is deployed to Weblogic. CM
Source is extracted from this environment.

PACKAGING: This is the Packaging Environment, which would either be a Windows-based

environment or a Unix-based environment. The operating system should be the same as the
target environment. CM Source is copied and applied to this environment so that a release
packages (or even patches) could be prepared for a target environment.

RELEASE: This is the Release Environment where release packages (or patches) are finally
deployed (or applied in the case of patches).

Packaging CM source take the following steps:s

1. Run extractCMSource.
2. Create/copy cm_jars_structure.xml
3. Copy the extracted CM source to the packaging environment.
4. Copy spl-shared jar file to $SPLEBASE/splapp/standalone/lib/
5. Run applyCM.

More discussions in the succeeding subsections.

Run extractCMSource
The extractCMSource script extracts all CM changes deployed to the current application server.
This script is typically executed from within the CM_Packaging folder. An example Windows
usage of this script is:

extractCMSource -s c:\spl\APP_SERVER_NAME –d c:\cmextract –v 000

This command line traverses the application server directory tree, picks up any deployed CM
code, and copies the CM source code to c:\cmextract in a subfolder that is named prefixed with
000.

©2019 Oracle Proprietary and Confidential 21

Installation Guide Oracle Utilities Software Development Kit

Copy the extracted CM Source folder to the

packaging environment
The applyCM script requires that you copy the extracted CM source folder to your packaging
environment. Use FTP or whatever way is needed to copy the files.

Run applyCM
Remain logged on to the packaging environment, Note that the applyCM script requires you to be
in the extracted CM source folder. You will need to fully qualify applyCM in order to invoke it.
Running applyCM in Unix would look like this:

/CM_Packaging/applyCM.sh (example in Unix)

C:\cmpkg_4_3_0_0_x\applyCM (example in Windows)

The script will then proceed with building several jar and ear files. Address any error that may
come up and run applyCM once again.

You should see “BUILD SUCCESSFUL” on the console once this script completes. At this point,
the CM source has been applied to the application server that is deployed in the packaging
environment. You have this opportunity to test the applied CM code.

The log files for this process will be in the extract folder. The artifact generator log will be in the
packaging application server’s “logs” directory.

Note: Please ensure that that the JDK version you are using is version 1.7. If not the CM build
process will fail because of a version mismatch. If you really need to use a newer version of the
JDK, you could edit the “target” parameter of the javac task in CMBuild.xml.

Creating CM Release Packages and CM

Release Patches
Once you have verified the CM code in the packaging environment, you may now package the
changes so that these could be deployed to any release environment. There are two CM scripts
that let you do that:

create_CM_Release: This script prepares a full release package that only contains customer
modification files.

create_CM_Patch: This script prepares an incremental release package that only contains
customer modification files that differ between two CM versions.

Both scripts require to be executed within the CM Packaging directory, but before you execute
either script, create a directory that will hold old and new release packages.

Log on and set up the packaging environment before running the scripts.

22 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

create_CM_Release
To prepare a full release package, run create_CM_Release. Here is an example:

./create_CM_Release.sh -e M4_Q1_LINDB2 -v M.4.3.0 -d /versions

The -e parameter takes the name of the packaging environment.

The -v parameter is the release package version number.
The -d parameter is the directory containing the release packages. This directory is also where
the new release package will be created.

create_CM_Patch
To prepare a patch package, run create_CM_Patch. Here is an example:

./create_CM_Patch.sh -d /versions
The -d parameter is the directory containing the release packages. This directory is also where
the new patch package will be created.

Installing a CM Release/Patch Package

Once create_CM_Release (or create_CM_Patch) successfully executes, an installation archive
should have been created. A Windows installation package takes the form of a ZIP file, while a
Unix installation package takes the form of a tar file.

The release environment is presumed to already have an installation of the application server.

Installing a CM Release/Patch Package takes the following steps:

1. Copy the installation package archive to the release environment using FTP or whatever
way is possible to copy the file over to the release environment.
2. Logon to and initialize the release environment.
3. Expand the installation package archive to a temporary working directory in the release
environment.
4. Change to the temporary working directory containing the expanded installation package.
5. Run the install script.

The customer modifications should be installed after running the install script. Verify that the
installation package was applied properly.

©2019 Oracle Proprietary and Confidential 23

Installation Guide Oracle Utilities Software Development Kit

Packaging CM Data
The previous sections dealt exclusively with CM code. Packaging CM data takes a separate
process on the same environments:
1. Copy the database from development environment to the packaging (project release)
environment. You may need the help of a DBA to do this task for you.
2. Generate a blueprint file from the packaging (project release) database.
3. Apply the blueprint file to a target release (product release) database.

In the expanded oracle folder (taken from DBPackaging-Oracle.zip) are two scripts CM-
extract.bat and CM-upload.bat. Modify both files to specify any logon information that is needed
to connect to the source and target databases.

Note: The blueprint tools -- OraSDBp and OraSDUpg -- are 32-bit Windows executables. These
require you to install a 32-bit Oracle client.

Generate a blueprint file from the packaging

(project release) database
The CM-extract.bat script generates a blueprint file of the CM data, which could either be a partial
or full extract from the database. It uses the extract_cmsystbls.lst file to extract CM data so
review and modify this file when necessary before running CM-extract.
The database logon information in CM-extract.bat should be that of the source database.

Apply the blueprint file to a target release

(product release) database
The CM-upload.bat script read the blueprint file and uses the extract_cmsystbls.lst file to upload
CM data to a target environment. Review the extract_cmsystbls.lst file and modify it when
necessary before running CM-extract.
The database logon information in CM-upload.bat should be that of the destination database
(packaging environment or target environment).

24 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Service Pack Upgrades

When a new service pack of an Oracle Utilities Application Framework based product is installed,
the customizations need to be migrated and applied to the new version of the product.

Important: This process does not guarantee that the customizations will be migrated free of
errors. We strive to remain compatible with older versions at all times, but there are occasionally
circumstances where that is not possible. In those cases it may be necessary to modify the
custom code.

Here is an overview of the steps:

1. Install the new application server on a Windows development workstation. It may be
installed alongside the old application server.
2. Install this SDK version on the new application server.
3. Migrate the custom data from the old application server. The SDK provided blueprint
process can be used for that. Refer to Packaging CM Data.
4. Copy the customizations from the old application server to the new application server.
The custom files may be in any of these locations (${cm_owner} is usually cm):
%SPLEBASE%\java\source\${cm_owner}

%SPLEBASE%\services\CM*.cbl

%SPLEBASE%\splapp\applications\appViewer\data\source\${cm_owner}\*

%SPLEBASE%\splapp\applications\appViewer\data\xml\${cm_owner}\*

%SPLEBASE%\splapp\applications\appViewer\data\javadocs\com\splwg\${cm_owner}

%SPLEBASE%\structures\${cm_owner}_*.xml

%SPLEBASE%\templates\${cm_owner}.*.template

%SPLEBASE%\scripts\cm

%SPLEBASE%\etc\lib\cm*.jar

%SPLEBASE%\splapp\applications\root\${cm_owner}

%SPLEBASE%\splapp\applications\help\XXX\cm

%SPLEBASE%\splapp\xai\schemas\cm*.*

%SPLEBASE%\java\target\cm\services\CM*.xml

%SPLEBASE%\splapp\applications\root\cmFlush*.jsp

Take note that OUAF 4.3.0 dropped support of COBOL so the source code in the
following folders need to be addressed appropriately:
%SPLEBASE%\cobol\source\cm\CM*.cbl

%SPLEBASE%\java\source\cm\cobolServices\CM*.xml

5. Start Eclipse and set up a project for the new application server. Refer to Running
Eclipse.
6. Run artifact generator and refresh the Eclipse project to compile the Java source.
Correct any errors before proceeding.

©2019 Oracle Proprietary and Confidential 25

Installation Guide Oracle Utilities Software Development Kit

7. Deploy the cm.jar using the Eclipse …Deploy_CM launch configuration.

8. Start the new application server and regression test all the customizations. Correct any
errors and repeat the previous steps as necessary until the results are satisfactory.
At this stage the customizations should be ready to be applied to the QA, test or production
environment. Following are the steps to use the CM packaging process (refer to Packaging CM
Code for more details).
9. Install two new application servers on the same platform (Linux, Solaris, AIX, etc.) as the
eventual production server:
a. A “packaging” application server for the intermediate packaging step
b. One “target” application server. This would initially be a QA or system test
environment, but could also be the production environment
10. Apply the blueprint data extract from step #3 to the new environments. Refer to
Packaging CM Data.
11. Run extractCMSource against the Windows source environment. This will create a
directory containing all the customizations. Copy it to the packaging server (#10a). Tip:
use a zip utility to maintain the directory structure.
12. Run applyCM against the new packaging environment. Resolve any errors before
proceeding.
13. Run create_CM_Release in the packaging environment. This will create an installation
package that can be installed on the target application server.
14. Log in to the target server and install the package on the target application server.
15. Test the customizations on the release environment.

26 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Appendix
The following additional steps may be necessary to configure the SDK.

Where is SPLSDKCommon?
Prior to Oracle Utilities SDK 4.2.0.2.3, Eclipse projects are created in
SPLSDKCommon\eclipseProject folder in the root of the application server directory structure.
Oracle Utilities SDK 4.2.0.2.3 eliminated the SPLSDKCommon directory structure and defaults
the project folder to the project workspace located at the root of the Oracle Utilities SDK
installation folder. Eclipse projects are now created in the respective application server
workspaces where the Oracle Utilities SDK is installed.

Remove COBOL References

If the Generate Artifacts run configuration references COBOL, but the product in question does
not use COBOL and therefore does not need to generate COBOL artifacts, you may see an error
similar to this when Generate Artifacts is launched.

If this is the case, the Generate Artifacts run configuration needs to be edited.
Go to Run -> Run Configurations…
Under Java Application, select the appropriate Generate Artifacts configuration, for example

Under VM Arguments, remove the property that references “cobol” as shown in the red rectangle
in the above snapshot. Note that the dash before the “Dspl…” is in fact part of the property
definition and needs to be removed as well.

©2019 Oracle Proprietary and Confidential 27

Installation Guide Oracle Utilities Software Development Kit

Suppressing Java Problems relating to

undeclared serialVersionUID
When you run the Artifact Generator the first time, you might notice that several warnings show
up in the Markers View:

These warnings should not affect your Java development in any way. The Artifact Generator will
be enhanced to address this issue in a future release. For now, should you really need to
suppress these warnings, you will need to bring up the Eclipse Preferences dialog and navigate
to Java  Compiler  Errors/Warnings:

Scroll down to “Potential Programming Problems” and change the value for “Serializable class
without serialVersionUID” to “Ignore”. The next build will suppress the warnings.

28 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

Server does not start; unsupported

lookup version
The application server does not run for the first deployment of the CM project. The server console
has some entries that resemble the following:
:
Caused By: java.lang.UnsupportedClassVersionError:
com/splwg/cm/api/lookup/CorrectedReadCancelReasonLookup_Gen : Unsupported
major.minor version 51.0
:

This error is most likely caused by an incompatible JVM version. Your Eclipse installation should
be using the same JVM version used by the application server. Edit the setsplenv.bat file in the
etc folder of your Oracle SDK workspace to change the JAVA_HOME environment variable.

Setting up the Oracle Utilities SDK for a

new Application Server
Starting with Oracle Utilities SDK 4.2.0.2.3, it would be possible for you to work on another
application server installation in your workstation. The script file
%SPLSDKROOT%\SDK\setsplenv.bat no longer contains application-server specific
configuration. All application server configuration are moved to the
%SPLSDKROOT%\%ENVNAME%\etc\setsplenv.bat script.
Use script %SPLSDKROOT%\SDK\shortcuts\createNewEnv.bat to create another workspace
in your workstation in addition to the one that was initially set up using ClientSetup.
The createNewEnv.bat script will first prompt you for the full path of your other application
server. It will then retrieve configuration information – database connection information, web app
server information, among others. Review the information and edit any entry when necessary and
create the new workspace.
Now that you have more than one application server configured for the SDK, running any shortcut
script will begin prompting you for the application server context under which it would run. This
environment selection is performed by each call to %SPLSDKROOT%\SDK\setsplenv.bat.

©2019 Oracle Proprietary and Confidential 29

Installation Guide Oracle Utilities Software Development Kit

Multiple CM Development and

Deployment
For application servers using FW 4.2.0.2.0, Oracle Utilities SDK (starting with 4.2.0.2.3) supports
the development and deployment of multiple cm jar files to your target server. This is particularly
useful when you have multiple sites developing code concurrently and the customizations need to
ultimately co-exist on a target production environment.
To deploy multiple cm jars, each developer site is expected to do the following:
1. Identify each developer site with a specific CM owner. The primary CM developer site is
‘CM’, the next CM developer site is ‘CM01’, etc. Assignment should be sequential, but
remember that “99” is reserved for the target environment owner (CM99).
2. Each developer site must develop site-specific code to com.splwg.cm# packages. That
is, CM will develop code in com.splwg.cm.* packages, while CM01 will develop code in
com.splwg.cm01.* packages.

Environmental Requirements
A developer site for CM would normally have an application server that would function as the
source environment; a clone for the source environment will function as a packaging
environment; and another clone of the source environment that will function as a target
environment. Each instance of the application server will require clones of the same database to
serve as the source database, the packaging database, and a target database.
1 Source Environment + 1 Source Database
1 Packaging Environment + 1 Packaging Database
1 Target Environment + 1 Target Database
All developer sites in the multiple CM project should follow the same setup. Note that all of these
environments could be installed in the same physical server box. The databases could be
identical schemas in the same database server.

Participating in a Multiple CM Project

The owner CM remains the primary developer of the Multiple CM project. All others -- CM01,
CM02, CM03 – are co-developers. Each co-developer site will need to make the following
metadata changes to their application server data (seen here in the context of CM01):
1. Provision CM01 application meta-data to the CM01 database:
insert into ci_lookup_val
(FIELD_NAME,FIELD_VALUE,EFF_STATUS,VERSION,OWNER_FLG,VALUE_NAME)
VALUES('OWNER_FLG','CM01','A',1,'CM01','cm01');

insert into ci_lookup_val_l

(FIELD_NAME,FIELD_VALUE,LANGUAGE_CD,VERSION,DESCR,OWNER_FLG,DESCR_OVRD,DESCRLONG)
values ('OWNER_FLG ','CM01','ENG',1,'Customer Modification
CM01','CM01',' ',' ');

30 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

insert into ci_install_prod

(INSTALL_OPT_ID,OWNER_FLG,RELEASE_ID,COMP_STATUS_FLG,UPDATE_DTTM,VERSION,SORT_SEQ,BUIL
D_NBR,PATCH_NBR,DISPLAY_SW,PRODUCT_NAME,RELEASE_ID_SFX,PROD_TYPE_FLG) values ('11111',
'CM01', 'V999', 'COMP', to_date('04-MAR-05','DD-MON-RR'),1, 0, ' ', ' ', ' ',
'Customer Modification CM01',' ','F1PL');

update f1_installation set owner_flg='CM01' where owner_flg='CM';

2. Create cm_owner.txt in %SPLEBASE%\etc with cm01.

3. Copy cm.jar from the CM environment to the following CM01 locations:
%SPLEBASE%\etc\lib
%SPLEBASE%\splapp\standalone\lib

4. Create cm_jars_structure.xml in %SPLEBASE%\structures.

5. Create cm01_jars_structure.xml in %SPLEBASE%\structures.
6. Edit %SPLEBASE%\splapp\standalone\config\spl.properties to append cm01 to the end of
the spl.tools.loaded.applications property.
7. Delete the following Weblogic cache folders from CM01:
%SPLEBASE%\splapp\servers\myserver\cache
%SPLEBASE%\splapp\servers\myserver\tmp
8. Run initialSetup.
9. Remember to specify cm01 as the cm owner when creating a new OUAF project.
10. Verify the following CM01 Generate Artifacts launch configurations:
* In the Program Arguments, the -appJars parameter must refer to cm.jar.
* In the VM Arguments, the spl.tools.loaded.applications system property must include cm01.

©2019 Oracle Proprietary and Confidential 31

Installation Guide Oracle Utilities Software Development Kit

Configuring the Multiple CM Target

Environment Metadata
The target environment database also needs to be configured so that the app server would know
what applications are installed. The original CM owner should already have entries in the
database, but CM01 would also need to be added to the database:
insert into ci_lookup_val
(FIELD_NAME,FIELD_VALUE,EFF_STATUS,VERSION,OWNER_FLG,VALUE_NAME)
VALUES('OWNER_FLG','CM01','A',1,'CM01','cm01');

insert into ci_lookup_val_l

(FIELD_NAME,FIELD_VALUE,LANGUAGE_CD,VERSION,DESCR,OWNER_FLG,DESCR_OVRD,DESCRLONG)
values ('OWNER_FLG ','CM01','ENG',1,'Customer Modification
CM01','CM01',' ',' ');

insert into ci_install_prod

(INSTALL_OPT_ID,OWNER_FLG,RELEASE_ID,COMP_STATUS_FLG,UPDATE_DTTM,VERSION,SORT_SEQ,BUIL
D_NBR,PATCH_NBR,DISPLAY_SW,PRODUCT_NAME,RELEASE_ID_SFX,PROD_TYPE_FLG) values ('11111',
'CM01', 'V999', 'COMP', to_date('04-MAR-05','DD-MON-RR'),1, 0, ' ', ' ', ' ',
'Customer Modification CM01',' ','F1PL');

By default CM is the cm owner of the installation, but in a multiple CM deployment, the cm owner
is CM99:
insert into ci_lookup_val
(FIELD_NAME,FIELD_VALUE,EFF_STATUS,VERSION,OWNER_FLG,VALUE_NAME)
VALUES('OWNER_FLG','CM99','A',1,'CM99','cm99');

insert into ci_lookup_val_l

(FIELD_NAME,FIELD_VALUE,LANGUAGE_CD,VERSION,DESCR,OWNER_FLG,DESCR_OVRD,DESCRLONG)
values ('OWNER_FLG ','CM99','ENG',1,'Customer Modification
CM99','CM99',' ',' ');

insert into ci_install_prod

(INSTALL_OPT_ID,OWNER_FLG,RELEASE_ID,COMP_STATUS_FLG,UPDATE_DTTM,VERSION,SORT_SEQ,BUIL
D_NBR,PATCH_NBR,DISPLAY_SW,PRODUCT_NAME,RELEASE_ID_SFX,PROD_TYPE_FLG) values ('11111',
'CM99', 'V999', 'COMP', to_date('04-MAR-05','DD-MON-RR'),1, 0, ' ', ' ', ' ',
'Customer Modification CM99',' ',' ');

update f1_installation set owner_flg='CM99' where owner_flg='CM';

Packaging and Deploying your Multiple CM

Project
As with the usual single CM deployment, each developer site should have a provisioned
packaging environment in which the site’s installation package will be built. Before CM packaging
could commence however, the CM source environment blueprint must be extracted and loaded
into the packaging environment database. You should note that the DB Packaging extraction and
upload scripts must only extract the records created by the respective CM owner. That is, the CM
blueprint must extract and upload only CM-owned data, the CM01 blueprint must extract and
upload only CM01-owned data, etc.
From the Source environment, run the extractCMSource script with the –m option, which
activates Multiple CM source extraction, for example:

32 ©2019 Oracle Proprietary and Confidential

SPL Oracle Utilities Software Development Kit Installation Guide

perl extractCMSource.plx -s C:\SPL\CM01_PROJ -d C:\CMExtract -v CM1.0 –m cm01

The –m option takes the module name/project directory name (lowercase CM owner) as a
parameter. This is a required parameter to properly extract CM01 source.
After extraction, copy the extract to your packaging environment and run the applyCM script. This
builds the extracted source code.
Finally, run the create_CM_release script to create a target environment installation. If an
installation package already exists, you may opt to run the create_CM_patch script to create a
target environment patch instead.
Refer to the CM Packaging Utilities Cookbook for details in using the App Server CM
Packaging Scripts.
In the target environment, each blueprint and installation package from the Multiple CM Project
participants should be uploaded and installed individually. Again, the installation owner
(F1_INSTALLATION) for the target environment should be different from the developer owners –
CM99.

©2019 Oracle Proprietary and Confidential 33