Java Runtime Environment

This software was developed using Java and runs on any platform with a supported Java Runtime Environment (JRE) >= Java version 11. The software was specifically compiled for and tested in OpenJDK 15.0.1. The following commands test the local Java installation in a UNIX-based environment:

% which java
/usr/bin/java
% java -version
openjdk version "15.0.1" 2020-10-20
OpenJDK Runtime Environment (build 15.0.1+9)
OpenJDK 64-Bit Server VM (build 15.0.1+9, mixed mode, sharing)
        

NOTE: Transform Tool requires 64-bit Java in order to enable Java Virtual Machine memory requirements. In version output above, note the line Java HotSpot(TM) 64-Bit Server VM

For Windows Users: The 32-bit JRE is the default on Windows, and even the the online installer for Windows on the Java Download All Operating Systems page only installs the 32-bit JRE. If you see an error with text like "Invalid maximum heap size", you have the wrong JRE installed.

If the either of these commands fail, it indicates Java is not installed or the version is not at least 1.9. Consult the local system administrator for installation of this software. For the do-it-yourself crowd, the Java software can be downloaded from the Java Download page.

UNIX-Based Environment

This section details the environment setup for UNIX-based machines. The binary distribution includes a shell script that must be executed from the command-line. Setting the PATH environment variable to the location of this script, enables the shell script to be executed from any location on the local machine.

The following command demonstrates how to set the PATH environment variable (in Bourne shell), by appending to its current setting:

% export PATH=${PATH}:/usr/local/transform-1.12.2/bin
        

In addition, the shell script requires that the JAVA_HOME environment variable be set to the appropriate location of the Java installation on the local machine. The following command demonstrates how to set the JAVA_HOME environment variable:

% export JAVA_HOME=/path/to/java/home
        

The system administrator for the local machine may need to be consulted for this location. The path specified should have a bin sub-directory that contains the java executable. This variable may also be defined within the scripts. Edit the scripts (files without the .bat extension) and change the line in the example above to represent the local Java installation.

Windows Environment

This section details the environment setup for Windows machines. The binary distribution includes a Windows batch script that must be executed from the command-line. Setting the PATH environment variable to the location of this script, enables the batch script to be executed from any location on the local machine. There are a few ways this can be done:

• Through the Command-Line
• Through the Windows System Properties Panel Interface

Both of these method are detailed below. Select one based on your preference.

Setting the Environment through Command-Line

In your DOS Terminal Window, run the following command to set the PATH environment variable, by appending to its current setting:

C:\> set PATH=%PATH%;"C:\Program Files\transform-1.12.2\bin"
        

Note that if the directory path to the Transform Tool contains spaces, the path will need to be surrounded in double quotes as shown above.

In addition, the batch script requires that the JAVA_HOME environment variable be set to the appropriate location of the Java installation on the local machine. The following command demonstrates how to set the JAVA_HOME environment variable:

C:\> set JAVA_HOME="C:\Program Files\Java\jreX.X.X"
        

The system administrator for the local machine may need to be consulted for this location. The path specified should have a bin sub-directory that contains the java executable. This variable may also be defined within the scripts. Edit the scripts (files with the .bat extension) and change the line in the example above to represent the local Java installation.

Setting the Environment through the Windows System Properties Panel Interface

An alternative method for setting the environment is through the Windows System Properties Interface.The instructions provided below were based off of a Windows 7 machine. Windows 8 and 10 users should be able to use these steps as well to modify their environment.

The Path environment variable can be modified as follows:

• Click on the Windows icon on the bottom left. In the search text box, type in edit system environment variables. A search result called Edit the system environment variables should appear under the Control Panel area as follows:

• Click on Edit the system environment variables and in there, click on the Environment Variables button. At this point, you should now see a window like the one below:

• Highlight the Path variable in the System Variables list and select the Edit button.
• Append to the current contents of the variable, the path to the bin directory within transform package. Separate the package path from the current contents of the variable with a semicolon.
• Select the OK button when you are finished editing the Path variable, then select the OK button on the Environment Variables window to apply the changes.

New environment variables (e.g., JAVA_HOME) may also be specified in the system properties panel. Instead of selecting the Edit button from the System Variables list, select the New button and enter the variable name and value. Select the OK button when you are finished, then select the OK button on the Environment Variables window to apply the changes.

Note: If you already have a DOS window open, you will need to close and re-open the window for the environment variable changes to take effect.

Installation Location

Both the shell and batch scripts for this software utilize system commands for determining the installation home directory that may or may not be available on all platforms. If these commands are not available in the current environment, their use can be replaced in the scripts by setting the PARENT_DIR variable with the actual installation path. Modify the UNIX-based shell scripts as follows (the actual installation path may be different in the current environment):

SCRIPT_DIR=`dirname $0`
PARENT_DIR=`cd ${SCRIPT_DIR}/.. && pwd`

  should be replaced with:

PARENT_DIR=/usr/local/transform-1.12.2
        

Modify the Windows-based batch scripts as follows (the actual installation path may be different in the current environment):

set SCRIPT_DIR=%~dps0
set PARENT_DIR=%SCRIPT_DIR%..
set LIB_DIR=%PARENT_DIR%\lib

  should be replaced with:

set PARENT_DIR="C:\Program Files\transform-1.12.2"
set LIB_DIR="%PARENT_DIR%\lib"
        

Note the use of double-quotes if the directory path to the Transform Tool contains spaces.

Java System Properties

The Transform Tool utilizes external programs to perform some of its transformations. The Java system property, external.programs.home, is used to point to the top-level directory of the location of these programs. By default, the Transform Tool shell script and batch file come configured to point to the external-programs directory of the deployment package. The following shows how the external.programs.home system property is set in the Transform Tool startup scripts:

In the transform shell script:

"${JAVA_HOME}"/bin/java -Xms256m -Xmx1024m -Dcom.sun.media.jai.disableMediaLib=true -Doverwrite.output=true -Dexternal.programs.home=${PARENT_DIR}/external-programs -jar ${TRANSFORM_JAR} "$@"
      

In the transform.bat batch file:

"%JAVA_HOME%"\bin\java -Xms256m -Xmx1024m -Dcom.sun.media.jai.disableMediaLib=true -Doverwrite.output=true -Dexternal.programs.home=%PARENT_DIR%\external-programs -jar "%TRANSFORM_JAR%" %*
      

Verifying the Installation

Verify that the tool was installed correctly by running the shell script or Windows batch file with no arguments. The output should look something like the following:

% transform

Type 'transform -h' for usage