MaxL Shell Commands


The MaxL Shell (essmsh) is a pre-parser mechanism for entering MaxL statements. The MaxL Shell has a separate set of useful commands, independent of the MaxL language itself. Before using any of the following MaxL Shell commands, you need to log in.

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 in the current directory, it is created. If FILE-NAME already exists in the current directory, it is overwritten. Message logging begins with spool on and ends with spool off.

Example

spool on to 'output.txt';

{MaxL statements}

spool off;

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:

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: No maximum.

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.

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;


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.


Shell Escape

Issue operating-system commands directly from a MaxL Shell session. The operating-system output becomes part of the shell session's output, and may be logged to a file. When the operating system finishes executing whatever commands are issued (as STRING), it returns control to the shell session.


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;
 

Error Checking and Branching

The MaxL Perl Module is the most powerful way to integrate error handling into MaxL. However, the following method is for users who do not implement the Perl module.

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.

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

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


Version

To see which version of MaxL you are using, type version.

Example

version;

Returns
Hyperion Essbase MaxL Shell - Release 7.0.0 
 (c) Copyright 2000-2003 Hyperion Solutions Corporation.
 All rights reserved.
 MAXL>

Logout

Log out from Essbase without exiting the interactive MaxL Shell.

Syntax

logout;

Example

logout;


Exit

Exit from the MAXL> prompt after using interactive mode.
Note: It is not necessary to exit at the end of MaxL script files or stream-oriented input (using the -i switch).

Syntax

exit;

Example

exit;

Closes the MaxL Shell window or terminal.

©2004 Hyperion Solutions Corporation. All Rights Reserved.
http://www.hyperion.com