Running Essbase Servers, Applications, and Databases

This chapter describes the various methods used to run the Essbase OLAP Server and its associated applications and databases. It defines the role of the Agent, which is the central organizing subsystem for the server, and describes different methods of starting and stopping the server, applications, and databases.

This chapter includes the following sections:

Essbase Executable Files

Seven main executable files contain the server and client software for Essbase:

Table 48: Main Essbase Executable Files

Executable File
Description
essbase.exe 

Essbase Agent process. For more information, see Understanding the Agent.

esssvr.exe 

Essbase application server process. For more information, see Starting and Stopping Applications.

essadmin.exe 

Essbase Application Manager client application. For more information, see the Essbase Application Manager Online Help.

essmsh.exe 

Essbase MaxL Shell. For more information, see the Technical Reference in the docs directory.

esscmd.exe 

Essbase ESSCMD command-line client interface. For more information, see Automating the Production Environment.

adminsvr.exe 

Essbase Administration Services executable. For more information, see the Essbase Administration Services Online Help.

admincon.exe 

Essbase Administration Services Console application. For more information, see the Essbase Administration Services Online Help.



The first five files are stored in the \essbase\bin directory (/essbase/bin on UNIX). The last two files are stored in the ARBORPATH\eas\bin directory (ARBORPATH/eas/bin on UNIX). On UNIX systems, these files do not have the .exe extension.

You can launch any of the executable files by typing its name at the operating-system command prompt. On Windows, you can also launch a program by double-clicking the file in Explorer, or entering its name in the dialog box that comes up when you select Run from the Start menu.

Understanding the Agent

The Essbase Agent is the process that starts and stops all applications and acts as the traffic coordinator for the OLAP Server. Use this section to understand more about the Agent:

The agent log is called the OLAP Server log. For information on viewing the OLAP Server log, see Viewing the Server and Application Logs.

When you start the Essbase server in the foreground, the Agent becomes active in an operating-system window. You should see information like this appearing in the window:

Figure 511: Sample Agent Output to Operating System Window

Unlimited login system
Hyperion Essbase OLAP Server - X.X
Copyright 1991-2000 Hyperion Solutions Corporation.
US Patent Number 5,359,724
All Rights Reserved.
Serial number:  XXXXXXXXXXXX-XXXXXXXXXXX
Registered to:  admin
                hyperion
Please type the system password: ********
Startup sequence completed
Security is enabled
Logins are enabled
Essbase Default Storage type is Multidimensional
[Wed Dec 06 14:00:20 2000]Local/ESSBASE0///Info(1051051)
Hyperion Essbase OLAP Server - started
Waiting for Client Requests... 

In the Agent, you can enter administrative commands and monitor the behavior of Essbase. The Agent is accessible only from the server console on the server computer. The server console is the primary terminal, or monitor, connected to the server computer. The server computer is the computer on which Essbase runs.

The Agent executable file is essbase.exe (ESSBASE on UNIX systems), which is stored in the \ARBORPATH\bin directory. Launching this executable file starts Essbase. You can start Essbase in the foreground or as a background process. If you start Essbase in the background, the terminal becomes free for other input, and the Agent activities are not visible in the terminal. For more information, see Starting Essbase as a Background Process.

Flow of Communications Events

When a user logs in to Essbase, these events occur:

  1. The Essbase client logs in, using a predefined address:
  2. The user selects an application/database combination.
  3. The Agent compares the requested application with applications currently running. If the specified application is already running, the Agent does not need to do anything. If the requested application is not already running, the Agent initiates startup, and the following events occur:
    1. The Agent assigns a dynamic port for the application server or creates a dynamic name for a named pipe.
    2. The application server returns the port number for the application to the Agent and to the client. Port number information is stored at run time in Essbase API.

  4. The Agent sets the application server as active with the current user and security information. When the client later sends a data request to the application server, the security information captured by the API is embedded in the request.
  5. The Agent sends the client query to the application server (ESSSVR).
  6. For every request that the client makes, the application server causes the following events to occur:
    1. Connect
    2. Send request
    3. Get response
    4. Send data
    5. Receive data
    6. Disconnect

