WebSphere variables are name and value pairs that are used
to provide settings for any of the string data type attributes that
are used to configure the product. After a variable is defined, the
symbolic name that is specified for that variable can be specified
in the Value field of any other configuration field for the
product that accepts a string value.
WebSphere variables can be used to configure:
- WebSphere® Application Server path names,
such as JAVA_HOME, and APP_INSTALL_ROOT
- A path value for the extendedDocumentRoot JSP or file serving
attribute. This capability enables you to add an application to each
node in a clustered environment without modifying the ibm-web-ext.xmi
file for that application on each node.
Supported configurations: For IBM
® extension
and binding files, the .xmi or .xml file name extension is different
depending on whether you are using a pre-Java EE 5 application or
module or a Java EE 5 or later
application or module. An IBM extension
or binding file is named ibm-*-ext.xmi or ibm-*-bnd.xmi where * is
the type of extension or binding file such as app, application, ejb-jar,
or web. The following conditions apply:
- For an application or module that uses a Java EE version prior to version 5, the file
extension must be .xmi.
- For an application or module that uses Java EE 5 or later, the file extension must
be .xml. If .xmi files are included with the application or module,
the product ignores the .xmi files.
However, a Java EE
5 or later module can exist within an application that includes pre-Java
EE 5 files and uses the .xmi file name extension.
The ibm-webservices-ext.xmi, ibm-webservices-bnd.xmi, ibm-webservicesclient-bnd.xmi, ibm-webservicesclient-ext.xmi,
and ibm-portlet-ext.xmi files continue to use
the .xmi file extensions.
sptcfg
- Certain cell-wide customization values
- The location service for the z/OS platform.
When a variable is defined, it is given a scope. The scope is the
range of locations within the product network where the variable is
applicable.
- A variable with a cell-wide
scope is available across the entire deployment manager cell.
- A variable with a cluster-wide
scope is available across the entire cluster in the cell.
- A variable with a node-level scope is available only on the node
and the servers on that node. If a node-level variable has the same
name as a cell-wide variable, the node-level variable value takes
precedence.
- A server variable is available only on the one server process.
A server variable takes precedence over a variable with the same name
that is defined at a higher level.
The value of a configuration attribute can contain references to
one or more variables. The syntax for such an attribute is the name
of the variable, enclosed in either a pair of curly braces { } or
a pair of parenthesis ( ). In either case, the variable is proceeded
by the dollar sign.
A string configuration attribute value can consist of:
- String literals, including the null value and an empty string
- Variable references that each includes one or more levels of indirection
- Nested variable references.
- Any combination of non-null and non-empty string literals, variable
references, and nested variable references.
Table 1. WebSphere variables and attributes . The following table illustrates all of the possible combinations.
Configuration attribute consists of: |
Configuration attribute value |
Variable name |
Second variable value |
Third variable value |
Fourth variable value |
Expanded configuration attribute value |
String literal |
/IBM/WebSphere/AppServer |
N/A |
N/A |
N/A |
N/A |
/IBM/WebSphere/AppServer |
Variable reference |
$(WAS_ INSTALL_ ROOT) |
WAS_ INSTALL_ ROOT |
/IBM/WebSphere/AppServer |
N/A |
N/A |
/IBM/WebSphere/AppServer |
Variable reference with a string literal |
$(USER_ INSTALL_ ROOT)/temp |
USER_ INSTALL_ ROOT |
N/A |
N/A |
/IBM/WebSphere/AppServer/profiles/AppSrv01 |
/IBM/WebSphere/AppServer/profiles/AppSrv01/temp |
Indirect variable reference with a string literal |
$(WAS_ INSTALL_ ROOT)/lib |
WAS_ INSTALL_ ROOT |
$(MY_INSTALL_ ROOT) |
MY_INSTALL_ ROOT |
N/A |
N/A |
Nested variable references with string literal (Example 1) |
$(${INSTALL_ TYPE}_ INSTALL_ ROOT)/lib |
INSTALL_ TYPE |
USER |
USER_INSTALL_ ROOT |
/IBM/WebSphere/AppServer/profiles/AppSrv01 |
/IBM/WebSphere/AppServer/profiles/AppSrv01/lib |
Nested variable references with string literal (Example 2) |
$(${INSTALL_ TYPE}_ INSTALL_ ROOT)/lib |
INSTALL_ TYPE |
WAS |
WAS_INSTALL_ ROOT |
/IBM/WebSphere/AppServer/AppServer |
/IBM/WebSphere/AppServer/AppServer/lib |
During the configuration process, whenever a variable is encountered
as the value for a configuration attribute, a variable expansion is
performed on that variable. A variable expansion is the process of
recursively replacing variable references with variable values until
only a string literal remains as the value for the configuration attribute.
If the expansion process encounters a variable that is not properly
defined, the expansion of that variable stops and a VariableExpansionException
exception is issued. The product configuration process continues.
However, processing errors might occur because the value for this
configuration attribute is not properly established.
Avoid trouble: The variable expansion syntax
that is provided in Versions 6.0.x, and 6.1.x, of the product, includes
a variant that consists of a dollar sign, and a single letter variable
name without any surrounding braces or parenthesis. This syntax is
not supported in
Version 8.0 or
higher. All WebSphere variables references must be surrounded by
matching parenthesis or braces, even if it is a single letter. That
syntax required escaping of dollar signs to avoid ambiguity.
gotcha
Table 2. Literal dollar sign . For backward compatibility,
the escaping of the literal dollar sign is still supported, and the
literal dollar sign is interpreted as indicated in the following table.
Input value |
Value after expansion |
$ |
$ |
$$ |
$ |
$$$ |
$$ |
$$$$ |
$$ |
$$$$$ |
$$$ |