In This Section:
Oracle Essbase Technical Reference for ESSCMD syntax and usage
Oracle Essbase Administration Services Online Help for information about MaxL Script Editor
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 Essbase 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 that you do for other calculation commands. However, differences exist between the ESSCMD 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.
CALC "Calc All;"
LOGIN "Localhost" "user1" "Password";
SELECT "SAMPLE" "BASIC";
In an ESSCMD script file, you should use the terminator, even though it is optional, if a command has many parameters. Doing so is especially important to signal the end of the parameter list if some parameters are optional.
Some commands require that you precede artifact or file names with a numeric parameter, from 1 to 4, that tells Essbase where to look for the artifact or file. The parameter directs ESSCMD to look for files in other applications, databases, or systems.
Table 253 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.
Table 253. List of Numeric Parameters
For example, the LOADDATA command can load a data file that resides on the client or Essbase 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:
Because ESSCMD supports multiple login instances on Essbase Server, you can access multiple databases in a single session. Even when you log on to multiple databases, you use only one port on your server license.
For backward compatibility, the Essbase Server searches for existing application and database names using the exact case first. However, if it cannot find the file, Essbase 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 displays an error message if application mYdATA exists and you try to create an application MyData.
Use the SETLOGIN command to toggle between active login instances. Use the LISTLOGINS command to view active login instances.
In interactive mode, you enter commands and respond to prompts, which 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 syntax conventions when working in interactive mode, see Understanding Syntax Guidelines.
To log on to Essbase Server:
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).
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:
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.
A script file contains ESSCMD commands. You can run a script file from the operating system command line or from within an operating system batch file, and the script file is processed by ESSCMD. By default, an ESSCMD script file has a .scr file extension. You can use a different extension.
A batch file is an operating system file that calls multiple ESSCMD scripts and can also include operating system commands. You can use a batch file to run multiple sessions of ESSCMD. You can run a batch file on Essbase Server from the operating system prompt; the file is processed by the operating system. On Windows, batch files have .bat file extensions.
Some commands may be changed in new releases of Essbase. Changes might affect existing scripts. To ensure that your scripts work correctly in the current release, see the Oracle Essbase New Features and the Essbase Readme for information about changed or deleted commands and change your scripts if needed.
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.
To define a script file:
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.
For example, enter the following if the script file is in the current directory:
ESSCMD C:\WORK\SCRIPTS\TEST.SCR (an absolute path on Windows)
ESSCMD..\SCRIPTS\TEST.SCR (a relative path on Windows)
ESSCMD 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; a state called nonzero status.
IFERROR checks the previously executed command for a nonzero return status (failure to execute). If the status is not zero, processing skips all subsequent commands and jumps to a user-specified point in the file, where it resumes. The script file can branch to an error-handling routine or the end of the file.
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:
LOGIN "localhost" "User1" "password" "Sample" "Basic"; LOADDATA 2 "calcdat"; IFERROR "Error"; CALC "Calc All;"; IFERROR "Error"; RUNREPT 2 "Myreport"; IFERROR "Error"; [possible other commands] EXIT; :Error
LOGIN "Poplar" "TomT" "Password"; SELECT "Sample" "Basic"; DISABLELOGIN; IMPORT 2 "ACTUALS" 4 "Y" 2 "ACTUAL" "N"; CALCDEFAULT; ENABLELOGIN; EXIT;
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;
LOGIN "Poplar" "TomT" "Password"; SELECT "Sample" "Basic"; RUNREPT 2 "REP1" "REP1.OUT"; RUNREPT 2 "REP2" "REP2.OUT"; RUNREPT 2 "REP3" "REP3.OUT"; EXIT;
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. See Handling Command Errors in Script Files.
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 continuing. 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 a Windows 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.
ESSCMD LOAD.SCR If not %errorlevel%==0 goto Error ESSCMD CALC.SCR If not %errorlevel%==0 goto Error ESSCMD REPORT.SCR If not %errorlevel%==0 goto Error Echo All operations completed successfully EXIT :Error Echo There was a problem running the script