Multithreading

essbase.exe and esssvr.exe (ESSBASE and ESSSVR on UNIX) are multithreaded applications. By default, the number of threads is based on the number of licensed ports that are purchased, as shown in Table 49. The number of ports represents the number of concurrent connections that Essbase supports. Essbase provides one reserve port for the system administrator. The system administrator uses the reserve port to log out one or more users when all other ports are in use.

Table 49: Licensed Ports and Multithreading

Number of Licensed Ports
Default Number of Threads

1-5 ports

5

6-10 ports

10

11 or more ports

20



You can set the number of threads for the Agent or the server in the essbase.cfg configuration file. For complete details on setting the number of threads for the Agent and the server, refer to the AGENTTHREADS and AGTSVRCONNECTIONS settings for the Agent, and SERVERTHREADS settings in the Technical Reference in the docs directory.

Displaying a List of Agent Commands

To display a list of all available Agent commands, press Enter in the operating system window where you started Essbase in the foreground (Figure 511).

Use this table to understand the function of each command displayed, and their MaxL or ESSCMD equivalents:

Table 50: Agent Commands and Equivalent MaxL and
ESSCMD Commands  

Agent Command
Function
Corresponding MaxL or ESSCMD

START appname

Starts the specified application.

MaxL: alter system load application appname;

ESSCMD: LOADAPP

STOP appname

Stops the specified application.

MaxL: alter system unload application appname;

ESSCMD:UNLOADAPP

USERS

Displays a list of all users that are connected to the server. The following information is displayed:

  • The names of all users connected to the server
  • The total number of ports installed
  • The total number of existing connections
  • The application to which each user is connected
  • The database to which each user is connected

MaxL: display user;

(lists all users and shows which users are logged in)

ESSCMD: LISTUSERS (lists all users)

PORTS

Displays the number of ports that are installed on the server and the number of ports that are in use.

MaxL: display system;

(to display available unused ports)

LOGOUTUSER user

Disconnects a user from the server and frees a port.

This command requires the Essbase system password.

MaxL: alter system logout session by user username;

ESSCMD: LOGOUTUSER

PASSWORD

Changes the system password that is required to start the OLAP Server.

This command requires the Essbase system password.

MaxL: alter user system supervisor set password password;

ESSCMD: SETPASSWORD

DUMP filename

Dumps information from the Essbase security system to a specified file in ASCII format. If you do not supply a path with the file name, the file is saved to the BIN directory, for example, \essbase\bin (/essbase/bin on UNIX). This command requires the Essbase system password.

N/A

VERSION

Displays the server software version number.

MaxL: display system;

ESSCMD: GETVERSION

HELP

Lists all valid Agent commands and their respective functions. Same as pressing Enter.

N/A

QUIT and EXIT

Shuts down all open applications and quits Essbase.

MaxL: alter system shutdown;

ESSCMD: SHUTDOWN-SERVER



Starting and Stopping

Use these sections for instructions about starting and stopping Essbase, applications, and databases:

Starting Essbase

You can start Essbase from the server console. In order to start Essbase, you must have the role of supervisor.

To start Essbase in the foreground, enter this command at the operating system command line on the computer where OLAP Server is installed:

ESSBASE password 

password is the password to access the OLAP Server.

On Windows, you can also start Essbase in any of these ways:

This action starts the Agent in the operating-system command console. In the Agent, you can enter commands or monitor Essbase activities (see Understanding the Agent).

You cannot start Essbase from ESSCMD or MaxL.

Changing the System Password

Using an Agent command, you can change the password that is required to start the OLAP Server.

Note: Changing the system password does not change the connection password that is established for the Essbase system supervisor.

