Running Essbase Servers, Applications, and Databases

In This Section:

Essbase Executable Files

Understanding the Agent

Starting and Stopping Essbase Server

Starting Essbase Server Remotely from Administration Services Console

Starting and Stopping Applications

Starting and Stopping Databases

Managing Ports

Controlling Query Size and Duration

Increasing Agent Connections to Essbase Server

Limiting the Number of User Sessions

Essbase Executable Files

Table 68 lists the Essbase server and client executable files:

Table 68. Main Essbase Executable Files

Executable File[a]

Description

Location

See

essbase.exe

Essbase Server Agent process

ESSBASEPATH/bin

Understanding the Agent

esssvr.exe

Application server 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

HYPERION_HOME/products/Essbase/eas/server/bin

Oracle Essbase Administration Services Online Help

admincon.exe

Administration Services Console application

HYPERION_HOME/products/Essbase/eas/server/bin

Oracle Essbase Administration Services Online Help

[a] On UNIX, files do not have the .exe extension.

Understanding the Agent

Launching the Agent executable file, essbase.exe, starts the Essbase Server Agent process. The Agent process starts and stops all applications and acts as the traffic coordinator for Essbase Server.

On the computer where Essbase Server is installed, the Agent is accessible only from the server console, which is the primary terminal, or monitor, connected to the server computer.

When you start Essbase Server in the foreground, the Agent becomes active in an operating system window. In the Agent window, you can view release and license information, enter login and administrative commands, and monitor the behavior of Essbase Server. On Windows, Essbase can be accessed only from the server console. On UNIX, a telnet session is used to access Essbase remotely.

When you start Essbase Server in the background, the terminal becomes free for other input, and the Agent activities are not visible in the terminal. See Starting Essbase Server as a Background Process.

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 licensed ports, as shown in Table 69. 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 69. Licensed Ports and Multithreading

Number of Licensed 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

