Performing Interactive and Batch Operations Using ESSCMD

The Hyperion Essbase OLAP Server includes ESSCMD, a command-line interface that performs operations interactively or through a batch or script file.

This chapter describes how to use ESSCMD's interactive and batch processing modes, and provides sample script and batch files. It includes the following topics:

• ESSCMD Basics
• Quick Start to ESSCMD
• Using Interactive Mode
• Using Script and Batch Files for Batch Processing

For MaxL and ESSCMD syntax and usage information, see the online Technical Reference in the DOCS directory.

ESSCMD Basics

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.

Syntax Guidelines

In general, use the same syntax for entering ESSCMD commands as you do for other Hyperion Essbase 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

Quotation marks ("") enclose character parameters and responses to commands.

• In interactive ESSCMD, using quotes is optional. Be sure to use quotes when a parameter has an embedded space. For example:

  CALC "Calc All;"
  

• In an ESSCMD script file, always enclose all character parameters and responses to commands in quotation marks. For example:

  LOGIN "Localhost" "user1" "Password";
  

• Numeric parameters and responses do not require quotation marks.
• Do not enclose quotation marks within quotation marks.

Semicolon Statement Terminator

The ; (semicolon) statement terminator signals the end of a command. For example:

SELECT "SAMPLE" "BASIC"; 

• In interactive ESSCMD, pressing the Enter key signals ESSCMD that the command is complete. The statement terminator is optional.
• In an ESSCMD script file, you should use the terminator, even though it is optional, if a command has many parameters. This is especially important in order to signal the end of the parameter list if some of the parameters are optional.

  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 online Technical Reference in the DOCS directory, are examples of commands which you should terminate with a semicolon to prevent any confusion in processing.

Running ESSCMD on Different Operating System Platforms

ESSCMD operates independently of any other Hyperion Essbase client interface, including the Application Manager, Spreadsheet Add-in, or custom-built application programs.

ESSCMD is available on the following platforms:

• Windows NT server
• Windows 2000 server
• HP-UX server
• AIX server
• Solaris server
• Red Hat 6.1 server
• Windows 95 and Windows 98 server

Canceling ESSCMD Operations

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.

Referencing Files

Some commands require that you precede object or file names with a numeric parameter, from 1 to 4, that tells Hyperion 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 (numeric), 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.

For example, the LOADDATA command can load a data file that resides on the client or the Hyperion Essbase server. The command requires the numeric parameter to tell Hyperion 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:

• If you use file option 3 (File), you must enter the file extension in both interactive and batch processing modes.
• If the object is in the directory from which you started ESSCMD, you do not need to enter a path.

Multi-User Considerations

Because ESSCMD supports multiple login instances on a Hyperion Essbase 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.

Case-Sensitivity

Case-sensitivity varies by operating system:

• Windows platforms are not case-sensitive. You can enter ESSCMD commands and file-names in uppercase or lowercase letters, or in any combination of the two.
• UNIX is case-sensitive. You must enter file names in the correct case or UNIX does not recognize them. However, you can enter ESSCMD command names and parameters in uppercase or lowercase.

Getting Help

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.

Quick Start to ESSCMD

Before you start ESSCMD, make sure that the following items are properly installed and running:

• Hyperion Essbase server
• Communications protocol (Named Pipes or TCP/IP) on the Hyperion Essbase server

For information on protocols supported by Hyperion Essbase, see the Hyperion Essbase Installation Guide.

Starting and Quitting ESSCMD

The Hyperion Essbase server 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).

To start ESSCMD:

Do one of the following:

• Enter ESSCMD at the operating system command prompt. ESSCMD runs within the operating system command line window.
• Run ESSCMD.EXE (ESSCMD on UNIX platforms), located in the BIN directory

To quit ESSCMD:

Enter EXIT at the prompt and press Enter.

ESSCMD disconnects from the application server, and terminates the session.

Using Interactive Mode

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.

Logging Into the Server

After starting ESSCMD, you must connect to the Hyperion Essbase server so that you can enter commands. Follow these steps:

1. At the ESSCMD prompt, log in to the server with the LOGIN command. For more information about this command, see the online Technical Reference, located in the ESSBASE/DOCS directory.
2. Enter the Hyperion Essbase server name. When you connect from the server console, the server name depends on your network setup. For example, the name could be aspen.
3. Enter your user name.
4. Enter your password.

   The ESSCMD prompt is displayed as follows:

   aspen:::userName[1]->
   

   where userName is your login name.

   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 Hyperion 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 ESSBASE/DOCS directory.

   The ESSCMD prompt is displayed as follows:

   aspen:appName:dbName:userName[1]->
   

   where:

   • appName is the name of the application.
   • dbName is the name of the database to which you are connected.

Entering Commands

There are two ways to enter commands in interactive mode. Choose either of the following methods to enter commands:

• Type the command and press Enter.

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

• Type the commands and all parameters, then press Enter.

  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.

Canceling Operations

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 Hyperion Essbase is processing a command. Pausing the system may prevent Hyperion Essbase from correctly completing the command.

Using Script and Batch Files for 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.

For syntax conventions when working in batch processing mode, see Syntax Guidelines.

• 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 the Hyperion Essbase server from the operating system prompt; the file is processed by the operating system. On Windows NT, batch files have *.BAT file extensions.

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 6, check on your use of changed or deleted commands. See the Hyperion Essbase 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.

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 "localhost" "User1" "password"; SELECT "Sample" "Basic"; GETDBSTATE EXIT;

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

Running Script Files

To Run Script Files in ESSCMD

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:

• IFERROR checks the previously executed command for a non-zero 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.
• RESETSTATUS reverts all saved status values to 0 (zero) in preparation for more status checking.
• GOTO forces unconditional branching to a user-specified point in the file, whether or not an error occurred.

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 EXIT;

For the syntax and usage of ESSCMD error commands, see the online Technical Reference, located in the ESSBASE/DOCS directory.

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 your Hyperion Essbase program. The scripts for these examples are available in your \ESSBASE\APP\SAMPLE\BASIC directory. On UNIX systems, the examples are available from /home/hyperion/essbase/app/Sample/Basic.

Sample Script: Importing and Calculating Data

Suppose you need a file that executes the following actions:

• Logs in to the Hyperion Essbase server.
• Selects an application and database.
• Prevents other users from logging on and making changes to the database.
• Imports data from a text file.
• Calculates the database.
• Exits ESSCMD.

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.

Sample Script: Building Dimensions and Importing/Calculating Data from a SQL Source

Suppose you need a script file that executes the following actions:

• Logs in to the Hyperion Essbase server.
• Selects an application and database.
• Prevents other users from logging on and making changes to the database.
• Updates the outline from an SQL data source.
• Imports data from SQL.
• Calculates the database.
• Exits ESSCMD.

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.

Sample Script: Scheduling Report Printing

Suppose you need a file that executes the following actions:

• Logs in to the Hyperion Essbase server.
• Selects an application and database.
• Assigns reports that output to files for later printing.
• Exits ESSCMD.

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.

Writing Batch Files

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.

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

Copyright © 1991-2000 Hyperion Solutions Corporation. All rights reserved.