To change the Essbase system password:

  1. Type password at the command prompt of the Agent window.
  2. Essbase prompts you to enter the old system password, as shown in Figure 512.

    Figure 512: Changing the Essbase System Password

  3. Type the old (current) system password.
  4. Type the new system password.
  5. Retype the new system password.

Essbase verifies that the system password has been updated.

For information about changing passwords for users or groups, see Managing Security for Users and Applications.

Stopping Essbase

You can stop Essbase from the server console, or from a MaxL or ESSCMD session running either on the server or on a client connected to the server. In order to stop Essbase, you must have the role of supervisor.

To stop (also "shut down") Essbase and all running applications, do one of the following:

Starting Essbase as a Background Process

Essbase can run as a background process on the server computer.

System administrators might choose to run Essbase as a background process when working in batch mode. Running in batch mode means, for example, that the administrator could start Essbase, launch MaxL or ESSCMD, log in to Essbase, load data, run calculation scripts or reports, stop Essbase, and perform a backup, all from a single UNIX shell script or a Windows NT .bat file.

System administrators running Essbase on Windows NT or Windows 2000 might also choose to run Essbase as a background process in order to use Windows settings to give a performance boost to applications running in the foreground.

If you start Essbase in the background, these conditions apply:

To start Essbase in the background on UNIX, or on Windows systems utilizing a UNIX-like shell such as MKS, enter the following command at the command prompt of your operating system:

essbase password -b & 

You can start Essbase without using the ampersand (&) at the end of the command, but if you do not use "&," the command prompt is not returned after the server is started.

Note: The ampersand (&) used in the above context has no effect when used on Windows, unless you are using a UNIX-like shell such as MKS. Essbase starts in the background, but control of the command prompt is not returned. You may need to press the Enter key twice in Windows before the command prompt returns.

On UNIX systems, to find out if Essbase is already running in the background, type this command at the command prompt of your operating system:

ps -ef | grep ESS 

If the server is running in the background, it appears in the process list:

essbase password -b & 

For information about hiding the password from the UNIX process list, see the Essbase Installation Guide.

For information about how to run Essbase as a Windows NT Service, or to see if Essbase is already installed as a Windows NT Service, see the Essbase Installation Guide.

Starting Essbase with Parallel Login Processing

To speed up parallel login processing with the command-line parameter quicklogin, start Essbase using this command:

essbase password -quicklogin 

The parameter quicklogin improves performance by caching the security file and writing it to disk at specified time intervals. This parameter is currently unavailable for AIX.

Note: You can use a configuration setting to ensure Essbase always starts with parallel login processing by adding QUICKLOGIN to your server configuration file essbase.cfg. For details, see Technical Reference in the docs directory of your Essbase installation.

Starting and Stopping Applications

When an application is started, Essbase loads the application and all associated databases into memory on the server. All client requests for data, such as data loads, calculations, reports, and spreadsheet lock and sends, are then handled through the application server, the ESSSVR process. The application server is always started by the Agent.

Multiple applications (ESSSVR processes), can run on Essbase concurrently. On Windows, a separate window opens for each ESSSVR process that is running. If an application contains multiple running databases, all databases are managed by the one application server.

When you stop an application, Essbase unloads all information and databases from memory on the server and closes the application server process.

Starting an Application

When you start an application, the following actions can happen:

To start an application from the Agent, enter the following command at the command prompt in the Agent:

START appname 

This action starts the application and, if you are running on Windows, opens the application server window.

To start an application using Application Manager:

  1. Connect to the server on which the application resides.
  2. Select the application from the Application Desktop window.
  3. Select Application > Start/Stop.
  4. If the application is not already loaded, a confirmation box is displayed.Click Yes to load the application.
  5. If the application is already loaded, the confirmation box asks if you want to stop the application. Click No to prevent Essbase from stopping the application.

You can also start an application by completing any of these actions:

See the Technical Reference in the docs directory for information about MaxL and ESSCMD.

See Essbase Administration Services Online Help for information about Essbase Administration Services.

