• Overview
• MaxL Grammar
• Definitions
• Perl Extension
• Keywords

Unless you embed MaxL statements in Perl programs, use the MaxL Command Shell as the interface for logging in to Hyperion Essbase and passing MaxL statements to the server. Before issuing MaxL statements,

1. Make sure the Hyperion Essbase server is running.
2. Invoke the MaxL Command shell (the simplest way is to type essmsh at the command prompt).
3. Log in to Hyperion Essbase from the MaxL Command Shell.

When using the MaxL Command Shell, you must use a semicolon (;) to terminate each MaxL statement.

Invocation — Start here

Logging in to Essbase

Syntax Notes

Output and Messages

Echoing Text and Variables

Shell Escape

Nesting Scripts

Version

Logging Out of Essbase

Quitting the Interactive Shell

Invocation

  overview   interactive   file   <STDIN>

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.

The following "man page" summarizes invocation options:

essmsh(1)

NAME
     essmsh -- MaxL Command Shell

SYNOPSIS
     essmsh [-hls] [-a | -i | file] [arguments...]

DESCRIPTION
     This document describes ways to invoke the MaxL Command Shell.
     The shell, invoked and nicknamed essmsh, takes input in the following
     ways: interactively (from the keyboard), standard input (piped from another 
     program), or file input (taken from file specified on the command line).
     The MaxL Command Shell also accepts any number of command-line arguments, 
     which can be used to represent any name.

OPTIONS
     essmsh accepts the following options on the command line:

     -h
      Prints this help.

     -l <user> <pwd>
      Logs in a user name and password to the local Essbase
      server instance.

     -s <server>
      Used after -l <user> <pwd>, logs the specified user into a named
      server. When omitted, localhost is implied.

     -i
      Starts a MaxL session which reads from <STDIN>, piped in from another program.
      The end of the session is signalled by the EOF character in that program.

     -a 
      Allows a string of command-line arguments to be referenced from within the
      subsequent INTERACTIVE session. These arguments can be referenced with positional
      parameters, such as $1, $2, $3, etc. Note: omit the -a when using arguments with 
      a file-input session.

NOTES
      
     No option is required to pass a filename to essmsh.

     Arguments passed to essmsh can represent anything: for example, a user name, an
     application name, or a filter name. Arguments must appear at the end of the 
     invocation line, following '-a', '-i', or filename.

EXAMPLES

     Interactive session, simplest case:
	essmsh

     Interactive session, logging in a user:
	essmsh -l user pwd

     Interactive session, logging user in to a server:
	essmsh -l user pwd -s server

     Interactive session, logging in with two command-line arguments
     (referenced thereafter at the keyboard as $1, $2, and $3):
	essmsh -l user pwd -a argument1 argument2
	
	 [More info]

     File-input session, simplest case:
	essmsh filename
     
     File-input session, with three command-line arguments 
     (referenced anonymously in the file as $1, $2, and $3):
	essmsh filename argument1 argument2 argument3
	
	 [More info]

     Session reading from <STDIN>, logging into a server with two
     command-line arguments:
	essmsh -l user pwd -s server -i argument1 argument2
	
	 [More info]
	

Interactive Input

No Flag

Invoked without a flag, file name, or arguments, the MaxL Command Shell starts in interactive mode and waits for you to log in. Note to Windows users: This is the same as double-clicking essmsh.exe, located in the ESSBASE\BIN directory.

Example:

essmsh

Hyperion Essbase MaxL Command Shell Version 1.0.0 Beta.
(c) Copyright 2000 Hyperion Solutions Corporation.
All rights reserved.
MAXL> login Fiona identified by sunflower;

      49 - User logged in: [Fiona].

-a Flag – Arguments

With the -a flag, the MaxL Command Shell starts in interactive mode and accepts space-separated arguments to be referenced at the keyboard with positional parameters. Note: If interactive arguments are used with spooling turned on, variables are recorded in the log file just as you typed them (for example, $1, $2, $ARBORPATH).

Example:

essmsh -a Fiona sunflower appname dbsname

Hyperion Essbase MaxL Command Shell Version 1.0.0 Beta.
(c) Copyright 2000 Hyperion Solutions Corporation.
All rights reserved.

MAXL> spool on to $HOME\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> echo $ARBORPATH;

D:\Hyperion\ESSBASE 

MAXL> spool off;

Contents of logfile 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> echo $ARBORPATH;

D:\Hyperion\ESSBASE 
	  
MAXL> spool off;

-l Flag – Login

With the -l flag followed by a user name and password, the MaxL Command 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 by a space.

Example:

essmsh -l Fiona sunflower

Entered at the command prompt, this starts the MaxL Command Shell in interactive mode and logs in user Fiona, who can henceforth issue MaxL statements at the keyboard.

File Input

File Only

If you type essmsh followed by a file name or path, the shell takes input from the specified file.

Examples:

essmsh C:\Hyperion\Essbase\scripts\filename.msh

Entered at the command prompt, this starts the shell, tells it to read MaxL statements from a file, and terminates the session when it is finished.

essmsh filename

Starts the shell to read MaxL statements from filename, located in the current directory (the directory from which the MaxL Command Shell was invoked).

File with Arguments

If you type essmsh 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.

Example:

D:\Scripts>essmsh filename.msh Fiona sunflower localhost newuser

Starts the shell to read MaxL statements from filename.msh, located in the current directory.

Contents of script filename.msh:

