The Wrapper supports environment variable expansion at run time within the values of any property. To maintain the platform independent nature of the configuration file "wrapper.conf", the Windows syntax is used for all platforms.

When the Wrapper is run as a service, environment variables will be loaded from the system registry rather than from the environment. This is necessary because Windows loads the environment variables which are available to services when the machine is booted. Any changes to the system environment variables in the registry (set directly or through the system control panel) are not made available to the services until the machine is once again rebooted. By loading the environment variables from the registry, the reboot can be avoided while providing the same functionality.

wrapper.java.command=%JAVA_HOME%/bin/java

This will expand at runtime to a fully qualified path on any system which defines the JAVA_HOME environment variable.

wrapper.java.command=C:\Sun\jdk1.3\bin\java

wrapper.java.command=/opt/IBMJava2-131/bin/java

If a referenced environment variable is not defined, then it will be left unchanged in the property value.

The Wrapper supports the ability to define environment variables from within the configuration file "wrapper.conf" or from the command line. Once defined, the environment variable can be referenced like any other environment variable. This includes use in variable expansion as described above.

Special Property Name starting with "set." and "set.default." :

Environment variables are defined by using special property names which begin with "set." or "set.default." followed by the name of the environment variable. The value of the property will be the value of the new environment variable.

set.EXTERN_APP=C:/ExternAppHome

If the "set.default." property name is used, the environment variable will only be set if it does not exist yet. This can be useful for defining a series of default environment variable values.

set.default.EXTERN_APP=C:/ExternAppHome

Example:

The ability to define environment variables make it possible to easily modify values that may be used throughout a configuration file. The example below shows how an environment variable can be used to specify the location of an external application.

set.EXTERN_APP=C:/ExternAppHome

wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=%EXTERN_APP%/lib/jar1.jar
wrapper.java.classpath.3=%EXTERN_APP%/lib/jar2.jar
wrapper.java.classpath.4=%EXTERN_APP%/lib/ext/jar3.jar
wrapper.java.classpath.5=%EXTERN_APP%/lib/ext/jar4.jar

The use of environment variables definitions can be very powerful if you understand how and when their values are set. Environment variables which were set before the Wrapper is launched can of course be used as usual. If the same variable name is specified in the configuration file then the value in the configuration file will override the existing value.

From Command Line:

Environment variables defined from the command line work a little differently. These values from command line will override any values from either the system or those set in the configuration file. This makes it possible to define default environment variables within the configuration file "wrapper.conf" and then also to change that value from the command line.

wrapper.exe -c ..\conf\wrapper.conf "set.EXTERN_APP=C:\Program Files\ExternAppHome"

wrapper ../conf/wrapper.conf set.EXTERN_APP=/usr/lib/externapphome

NOTE

Notice that like all properties set from the command line, properties including spaces can be defined by including the entire pair of "property name and value" in quotes.

On startup of Wrapper, it sets the following environment variables into its own environment. These variables can be used within the configuration file "wrapper.conf" or by accessing the environment of the JVM or any of its child processes.

• The WRAPPER_ARCH variable is set to the name of the architecture for which the currently running Wrapper was built.

• The WRAPPER_BIN_DIR variable is set to location of the Wrapper binary on startup. It can be used to define paths relative to this location even if the current working directory is modified.

• The WRAPPER_BITS variable is set to the 32-bit or 64-bit depth for which the currently running Wrapper was built.

• The WRAPPER_FILE_SEPARATOR variable is set to '\' on Windows and '/' on Linux/Unix platforms, as a file separator. The variable can be used to set platform independent values for additional environment variables or properties.

  In general it is safe to always use '/' as a file separator for paths used within Java. Java is designed to work correctly on all platforms when '/' is used.

• The WRAPPER_HOSTNAME and WRAPPER_HOST_NAME variables are set to the resolved name of the machine where the Wrapper is currently running.

• The WRAPPER_JAVA_HOME variable is set on Windows platforms when the Java command is located using the system registry. In other cases, it is recommended that a JAVA_HOME variable be set.

• The WRAPPER_OS variable is set to the name of the OS for which the currently running Wrapper was built.

  Example:

  wrapper.java.library.path.1=../lib wrapper.java.library.path.2=../lib/native/%WRAPPER_OS%-%WRAPPER_ARCH%-%WRAPPER_BITS%

  The example above resolves to the following:

  Windows:

  wrapper.java.library.path.1=../lib wrapper.java.library.path.2=../lib/native/windows-x86-32

  Linux:

  wrapper.java.library.path.1=../lib wrapper.java.library.path.2=../lib/native/linux-x86-32

  Solaris:

  wrapper.java.library.path.1=../lib wrapper.java.library.path.2=../lib/native/solaris-sparc-32

