Running Essbase Servers, Applications, and Databases

In This Section:

Essbase Executable Files

Understanding the Agent

Starting and Stopping Essbase Server

Starting and Stopping Applications

Starting and Stopping Databases

Managing Ports

Communicating with Essbase Using SSL

Controlling Query Size and Duration

Increasing Agent Connections to Essbase Server

Limiting the Number of User Sessions

Essbase Executable Files

Table 131 lists the Essbase server and client executable files:

Table 131. Main Essbase Executable Files

Executable File[1]

Description

Location

See

essbase.exe

Essbase Server Agent process

ESSBASEPATH/bin

Understanding the Agent

esssvr.exe

Application process

ESSBASEPATH/bin

Starting and Stopping Applications

essmsh.exe

MaxL Shell

ESSBASEPATH/bin

Oracle Essbase Technical Reference

esscmd.exe

ESSCMD command-line client interface

ESSBASEPATH/bin

Oracle Essbase Technical Reference

adminsvr.exe or startEAS.exe

Essbase Administration Server executable

EPM_ORACLE_HOME/products/Essbase/eas/server/bin

Oracle Essbase Administration Services Online Help

admincon.bat

Administration Services Console application

EPM_ORACLE_HOME/products/Essbase/eas/server/bin

Oracle Essbase Administration Services Online Help

1 On UNIX, executable files do not have an .exe extension.

Understanding the Agent

The Essbase Agent manages Essbase Server. The Agent process starts and stops all applications and acts as the traffic coordinator for Essbase Server. OPMN manages the Essbase Agent.

Essbase Server start and stop scripts redirect to OPMN. By default, OPMN starts Essbase as a background service.

During installation, Oracle Hyperion Enterprise Performance Management System Installer installs OPMN and registers Essbase Server for OPMN. See Managing Essbase Using OPMN.

The agent log is called the Essbase Server log. See Viewing the Essbase Server and Application Logs.

Multithreading

essbase.exe and esssvr.exe (ESSBASE and ESSSVR on UNIX) are multithreading and symmetric multiprocessing (SMP) applications. Multithreading ensures high performance in a client-server environment. SMP provides scalability when a single server computer hosts multiple Essbase applications. Essbase Server uses POSIX kernel threads, which are included in UNIX operating systems.

By default, the number of threads is based on the number of ports, as shown in Table 132. The number of ports represents the number of concurrent connections that Essbase supports. Essbase provides one reserve port for the system administrator, which is used to log off users when all other ports are in use.

Table 132. Ports and Multithreading

Number of Ports

Default Number of Threads

1–5 ports

5

6–10 ports

10

11+ ports

20

You can set the number of threads for the Agent or Essbase Server in the essbase.cfg file using the AGENTTHREADS, AGTSVRCONNECTIONS, and SERVERTHREADS configuration settings. See the Oracle Essbase Technical Reference.

Note:

Enabling hyperthreading on the computer on which Essbase Server runs is not recommended.

List of Agent Commands and Equivalents

Agent commands can be entered in the OPMN command line interface. Table 133 describes each Agent command, and the MaxL, ESSCMD, or Administration Services equivalents:

Table 133. Agent Commands and MaxL, ESSCMD, or Administration Services Equivalents

Agent Command

Function

MaxL, ESSCMD, or Administration Services Equivalent

START appname

Starts the specified application.

  • MaxL: alter system load application appname;

  • ESSCMD: LOADAPP

  • Administration Services: Start, then Application on the application node in Enterprise View

STOP appname

Stops the specified application.

  • MaxL: alter system unload application appname;

  • ESSCMD: UNLOADAPP

  • Administration Services: Stop, then Application on application node in Enterprise View

USERS

Displays a list of users connected to the Essbase Server. The following information is displayed:

  • Names of users connected to the Essbase Server

  • Number of ports installed

  • Number of connections

  • Application to which each user is connected

  • Database to which each user is connected

  • MaxL: display user;

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

  • ESSCMD: LISTUSERS

    (lists all users)

  • Administration Services: Edit, then Sessions on the server node in Enterprise View

