Essbase XTD Analytic Services Release 6.5.2 Readme

IBM DB2 OLAP Server, Version 8.1

Now on Linux!

May 2003

Readme File for Linux

This file contains the following sections:

About the V8.1 Linux release
Hardware and software requirements
Supported ODBC drivers and relational data sources
Installing the Linux release
Setting Linux library path variables
Installing Java
Documentation provided
Documentation updates
Known issues
Tips
Copyright information

About the V8.1 Linux release

Top

DB2 OLAP Server V8.1 now supports Linux Red Hat version 7.3.

This download contains the OLAP server component at the following service level:

DB2 OLAP Server V8.1 Fix Pack 1 (Essbase XTD Analytic Services 6.5.2 -- same code level as 6.5.1)

You must use the DB2 OLAP Server V8.1 Fix Pack 1 (Essbase 6.5.1) clients with the OLAP server on Linux.

The following OLAP products do not run on Linux, although you can run them on other supported operating systems and use them with an OLAP server on Linux:

DB2 OLAP Miner
DB2 OLAP Server Analyzer (Hyperion Analyzer)
DB2 OLAP Integration Server (Essbase Integration Services)
DB2 OLAP Server Enterprise Services (Essbase Deployment Services)
DB2 OLAP Server Spreadsheet Services (Essbase Spreadsheet Services)
DB2 OLAP Server Administration Services (Essbase Administration Services)

Hardware and software requirements

Top

The OLAP server for Linux requires a system with the minimal hardware and software requirements shown in the following table.

Linux system requirements

Component Requirement
Server platform Intel computers
Linux version Linux 7.3 for Intel Microprocessor-based computers
RAM 128 MB RAM (256 MB or more recommended)
Large databases have greater memory requirements
Swap space At least two times the amount of physical memory is recommended when physical memory is less than .5 GB. Contact your system administrator or hardware vendor for optimum swap configuration.
Disk space

75 MB
Server software uses 38 MB
Sample applications use 15 MB as shipped and use 37 MB after they are fully loaded with default settings.

Network protocol TCP/IP (included with Linux)
Thread type POSIX Kernel Threads (included with Linux)
Java platform Java Runtime Environment version 1.3.1

Component	Requirement
Server platform	Intel computers
Linux version	Linux 7.3 for Intel Microprocessor-based computers
RAM	128 MB RAM (256 MB or more recommended) Large databases have greater memory requirements
Swap space	At least two times the amount of physical memory is recommended when physical memory is less than .5 GB. Contact your system administrator or hardware vendor for optimum swap configuration.
Disk space	75 MB Server software uses 38 MB Sample applications use 15 MB as shipped and use 37 MB after they are fully loaded with default settings.
Network protocol	TCP/IP (included with Linux)
Thread type	POSIX Kernel Threads (included with Linux)
Java platform	Java Runtime Environment version 1.3.1

Supported ODBC drivers and relational data sources

Top

DataDirect Technologies ODBC driver version 4.1 is provided with the Linux release, which supports Red Hat Linux 7.3.

The Linux release supports the following relational data sources:

For DB2 Universal Database 7.1 and 7.2, use the DB2 7.1 ODBC.
For Oracle 8i (Net8) and Oracle 9i (Oracle Net), use the MERANT 4.1 Wire Protocol. When using Wire Protocol drivers, you are not required to use the RDBMS client software.

Installing the Linux release

Top

Before installing the Linux release for the first time, you must have installed either an OLAP server on another operating system or the Windows clients.

To install the Linux release:

Download the linux.tar file to a temporary directory (called the CD directory) on your Linux computer and decompress it. After decompressing the tar file, make sure the setup.sh file exists in the directory.
From an existing DB2 OLAP Server installation, copy the bin/license.id file to your CD directory. For example, if the installation CD directory is called /maincd, and setup.sh is located in this directory, then copy the license.id file to /maincd. If the license.id file is not located in the same directory as the setup.sh file, the installation program prompts you for a license number, which you can manually copy from the license.id file.
During the installation, you are prompted to enable the license option for Integration Services (DB2 OLAP Integration Server, or OIS). OIS does not run on Linux, but you can run OIS on other supported operating systems and use it with an OLAP server on Linux. To run this type of configuration, put a check next to Integration Services in the Linux installation program.
The rest of the instructions for installing the Linux release of DB2 OLAP Server V8.1 are identical to the instructions for installing on AIX (with the exception of any filenames that are specific to the operating system, such as jrte_lnx_ess.tar and essbase.cfg.linux in the /bin directory). See the Installation Guide for more information.