• The WRAPPER_PATH_SEPARATOR variable is set to ';' on Windows and ':' on Linux/Unix platforms. The variable can be used to build up platform independent paths.

  Example:

  set.PATH=..%WRAPPER_FILE_SEPARATOR%lib%WRAPPER_PATH_SEPARATOR%%PATH%

  The example above resolves to the following:

  Windows:

  set.PATH=..\lib;%PATH%

  Unix:

  set.PATH=../lib:%PATH%

• The WRAPPER_PID variable is set to the PID of the Wrapper process when it is launched. It can be used in file names like the PID file or log file to make sure that you get a unique file name when launching multiple copies of the Wrapper with the same configuration file.

  Example:

  wrapper.logfile=../logs/wrapper-%WRAPPER_PID%.log

• The WRAPPER_RAND_NNNNNN variable is set to a random number at each location it is used within the Wrapper configuration file.

  wrapper.app.parameter.1=mytempfile-%WRAPPER_RAND_NNNNNN%.txt

  The value is set once when the configuration file is loaded and parsed. If the value should be set each time a JVM is launched, it is necessary to specify the wrapper.restart.reload_configuration=TRUE configuration property to cause the configuration to be reparsed prior to each JVM invocation.

  A different random number will be generated each place that the variable is specified. If it is necessary to reference the same random number in multiple locations, please first store the value into a local variable and then reference that as needed. For example:

  set.RNUM=%WRAPPER_RAND_NNNNNN% wrapper.java.additional.1=-Dtempid=%RNUM% wrapper.app.parameter.1=mytempfile-%RNUM%.txt

  Additional formats exist for 1 though 6 digit random numbers: WRAPPER_RAND_N, WRAPPER_RAND_NN, WRAPPER_RAND_NNN, WRAPPER_RAND_NNNN, and WRAPPER_RAND_NNNNN.

• The WRAPPER_TIME_YYYYMMDDHHIISS variable is set to a timestamp at each location it is used within the Wrapper configuration file. The time returned is the time that the configuration file is loaded. The variable will return the same value when referenced multiple times in the same configuration file.

  The following example demonstrates how to generate a timestamped file name and pass it to the JVM:

  wrapper.app.parameter.1=mytempfile-%WRAPPER_TIME_YYYYMMDDHHIISS%.txt

  The above example results in a value like:

  wrapper.app.parameter.1=mytempfile-20090409124532.txt

  The value is set once when the configuration file is loaded and parsed. If the value should be set each time a JVM is launched, it is necessary to specify the wrapper.restart.reload_configuration=TRUE configuration property to cause the configuration to be reparsed prior to each JVM invocation.

  The following additional formats can also be referenced: WRAPPER_TIME_YYYYMMDD_HHIISS, WRAPPER_TIME_YYYYMMDDHHII, WRAPPER_TIME_YYYYMMDDHH, and WRAPPER_TIME_YYYYMMDD.

• The WRAPPER_WORKING_DIR variable is set to the location of the Wrapper binary on startup but will be changed to reflect the current working directory of the Wrapper.

  The working directory of the Wrapper can be changed using the wrapper.working.dir property. Be sure to read the documentation as its usage is a bit tricky.

In additional to the above environment variables, the following variables can also be referred in event properties when those events are fired. The variable values can be referenced by event properties as documented within those properties. The variables are not actually set as TRUE environment variables.

• The WRAPPER_NAME variable is set to the value of the wrapper.name property.

• The WRAPPER_DISPLAYNAME variable is set to the value of the wrapper.displayname property.

• The WRAPPER_DESCRIPTION variable is set to the value of the wrapper.description property.

• The WRAPPER_EVENT_JVM_ID variable is set to an integer value starting with 1, indicating how many times the JVM has been restarted. Only set for "jvm_*" events.

• The WRAPPER_EVENT_JVM_PID variable is set to an integer value containing the PID of the JVM process. Only set for "jvm_*" events with the exception of the "jvm_prelaunch" event.

• The WRAPPER_EVENT_NAME variable is set to the name of the event being fired.

• The WRAPPER_EVENT_WRAPPER_PID variable is set to an integer value containing the PID of the Wrapper process. (This environment is an alias of the WRAPPER_PID environment variable and is maintained only for backwards compatibility.)

Some users have noticed that the Windows APPDATA environment variable is not set when the Wrapper is run as a service unless the configured user has already been logged in. This appears to be a Windows bug.

It can be easily worked around however by placing the following at the top of the wrapper.conf file:
set.default.APPDATA=%USERPROFILE%\Application Data

HOMEDRIVE and HOMEPATH also fail to be set.

HOMEPATH can be worked around like this:
set.default.HOMEPATH=%USERPROFILE%

HOMEDRIVE can be worked around like this. Not sure if this will work on all systems, but should on most:
set.default.HOMEDRIVE=%SYSTEMDRIVE%