PORTS

Displays the number of ports installed on the Essbase Server and the number of ports in use.

  • MaxL: display system;

    (to display available unused ports)

  • ESSCMD: N/A

  • Administration Services: Edit, then Properties (Essbase Server Properties window, Statistics tab) on the server node in Enterprise View

LOGOUTUSER user

Disconnects a user from the Essbase Server and frees a port.

This command requires the Essbase system password.

  • MaxL: alter system logout session by user username;

  • ESSCMD: LOGOUTUSER

  • Administration Services: Edit, then Sessions on the server node in Enterprise View

PASSWORD

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

This command requires the Essbase system password.

  • MaxL: alter user system_administrator set password password;

  • ESSCMD: SETPASSWORD

  • Administration Services: N/A

COMPACT

Enables compaction of the security file when the Agent is running. See Managing Essbase Security File Fragmentation.

Note:

Essbase compacts the security file automatically each time the Agent is stopped.

  • MaxL: alter system compact security file;

  • ESSCMD: N/A

  • Administration Services: Compact security file on the server's security node in Enterprise View

DUMP filename

Dumps information from the Essbase security file (essbase.sec) to a specified file in text (ASCII) format. If you do not supply a path with the filename, the file is saved to the ARBORPATH/bin directory.

This command requires the Essbase system password.

Note:

You cannot use the DUMP command against an Essbase Server that is run as a service. If the server is running as a service, use the Export Security File command in Administration Services or the export security_file MaxL statement.

  • MaxL: export security_file;

  • ESSCMD: N/A

  • Administration Services: Export Security File on the server's security node in Enterprise View

See Exporting the Essbase Security File to a Readable Format.

Note:

You can use the export security file command against an Essbase Server that is run as a service.

VERSION

Displays the Essbase Server software version number.

  • MaxL: display system;

  • ESSCMD: GETVERSION

  • Administration Services: Edit, then Properties (Essbase Server Properties window, License tab) on the server node in Enterprise View

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 stops Essbase Server.

  • MaxL: alter system shutdown;

  • ESSCMD: SHUTDOWNSERVER

  • Administration Services: Stop on the server node in Enterprise View

To start Essbase Server, you must have Administrator permissions.

Note:

You cannot start Essbase Server from ESSCMD or MaxL.

Starting Essbase on Ports Qualified by Host Names

You can specify the host name to which Essbase binds by using the ESSBASESERVERHOSTNAME configuration setting in essbase.cfg. If no host name is specified, Essbase uses a system API to get the host name. Using host names enables you to partition network traffic on all the network interfaces of a computer. This is useful on computers with single network cards and those with multiple NIC cards.

Hiding Essbase Server Passwords on HP-UX and Solaris

On HP-UX and Solaris, the ps -ef utility creates a process listing that includes the system password.

Note:

On IBM AIX, the Essbase Server system password is hidden automatically.

  To hide the Essbase Server system password:

  1. Create a shell script, named essbase.secure, that contains these commands:

    #!/bin/sh
    PASS=$1
    ESSBASE -b -secure << EOF &
    ${PASS} 
    EOF
  2. To launch the Agent, use this command:

    essbase.secure password
    • To have the script to return to a command prompt without manually entering a carriage return or to imbed the script within a larger script, execute the script with this command:

      essbase.secure &
    • (Optional) To redirect the standard output to a file named nohup.out, which is useful when running the script in a nonactive terminal session, use this command:

      nohup essbase.secure &

Changing the Essbase Server System Password

You can change the password that is required to start Essbase Server.

Note:

Changing the system password does not change the connection password for the Essbase system Administrator.

  To change the Essbase Server system password, use a tool:

Tool

Topic

Location

Agent

password

Enter the Agent command in the OPMN command line interface.