Setting Linux library path variables

The essbaseenv.sh script in the $ARBORPATH directory contains the DB2 OLAP Server environment variable settings. These environment variables must be set prior to running the server. Here are two alternative methods of activating the script:

Launch the script from your .profile file as follows, and then log out and back in to activate the settings:

. <arborpath>/essbaseenv.sh

Or launch the script from the command lline: . <arborpath>/essbaseenv.sh

Installing Java

You must manually install the Java 2 Runtime Environment (JRE) or the Java 2 platform, Standard Edition, version 1.3.1. The instructions for installing Java is the same as for the other UNIX operating systems, as described in the Installation Guide.

Please note that the JRE install package for Linux is in: /linux/server/jre/

The JVM library file is either:

/usr/java/jdk1.3.1_04/jre/lib/i386/client/libjvm.so

$JAVAINST/jre/lib/i386/client/libjvm.so

where the JAVAINST environment variable is set to where the JDK is installed.

Documentation provided

Top

For this release, all information about running DB2 OLAP Server on Linux is provided in this readme file.

For the rest of your documentation needs, use the DB2 OLAP Server documentation that you can install with the Windows clients. You can also download the book from our Web site:

http://www-3.ibm.com/software/data/db2/db2olap/library.html#v81

Documentation updates

Top

This section provides information about changes to the installation process and platform support not documented elsewhere.

Direct I/O:

The Linux release of DB2 OLAP Server V8.1 does not support Direct I/O.

The directory path and name of the library that implements the authentication protocol:

For all platforms, the library that implements the authentication protocol is located in ARBORPATH\bin. The library name depends on the operating system where you have installed Essbase. The library name on Linux is:

libessldap.so.

The Essbase 6.5.2 release supports the following relational data sources:

DB2 Universal Database 7.1 Server (with a DB2 7.1 client)
DB2 Universal Database 7.2 Server (with a DB2 7.1 client)
Oracle 8i Server
Oracle 9i Server

Oracle 8i and 9i servers are supported only with DataDirect 4.1 Wire Protocol Drivers. When using DataDirect 4.1 Wire Protocol Drivers, you do not need RDBMS client software.

Sample configuration file:

A sample configuration file, called essbase.cfg is provided with this release. You can edit this file in a text editor to add or remove configuration settings.

Updating the odbc.ini file:

The odbc.ini file is a sample file located in $ARBORPATH. This file must be updated based on your environment settings.

Setting your environment to run SQL interface:

After running inst-sql.sh, you must set the ODBCINI environment variable to:

$HOME/.odbc.ini

To use Hybrid Analysis with the Linux release, you must meet the following requirements:

Set the environment variable ODBCINI to $ARBORPATH/odbc.ini file.
Use DB2 OLAP Server V8.1 FixPak 1 clients.
Use DB2 OLAP Integration Server V8.1 FixPak 1.
Run inst-sql.sh, located in $ARBORPATH. Doing so will set the required library link:
libesssql.so -> libesssql.insolv.so

Limitation on server thread and agent thread settings:

For this release, the recommended maximum server thread and agent thread settings in your essbase.cfg file is 150.

To compile C-API programs on LINUX, you must complete the following tasks:

Make sure that $ARBORPATH/api/lib is part of both LPATH and LD_LIBRARY_PATH environment variables.
Make sure that $ARBORPATH/bin is part of both LPATH and LD_LIBRARY_PATH environment variables.
Make sure that $ARBORPATH/api/include is part of the include path, for example:
cc -o foo foo.c -I$ARBORPATH/api/include.
Make sure that the required api libraries are included while linking the api program, for example:
cc -o foo foo.c -I$ARBORPATH/api/include -lessapi -lglobalc.
Make sure that the required system libraries ( librt.so and libdl.so ) are included while linking the api program, for example:
cc -o foo foo.c -I$ARBORPATH/api/include -lessapi -lglobalc -lrt -ldl.

Known issues

Top

Every effort has been made to ensure that DB2 OLAP Server performs without problems. However, these issues remain at the time of release:

Killing processes not supported on UNIX

Executing a "kill" command of any kind in UNIX against any type of Essbase process is unsupported. Issuing a kill command, especially on a database that is calculating, has a high probability of corrupting the database.

If all supported methods of shutting down an Essbase process have been exhausted, and a kill must be executed, heed the following precautions to reduce the amount of damage to the database:

Make sure a current, validated back up of each database being killed is available.
If a current, validated back up is not available, make sure source files for each database are available for rebuilding.
If a kill must be executed, use kill -9 and execute it against the problem application, then try a normal shutdown of DB2 OLAP Server.
If the Essbase agent (essbase.exe) must be killed, kill all of the agent's child processes first (that is, all applications that are running) before issuing the kill command against the agent.
Any application that is killed must then be brought up and validated, preferably using both the validate command and a full export. This step applies for any application that has had a kill command issued against it, even if it was only issued to allow the Essbase agent to be killed.

Whenever possible, avoid issuing kills against Essbase processes as it is unsupported and greatly increases the possibility of corruption.

Hybrid Analysis known issues

When working with a Hybrid Analysis-enabled outline with DB2 OLAP Server formulas attached to one or more members in the Accounts dimension that have parent members that are not marked as Label Only, you must explicitly propagate these formulas up the Accounts dimension hierarchy in order for queries involving relational members to reflect calculations using the formulas. Otherwise, DB2 OLAP Server uses the hierarchical relationships between members to determine the values for the relational cells. For example, in the sample Hybrid Analysis application shipped with the product, Ratios is a member in the Accounts with two children, Margin% and Profit%, containing formulas. If Ratios is not marked as Label Only and Ratios is intended to be the sum of Margin% and Profit% values, you must edit the outline to add the formula Ratios = Margin%Sales + Profit%Sales. This limitation will be addressed in a future release. (23411)

Although the limit for stored calculations is 64 KB, calculation scripts created in MaxL that have multi-byte characters cannot exceed 40 KB.

Database notes created using MaxL appear stripped of newline-character formatting when viewed in the Spreadsheet Add-in.

Bugs not fixed for this Linux release:

Bug Number	Description
16412	In Excel, in Query Designer, the server location radio button may not be active in the "Hyperion Essbase Query Designer Save As Query" window when you try to save a query. This occurs because a selected cell is in Edit mode. If you are typing in a cell, Essbase menu items do not function, although they appear enabled, until you get out of Edit mode.
17023	If a member name contains the ampersand (&), even if it is surrounded with quotation marks, and if the member name is in a calculation script, the script may fail validation if the user has Application Designer permission. DB2 OLAP Server incorrectly interprets the ampersand as the signal for a substitution variable. If you run the script without validation, it performs the calculation correctly. Users with supervisor privilege do not receive this validation error.
17253	DB2 OLAP Server does not support discontinuous selection in Lotus, although it does in Excel.
17267	At the end of a calculation started in Lotus, a dialog box appears with a message that the calculation is complete. Clicking on the dialog box does not close it. Press Esc/Cancel from the keyboard to close the dialog box.
17927	DB2 OLAP Server does not warn you if you request that export results be written to a file that already exists. Essbase overwrites the existing file.
17957	If you create a dimension build rule that uses "Create Using Text" on the last column, and if the last true field in the input file is an "Alias" column that has some blank records, the text generated by the "Create Using Text" feature will not be placed into the last column, but will be placed in any record where the "Alias" column is blank. The rule, which passes validation, will fail during the build. To correct, delimit the blank fields.
18041	DB2 OLAP Server may not be able to open a file if the directory location contains a space. This is true for all files such as load files, rules files, calculation scripts, etc. Consider moving the file so that there are no spaces in the directory path.
18046	When logged in with database designer privilege, the entire list of users is displayed in Security > Database, even though only the list of users that the database designer has privileges to modify should appear. Attempts to modify users for whom database designer should not have privileges will not be successful.
19288	Using Dynamic Time Series (DTS) members on a partitioned database may cause a server crash if these conditions are true: The outline has DTS members defined in the Time dimension and The partition definition doesn't mention the Time dimension, indicating it should include all members. If both of these conditions are true, you should edit your partition definition so that it mentions the Time dimension explicitly, for example, `@Idesc("Time-dimension-name")`.
20775	If you use the Query Designer to change members in a spreadsheet, then select a dimension and choose Essbase > Cascade, and then in the Destination Options tab, select the option "One Workbook, Separate Sheets," you may receive the Microsoft Visual C++ Runtime Library error: `Runtime Error! C:\Program Files\Microsoft Office\Office\Excel.exe....abnormal program termination! error.`
22233, 23800, 23344	Running too many concurrent reports may overwhelm DB2 OLAP Server or operating system resources, especially against partitioned databases. If this occurs, reduce the number of such reports running concurrently.
22999	If, during outline revision, you delete a member with a particular alias name, and then create a new member with the same alias name, the alias will fail to register and DB2 OLAP Server creates the new member without an alias. Workaround: Either delete the alias from the Outline Editor and save, or use a different alias name when revising.
23086	Due to a Microsoft bug, you may not be able to display the Spreadsheet Add-in in IE 5.0 if you are running on operating system NT4.0. If you try to open an `.xls` file from IE 5.0 on NT4.0, the spreadsheet may open in a separate window.
23374	The application log, when displayed via Application Manager, may incorrectly fail to show some log entries for the current day because it evaluates the time using GMT. To view missing log entries, select "All Dates."
24044	For EssOtlQueryMembers on UNIX, the currency conversion type returned is incorrect. Workaround: Use EssOtlFindMember instead.
24351	Some characters, such as those using umlaut or accent marks, cannot be typed in ESSCMD interactive mode.
25659	If you use a partition definition where one or more member functions in the definition resolve to an empty set, then DB2 OLAP Server may write more than one message in the application log when you validate the partition. Each message has the same information about a member function resolving to an empty set. All but the first message in the sequence can be ignored.
26028	If you enable parallel calculation (CALCPARALLEL or SET CALCPARALLEL greater than the default 0) on a database that is part of a transparent partition, increase the value of SERVERTHREADS for each source database that is part of the transparent partition, using these rules: If each source database is part of a different application on a different machine, increase SERVERTHREADS in the configuration file `essbase.cfg` on each machine. Increase the value by the same number you use in CALCPARALLEL. If all source databases are part of the same application on the same machine, increase the value of SERVERTHREADS using this formula: `(number of source databases) * (value of CALCPARALLEL)`
31691	You must save a rules file and the data file it uses to the same ARBORPATH`/App/`database_name directory as the database whose outline you are working with.
43406	In DB2 OLAP Server Version 8.1 (Essbase 6.5), Application Manager is unable to modify an outline or load data if the text file is located in a different application database directory on the same server.
55620	Adding both shared and non-shared members to a parent in the outline of a partitioned database may cause the application to crash and may cause an access violation error. Workaround: Change the order in which the shared and non-shared children are listed in the outline under the parent. The non-shared children should be listed first and the shared children should be listed at the end of the outline.
55926	Before using the MaxL alter database statement to get invalid block header information for a given database, be sure that the server is not performing other operations, such as calculations or dataloads; otherwise, an exception error may occur. Before running the MaxL statement to get invalid block header information, the database administrator must forcibly log off all users and disable all logins to ensure that no other users or processes are using the server. The complete MaxL statement to get invalid block header information is `alter database DBS-NAME validate data to local logfile 'FILE-NAME';`.

