MaxL Shell Invocation

• back to MaxL Shell main page
• back to MaxL Statements

The MaxL Shell (essmsh) is a pre-parser mechanism for entering MaxL statements.

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.

• Prerequisites
• Invocation Summary
• Interactive Mode
• File-Input Mode
• Stream-Input Mode
• Login

Prerequisites

Before the Essbase OLAP Server can receive MaxL statements,

1. The Essbase OLAP Server must be running.
2. The MaxL Shell (essmsh) must be invoked, if you are using the shell.
3. You must log in to the Essbase OLAP Server from the MaxL Shell. If you are running a MaxL script, the first line of your script must be a login statement.

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

Invocation Summary

The following MaxL Shell help page summarizes invocation options. This help is also available at the operating-system command prompt if you type essmsh -h | more.

essmsh(1)

NAME
     essmsh -- MaxL Shell

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

DESCRIPTION
     This document describes ways to invoke the MaxL 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 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.

     -u <user>
      Specifies a user to be logged in to Essbase server instance. 
      If omitted but the '-p' or '-s' flags are used, essmsh will 
      prompt for the username.

     -p <pwd>
      Specifies a password of the user set by the '-u' option to 
      be logged in to Essbase server instance. If omitted, essmsh 
      will prompt for the password, and the password will be hidden 
      on the screen.

     -s <server>
      Used after -l, or with [-u -p], logs the specified user into a named
      server. When omitted, localhost is implied.
	  
     -m <msglevel>
      Sets the level of messages returned by the shell. Values for <msglevel> 
      are: all (the default), warning, error, and fatal.

     -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 and $2):
	   essmsh -l user pwd -a argument1 argument2
	
	 [More info]
	 
     Interactive session, with setting the message level:
      essmsh -m error
	  
     Interactive session, hiding the password:
      essmsh -u user1
      Enter Password > ******

     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

You can log into the MaxL Shell for interactive use (typing statements at the keyboard) in the following ways. See the manpage for more descriptions of login flags.

No flag
Flag for arguments
Flag for logging in
Flags for Login Prompts and Hostname Selection

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 Windows users: This is the same as double-clicking essmsh.exe, located in the ESSBASE\BIN directory.

Example:

essmsh

Hyperion Essbase MaxL Shell - Release 6.5
Copyright 1991-2002 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 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 Shell
Copyright 1991-2002 Hyperion Solutions Corporation.
All rights reserved.

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

D:\Hyperion\ESSBASE 

MAXL> spool off;

Contents of logfile createapp.out:

MAXL> login $1 identified by $2;

 OK/INFO - 1051034 - Logging in user Fiona.
 OK/INFO - 1051035 - Last login on Friday, January 18, 2002 4:09:16 PM.
 OK/INFO - 1241001 - Logged in to Essbase.

MAXL> create application $3;

 OK/INFO - 1051061 - Application appname loaded - connection established.
 OK/INFO - 1054027 - Application [appname] started with process id [404].
 OK/INFO - 1056010 - Application appname created.

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

 OK/INFO - 1056020 - Database appname.dbname created.

MAXL> echo $ARBORPATH;

D:\Hyperion\ESSBASE 
	  
MAXL> spool off;

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

Example:

essmsh -l Fiona sunflower

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

-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 OLAP Server.

-s Flag: Host Name

If -s <host-name> is passed to the shell, MaxL will prompt for the user name and password, and the password will be hidden.
Example:

essmsh -s localhost
Enter UserName> admin
Enter Password> ********

 OK/INFO - 1051034 - Logging in user admin.
 OK/INFO - 1051035 - Last login on Monday, January 28, 2002 10:06:16 AM.
 OK/INFO - 1241001 - Logged in to Essbase.
 

-u Flag: User Name

If -u <username> is passed to the shell and -p <password> is omitted, MaxL Shell will prompt for the password, and the password will be hidden.
Example:

 essmsh -u user1
 Enter Password > ******
 

-p Flag: Password

If -p <password> is passed to the shell and -u <username> is omitted, MaxL Shell will prompt for the user name.
Example:

 essmsh -p passwrd
 Enter Username > user1
 

File Input

You invoke the MaxL Shell to run scripts (instead of typing statements at the keyboard) in the following ways. See the manpage for a complete description of login flags.

File only
File with arguments

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 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 Shell takes input from the echo command's output. User Fiona is logged in, and user privileges are displayed.

Login

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

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

Note: Login is part of the MaxL Shell grammar, not the MaxL language itself. You can use a login statement in MaxL scripts and the MaxL 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.

Copyright 1991-2002 Hyperion Solutions Corporation. All rights reserved.