Apama 10.15.0 | Deploying and Managing Apama Applications | Deploying Apama Components with Command Central | Administering Apama in Command Central | Configuration types that Apama components support | Usage notes | Apama environment variables
 
Apama environment variables
Use to define the environment variables for the Apama correlator and IAF instances. The defined variables are set when you start the instances. You can define the environment variables using the web interface and the command line interface. You can define the environment variables only when you update the configuration of an instance. The environment variables must be defined in key-value pairs syntax as a properties file. Use the sagcc update configuration data command to define the environment variables. If an environment variable is already defined and if you define that environment variable again, the old value is replaced by the new value.
Using existing environment variables
You can use an existing environment variable in the definition of a new environment variable using the syntax ${env:EnvironmentVariableName}. The same syntax can also be used to update the value of an existing environment variable, for example:
MY_HOME=C:\project1
PATH=C:\Program Files
# Define MY_BIN environment variable using existing MY_HOME environment
# variable
MY_BIN=${env:MY_HOME}/bin

# Update PATH environment variable with MY_BIN value to existing PATH value
PATH=${env:MY_BIN};${env:PATH}
Where the value of the MY_BIN environment variable during runtime is C:\project1\bin. The value of the PATH environment variable after the update is C:\project1\bin; C:\Program Files. Environment variables are evaluated and defined when an instance is started. Any existing environment variable used with the syntax ${env:EnvironmentVariableName} is replaced with its current value known at the time of evaluation. If an environment variable is not defined and is used in another environment variable, the undefined variable is replaced by an empty string. For example:
# MY_HOME is not defined
# Define MY_BIN
MY_BIN=${env:MY_HOME}/bin
In the above example, the value of the MY_BIN environment variable is /bin, because ${env:MY_HOME} is replaced by an empty string. The order of defining an environment variable is very important. The environment variable used in the definition of another environment variable must be defined before it is used. For example, if you want to use MY_HOME in the definition of MY_BIN, ensure that you have defined MY_HOME before using it MY_BIN.
Using special substitution variables
You can also use special substitution variables when defining an environment variable. The special substitution variables must be used in the syntax ${VARIABLE_NAME}. At present, only the following special substitution variables are supported:
*APAMA_HOME
*APAMA_WORK
*INSTANCE_NAME
*START_TIME (date and time at which the instance is started)
*$ (the value of this substitution variable $ is $)
Example for using special substitution variables:
MY_CONFIGS = ${APAMA_WORK}/project/${INSTANCE_NAME}/configs
Using the special substitution variable $
You can use the special substitution variable $ to escape any defined or undefined environment variables, and special substitution variables. That is, if you want to use ${ENV_VAR} as a value and do not want it to be expanded, you should use $ as ${$} so that ENV_VAR is not expanded and the value will be ${ENV_VAR}. For example:
ENV1 = ${$}{env:PATH}:/bin
ENV2 = ${$}{env:SOME_ENV}:/example
ENV3 = ${$}{APAMA_HOME}/samples
ENV4 = ${$}{MY_VAR}/demo
The values of ENV1, ENV2, ENV3 and ENV4 are:
${env:PATH}:/bin
${env:SOME_ENV}:/example
${APAMA_HOME}/samples
${MY_VAR}/demo
# Here, the environment variables are not expanded
# because of the special substitution variable $,
# and ${$} is replaced by $.
Example format of a properties file:
MY_HOME=C:\project1
MY_BIN=${env:MY_HOME}/bin
MY_CONFIG=${APAMA_WORK}/project/${INSTANCE_NAME}/configs
Examples when executing on Command Central
*To define environment variables for a correlator instance:
sagcc update configuration data local Apama-correlator-myCorrelator
APAMA-ENVVAR -i Correlator.properties
*To define environment variables for an IAF instance:
sagcc update configuration data local Apama-iaf-myIAF
APAMA-ENVVAR -i IAF.properties