*  To display a list of available Agent commands, press Enter in the operating system window where you started Essbase Server in the foreground.

    Table 70 describes each Agent command, and the MaxL, ESSCMD, or Administration Services equivalents:

    Table 70. 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 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 ESSBASEPATH/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 Security File.

    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

    Starting and Stopping Essbase Server

    To start Essbase Server, you must have Administrator permissions.

    Note:

    You cannot start Essbase Server from ESSCMD or MaxL.

    Starting Essbase Server in the Foreground

    Starting Essbase Server in the foreground starts the Agent in an operating system window, in which you can enter commands and monitor Essbase Server activities.

    When starting an Essbase Server for the first time (for example, after installing Essbase), the administrator enters a company name, Essbase Server system administrator user ID, and a system password. This information is saved in the Essbase security file (essbase.sec). As long as essbase.sec is present in your Essbase installation, you are not prompted to provide this information when subsequently starting Essbase Server.

    To start Essbase Server in the foreground, use a method for the operating system on which Essbase Server runs (these examples assume that Essbase Server had been started at least once before):

    • For UNIX, enter the following command at the operating system prompt:

      ESSBASE
    • For Windows, choose a method:

      • Enter the following command at the operating system prompt:

        essbase
      • On the Start menu, select Programs, then Oracle EPM System, then Essbase, then Essbase Server, and then Essbase.

      • In the file system, double-click the essbase.exe file.

      • On the Start menu, select Run and enter essbase.

    Starting Essbase Server as a Background Process

    A system administrator may run Essbase Server as a background process when working in batch mode (for example, when using a UNIX shell script or Windows .bat file to run multiple tasks, such as starting and logging onto Essbase Server, loading data, and running calculation scripts and report).

    Also, on Windows, running Essbase Server as a background process allows a system administrator to use Windows settings to improve performance of applications running in the foreground.

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

    • You do not have access to Agent commands.

    • You cannot shut down Essbase Server from the Agent. You must use MaxL or ESSCMD.

    • You cannot access the application server window to monitor a running application. You must access this information from the application log (ARBORPATH/app/appname/appname.log).

    • You cannot monitor Essbase Server activity using the Agent. You must access this information from the Essbase Server log (HYPERION_HOME/logs/essbase/essbase.log).

    You can run instances of the Agent as Windows services. You must first use EPM System Configurator to register the service. See the Oracle Hyperion Enterprise Performance Management System Installation and Configuration Guide.

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

    essbase -b &

    Using the ampersand (&) at the end of the command is optional; however, if you do not use “&,” the command prompt is not returned after Essbase Server is started.

    Note:

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

    On UNIX systems, to find out if Essbase Server is already running in the background, enter the following command at a command prompt:

    ps -ef | grep ESS

    If Essbase Server is running in the background, it appears in the process list.

    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 at the command prompt in the Essbase Server console window.

    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 at the command prompt in the Essbase Server console window.

      Administration Services

      Stopping Essbase Server

      Oracle Essbase Administration Services Online Help

      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 Essbase Server Remotely from Administration Services Console

        You can start Essbase Server remotely from the Enterprise View tree in Administration Services Console. To enable this functionality, you configure and start Remote Start Server on the Essbase Server computer. Remote Start Server then handles requests from Administration Services to start Essbase Server.

        Each Essbase Server installation includes all files necessary to configure and start Remote Start Server. To start different Essbase Servers from Administration Services Console, you must configure and start a Remote Start Server instance for each Essbase Server.

        See these topics:

        Configuring Remote Start Server

        Before starting Remote Start Server, you must configure it if any of the following conditions apply:

        • Essbase Server is configured to run on a non-default port.

        • Environment variables must be set when Essbase Server is started.

        • The default port used for Remote Start Server (9010) is being used by another program.

        • More than one instance of Essbase Server is installed on one computer.

        If none of these conditions apply, you are ready to start Remote Start Server. Skip to Starting and Stopping Remote Start Server.

        To configure Remote Start Server, see the following topics.

        About the Server.Properties Configuration File

        Each Essbase Server installation contains a configuration file, server.properties, in the ESSBASEPATH/bin directory, which you can use to configure Remote Start Server.

        The default configuration file contains the following lines:

        Server1=localhost
        localhostExecutable=PathToEssbase.exe

        Where PathToEssbase.exe is the location of the Essbase Server executable file.

        When editing the configuration file, keep in mind the following information:

        • You can edit the file in any text editor.

        • On Windows, you must escape the backslash (\) with an additional backslash (\\), as shown in the following examples.

        • The structure of each line in the file:

          key=keyValue

        • The value for the Server1 key may be any one of the following:

          • localhost

          • machineName

          • machineName:port

        • If you change the value of Server1 to machineName, you must use machineName in place of localhost as the key prefix for any rows you add to the file. For example, on UNIX:

          Server1=jdoe2
          jdoe2Executable=Hyperion/products/Essbase/EssbaseServer/bin/essbase.exe
        • If you change the value of Server1 to machineName:port, you must use Server1 in place of localhost as the key prefix for any rows you add to the file. For example, on Windows:

          Server1=jdoe2:4050
          Server1Executable=C:\\Hyperion\\products\\Essbase\\EssbaseServer\\bin\\essbase.exe
        • When adding environment rows to the file, you first specify how many environment rows you are adding by using the localhostEnvRows setting. For example:

          localhostEnvRows=3
          localhostEnv1=Variable=VariableValue
          localhostEnv2=Variable=VariableValue
          localhostEnv3=Variable=VariableValue

          See Setting Environment Variables for Startup.

        • You can set a non-default port for Remote Start Server to use.

        The following sample configuration file for Windows sets the Essbase Server port to 4050; sets the ARBORPATH environment variable; and sets Remote Start Server port to 9030:

        Server1=jdoe2:4050
        Server1EnvRows=1
        Server1Env1=ARBORPATH=C:\\Hyperion\\products\\Essbase\\EssbaseServer
        Server1Executable=C:\\Hyperion\\products\\Essbase\\EssbaseServer\\bin\\essbase.exe
        ServerPort=9030

        Specifying a Nondefault Essbase Server Port

        In the configuration file for Remote Start Server, you must specify the port number being used for Essbase Server if Essbase Server is configured to run on a non-default port.

        If you are using a non-default port because you are using multiple instances of Essbase Server on one computer, see Configuring Remote Start Server for Multiple Instances of Essbase Server.

        *  To specify a non-default Essbase Server port:

        1. On the Essbase Server computer, open the server.properties configuration file. For example:

          ESSBASEPATH/bin/server.properties
        2. Change the following lines from:

          Server1=localhost
          localhostExecutable=PathToEssbase.exe 

          to

          Server1=MachineName:Port
          Server1Executable=PathToEssbase.exe

          For example, on Windows:

          Server1=jdoe2:4050
          Server1Executable=C:\\Hyperion\\products\\Essbase\\EssbaseServer\\bin\\essbase.exe

        Setting Environment Variables for Startup

        If environment variables must be set when starting Essbase Server remotely, you must add environment information to the Remote Start Server configuration file.

        • On Windows, if you are not using multiple instances of Essbase Server on the same computer, you need not set environment variables. See Configuring Remote Start Server for Multiple Instances of Essbase Server.

        • On UNIX, the environment must be set properly when starting Essbase Server. If the environment is not set, you must specify environment variable information in the Remote Start Server configuration file to be used for startup. Each UNIX platform has different environment variable requirements; see the Oracle Hyperion Enterprise Performance Management System Installation and Configuration Guide.

        *  To set environment variables for startup:

        1. From the Essbase Server computer, open the server.properties configuration file. For example:

          ESSBASEPATH/bin/server.properties
        2. Add lines for each environment variable that you must specify, using the format described in About the Server.Properties Configuration File.

          The number of environment rows that must be set depends on your platform.

        The following sections show examples of how to set environment variables for different UNIX platforms, using the default Essbase Server port and an English ESSLANG value.

        Solaris Example:

        Server1=localhost
        localhostEnvRows=4
        localhostEnv1=ARBORPATH=/vol1/essbase
        localhostEnv2=LD_LIBRARY_PATH=/vol1/common/ODBC/Merant/
          5.2/lib:/vol1/essbase/bin;$LD_LIBARY_PATH
        localhostEnv3=ESS_JVM_OPTION1=-Xusealtsigs
        localhostEnv4=ESSLANG=English_UnitedStates.Latin1@Binary
        localhostExecutable=/vol1/essbase/bin/ESSBASE

        AIX Example:

        Server1=localhost
        localhostEnvRows=3
        localhostEnv1=ARBORPATH=/vol1/essbase
        localhostEnv2=LIBPATH=/vol1/common/ODBC/Merant/
          5.2/lib:/vol1/essbase/bin;$LIBPATH
        localhostEnv3=ESSLANG=English_UnitedStates.Latin1@Binary
        localhostExecutable=/vol1/essbase/bin/ESSBASE

        HP-UX Example

        Server1=localhost
        localhostEnvRows=3
        localhostEnv1=ARBORPATH=/vol1/essbase
        localhostEnv2=SHLIB_PATH=/vol1/common/ODBC/Merant/
          5.2/lib:/vol1/essbase/bin;$SHLIB_PATH
        localhostEnv3=ESSLANG=English_UnitedStates.Latin1@Binary
        localhostExecutable=/vol1/essbase/bin/ESSBASE

        Specifying a Nondefault Remote Start Server Port

        By default, Remote Start Server is configured to run on port 9010. If this port is being used by another program, you must specify a different port number before you start Remote Start Server. The port number must be specified in the Remote Start Server configuration file on the Essbase Server computer and in a configuration file on the Essbase Administration Server computer.

        *  To specify a nondefault Remote Start Server port:

        1. On the Essbase Server computer, open the configuration file. For example:

          ESSBASEPATH/bin/server.properties
        2. Add the following line:

          ServerPort=PortNumber 

          For example:

          ServerPort=9030
        3. On the Essbase Administration Server computer, open the following configuration file:

          EASPATH/server\olapadmin.properties
        4. Add one of the following lines:

          • If you want Remote Start Server to use a specific port for a specific Essbase Server, add the following line:

            EssbaseServerName.REMOTE_START_SERVER=PortNumber

            For example:

            jdoe2.REMOTE_START_SERVER=9030
          • If you want Remote Start Server to use the same, non-default port for all Essbase Servers, add the following line:

            REMOTE_START_SERVER=PortNumber

            For example:

            REMOTE_START_SERVER=9030

        Configuring Remote Start Server for Multiple Instances of Essbase Server

        If multiple instances of Essbase Server are installed on one computer, you must configure and start Remote Start Server for only one of the installations.

        Note:

        For information about installing multiple Essbase Server instances, see the Oracle Hyperion Enterprise Performance Management System Installation and Configuration Guide.

        *  To configure Remote Start Server for multiple instances of Essbase Server on one computer:

        1. Select one of the Essbase Server instances and open its configuration file. For example:

          ESSBASEPATH/bin/server.properties
        2. Add the following lines to the file:

          Server2=MachineName:PortNumber
          Server2EnvRows=1
          Server2Env1=ARBORPATH=ARBORPATHvalue
          Server2Executable=PathToEssbase.exe

          For example, on Windows:

          Server2=jdoe2:4050
          Server2EnvRows=1
          Server2Env1=ARBORPATH=C:\\Hyperion\\products\\Essbase\\EssbaseServer-2
          Server2Executable=C:\\Hyperion\\products\\Essbase\\EssbaseServer-2\\bin\\essbase.exe

          Note that ARBORPATH must be set explicitly for the second server instance. Also, for UNIX platforms, if the environment is not already set for either Essbase Server instance, you must specify environment variable information in the Remote Start Server configuration file. For information about the environment variables that are required for each UNIX platform, see the Oracle Hyperion Enterprise Performance Management System Installation and Configuration Guide.

        The following sections show examples for Windows and UNIX (Solaris).

        Windows Example

        The default configuration for localhost and for the second instance of Essbase Server (jdoe2), which runs on port 4050.

        Server1=localhost
        localhostExecutable=C:\\Hyperion\\products\\Essbase\\EssbaseServer\\bin\\essbase.exe
        Server2=jdoe2:4050
        Server2EnvRows=1
        Server2Env1=ARBORPATH=C:\\Hyperion\\products\\Essbase\\EssbaseServer-2
        Server2Executable=C:\\Hyperion\\products\\Essbase\\EssbaseServer-2\\bin\\essbase.exe

        UNIX Example (Solaris)

        The configuration for localhost and for the second instance of Essbase Server (jdoe2), which runs on port 4050. The environment is set for both Essbase Server instances.

        Server1=localhost
        localhostEnvRows=4
        localhostEnv1=ARBORPATH=/vol1/essbase
        localhostEnv2=LD_LIBRARY_PATH=/vol1/common/ODBC/Merant/
          5.2/lib:/vol1/essbase/bin;$LD_LIBARY_PATH
        localhostEnv3=ESS_JVM_OPTION1=-Xusealtsigs
        localhostEnv4=ESSLANG=English_UnitedStates.Latin1@Binary
        localhostExecutable=/vol1/essbase/bin/ESSBASE
        Server2=jdoe2:4050
        Server2EnvRows=4
        Server2Env1=ARBORPATH=/vol2/essbase–2
        Server2Env2=LD_LIBRARY_PATH=/vol2/common/ODBC/Merant/
          5.2/lib:/vol2/essbase–2/bin:$LD_LIBRARY_PATH
        Server2Env3=ESS_JVM_OPTION1=-Xusealtsigs
        Server2Env4=ESSLANG=English_UnitedStates.Latin1@Binary
        Server2Executable=/vol2/essbase–2/bin/ESSBASE

        Starting and Stopping Remote Start Server

        After Remote Start Server is started, you can start Essbase Server.

        Note:

        On UNIX platforms, Remote Start Server can start an Essbase Server only if Essbase Server is installed by the same user name that was used to start Remote Start Server. If Remote Start Server is started by the root user, it can start an Essbase Server that was installed by any user.

        *  To start Remote Start Server:

          • On Windows, launch:

            ESSBASEPATH/bin/remoteStart.exe
          • On UNIX, launch:

            ESSBASEPATH/bin/remotesvr

          *  To stop Remote Start Server:

            • On Windows platforms, launch

              ESSBASEPATH/bin/stopsvr.exe
            • On UNIX platforms, launch

              ESSBASEPATH/bin/stopsvr

            Running Remote Start Server as a Windows Service

            You can install and start Remote Start Server as a Windows service.

            To install and start Remote Start Server as a Windows service, launch:

            ESSBASEPATH/bin/install_service.bat

            install_service.bat installs Remote Start Server as a Windows service (named Essbase Remote Start Server) and starts the service. You can then manage the service from Windows Control Panel or by using net start and net stop commands.

            To remove the Essbase Remote Start Server Windows service, launch:

            ESSBASEPATH/bin/remove_service.bat

            Starting Essbase Server from Administration Services Console

            After starting Remote Start Server, you can start Essbase Server from Enterprise View in Administration Services Console.

            Before you start Administration Services, ensure that the Essbase Servers you want to manage are started. First start Essbase Administration Server, and then start Administration Services Console.

            To start Administration Services, see the Oracle Essbase Administration Services Online Help.

            *  To start Essbase Server from Enterprise View:

            1. From Enterprise View, select the Essbase Server node that you want to start.

            2. Right-click and select Start.

            3. When prompted, enter the password for Essbase Server.

              The request is sent to Remote Start Server, which then starts Essbase Server. If Remote Start Server is not running, an error message is displayed in Administration Services Console.

              Note:

              Essbase Server starts in the background on all platforms, with the password hidden.

            Starting and Stopping Applications

            When an application is started, Essbase loads it 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 server process (ESSSVR). The application server is always started by the Agent.

            Multiple application servers can run on Essbase Server 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 Essbase Server computer and closes the application server 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 at the command prompt in the Essbase Server console window.

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

                If you stop the Agent by closing the server console 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 at the command prompt in the Essbase Server console window.

                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 upper-right corner of the application server window.

                    • Taskkill the process ID.

                      You can find the process ID for individual application servers in the HYPERION_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 at the command prompt in the Essbase Server console window.

                    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 server console window.

                        If you stop the Agent by closing the server console 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 at the command prompt in the Essbase Server console window.

                        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

                          Managing Ports

                          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 at the command prompt in the Essbase Server console window.

                          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 at the command prompt in the Essbase Server console window.

                            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 the Oracle's Hyperion Enterprise Performance Management System Configurator to assign the second Essbase Server instance to a different port than the first. See the Oracle Hyperion Enterprise Performance Management System Installation and Configuration Guide.

                              Changing Port Default Values

                              If you need to change one or more of the default values associated with Agent and server ports, see the Oracle Essbase Technical Reference for the correct configuration setting to change.

                              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.

                              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 at the same time.

                              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. The default value for each setting is 5, the minimum is 1, and the maximum is 500. 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.