You can control how applications are started:

When application startup (Allow Application to Start) is enabled, if an application is stopped and a user attempts to retrieve data from any databases within that application, the application starts on the server automatically.

When application autostartup (Start When Essbase Starts) is enabled, users may experience better initial performance when they make requests of databases in that application, because the application and databases are already loaded into memory on the server computer.

Stopping an Application

When you stop an application, transactions may be currently running. If you issue the STOP command in the Agent window, the alter system unload application statement in MaxL, or an UNLOADAPP command in ESSCMD, the application does not stop if a calculation or data load is in progress. Instead, Essbase displays a message in the Agent console.

If you stop the Agent by closing the Agent window or by pressing Ctrl + C, the application stops, and the next time you start the application, Essbase rolls back any transactions that were in progress.

See Rollback with Committed Access or Rollback with Uncommitted Access for more information about roll backs (undoing all transactions after the last committed transaction).

It is important to stop an application properly by using the Essbase Agent, MaxL, ESSCMD, Essbase Administration Services, or Essbase Application Manager. If the application server is not brought down properly, databases within the application may become corrupt.

Do not use the following methods to stop an application:

To stop an application from the Agent, enter the following command at the command prompt in the Agent:

stop appname  

This action stops the application and, if you are running on Windows, closes the application server window.

To stop an application using Application Manager:

  1. Connect to the server on which the application resides.
  2. Select the application from the Application Desktop window.
  3. Select Application > Start/Stop.
  4. A confirmation dialog box is displayed:

    Figure 513: Stop Application Dialog Box

  5. Click OK to stop the application. Essbase unloads the application from memory.

Tip: You can stop an application using methods other than Application Manager:

Tool
Instructions
For more information

Administration Services

Enterprise View > select and right-click application > select Stop.

Essbase Administration Services Online Help

MaxL

alter system unload application

Technical Reference in the docs directory

ESSCMD

UNLOADAPP



Stopping an Application Improperly

There are times when stopping the application server process improperly is necessary; for example, if the application server is corrupted and not processing client requests. In this case, stopping the application server by shutting down its corresponding window is the only method of the stopping the application.

The Windows NT Task Manager does not display process IDs for individual Essbase applications: all of the running Essbase applications are displayed as undifferentiated ESSSVR processes. This prevents you from stopping a single application, in the event that the application freezes.

You can find the process ID for individual servers in the essbase.log file in your ESSBASE directory. When the server starts, a line like the following is displayed in the OLAP Server log:

Application [Sample] started with process id [225] 

If an application freezes, you can stop the application by using the process ID number in conjunction with a kill operating-system utility. Such a utility is provided with Windows NT Resource Kit and with various other toolkits.

On UNIX platforms, you can use the ps output to identify individual applications. If an application freezes, you can stop the application by using this command:

kill -9 <pid>

Starting and Stopping Databases

Starting a database loads the database into memory on the OLAP Server computer. Stopping a database unloads all database information from memory on the server computer.

Starting a Database

When Essbase starts a database and loads it to memory, the entire index cache for that database is allocated in memory automatically. The data cache and data file cache are allocated as blocks are requested from Essbase clients.

When you start an application, Essbase loads the application and its databases into memory on the server computer. When you start a database from an application that is not loaded, the application is loaded along with all its related databases.

To start a database from the Agent, enter the following command at the command prompt in the Agent window:

start appname  

This action starts the application that contains the database you want to start and opens the application server window.

To start a database using Application Manager:

  1. Connect to the server on which the database resides.
  2. From the Application Desktop window, select the application and then the database.
  3. Select Database > Start/Stop.
  4. If the database is not already loaded, a confirmation box is displayed. Click Yes to load the database.

    If the database is already loaded, the confirmation box asks if you want to stop the database. Click No to prevent Essbase from stopping the database.

You can also start a database by completing any of the following actions in Application Manager:

Tip: You can also start a database outside of the Application Manager using any of the following methods.

