ESSCMD Batch Processing

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.

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 Hyperion Essbase Release 6, check on your use of changed or deleted commands. See the Start Here booklet for information about new and changed commands.

Writing Script Files

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:

  1. Enter ESSCMD commands in any editor that saves data in ASCII text.
  2. Save the file with the .SCR ESSCMD script file extension.

For example, the following script file, TEST.SCR, was created in Notepad:


LOGIN "LOCAL" "TOMT" "PASSWORD";
SELECT "SAMPLE" "BASIC";
GETDBSTATE
EXIT;

When run from the operating system command line, this script logs TomT into the Hyperion Essbase Local server, selects the Sample application and Basic database, gets database statistics, and quits the ESSCMD session.

Running Script Files

Enter the following command at the operating system prompt: 

ESSCMD scriptFileName.SCR

Replace scriptFileName with the name of the script file. For example, type the following if the script file is in the current directory: 

ESSCMD TEST.SCR

If the script file is in another directory, include the path. For example:

ESSCMD C:\WORK\SCRIPTS\TEST.SCR (an absolute path on Windows NT)
or
ESSCMD ..\SCRIPTS\TEST.SCR (a relative path on Windows NT)

Handling Command Errors in a Script File

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 a command does not execute successfully, ESSCMD branches to the end of the file to avoid completing other operations.

 
LOGIN "local" "User1" "password" "Sample" "Basic";
LOADDATA 2 "calcdat";
IFERROR "Error";
CALC "Calc All;";
IFERROR "Error";
RUNREPT 2 "Myreport";
IFERROR "Error";
[possible other commands]
EXIT;
 
:Error
 
EXIT;

Note: You can use the OUTPUT command to log errors to a text file.

Sample Script Files

The following script files demonstrate common Hyperion Essbase batch operations. All samples are based on the Sample Basic database that comes with Hyperion Essbase. The scripts for these examples are available in your \ESSBASE\APP\SAMPLE\BASIC directory. On UNIX systems, the examples are available from /home/essbase/app/Sample/Basic.

Importing and Calculating a Data Sample File

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 NT, this script file, SAMPLE1.SCR, is available in your \ESSBASE\APP\SAMPLE\BASIC directory. On UNIX platforms, SAMPLE1.SCR is in your /essbase/app/Sample/Basic directory.

Updating a SQL Script, Importing, and Calculating a Data Sample File

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 NT, this script file, SAMPLE2.SCR, is available in your \ESSBASE\APP\SAMPLE\BASIC directory. On UNIX systems, SAMPLE2.SCR is in your /essbase/app/Sample/Basic directory.

Writing Batch Files

You can write a batch file that runs one or more report scripts, and includes operating system commands. See your operating system instructions to learn the syntax for writing batch files.

Handling Command Errors in Batch Files

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

 
ESSCMD LOAD.SCR
If not %errorlevel%==goto Error
ESSCMD CALC.SCR
If not %errorlevel%==goto Error
ESSCMD REPORT.SCR
If not %errorlevel%==goto Error
Echo All operations completed successfully
EXIT

:Error
Echo There was a problem running the script

Sample Script: Scheduling Report Printing

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 NT, this script file, SAMPLE3.SCR, is available in your \ESSBASE\APP\SAMPLE\BASIC directory. On UNIX platforms, SAMPLE3.SCR is in your /essbase/app/Sample/Basic directory.


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