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.

Interactive Input Flags

You can log into the MaxL Shell for interactive use (typing statements at the keyboard) in the following ways.

startMAXL.bat

startMAXL.bat -a Fiona sunflower appname dbsname

MAXL> spool on to 'D:\output\createapp.out';

MAXL> login $1 identified by $2;

      49 - User logged in: [Fiona].

MAXL> create application $3;

      30 - Application created: ['appname'].

MAXL> create database $3.$4 as Sample.Basic;

      36 - Database created: ['appname'.'dbsname'].
          
MAXL> spool off;

startMAXL.bat -l Fiona sunflower

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.msh

Entered 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 filename

The 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 localhost

The 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 -i

When 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 -i

In the above example, the MaxL Shell takes input from the echo command's output. User Fiona is logged in, and user privileges are displayed.

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.

FILE-NAME

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 

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

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.

COLUMN-WIDTH

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.

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.

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 LABELNAME

Example: 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.

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.