Tool
Instructions
For more information

Administration Services

Enterprise View > select the name of the database > right-click > click Start.

Essbase Administration Services Online Help

MaxL

alter application load database

Technical Reference in the docs directory

ESSCMD

LOADDB or SELECT



To configure a database to start automatically when its parent application starts,

  1. In Application Manager, open the Database Settings dialog box.
  2. Enable the Start when Application Starts option.

Tip: You can also configure a database to start automatically when its parent application starts by using one of the following:

Tool
Instructions
For more information

Administration Services

Database Properties window > General tab > Start database when application starts

Essbase Administration Services Online Help

MaxL

alter database enable autostartup

Technical Reference in the docs directory



Stopping a Database

Stopping a database unloads all data from memory and commits any updated data to disk.

If a database is stopped and a user attempts to retrieve data from it, the database starts in the server automatically, without any explicit commands issued.

When you stop a database, transactions may be currently running. If you issue the STOP command in the Agent window, an UNLOADDB command in ESSCMD, or alter application unload database in MaxL, the database does not stop if a calculation or data load is in progress. Instead, Essbase displays a message in the Agent window. If you stop the Agent by closing the Agent window or by pressing Ctrl + C, the database stops, and the next time you start the database, Essbase rolls back any transactions that were in progress.

See Rollback with Committed Access or Rollback with Uncommitted Access for more information about roll backs (undoing all transactions after the last committed transaction).

To stop a database from the Agent, enter the following command at the command prompt in the Agent window:

stop appname 

This action stops the application that contains the database you want to stop and closes the application server window.

To stop a database using Application Manager:

  1. Connect to the server on which the database resides.
  2. From the Application Desktop window, select the application and then the database.
  3. Select Database > Start/Stop. This confirmation is displayed:
  4. Figure 514: Stop Database Dialog Box

  5. Click Yes to stop the database. Essbase unloads the database from memory.

You can also stop a database by completing any of the following actions:

Tool
Instructions
For more information

Application Manager

Application Start/Stop command (stops the application that contains the database that you want to stop)

See Stopping an Application.

Essbase Application Manager Online Help

Administration Services

Right-click the name of the database > select Stop

Essbase Administration Services Online Help

MaxL

alter application unload database

 

Technical Reference in the docs directory

ESSCMD

UNLOADDB



Viewing a List of Users and Available Ports

The Agent enables you to view a list of all users that are connected to the server at any given time. Additionally, you can view the total number of ports available, as well as the number of existing connections.

To view a list of all users connected to the server, type the command USERS at the command prompt of the server console. The server console displays the following information:

To view the number of ports installed on the server, as well as the number of ports in use, type PORTS at the command prompt of the server console.

Tip: You can also use display user in MaxL or the LISTUSERS command in ESSCMD to view a list of users on the system. These do not return information about the available ports and connections or the application or database to which users are connected. For more information, see the Technical Reference in the docs directory.

You can also use Essbase Administration Services and select the Statistics tab from the OLAP Server Properties window to display the number of ports in use on the server and the number of ports available for use on the server. For more information, see Essbase Administration Services Online Help.

Controlling Query Size and Duration

Users may unintentionally request information that is so large or so complex to retrieve that the query will slow performance or fail to complete properly. To prevent this, you may use two configuration settings to control query size or duration:

These two configuration settings are also referred to as query governors.

You can apply these settings to all the applications and databases on an OLAP Server, to all the databases on a single application, or to a single database.

For details about how to use these configuration settings, see the Technical Reference in the docs directory, in the "essbase.cfg Settings" topic.

Specifying Non-Default Port Values

If you wish to change the default port values used by the Agent, you must set one or more of these configuration settings:

You may wish to change the default for many reasons. Here are two examples:

Changing Port Default Values

If you simply need to change one or more of the default values associated with Agent and server ports, review the Technical Reference in the docs directory for instructions about the correct configuration setting to change:

Installing Additional Agents: Windows

To install and configure an additional Agent on a single Windows computer:

  1. On a computer where you have already installed Essbase according to the instructions in the Essbase Installation Guide, install the server portion in a different directory from the first Essbase installation. You need not install any of the clients, such as MaxL or Administration Services.
  2. In the /bin directory of the new installation, create or modify the server configuration file essbase.cfg so that it contains these settings:
  3. AGENTPORT: The port that this second Agent will use to connect.

    SERVERPORTBEGIN: The first port that the first server process will try to use to connect.

    SERVERPORTEND: The highest value for a port number that a server process can use to connect.

    PORTINC: The increment between ports. For example, if PORTINC is assigned a value of 5, Essbase will look for ports 32700, 32705, and so on up to the value of SERVERPORTEND.

    Use the instructions in the Technical Reference in the docs directory to select values for these settings.

  4. Repeat Step 2f for the client configuration file essbase.cfg. The client configuration file is located at /ARBORPATH/bin.
  5. Create a batch script (.bat) that performs these tasks:
  6. Use a client to connect to the new installation.

Note: This is a separate installation of Essbase. It shares none of the security or objects of any other Essbase installation on the same computer.

Installing Additional Agents: UNIX

To install and configure a second agent on a single UNIX computer:

  1. On the computer where you plan to use two Agents, create a new operating system login ID to run the new Agent. For instructions, refer to your operating system documentation.
  2. On a computer where you have already installed Essbase according to the instructions in the Essbase Installation Guide, install the server portion in a different directory from the first Essbase installation. You need not install any of the clients, such as MaxL or Administration Services.
  3. Assign the correct privileges so the new login ID can be used run the Agent. For instructions, see the Essbase Installation Guide.
  4. Create the necessary path and library statements in the profile for the new login ID. You may want to copy an existing login ID profile for a login ID that runs the existing Essbase installation, and change the values for the new installation.
  5. Perform Step 2f from Installing Additional Agents: Windows.
  6. Repeat previous step for the client configuration file essbase.cfg.
  7. Start the new Essbase Agent using the new login ID.

Increasing Agent Connections to Server

You can use the configuration settings AGENTTHREADS and AGTSVRCONNECTIONS to control the maximum number of threads that the Agent creates to perform initial connection to the OLAP Server.

Increasing the maximum number of possible threads between the server and agent allows more than one user to log in and connect to an application and database at a time.

Note: All requests for information after initial connection and before disconnection are handled by a different set of server threads, whose maximum number is controlled by the SERVERTHREADS configuration parameter.

To increase the maximum possible number of agent threads:

  1. Create or edit the server configuration file essbase.cfg to include these settings:
  2. Save the configuration file essbase.cfg.
  3. Stop and restart the server to initialize your changes.

For more information, see the Technical Reference in the docs directory.

Limiting the Number of User Sessions

You can limit the maximum number of user sessions allowed to connect to the OLAP Server at any one time, using the configuration parameter MAXLOGIN. This number includes multiple instances of the same user.

For example, the same user with five open Excel worksheets connected to the same OLAP Server use one port, but five sessions.

You may wish to adjust the value of MAXLOGIN to match computer resources, or to more closely manage concurrent ports and user sessions. A concurrent port is used for each unique combination of client machine, OLAP Server and login name.

To limit the number of simultaneous user sessions using the configuration setting MAXLOGIN, create or edit the server configuration file essbase.cfg to contain this setting:

MAXLOGIN maximum_number_of_user_sessions 

The maximum_number_of_user_sessions minimum is 1, maximum is 1048575, and the default value is 1000.

User sessions use the threads whose maximum is controlled by the configuration setting SERVERTHREADS, and are not related to the threads whose maximum is controlled by AGENTTHREADS and AGTSVRCONNECTIONS.

For more information, see the Technical Reference in the docs directory.




© 2002 Hyperion Solutions Corporation. All rights reserved.
http://www.hyperion.com