Enter the current system password.

Enter the new system password; then re-enter it.

MaxL

alter user system_administrator set password password

Oracle Essbase Technical Reference

ESSCMD

SETPASSWORD

Oracle Essbase Technical Reference

Essbase verifies that the system password has been updated.

Stopping Essbase Server

You need Administrator permissions to stop or shut down Essbase Server.

  To stop Essbase Server and all running applications, use a tool:

Tool

Topic

Location

Agent

quit exit

Enter the Agent command in the OPMN command line interface.

MaxL

alter system shutdown

Oracle Essbase Technical Reference

ESSCMD

SHUTDOWNSERVER

Oracle Essbase Technical Reference

If you stop the Agent by closing the Agent window or by pressing Ctrl + C, 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.

Caution!

When running Essbase Server as a Windows service, do not stop the service from Windows Control Panel. Doing so is comparable to issuing a kill command on UNIX platforms and may cause data corruption.

Starting and Stopping Applications

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

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

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

Starting an Application

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

  • Users can connect to the application.

  • The application can respond to commands from the Agent.

  • Users can change the settings of the application.

  • Data and user security are enabled.

  • Each database in the application can start.

  To start an application, use a tool:

Tool

Topic

Location

Agent

START appname

Enter the Agent command in the OPMN command line interface.

Administration Services

Starting Applications

Oracle Essbase Administration Services Online Help

MaxL

alter system load application

Oracle Essbase Technical Reference

ESSCMD

LOADAPP or SELECT

Oracle Essbase Technical Reference

The application starts and, if you are running on Windows, opens the application server window on the Essbase Server computer.

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

  • Starting a database within an application. See Starting a Database.

  • Saving an outline to Essbase Server. (Opening an outline does not start an application.)

You can set options that control how applications start:

  • startup (Allow user to start application): If an application is stopped, and a user attempts to retrieve data from any databases within that application, the application starts on the Essbase Server computer automatically.

  • autostartup (Start application when Essbase starts): 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 Essbase Server computer.

  To control how applications are started, use a tool:

Tool

Topic

Location

Administration Services

Configuring Applications to Start Automatically

Oracle Essbase Administration Services Online Help

MaxL

alter application enable startup

alter application enable autostartup

Oracle Essbase Technical Reference

Stopping an Application

Stop applications properly to prevent the databases within them from becoming corrupt. When you stop an application, transactions may be running. If you stop an application using any of the proper methods (see the following table), the application 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 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.

  To properly stop applications, use a tool:

Tool

Topic

Location

Agent

stop appname

Enter the Agent command in the OPMN command line interface.

Administration Services

Stopping Applications

Oracle Essbase Administration Services Online Help

MaxL

alter system unload application

Oracle Essbase Technical Reference

ESSCMD

UNLOADAPP

Oracle Essbase Technical Reference

Stopping an Application Improperly

Sometimes, stopping the application server process improperly, by closing the application server window, is necessary; for example, if the application server is corrupted and is not processing client requests.

  To stop the application improperly, use a method for the operating system on which Essbase Server runs:

  • For UNIX platforms, kill the ESSSVR process.

    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>
  • For Windows, choose a method:

    • Perform a Windows operating system End Task.

      Windows does not display process IDs for individual Essbase applications—all of the running Essbase applications are displayed as undifferentiated ESSSVR processes, preventing you from stopping a single application in the event that the application freezes.

    • Click the Close button in the application server window.

    • Taskkill the process ID.

      You can find the process ID for individual application servers in the EPM_ORACLE_HOME/logs/essbase/essbase.log file. When the server starts, a line like the following is displayed in the Essbase Server log:

      Application [Sample] started with process id [225]

Starting and Stopping Databases

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

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 requested from Essbase clients.

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

  To start a database, use a tool:

Tool

Topic

Location

Agent

START appname

Enter the Agent command in the OPMN command line interface.

Administration Services