Tips

Top

If your database allows or requires 'Aggregate Missing Values' setting set to YES, then you may want to consider using ZLIB as the compression scheme. ZLIB particularly works well on such databases compared to other compression schemes. However, changing the aggregate missing values setting may have an impact on calculation results - see the Database Administrator's Guide. Consider using ZLIB only if you have already determined that the setting should be YES for other reasons.
Outlines containing formulas that use custom-defined functions (CDFs) cannot be validated on the client. Outlines containing CDFs must be validated on the server.
If you receive compilation errors in your calculation scripts, check the errors to be sure that variable names are not enclosed in quotation marks. The first character of variable names must be a letter (a through z). Variable names may contain: letters, numbers (0 through 9), and the special characters: $ (dollar sign), # (number sign), and _ (underscore).
The essbase.jar file should always reside in the /java directory of your DB2 OLAP Server installation if you intend to use the samples provided.
Java adds a startup memory requirement of approximately 10MB per application. If you install Java but are not using custom-defined macros or functions, you can reduce your startup memory requirement by disabling Java. To disable Java, remove all parameters from the JVMMODULELOCATION setting in the essbase.cfg file. For more information about this setting, see the online Technical Reference in the /docs directory of your DB2 OLAP Server installation.

Copyright information

The following statements apply to all server and client components of IBM DB2 OLAP Server:

Licensed Material - Program Property of IBM
(c) Copyright IBM Corp. 1998, 2003. All Right Reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
IBM, DB2, and DB2 OLAP Server are trademarks of International Business Machines Corporation in the United States, other countries, or both.
Portions (c) 1991-2003 Hyperion Solutions Corporation. All rights reserved. Hyperion is a registered trademark and Hyperion Solutions is a trademark of Hyperion Solutions Corporation.
Portions (c) Blue Sky Corporation. All rights reserved.