To
simplify configuration, you can use symbols as values for XML elements
in configuration files. Create a file named substitution.xml in
the rootinstall/conf folder that maps the symbols to strings
that the server substitutes when it reads the configuration files.
After you’ve set up a map file, future updates are faster: you can
edit the map file instead of editing each configuration file.
The installer defines a few mappings during the installation
process and stores them in the fms.ini file. When the server starts,
it looks for the fms.ini file and the substitution.xml file in the rootinstall/conf
directory. You can also create additional map files and reference
them from the substitution.xml file.
The server has two predefined symbols, ROOT and CONF,
that are always available. The ROOT symbol is mapped
to the location of the FMSMaster.exe file and the CONF symbol
is mapped to the location of the Server.xml file.
The server builds the symbol map in the following order:
The predefined symbols ROOT and CONF are
evaluated.
The fms.ini file is evaluated.
If the substitution.xml file exists, the server looks for
the Symbols tag and processes the child tags in
the order in which they appear.
The server processes the additional map files in the order
in which they appear (in KeyValueFile elements
in the substitution.xml file).
Symbols defined in external map files are processed in the
order in which they appear in each file.
Create a substitution.xml file:
Create a new XML file
and save it in the rootinstall/conf folder as substitution.xml.
Enter the following XML structure:
<Root>
<Symbols>
<SymbolName>StringToMapTo</SymbolName>
</Symbols>
</Root>
Add a SymbolName element
for each symbol you want to create.
For example, this substitution.xml file maps the symbol TESTUSERNAME to the
value janedoe:
<Root>
<Symbols>
<TESTUSERNAME>janedoe</TESTUSERNAME>
</Symbols>
</Root>
Open the rootinstall/conf/Users.xml file in a text
editor.
Locate the line <User name="${SERVER.ADMIN_USERNAME}"> and replace
the symbol SERVER.ADMIN_USERNAME with the symbol TESTUSERNAME.
When
the server reads the XML file, it substitutes the value from the
substitution.xml file as follows:
<User name="janedoe">
Note: Because this symbol is used as an attribute, it
is surrounded by quotation marks. If the symbol were used as a regular
value, it would not be surrounded by quotation marks.
Restart the Administration Server.
Note: If you change the Users.xml file, you must restart
the Administration Server. If you change any other XML configuration
file, you must restart the server.
Creating additional map files
You
can specify all of your text substitution mappings under the Symbols tag
in substitution.xml. However, you can also create additional map
files. To do this, create one or more KeyValueFile elements
in the substitution.xml file. Each element can hold the location
of one external file.
For example, the following references
the file C:\testfiles\mySymbols.txt:
<Root>
<KeyValueFile>C:\testfiles\mySymbols.txt</KeyValueFile>
</Root>
These external files are not in XML
format. They simply contain a collection of symbol-value pairs,
where each pair appears on a separate line and takes the following
form:
symbol=value
The
following example shows three symbol-value pairs:
USER_NAME=foo
USER_PSWD = bar
HELLO= "world and worlds"
Place comments on separate
lines that begin with a number sign (#). Do not place
comments on the same line as a symbol definition.
The first
equal sign (=) in a line is considered the delimiter
that separates the symbol and the value. The server trims leading
or trailing white space from both the symbol and the value, but
no white space within double quotation marks.
Using environment variables
To
refer to an environment variable in one of the XML configuration
files, use the name of the environment variable within percent (%)
characters. The % characters indicate to the server
that the symbol refers to an environment variable and not to a user-defined
string.
The syntax for specifying an environment variable
as a symbol is ${%ENV_VAR_NAME%}.
For
example, the server maps the following symbol to the COMPUTERNAME variable:
${%COMPUTERNAME%}
When
you use an environment variable, you don’t have to define it in
the substitution.xml file.