Starting Databases

Oracle Essbase Administration Services Online Help

MaxL

alter application load database

Oracle Essbase Technical Reference

ESSCMD

LOADDB or SELECT

Oracle Essbase Technical Reference

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

Tool

Topic

Location

Administration Services

Configuring Databases to Start Automatically

Oracle Essbase Administration Services Online Help

MaxL

alter database enable autostartup

Oracle Essbase Technical Reference

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 on Essbase Server automatically, without any explicit commands issued.

When you stop a database, transactions may be currently running. If you stop a database using any of the proper methods (see the following table), the database does not stop if a calculation or data load is in progress. Instead, Essbase displays a message in the Essbase Server window.

If you stop the Agent by closing the Essbase Server 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.

  To stop a database, use a tool:

Tool

Topic

Location

Agent

STOP appname

Enter the Agent command in the OPMN command line interface.

Administration Services

Stopping Databases

Oracle Essbase Administration Services Online Help

MaxL

alter application unload database

Oracle Essbase Technical Reference

ESSCMD

UNLOADDB

Oracle Essbase Technical Reference

The Agent enables you to manage ports on Essbase Server.

Viewing a List of Users and Available Ports

You can view a list of users that are connected to Essbase Server at any given time, the number of ports available, and the number of connections.

  To view a list of users connected to Essbase Server, use a tool:

Tool

Topic

Location

Agent

USERS

Enter the Agent command in the Oracle Process Manager and Notification Server command line interface.

Administration Services

Viewing Essbase Server Users and Groups

Oracle Essbase Administration Services Online Help

MaxL

display user

Oracle Essbase Technical Reference

ESSCMD

LISTUSERS

Oracle Essbase Technical Reference

  To view the number of ports installed on Essbase Server, as well as the number of ports in use, use a tool:

Tool

Topic

Location

Agent

PORTS

Enter the Agent command in the command line interface.

Administration Services

Checking Available Ports

Also see About Essbase Connections and Ports

Oracle Essbase Administration Services Online Help

MaxL

display user

Oracle Essbase Technical Reference

ESSCMD

LISTUSERS

Oracle Essbase Technical Reference

Specifying Nondefault Port Values

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

  • AGENTPORT specifies the port that the Agent uses.

  • SERVERPORTBEGIN specifies the first port number the Agent on a computer tries to use for its first server process.

  • SERVERPORTEND specifies the highest value the Agent tries to use for a port when it tries to start a server process. If the value is unavailable, the server process fails.

  • PORTINC specifies the value of the increment in between port numbers used by the Agent.

You may want to change the default value. Two possible reasons:

  • The default value specifies a port number already in use.

  • You may want to install a second instance of Essbase Server on a computer to facilitate testing. You can use Oracle Hyperion Enterprise Performance Management System Configurator to assign the second Essbase Server instance to a different port than the first. See the Oracle Enterprise Performance Management System Deployment Options Guide

Changing Port Default Values

If you need to change one or more of the default values associated with Agent and server ports, or to expand port ranges using MaxL, see the Oracle Essbase Technical Reference.

Viewing Port Statistics

You can enable Essbase to log, at a specified interval, the number of ports being used. By analyzing the information in the log, you can monitor port utilization and identify a need for more ports before users are unable to connect.

To enable Essbase Server to check port use statistics and write those statistics to the Essbase Server log, use the PORTUSAGELOGINTERVAL configuration setting:

PORTUSAGELOGINTERVAL n

where n represents the number of minutes between each check of the number of ports in use. The value of n can be any whole number from 1 to 60, with 5 being the recommended minimum and default value. Essbase ignores any portion of a nonwhole number. For example, Essbase evaluates 2.5 as 2 minutes. Statistics are written to the Essbase Server log immediately after each check. The log file will resemble the following output:

[Mon Apr 22 00:48:50 2003]Local/ESSBASE0///Info(1056214)
[3] ports in use, [10] ports allowed 

