Locally Defined Shell Variables
Quotation Marks and Variable Expansion
In the MaxL Shell, you can use variables as placeholders for any data that is subject to change or that you refer to often; for example, the name of a computer, user names, and passwords. You can use variables in MaxL scripts as well as during interactive use of the shell. Using variables in MaxL scripts eliminates the need to create many customized scripts for each user, database, or host.
Variables can be environment variables (for example, $ESSBASEPATH, which references the directory Essbase is installed to), positional parameters (for example, $1, $2, etc.), or locally defined shell variables.
All variables must begin with a $ (dollar sign). Locally defined shell variables should be set without the dollar sign, but should be referenced with the dollar sign. Example:
set A = val_1; echo $A; val_1
Note: | Variables can be in parentheses. Example: if $1 = arg1, then $(1)23 = arg123. |
Use double quotation marks around a string when you want the string interpreted as a single token with the variables recognized and expanded. For example, "$ESSBASEPATH" is interpreted as C:\Hyperion\products\Essbase\EssbaseServer.
Use single quotation marks around a string to tell essmsh to recognize the string as a single token, without expanding variables. For example, '$ESSBASEPATH' is interpreted as $ESSBASEPATH, not C:\Hyperion\products\Essbase\EssbaseServer.
You can reference any environment variable in the MaxL Shell.
Example (Windows): spool on to "$ESSBASEPATH\\out.txt";
Result: MaxL Shell session is recorded to C:\Hyperion\products\Essbase\EssbaseServer\out.txt.
Example (UNIX): spool on to "$HOME/output.txt";
Result: MaxL Shell session is recorded to output.txt in the directory referenced by the $HOME environment variable.
Positional parameter variables are passed in to the shell at invocation time as arguments, and can be referred to generically by the subsequent script or interactive MaxL Shell session using $n, where n is the number representing the order in which the argument was passed on the command line.
For example, given the following invocation of the MaxL Shell,
essmsh filename Fiona sunflower
and the following subsequent login statement in that session,
login $1 identified by $2 on $COMPUTERNAME;
$COMPUTERNAME is a Windows environment variable.
$1 and $2 refer to the user name and password passed in as arguments at invocation time.
The values of positional parameters can be changed within a session. For example, if the value of $1 was originally Fiona (because essmsh was invoked with Fiona as the first argument), you can change it using the following syntax:set 1 = arg_new;
Note: | If you nest MaxL Shell scripts or interactive sessions, the nested shell does not recognize positional parameters of the parent shell. The nested shell should be passed separate arguments, if positional parameters are to be used. |
The file or process that the MaxL Shell reads from can be referred to with the positional parameter $0. Examples:
1) Invocation: essmsh filename $0 = filename 2) Invocation: program.sh | essmsh -i $0 = stdin 3) Invocation: essmsh $0 = null
You can create variables of any name in the MaxL Shell without the use of arguments or positional parameters. These variables persist for the duration of the shell session, including in any nested shell sessions.
Example:
MaxL>login user1 identified by password1; MaxL>set var1 = sample; MaxL>echo $var1; /* see what the value of $var1 is */ sample MaxL>display application $var1; /* MaxL displays application "sample" */
Note: | Locally defined variables can be named using alphabetic characters, numbers, and the underscore (_). Variable values can be any characters, but take note of the usual quoting and syntax rules that apply for the MaxL Shell (see MaxL Shell Syntax Rules and Variables). |
Note: | Variables defined or changed in a nested script persist into the parent script after the nested script executes. |
In the following examples, assume you logged in to the MaxL Shell interactively with arguments, as follows. In addition to these examples, see Quoting and Special Characters Rules for MaxL Shell.
essmsh -a Fiona sunflower sample basic login $1 $2;
Example | Return Value | Explanation |
---|---|---|
echo $1; | Fiona | $1 is expanded as the first invocation argument. |
echo "$1's hat"; | Fiona's hat | $1 is expanded as the first invocation argument, and the special character ' is allowed because double quotation marks are used. |
echo $3; | sample | $3 is expanded as the third invocation argument. |
echo '$3'; | $3 | $3 is taken literally and not expanded, because it is protected by single quotation marks. |
display database $3.$4; | Database sample.basic is displayed. | $3 and $4 are expanded as the third and fourth invocation arguments. $3.$4 is interpreted as two tokens, which makes it suitable for DBS-NAME. |
echo "$3.$4"; | sample.basic, but interpreted as one token (NOT suitable for DBS-NAME, which requires two tokens). | $3 and $4 are expanded as the third and fourth invocation arguments, but the entire string is interpreted as a single token, because of the double quotation marks. |
A successful MaxL Shell operation should have an exit status of zero. Most unsuccessful MaxL Shell operations have an exit status number, usually 1. Exit status can be referred to from within the shell, using $?. For example,
MAXL> create application test1; OK/INFO - 1051061 - Application test1 loaded - connection established. OK/INFO - 1054027 - Application [test1] started with process id [234]. OK/INFO - 1056010 - Application test1 created. MAXL> echo $?; 0 MAXL> drop application no_such; ERROR - 1051030 - Application no_such does not exist. MAXL> echo $?; 2