1. Scripting Reference for Oracle Essbase
  2. MaxL
  3. MaxL Shell Syntax Rules and Variables

MaxL Shell Syntax Rules and Variables

The MaxL Shell requires semicolon terminators at the end of MaxL statements. You can work with variables in MaxL scripts to make them more flexible. Learn the quoting and special characters rules for MaxL Shell to ensure that your MaxL scripts for Essbase work as expected.

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

When a MaxL statement is passed to Essbase Server 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, do not use semicolons.

Table 3-23 Semicolon Usage Examples in MaxL

Program Example
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;

Variables

Overview of Variables in MaxL Shell

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" could be interpreted as /scratch/user/oracle_home/essbase/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 /scratch/user/oracle_home/essbase/products/Essbase/EssbaseServer.

Environment Variables

You can reference any environment variable in the MaxL Shell.

Example (Unix): spool on to "$ESSBASEPATH\\out.txt";

Result: MaxL Shell session is recorded to /scratch/user/oracle_home/essbase/products/Essbase/EssbaseServer/out.txt .

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 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" */

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.

Variables defined or changed in a nested script persist into the parent script after the nested script executes.

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 Quoting and Special Characters Rules. 

essmsh -a Fiona sunflower sample basic login $1 $2;

Table 3-24 Quotation Marks' Usage and Effect on Variables in MaxL

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

Quoting and Special Characters Rules

These rules are for MaxL Shell commands. Applicable commands include spool on/off, echo, and nesting.

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 "$ESSBASEPATH\\out.txt";

Result: MaxL Shell session is recorded to /scratch/user/oracle_home/essbase/products/Essbase/EssbaseServer/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)

  • '\ ' = (nothing) (MaxL)

  • '\\' = \\ (MaxL Shell)

  • '\\' = \ (MaxL)

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, '\' is ignored.

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.