See the Oracle Essbase Technical Reference.

Managing Essbase Administration Server Communication Ports

Essbase Administration Server has several configurable communication ports, which are different from Essbase Server ports. See About Essbase Administration Server.

Communicating with Essbase Using SSL

Essbase supports the Secure Socket Layer (SSL) protocol for all client-to-server and server-to-server communication. SSL allows Essbase to communicate unilaterally across a network with Essbase clients, including Provider Services, Administration Services, and Essbase Studio, while preventing eavesdropping and tampering. End-point authentication and communications occur confidentiality over the Internet using CipherSuite cryptography.

These configuration settings supply parameters that enable SSL communication:

  • AGENTSECUREPORT

  • CLIENTPREFERREDMODE

  • ENABLECLEARMODE

  • ENABLESECUREMODE

  • NETSSLHANDSHAKETIMEOUT

  • SSLCIPHERSUITES

  • WALLETPATH

The following considerations apply when partitioning in secure (SSL) mode:

  • The partition source and target must have the same security protocol; for example, both or neither use SSL.

  • To enable Essbase to use SSL connectivity, you must set ENABLESECUREMODE to TRUE.

  • Consider setting CLIENTPREFERREDMODE to SECURE.

    If CLIENTPREFERREDMODE is not set, or is set to FALSE, but ENABLESECUREMODE is set to TRUE, you can securely create and refresh partitions in MaxL by adding :secure to the HOST-NAME string. For example,

    login esbuser esbpassword on “localhost:6423:secure”;

The following considerations apply when using location aliases in secure (SSL) mode:

  • To enable Essbase to use SSL connectivity, you must set ENABLESECUREMODE to TRUE.

  • If the location alias is being set up to a secure port, you must append :secure to the server name specification. For example, using MaxL,

    create location alias EasternDB from Sample.Basic to East.Sales at Easthost:6423:secure as User1 identified by password1;

To configure Essbase for encrypted (SSL) communication with Provider Services, you must perform a configuration task to enable the Essbase libcurl library to set up a secure channel to Provider Services. See Configuration for SSL Encrypted Communication with Provider Services.

For more information on using SSL with Essbase, see the Oracle Enterprise Performance Management System User Security Administration Guide.

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. Use the QRYGOVEXECTIME and QRYGOVEXECBLK configuration settings, referred to as query governors, to control query size or duration:

  • QRYGOVEXECTIME [appname [dbname]] n

    Limits the time Essbase Server allows a query to run before terminating the query.

  • QRYGOVEXECBLK [ appname [dbname]] n

    Limits the number of blocks a query can access before terminating the query.

You can apply these settings to all the applications and databases on Essbase Server, to all the databases on a single application, or to one database. See the Oracle Essbase Technical Reference.

Increasing Agent Connections to Essbase Server

Increasing the maximum possible threads between Essbase Server and the Agent allows multiple users to log on and connect to an application and database simultaneously.

Use the AGENTTHREADS and AGTSVRCONNECTIONS configuration settings to control the maximum number of threads created to perform the initial connection to Essbase Server:

  • AGENTTHREADS maximum_number_of_threads

  • AGTSVRCONNECTIONS maximum_number_of_threads

    Keep the maximum_number_of_threads value for AGTSVRCONNECTIONS equal to or less than the value for AGENTTHREADS to avoid wasting resources. Each connection requires one thread each from the server and Agent, so there is no need for higher values for AGTSVRCONNECTIONS. See the Oracle Essbase Technical Reference.

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.

Limiting the Number of User Sessions

Use the MAXLOGIN configuration setting to limit the maximum number of simultaneous user session connections to Essbase Server. This number includes multiple instances of the same user. For example, one user with five open Excel worksheets connected to the same Essbase Server uses one port but five sessions.

You can 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 computer, Essbase Server, and login name. See the Oracle Essbase Technical Reference.

Note:

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