spool on to $HOME\output\filename.out;
login $1 $2 on $3;
create user $4 identified by $2;
echo "Essbase is installed in $ARBORPATH";
spool off;
exit;

Contents of logfile filename.out:

MAXL> login Fiona sunflower on localhost;

      49 - User logged in: [Fiona].

MAXL> create user newuser identified by sunflower;

      20 - User created: ['newuser'].

Essbase is installed in D:\Hyperion\ESSBASE 

Standard Input

With the -i flag, essmsh uses standard input, which could be input from another process. For example,

program.sh | essmsh -i

When program.sh generates MaxL statements as output, you can pipe program.sh to essmsh -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;|essmsh -i

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

Syntax Notes

The following syntax rules apply to the use of the MaxL Command Shell.

Semicolons

When a MaxL statement is passed to Essbase interactively or in batch mode via the MaxL Command 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

Variables, Quotation Marks, and Special Characters

In the MaxL Command 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), or positional parameters (for example, $1, $2, etc.).

A variable always begins with a $ (dollar sign).

Use single quotation marks to tell essmsh to recognize a string as a single token, without expanding variables.

Use double quotation marks when you want a string interpreted as a single token with variables expanded.

On certain shells, for example on the Windows NT cmd.exe shell, you may need to use single quotation marks inside of double quotation marks to have a string be interpreted as a single token with variables expanded. In this case, if you are specifying file paths, you may also need to "escape" the special backslash character with another backslash character preceding it. Example

The following characters, when when you intend them to be interpreted literally (for example, in names or file paths), may need to be escaped so that they are not interpreted as something else by the MaxL Command Shell: $ (dollar sign).  \ (backslash).

Example: Positional Parameters

essmsh filename Fiona sunflower sample basic
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.

alter database $3.$4 begin archive to file "'$HOME\Archives\$4.bak'";

Interpreted as alter database sample.basic begin archive to file C:\Archives\sample.bak;.
$HOME is an environment variable referring to the home directory (C:). $3 and $4 refer to the application name database name passed in as arguments at invocation time.

The file or process that the MaxL Command 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

Example: Quotation Marks and Variable Expansion

In the following examples, assume you logged in to the MaxL Command Shell interactively with arguments, as follows:
essmsh -a Fiona sunflower sample basic

Example: Escape Sequences

In the next three examples, assume there is an application named $App1. The dollar sign is part of the application name, and is not meant to denote a variable.

display application $App1

Returns essmsh error: Variable doesn't exist - $App1

display 'application $App1'

Returns display application $App1, as a single token. NOT suitable for display application, which requires three tokens.

display application \$App1;

Returns display application $App1;, as three tokens. Suitable for display application.

Example: Exit Status

A successful MaxL Command Shell operation should have an exit status of zero. Most unsuccessful MaxL Command 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

Example: Setting Up Sample Applications (Windows)

/* 
1. Copy this example into a text file.
2. Save it as setup_samples.msh, and remove the .txt extension.
3. At the command prompt, change to the directory where you saved the script.
4. Invoke the MaxL script as follows:  
essmsh setup_samples.msh username password host
Use a password other than password, or use single quotes ('password').
 */

/* Logs in user, password (on hostname) as specified in invocation arguments */
login $1 $2 on $3;

/* Begins recording this session to a log file */
spool on to 'setup_samples.txt';

/* Loads data into sample databases (except partitioning) 
and provides write access. */

import database sample.basic data from data_file
 "'$ARBORPATH\\app\\sample\\basic\\calcdat.txt'";
alter database sample.basic set minimum permission write;

import database sample.interntl data from data_file
 "'$ARBORPATH\\app\\sample\\interntl\\currcalc.txt'";
alter database sample.interntl set minimum permission write;

import database sample.xchgrate data from data_file
 "'$ARBORPATH\\app\\sample\\xchgrate\\rates.txt'";
alter database sample.xchgrate set minimum permission write;

import database demo.basic data from data_file
 "'$ARBORPATH\\app\\demo\\basic\\data.txt'";
alter database demo.basic set minimum permission write;

/* Stops logging */
spool off;
logout;

Logging In to Essbase

Before you can send MaxL statements from the MaxL Command Shell to Hyperion Essbase, you must log in to an Essbase session.

Note: Before logging in to an Essbase session, you must start the command shell.
Or, you can start the command shell and log in at the same time.

Note: Login is part of the MaxL Command Shell grammar, not the MaxL language itself. You can use a login statement in MaxL scripts and the MaxL Command Shell, but you cannot embed it in Perl.

Example

login admin mypassword on localhost;

Establishes a connection to the Hyperion Essbase server for user Admin identified by mypassword.

Logging Output (Spooling)

Log the output of a MaxL Command 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 appended to or 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 Command Shell was invoked).

Echoing Text and Variables

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

Example

Operating System Shell Escape

Issue operating-system commands directly from a MaxL Command 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 Scripts

Reference 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

Example

login fiona sunflower;
alter database sample.basic end archive;
msh calculate.msh;
alter database sample.basic
 begin archive to file bak;
 logout;
 

Version

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

Example

version;

Returns

Hyperion Essbase MaxL Command Shell Version 6.0.0.
 (c) Copyright 2000 Hyperion Solutions Corporation.
 All rights reserved.
 MAXL>

Logging Out of Essbase

Log out from Essbase without exiting the interactive MaxL Command Shell.

Syntax

logout;

Example

logout;

Quitting the Interactive Shell

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 Command Shell window or terminal.

Copyright (c) 2000 Hyperion Solutions Corporation. All rights reserved.