MaxL Shell Commands
There are different ways to start (invoke) the MaxL Shell, and you may often need MaxL Shell commands in addition to MaxL statements when you work with Essbase. MaxL Shell commands include login, spool, set column width, set message level, set timestamp, echo, nesting, iferror/goto, and logout.
The MaxL Shell has a separate set of useful commands, independent of the MaxL language itself.
MaxL Shell Invocation
The MaxL Shell (essmsh) is a pre-parser mechanism for entering MaxL statements.
You can start the shell to be used interactively, to read input from a file, or to read stream-oriented input (standard input from another process). You can log in after you start the shell, interactively or using a login statement in the input file. You can also log in at invocation time, by using the -l flag.
To start the essmsh shell, do not invoke it directly. In order for the environment to be set correctly, you must start essmsh using startMAXL.bat (Windows) or startMAXL.sh (UNIX).
Help is available at the operating-system command prompt if you type startMAXL.bat -h | more.
Note:
The help text is for essmsh shell; however, in order for the environment to be set correctly, you must start essmsh using startMAXL.bat (Windows) or startMAXL.sh (UNIX). You can pass the same arguments to startMAXL as you would formerly pass to essmsh. For example, instead of essmsh -l username password, you should now use startMAXL.bat -l username password.
Interactive Input Flags
You can log into the MaxL Shell for interactive use (typing statements at the keyboard) in the following ways.
| Flag | Description/Example |
|---|---|
| No Flag |
Invoked without a flag, file name, or arguments, the MaxL Shell starts in interactive mode and waits for you to log in. Note to UNIX users: In the following examples, replace |
| -a Flag: Arguments |
With the -a flag, the MaxL Shell starts in interactive mode and accepts space-separated arguments to be referenced at the keyboard with positional parameters. If interactive arguments are used with spooling turned on, variables are recorded in the log file just as you typed them (for example, |
| -l Flag: Login |
When the -l flag is used followed by a user name and password, the MaxL Shell logs in the given user name and password and starts in interactive or non-interactive mode. The user name and password must immediately follow the -l, and be separated from it by a space. |
| -u, -p, and -s Flags: Login Prompts and Hostname Selection |
The MaxL Shell can be invoked using -u and -p options in interactive mode, for passing the user name and password to the shell upon startup. To be prompted for both username and password, use the -s option with the host name of the Essbase Server.
|
| -m Flag: Message Level |
If -m <messageLevel> is passed to the shell, only the specified level of messages will be returned by the shell. Example: Values for the <messageLevel> include: default, all, warning, error, and fatal. The default value is all (same as specifying default). |
File Input
You invoke the MaxL Shell to run scripts (instead of typing statements at the keyboard) in the following ways.
If you type startMAXL.sh or startMAXL.bat followed by a file name or path, the shell takes input from the specified file.
startMAXL.sh /client/scripts/filename.mshEntered at the command prompt, the above example starts the shell, tells it to read MaxL statements from a file, and terminates the session when it is finished.
startMAXL.bat filenameThe above example starts the shell to read MaxL statements from filename, located in the current directory (the directory from which the MaxL Shell was invoked).
If you type startMAXL.sh or startMAXL.bat, followed by a file name, followed by an argument or list of space-separated arguments, essmsh remembers the command-line arguments, which can be referenced as $1, $2, etc. in the specified file. If spooling is turned on, all variables are expanded in the log file.
startMAXL.bat filename.msh Fiona sunflower localhostThe above example starts the shell to read MaxL statements from filename.msh, located in the current directory.
Standard Input
With the -i flag, essmsh uses standard input, which could be input from another process. For example,
program.sh | startMAXL.bat -iWhen program.sh generates MaxL statements as output, you can pipe program.sh to startMAXL.bat -i to use the standard output of program.sh as standard input for essmsh. Essmsh receives input as program.sh generates output, allowing for efficient co-execution of scripts.
Example
echo login Fiona sunflower on localhost; display privilege user;|startMAXL.bat -iIn the above example, the MaxL Shell takes input from the echo command's output. User Fiona is logged in, and user privileges are displayed.
Before using any of the MaxL Shell commands that follow, you need to log in (see Login)Spool On/Off
Log the output of a MaxL Shell session to a file. Send standard output, informational messages, error messages, and/or warning messages generated by the execution of MaxL statements to a file.
If FILE-NAME does not exist, it is created. If FILE-NAME already exists, it is overwritten. If a directory path is not specified for FILE-NAME, FILE-NAME is created in the current directory of the MaxL Shell. Directories cannot be created using the spool command.
Message logging begins with spool on and ends with spool off.
Description of the illustration hspool.gif
Example
spool on to 'output.txt';Sends output of MaxL statements to a file called output.txt, located in the current directory where the MaxL Shell was invoked.
Description
Most operating systems support three channels for input/output:
-
STDIN (standard input channel)
-
STDOUT (standard output channel)
-
STDERR (standard error channel)
Most operating systems also provide command-line options for re-directing data generated by applications, depending on which of the above channels the data is piped through.
Errors in MaxL are flagged as STDERR, allowing command-line redirection of errors using operating-system redirection handles. Non errors are flagged as STDOUT; thus normal output may be logged separately from error output. Here is an example of redirecting error-output at invocation time:
essmsh script.mxl 2>errorfile.err Note:
Operating-system redirection handles vary; check the platform documentation.
You can also redirect STDERR and STDOUT independently to different MaxL output logs, using the corresponding options in the spool command. For example, you can direct errors to one file and output to another by placing the following lines in your script:
spool stdout on to 'output.txt';
spool stderr on to 'errors.txt';or you can direct errors only:
spool stderr on to 'errors.txt';or you can direct output only:
spool stdout on to 'output.txt';Note:
You cannot use the generic spool and the special output-channel spools in the same script. For example, the following is not valid:
spool on to 'session.txt';
spool stderr on to 'errors.txt';Set Display Column Width
Set the width of the columns that appear in MaxL display output tables, for the current MaxL Shell session.
-
Default: 20 characters
-
Minimum: 8 characters
-
Maximum: None.
Description of the illustration hsetcol.gif
Example
set column_width 10;Sets the column width to 10 characters.
set column_width default;Sets the column width back to 20 characters.
Set Message Level
Set the level of messaging you want returned from MaxL Shell sessions. By default, all messages are returned.
Description of the illustration hsetmsg.gif
Table 3-22 MaxL Shell Message Levels
| Message level | Description |
|---|---|
| all | Errors, warnings, status reporting, and informational messages. This is the default message level. |
| error | Essbase and MaxL Shell error messages. |
| warning | Essbase warning messages. |
| fatal | Only errors which cause the shell to disconnect from Essbase. |
Example
set message level all;Set Timestamp
Enable or disable the display of a timestamp after execution of each MaxL statement. By default, no timestamps are returned.
Description of the illustration set_timestamp.gif
Note:
The timestamp information does not display after the error-control shell statements goto, iferror, and define.
Example
set timestamp on;Echo
Display text or expand variables to the screen or to a log file. When used in scripts with spooling (log-file generation) turned on, echo expands variables in the log file. For interactive sessions, variables are not expanded in the log file; instead, the variable name you typed is recorded (for example, $1).
Syntax
echo <text> | <variablename>Example
See examples of echo under the discussion of variables (MaxL Shell Syntax Rules and Variables).
Nesting
Reference (include) a MaxL script from within another MaxL script. You might use this if variables are defined in the referenced MaxL script which are useful to the current MaxL script.
Syntax
msh <scriptfile>;
Example
login fiona sunflower;
alter database sample.basic end archive;
msh calculate.msh;
alter database sample.basic
begin archive to file bak;
logout;
Notes
Variables defined or changed in a nested script persist into the parent script after the nested script executes.
Because msh is a shell command, it is limited to the originating session. Therefore, you should not reference MaxL scripts that contain new login statements.
Error Checking and Branching
IfError instructs the MaxL Shell to respond to an error in the previous statement by skipping subsequent statements, up to a certain location in the script that is defined by a label name.
IfError checks the presence of errors only in the precedent statement. IfError checks for:
-
Errors in MaxL statement execution
-
Errors in MaxL Shell command execution, including:
-
Errors in
spool on/off, such as permission errors -
Errors in
set column_width, such as invalid widths -
Errors in script nesting, such as permission errors or nonexistent include files
-
Goto forces the MaxL Shell to branch to a certain location in the script defined by a label name; goto is not dependent on the occurence of an error.
Syntax
iferror LABELNAME
goto LABELNAME
define label LABELNAMEExample: Iferror (MaxL)
The following example script contains a dimension build statement and a data load statement. If the dimension build fails, the data load is skipped.
login $1 $2;
import database sample.basic dimensions
from data_file 'C:\\data\\dimensions.txt'
using rules_file 'C:\\\\data\\rulesfile.rul'
on error append to 'C:\\\\logs\\dimbuild.log';
iferror 'dimbuildFailed';
import database sample.basic data from data_file
"$ARBORPATH\\app\\sample\\basic\\calcdat.txt"
on error abort;
define label 'dimbuildFailed';
exit;Example: Iferror (MaxL Shell)
The following example script tests various errors including MaxL Shell errors, and demonstrates how you can set the exit status variable to a nonzero argument to return an exit status to the MaxL Shell.
### Begin Script ###
login $1 $2;
echo "Testing syntactic errors...";
spool on to spool.out;
set timestamp on;
iferror 'End';
msh "doesnotexistlerr.mxl";
iferror 'FileDoesNotExistError';
echo "Script completed successfully...";
spool off;
logout;
exit 0;
define label 'FileDoesNotExistError';
echo "Error detected: Script file does not exist";
spool off;
logout;
exit 1;
define label 'ShellError';
echo ' Shell error detected...';
spool off;
logout;
exit 2;
define label 'End';
echo ' Syntax error detected...';
spool off;
logout;
exit 3;
### End Script ###
Example: Goto
The following example script contains a dimension build statement and a data load statement. Goto is used to skip the data load.
login $1 $2;
import database sample.basic dimensions
from data_file 'C:\\data\\dimensions.txt'
using rules_file 'C:\\\\data\\rulesfile.rul'
on error append to 'C:\\\\logs\\dimbuild.log';
goto 'Finished';
import database sample.basic data from data_file
"$ARBORPATH\\app\\sample\\basic\\calcdat.txt"
on error abort;
define label 'Finished';
exit;Notes
The MaxL Shell will skip forward in the script to LABELNAME but not backwards.
Version
To see which version of MaxL you are using, type version.
Example
version;Logout
Log out from Essbase without exiting the interactive MaxL Shell.
Example
logout;Exit
Exit from the MAXL> prompt after using interactive mode. You can optionally set the exit status variable to a non zero argument to return an exit status to the parent shell.
Note:
It is not necessary to exit at the end of MaxL script files or stream-oriented input (using the -i switch).
Example
exit 10;Closes the MaxL Shell window or terminal with a return status of 10. You can use this in combination with IfError to return a non zero error status to the parent shell.