The OLAP Server includes MaxL and ESSCMD, both command-line interfaces that perform operations interactively or through batch or script files.
MaxL improves upon ESSCMD in that it is a multi-dimensional access language for Essbase. Using MaxL, you make requests to Essbase using English-like statements, rather than commands. MaxL scripts can be developed flexibly to accommodate many uses, and the MaxL language is easy to learn. MaxL is installed with a Perl module that enables you to embed its statements in Perl programs.
This chapter focuses on ESSCMD. It describes how to use ESSCMD's interactive and batch processing modes, and provides sample script and batch files. It includes the following topics:
For an overview of MaxL, see the MaxL User's Guide (essmaxl.pdf in the \docs\pdf directory of your Essbase installation).
For MaxL and ESSCMD syntax and usage information, see the Technical Reference in the docs directory.
For information on the Administration Services and MaxL Script Editor, see Essbase Administration Services Online Help.
With ESSCMD, you can execute server operations at the command line, in either interactive or batch mode.
Interactive mode means entering commands at the ESSCMD command line, and receiving prompts where necessary. Interactive mode is convenient for short operations that require few commands, checking for information on the fly, and error checking.
Batch processing mode is used for automating routine server maintenance and diagnostic tasks. You can write a script or batch file and run it from the command line. Batch processing mode is convenient if you frequently use a particular series of commands, or if a task requires many commands.
In general, use the same syntax for entering ESSCMD commands as you do for other calculation commands. However, there are differences between ESSCMD's interactive and batch processing modes in the requirements for quotation marks and the semicolon statement terminator. Use the guidelines in this section when creating script or batch files.
Quotation marks (" ") enclose character parameters and responses to commands.
CALC "Calc All;"
LOGIN "Localhost" "user1" "Password";
The ; (semicolon) statement terminator signals the end of a command; for example:
SELECT "SAMPLE" "BASIC";
If you omit some optional parameters and do not use a semicolon to end the list, ESSCMD looks for the remaining values in the next command in the file, leading to unpredictable results.
The SETAPPSTATE and SETDBSTATE commands, defined in the Technical Reference in the docs directory, are examples of commands which you should terminate with a semicolon to prevent any confusion in processing.
Note: All syntax examples in this chapter use quotation marks and semicolon terminators.
ESSCMD operates independently of any Essbase client interface, including the Application Manager, Spreadsheet Add-in, or custom-built application programs.
ESSCMD is available on the platforms listed in the Essbase Installation Guide, in the server platform system requirements section.
When running ESSCMD, you can cancel an asynchronous operation, such as a calculation, export, or restructure operation, by pressing and holding the Esc key until ESSCMD responds.
Some commands require that you precede object or file names with a numeric parameter, from 1 to 4, that tells Essbase where to look for the object or file. The parameter directs ESSCMD to look for files in other applications, databases, or systems.
The following table lists each value for the numeric parameter (Number), the file location to which it applies, and the information that ESSCMD requests when you use each parameter setting. appName is the application name and dbName is the database name.
Number |
File |
Essbase prompts user for: |
---|---|---|
Fully-qualified path to the file, unless file is in the current ESSCMD directory |
||
For example, the LOADDATA command can load a data file that resides on the client or OLAP Server. The command requires the numeric parameter to tell Essbase where to look for the data file. This example causes ESSCMD to prompt for the fully-qualified path name of the file to load:
LOADDATA 3
File extensions are usually optional in both interactive and batch processing modes, except when using commands that require a numeric parameter that indicates the location of files:
Because ESSCMD supports multiple login instances on OLAP Server, you can access more than one database in a single session. Even when you log in to multiple databases, you use only one port on your server license.
The OLAP Server creates application and database names exactly as the user specifies. Case is not changed for any platform.
For backward compatibility, the OLAP Server searches for existing application and database names using the exact case first. However, if it cannot find the file, OLAP Server searches all possible case combinations to find the existing application and database names.
Essbase does not allow you to create application and database names that differ only in case. For example, Essbase would display an error message if you tried to create an application MyData if you already had an application mYdATA.
You can choose to make member names case sensitive. For details, see Making Members Case-Sensitive.
To display a list of all currently available ESSCMD commands, enter HELP?. To see documented descriptions and syntax for individual ESSCMD commands, see the online Technical Reference, located in the ESSBASE/DOCS directory.
Before you start ESSCMD, make sure that the following items are properly installed and running:
For information on protocols supported by Essbase, see the Essbase Installation Guide.
The Essbase installation places the esscmd.exe and esscmd.hlp files (esscmd and esscmd.hlp on UNIX platforms) in the BIN directory of your application server.
Once you start the application, a command prompt like this one displays:
:::[n]->
where n is the value of the active login instance. Each subsequent, successful login increments this value by one. When you start ESSCMD, the instance number is zero (0).
Note: Use the SETLOGIN command to toggle between active login instances. Use the LISTLOGINS command to view active login instances. For more information, see the online Technical Reference, located in the essbase/docs directory.
To start ESSCMD, do one of the following:
To quit ESSCMD, Enter EXIT at the prompt and press Enter. ESSCMD disconnects from the application server, and terminates the session.
In interactive mode, you enter commands and respond to prompts. This is useful when you are performing simple tasks that require few commands. If you are performing more complex tasks that require many commands, consider creating a script file or batch file; see Using Script and Batch Files for Batch Processing for information.
For syntax conventions when working in interactive mode, see Syntax Guidelines.
After starting ESSCMD, you must connect to OLAP Server so that you can enter commands. Follow these steps:
The ESSCMD prompt is displayed as follows:
aspen:::userName[1]->
You can enter any valid ESSCMD command. For a complete listing of commands, type HELP.
Note: To load an application into memory and select a database on the Essbase server, use the SELECT command to select a database from an application that resides on the server. For more information, see the online Technical Reference, located in the ARBORPATH/docs directory.
The ESSCMD prompt is displayed as follows:
aspen:appName:dbName:userName[1]->
appName is the name of the application. dbName is the name of the database to which you are connected.
There are two ways to enter commands in interactive mode. Choose either of the following methods to enter commands:
ESSCMD prompts you for each of the command parameters. For example, the SELECT command has two parameters, as shown in the command syntax:
SELECT "appName" "dbName";If you enter only SELECT and press Enter, ESSCMD prompts you for the first parameter, the application name (appName). After you enter the application name and press Enter, ESSCMD prompts you for the database name (dbName).
Using SELECT as the example, you would type:
SELECT "Sample" "Basic";
Whichever method you use, the interactive prompt now reflects the application and database names. For example, the following prompt tells you that the Sample application and Basic database are selected:
aspen:Sample:Basic:User[1]->
In this case, you can enter other commands without the application or database name parameters that it normally requires.
While ESSCMD is running, you can cancel an asynchronous operation, such as a calculation, export, or restructure operation, by pressing and holding the Esc key until ESSCMD responds.
Caution: Do not pause or suspend your system while Essbase is processing a command. Pausing the system may prevent Essbase from correctly completing the command.
If you use a series of commands frequently or you must enter many commands to complete a task, consider automating the task with a script or batch file. These files are useful for batch data loads and complex calculations.
For syntax conventions when working in batch processing mode, see Syntax Guidelines.
Note: On UNIX, a batch or script file is written as a shell script. A shell script usually has the file extension .sh (Bourne or Korn shell) or .csh (C shell).
When you run a script or batch file, ESSCMD executes the commands in order until it reaches the end of the file.
Existing script or batch files might be affected by changes to some commands. To ensure that your files work in Essbase 6, check on your use of changed or deleted commands. See the Essbase Installation Guide for information about new and changed commands.
ESSCMD script files automate an often-used or lengthy series of commands. Each script file must be a complete ESSCMD session, with login, application and database selection, logout, and termination commands.
For example, the following script file, TEST.SCR, was created in Notepad:
When run from the operating system command line, this script logs User1 into the Essbase localhost server, selects the Sample application and Basic database, gets database statistics, and quits the ESSCMD session.
To run script files in ESSCMD:
ESSCMD scriptFileName.SCR
ESSCMD TEST.SCR
ESSCMD C:\WORK\SCRIPTS\TEST.SCR (an absolute path on Windows NT) ESSCMD..\SCRIPTS\TEST.SCR (a relative path on Windows NT)
ESSCMD's error-handling features provide error checking and handling for your script files. You can write error-handling commands into your script file to check for errors and, if necessary, branch to an appropriate error-handling response.
After each ESSCMD command is executed, a number is stored in an internal buffer. If the command executes successfully, 0 is returned to the buffer; If the command is unsuccessful, the error number is stored in the buffer; this is called non-zero status.
For error checking within an ESSCMD script file, ESSCMD provides the following error-handling commands:
In this LOAD.SCR example file, if the LOADDATA command does not execute successfully, ESSCMD branches to the end of the file to avoid attempting to calculate and run a report script on the empty database.
Note: You can use the OUTPUT command to log errors to a text file.
For the syntax and usage of ESSCMD error commands, see the online Technical Reference, located in the ESSBASE/DOCS directory.
The following script files demonstrate common Essbase batch operations. All samples are based on the Sample Basic database that comes with your Essbase program. The scripts for these examples are available in your \ARBORPATH\app\sample\basic directory. On UNIX systems, the examples are available from /home/hyperion/essbase/app/Sample/Basic.
Suppose you need a file that executes the following actions:
The following script file does the job:
LOGIN "Poplar" "TomT" "Password"; SELECT "Sample" "Basic"; DISABLELOGIN; IMPORT 2 "ACTUALS" 4 "Y" 2 "ACTUAL" "N"; CALCDEFAULT; ENABLELOGIN; EXIT; |
On Windows, this script file, SAMPLE1.SCR, is available in the \ESSBASE\APP\SAMPLE\BASIC directory. On UNIX platforms, SAMPLE1.SCR is in the /essbase/app/Sample/Basic directory.
Suppose you need a script file that executes the following actions:
The following script file does the job:
LOGIN "Poplar" "TomT" "Password"; SELECT "Sample" "Basic"; DISABLELOGIN; BUILDDIM 2 "PRODRUL" 4 "PRODTBL" 4 "PROD.ERR"; IMPORT 4 "TOMT" "PASSWORD" 2 "ACTUAL" "N"; CALCDEFAULT; EXIT; |
On Windows, this script file, SAMPLE2.SCR, is available in the \ESSBASE\APP\SAMPLE\BASIC directory. On UNIX systems, SAMPLE2.SCR is in the /essbase/app/Sample/Basic directory.
Suppose you need a file that executes the following actions:
The following script file does the job:
LOGIN "Poplar" "TomT" "Password"; SELECT "Sample" "Basic"; RUNREPT 2 "REP1" "REP1.OUT"; RUNREPT 2 "REP2" "REP2.OUT"; RUNREPT 2 "REP3" "REP3.OUT"; EXIT; |
On Windows, this script file, SAMPLE3.SCR, is available in the \ESSBASE\APP\SAMPLE\BASIC directory. On UNIX platforms, SAMPLE3.SCR is in the /essbase/app/Sample/Basic directory.
You can write a batch file that runs one or more ESSCMD scripts, and includes operating system commands. See your operating system instructions to learn the syntax for writing batch files.
For an example of a batch file, see Handling Command Errors in a Script File.
For the operating system batch file, you can use ESSCMD command return values to control the flow of scripts that the batch file executes.
An ESSCMD program returns an integer value upon exiting. This value represents the status of the last executed command, usually whether the command succeeded or failed. You can set up your batch file to test for this value, and if the test fails, branch to an error-handling response. This process is similar to creating a script file. For information about handling errors in script files, see Handling Command Errors in a Script File.
For example, a batch file could contain three scripts: an ESSCMD batch file that loads data, a calculation script that performs calculations on the data, and a report script that reports on the results of the calculation. If the load batch file fails, the calculations and reporting also fail. In this case, it would be best to stop the batch file after the failure of the load file and correct the error that caused the failure before going on. If your batch file tests for the return value of the load process, and this return value indicates failure, the batch file can jump to the end of the file and stop or execute some other error-handling procedure, rather than attempting to calculate data that did not load.
The following example shows an NT operating system batch file and the contents of one of the ESSCMD scripts it runs, LOAD.SCR. Because error-checking requirements vary, the syntax in this example may not correspond to that of your operating system. See your operating system documentation for error checking in batch files.
An operating system batch file could contain commands like this:
![]() © 2002 Hyperion Solutions Corporation. All rights reserved. http://www.hyperion.com |