MaxL Shell Syntax Rules and Variables

back to MaxL Shell main page
back to MaxL Statements

The MaxL Shell (essmsh) is a pre-parser mechanism for entering MaxL statements. The following syntax information can help you use the MaxL Shell successfully.

Semicolons
Variables
Quoting and Special Characters

Semicolons

When a MaxL statement is passed to Essbase interactively or in batch mode via the MaxL Shell (essmsh), it must be terminated by a semicolon. Semicolons are used only to tell essmsh when to terminate the statement; semicolons are not part of the MaxL language itself. Therefore, when issuing MaxL statements programmatically through Perl or API programs, do not use semicolons.

Examples

Interactive MaxL Shell	`create application Sample;`
MaxL Shell script:	`login $1 identified by $2; create application Sample; create currency database Sample.Interntl; display database Sample.Interntl; exit;`
Perl function (Correct)	`print $dbh->do("create currency database Sample.Interntl");`
Perl function (Incorrect)	`print $dbh->do("create currency database Sample.Interntl;");`

Variables

Overview
Environment Variables
Positional Parameters
Locally Defined Shell Variables
Quotation Marks and Variable Expansion
Special Exit Status Variable

Overview of MaxL Shell Variables

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, $ARBORPATH, 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, "$ARBORPATH" is interpreted as c:\hyperion\essbase.

Use single quotation marks around a string to tell essmsh to recognize the string as a single token, without expanding variables. For example, '$ARBORPATH' is interpreted as $ARBORPATH, not c:\hyperion\essbase.

Environment Variables

You can reference any environment variable in the MaxL Shell.

Example (Windows): spool on to "$ARBORPATH\\out.txt";
Result: MaxL Shell session is recorded to c:\hyperion\essbase\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 Parameters

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 NT 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

Locally Defined Shell Variables

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.

Quotation Marks and Variable Expansion

In the following examples, assume you logged in to the MaxL Shell interactively with arguments, as follows. In addition to these examples, see the quoting rules.
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.

Exit Status Variable

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;
      30 - Application created: ['test1'].
MAXL> echo $?;
0
MAXL> drop application no_such;
      28 - Application does not exist: ['no_such'].
      51 - MaxL execution failed.
MAXL> echo $?;
1

Quoting and Special Characters Rules for MaxL Shell

These rules are for MaxL Shell commands only; not for MaxL Language. Applicable MaxL Shell commands include spool, echo, shell, and msh.

Tokens enclosed in single quotation marks
Tokens enclosed in double quotation marks
Use of apostrophes
Use of backslashes

Tokens enclosed in single quotation marks

Contents within single quotation marks are preserved as literal, without variable expansion.

Example: echo '$3';
Result: $3

Tokens enclosed in double quotation marks

Contents of double quotation marks are treated as a single token, and the contents are perceived as literal except that variables are expanded.

Example: spool on to "$ARBORPATH\\out.txt";
Result: MaxL Shell session is recorded to c:\hyperion\essbase\out.txt.

Example: spool on to "Ten o'clock.txt"
Result: MaxL Shell session is recorded to a file named Ten o'clock.txt

Use of apostrophes (single quotation marks)

Preserved if enclosed in double quotation marks. Otherwise, causes a syntax error.

Example: spool on to "Ten o'clock.txt"
Result: MaxL Shell session is recorded to a file named Ten o'clock.txt

Use of backslashes

Backslashes must be enclosed in single or double quotation marks because they are special characters.
One backslash is treated as one backslash by the shell, but is ignored or treated as an escape character by MaxL. Two backslashes are treated as one backslash by the shell and MaxL.

'\' = '\' (MaxL Shell)
'\' = ' ' (MaxL)
'\\' = '\' (MaxL and MaxL Shell)

Example: spool on to 'D:\output.txt'
Result: MaxL Shell records output to D:\output.txt.

Example: spool on to 'D:\\output.txt'
Result: MaxL Shell records output to D:\output.txt.

Example: import database sample.basic lro from directory "'$ARBORPATH\app\sample-basic-lros'";
Result: Error. Import is a MaxL statement, and for MaxL, '\' = ' '.

Example: import database sample.basic lro from directory "'$ARBORPATH\\app\\sample-basic-lros'";
Result: MaxL imports LRO information to Sample Basic from $ARBORPATH\app\sample-basic-lros.