IBM DB2 OLAP Server 8.1

New features in FixPak 1 (Essbase 6.5.1)

• New Range Function
• New Moving Sum Function
• New Moving Sum Function with Member Value Options
• Drill-Through Filter Persistence
• Report Command LINK
• Parallel Calculation Correction

• Hybrid Analysis Support for Additional Platforms
• Support for Microsoft 4 GB RAM Tuning (4GT)
• External Authentication Support for MS Active Directory
• Excel 97 Support

• Port Statistics
• Enhanced Security File Backup
• New Compression Algorithm
• Query Logging
• Improved #MISSING Handling with DATACOPY
• Invalid Block Header Identification and Correction
• Improved Exception Handling
• Application Memory Manager

• MaxL What's New
• API What's New

@XRANGE is a new calculator function that takes as input two members (single or cross-dimensional) and returns a member range. @XRANGE is a member set function. Member set functions return a list of members.

This function is useful, for example, when you work with the Time and Scenario dimensions. You can use @XRANGE to return a member set combination of Time and Scenario instead of creating a dimension that combines the two (which creates many more individual members than necessary).

Syntax

@XRANGE identifies a range of members using the level of the arguments, determines the cross product of all members in the range and then prunes the set to include only the range requested.

Example

This example returns this range:

1998->Jun, 1998->Jul, ... 1998->Dec,
1999->Jan, 1999->Feb, ... 1999->Dec,
2000->Jan, 2000->Feb, ..., 2000->Dec,
2001->Jan, 2001->Feb, 2001->Mar

Rules

@XRANGE can be used only in these functions:

@AVGRANGE, @SUMRANGE, @MINRANGE, @MINSRANGE, @MAXRANGE, @MAXSRANGE, @STDDEVRANGE, @MOVSUM, @MOVAVG, @MOVMIN, @MOVMAX, @MOVMED, @SPLINE

@XRANGE can appear anywhere in a formula where a range can normally appear.

The two arguments to @XRANGE must be either single members or cross-dimensional members with the same member components. You cannot mix a single member and cross-dimensional member. For example, @XRANGE(1998->Jun, 2001) is invalid because a single member and a cross dimensional member are used together.

The dimension order of members must match for both arguments. For example, @XRANGE(1998->Jun, March->2001) is invalid because the two member components are in different orders. Changing 1998->Jun to Jun->1998 or changing March->2001 to 2001->March results in a valid function.

Although the syntax is correct, a function such as @XRANGE (2001, 1998) is meaningless because it results in an empty set.

The member components of each argument must be from the same level. For example, @XRANGE(1998->Jun, 2001->Qtr1) is invalid because Jun and Qtr1 are not from the same level.

Essbase now provides a moving sum function, @MOVSUM. This function applies a moving n-term sum to an input data set. Each term of the set is replaced by a trailing sum of n terms, and the first terms (the n-1 terms) are copies of the input data. @MOVSUM modifies a data set for smoothing purposes.

Syntax

Notes

• The @MOVSUM function calculates a trailing, rather than a centered, sum. This example illustrates the difference:

   Trailing Sum          Centered Sum
    1   2   3              1   2   3
            6                  3

• While calculating the moving sum, @MOVSUM skips #MISSING values. For example, if one value out of three is #MISSING, Essbase adds the remaining two values.
• If you use an Essbase member set function to generate a member list for the rangeList parameter (for example, @SIBLINGS), to ensure correct results, consider the order in which Essbase sorts the generated member list. For more information, see the online Technical Reference topic for the member set function that you are using.
• When you use @MOVSUM in a calculation script, use it within a FIX statement. Although FIX is not required, using it may improve calculation performance.

 

 
 
 

For periods where the value of n cannot be used to compute the moving sum, the value returned is the same as for the source member. For example, the formula "Mov Sum" = @MOVSUM(Sales,3,Jan:Jun); produces this result for January and February:

 Colas   New York   Actual                                
              Sales     Mov Sum          
              =====     =======            
Jan            678        678            
Feb            645        645

For January and February, Essbase cannot compute a moving sum over the last three months (the value of n) because the three months do not yet exist. Essbase simply copies the values for Jan and Feb for the moving sums.

If you wish to assign different values to members before the value sum parameter is reached, or use different member values for the trailing members, use @MOVSUM instead.

• When you use @MOVSUM across a large range in a sparse dimension, you may need to increase the size of the calculator cache. For more information on the calculator cache, see the Database Administrator's Guide.

Example

"Mov Sum" = @MOVSUM(Sales,3,Jan:Jun);

This example produces the following report:

          Colas   New York   Actual              
              Sales     Mov Sum 
              =====     =======   
Jan            678        678   
Feb            645        645   
Mar            675       1998   
Apr            712       2032   
May            756       2143   
Jun            890       2358

Essbase provides an additional moving sum function, @MOVSUMX, that is similar to @MOVSUM, in that it applies a moving n-term sum to an input data set. Unlike @MOVSUM, @MOVSUMX provides several options that control the value assigned to trailing members, and how to assign values to members that precede the n-term parameter. @MOVSUMX modifies a data set for smoothing purposes.

Syntax

Examples

SalesSum = @MOVSUMX (COPYFORWARD,Sales,3,Jan:Aug);
 

Member	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug
Sales	100	150	200	250	300	350	400	450
SalesSum	100	150	450	600	750	900	1050	1200

 
 
 

Example 2

SalesSum = @MOVSUMX (TRAILMISSING,Sales,3,Jan:Aug);
 

Member	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug
Sales	100	150	200	250	300	350	400	450
SalesSum	#MISSING	#MISSING	450	600	750	900	1050	1200

 
 
 

Example 3

SalesSum = @MOVSUMX (TRAILSUM,Sales,3,Jan:Aug);
 

Member	Jan	Feb	Mar	Apr	May	Jun	Jul	Aug
Sales	100	150	200	250	300	350	400	450
SalesSum	100	250	450	600	750	900	1050	1200

 
 

Beginning with Essbase 6.5.1, when you customize a drill-through report in Essbase Spreadsheet Add-in, you can save the drill-through filters that you create in the Select Data Filters dialog box. In prior releases of Essbase, users cannot save filters that they create when customizing a drill-through report. Users of 6.5.0 and previous releases have to recreate a filter each time they create a drill-through report.

In addition, you can add new filters, rename filters, delete filters, and select existing filters that you have previously saved.

To add new filters:

1. In the Select Data Filters dialog box, click Add new filter. The Filter Name dialog box is displayed.
2. In the Filter Name dialog box, enter the name for the filter that you are creating.
3. If you want the filter to have the same description and conditions as the filter currently selected in the Select Data Filters dialog box, select Copy definition of current filter.
4. Click OK.
5. The filter is added to the list of saved filters in the Filter drop-down list box.
6. Optionally, if you want to describe the filter, create a short description for the filter in the Description box.
7. Click Save Filters.

1. In the Select Data Filters dialog box, select the filter that you want to delete from the Filter drop-down list box.
2. Click Delete.
3. Click Save Filters.

1. In the Select Data Filters dialog box, select the filter that you want to rename from the Filter drop-down list box.
2. Click Rename.
3. In the Filter Name dialog box, enter a new name for the filter.
4. Click OK.
5. Click Save Filters.

In the Select Data Filters dialog box, click Save Filters. All filters created for the drill-through report are saved.

Whenever you use the Select Data Filters dialog box, you can select from the list of filters that you have saved.

Note: You must click Save Filters to save any changes, such as adding, deleting, or renaming, to the filters.

See these sources for more information about using drill-through:

• Hyperion Essbase Spreadsheet Add-in User's Guide, Chapter 4, "Using Drill-Through"
• Hyperion Essbase Drill-Through Online Help

The LINK Report Writer command has been extended to span into dimension levels that are located in the Hybrid Analysis portion of an Essbase cube. For more information about LINK, see the Technical Reference topic Report Writer Commands: LINK. For more information about Hybrid Analysis, see the Database Administrator's Guide Appendix D "Accessing Relational Data with Hybrid Analysis."

Parallel Calculation Correction

Top

Valid values for CALCPARALLEL (or SET CALCPARALLEL) are 1 through 4. Essbase 6.5.0 documentation incorrectly states 0 through 4.

Hybrid Analysis functionality has been extended to include support of two additional RDBMS platforms, SQL Server and Teradata.

See the Essbase Installation Guide for information about release levels, operating systems and drivers supported.

Support for Microsoft 4 GB RAM Tuning (4GT)

Top

Essbase Release 6.5.1 supports Microsoft 4 GB RAM Tuning (4GT). This feature enables users with extremely large databases to take advantage of a larger address space to improve performance.

Currently, the total addressable limit of RAM on servers running Windows 2000 or Windows NT is 4 GB. By default, applications can access 2 GB, with the Windows kernel using the other 2 GB. For selected versions of Windows running on Intel architecture servers, Microsoft provides the 4GT feature. The 4GT feature increases the addressable limit for applications to 3 GB, reducing the potential RAM allocated to the Windows kernel from 2 GB to 1 GB.

Essbase currently supports the 4GT feature on computers that use Intel-based processors with more than 2 GB of physical RAM, and that have either of these versions of Windows:

• Windows 2000 Advanced Server
• Windows NT Server 4.0, Enterprise Edition

• Essbase is configured to use direct I/O. (Enabling 4GT on Essbase installations configured for buffered I/O is not recommended.)
• The index and data caches are sized correctly and Essbase performance is consistently improved by increasing the data file cache, but further increases are bounded by the previous 2 GB addressability limitation. For information about setting cache values, see the "Optimizing Essbase Caches" section of the Database Administrator's Guide.

Enabling 4GT

Consider this example:

[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(2)\WIN2KADV
[operating systems]
multi(0)disk(0)rdisk(0)partition(2)\WIN2KADV="Microsoft Windows 2000 Advanced Server" /3GB /fastdetect
multi(0)disk(0)rdisk(0)partition(2)\WINNT="Windows NT Server Version 4.0" /3GB /fastdetect

Notes

• This change is effective only if you are using Windows NT Server 4.0 Enterprise Edition or Windows 2000 Advanced Server. On standard Windows NT, although the /3GB flag relocates the kernel, applications are unable to access more than 2 GB.
• On a dual boot system, to ensure that the boot loader supporting the 4GT feature is installed, be sure that the last operating system you install is a version that supports the 4GT feature.
• Because the Windows kernel area is reduced, it is unlikely, but conceivable, that certain applications and workloads in certain environments may experience degraded performance. Testing your workload in your environment is recommended.

Essbase now provides external authentication drivers for Microsoft Active directory server, in addition to the support for LDAP authentication introduced in 6.5.0.

To enable external authentication:

1. Add the AUTHENTICATIONMODULE configuration setting to your server configuration file essbase.cfg. Be sure to use the correct values for the entry as listed in Syntax.
2. Restart OLAP Server to initialize the change.
3. Create users with Application Manager or MaxL, and specify the correct external authentication module. For instructions, see the Database Administrator's Guide security chapters or the MaxL Reference entry for create user.

Syntax

LDAP Example

AUTHENTICATIONMODULE LDAP essldap.dll 30 cn=Engineers, ou=Groups, dc=yahoo, dc=com@Gorky:389

MSAD Example

AUTHENTICATIONMODULE MSAD essmsad.dll  45  ou=Engineers,ou=Groups,dc=yahoo,dc=com@129.63.140.122:389

Notes

Microsoft Excel 97 support has been reinstated for Essbase Spreadsheet Add-in.

You can enable OLAP Server 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 end users are unable to connect.

To enable OLAP Server to check port use statistics and write those statistics to the OLAP Server log:

1. Edit the server configuration file essbase.cfg to include the setting PORTUSAGELOGINTERVAL:

 

 
 
 

PORTUSAGELOGINTERVAL x

The value of x represents the number of minutes between each check of the number of ports in use. The value of x can be any whole number from 1 - 60, with 5 the recommended minimum and default value. Essbase ignores any portion of a non-whole number. For example, Essbase evaluates 2.5 as 2 minutes. Statistics are written to the log immediately after each check.

2. Restart OLAP Server.

 

 
 
 

View the OLAP Server Log file. You will see entries similar to this:

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

Examples

Essbase writes the port use statistics to the OLAP Server log every 10 minutes.
PORTUSAGELOGINTERVAL

Essbase writes the port use statistics to the OLAP Server log every five minutes (the default value).
PORTUSAGELOGINTERVAL 6.75

Essbase ignores the non-whole portion of the number, and writes the port use statistics to the OLAP Server log every six minutes.

Enhanced Security File Backup

Top

Essbase now compares the security backup file essbase.bak to the security file essbase.sec at specified intervals instead of only when OLAP Server starts.

Using Application Manager, you can change the frequency of these comparisons. You can also use a new ESSCMD, MaxL or API command to compare the security backup file essbase.bak to the security file essbase.sec at any time. Essbase always updates the backup file if it does not match the security file when the two files are compared, regardless of which tool is used to trigger the comparison.

To change how often Essbase checks for differences between the security file and the security backup file, and updates the security backup file if needed:

1. Navigate to the Server Settings dialog box in Application Manager.
2. Enter a value for the time interval in the Check every text box.
3. Click OK to initialize the new value.

Review these facts before changing the interval value:

• The same control manages how often the security backup file is checked against the security file and how often user inactivity is checked.
• By default, the value is five minutes. Five minutes is the recommended setting to ensure that the security backup file is checked frequently enough to capture security changes. Five minutes is also the recommended value for the inactivity check.
• If you set the value to zero, the inactivity check is disabled and the essbase.bak is compared to essbase.sec every five minutes (and, as always, updated if necessary).
• Enter a larger value if your security file does not need to be updated frequently. Enter a smaller value if performance is not an issue.

• The ESSCMD UpdateBakFile command
• The MaxL alter system command
• The API function EssUpdateBakFile

ESSCMD Syntax

MaxL Syntax

API Syntax

Caution: If Essbase stops running unexpectedly for any reason, such as a freeze or crash, or as the result of terminating a process, do not restart OLAP Server until you copy the backup file essbase.bak to the security file essbase.sec. If you do not perform the copy first, when OLAP Server starts, Essbase notes that essbase.sec is corrupt, creates an empty security file and copies it to essbase.bak, thus destroying the backup of your security information.

New Compression Algorithm

Top

In addition to the options provided in previous releases (RLE, bitmap compression, or no compression), OLAP Server now supports ZLIB compression. This method is used in packages like PNG, Zip, and gzip.

Calculation and data loading is faster with direct I/O and ZLIB compression than with buffered I/O and ZLIB compression. If data storage is your greatest limiting factor, use ZLIB, but be aware that, under some circumstances, data loads may be up to 10% slower than bitmap compression. On the other hand, the size of the database will be significantly smaller when you use ZLIB as your compression technique.

Bitmap compression uses an algorithm that tracks which values are missing, and does not interact with any other type of data. ZLIB compression, in contrast, builds a data dictionary based on the actual data being compressed. Therefore, ZLIB compression should provide greater compression ratios over bitmap compression given extremely dense data. However, because the effectiveness of the ZLIB algorithm is dependent (at the bit level) on the actual data being compressed, general guidelines about when ZLIB compression will provide greater compression than bitmap compression based solely on density are not available. Unlike other compression methods, the storage space saved has little or no relationship to the number of missing cells or the number of contiguous cells of equal value. It is best to test with a representative sample of data.

To estimate the storage savings you may obtain with ZLIB, create a small database with a small sampling of real data, change the compression setting, restart Essbase, and note the difference in storage.

You can also use the small sample database to estimate any changes in calculation or data loading speed.

To change the compression setting, use Application Manager, MaxL, or Essbase Administration Services as currently documented. Simply substitute "ZLIB," for the values listed. For more information on how to use ZLIB compression in Essbase Administration Services, refer to the Essbase Administration Services Online Help.

Query Logging

Top

Query logging provides a way for Essbase administrators to track query patterns of an Essbase database. The query log file tracks all queries performed against the database regardless of whether the query originated from Spreadsheet Add-in or Report Writer. Query logging can track members, generation or level numbers of members belonging to specific generations or levels, and Hybrid Analysis members. Query logging also offers the flexibility to exclude logging of certain dimensions and members belonging to generations or levels. Because the query log file output is an XML document, you can import the log file to any XML-enabled tool to view the log. For details about the query log file structure, refer to querylog.dtd in the ARBORPATH/bin directory.

To enable query logging, create a query configuration file (distinct from the essbase.cfg file) and add to the file the configuration settings that control how query logging is performed.

Create a query log configuration file for each database that requires query logging. If the configuration file is missing or the QUERYLOG setting is off, query logging is disabled.

To enable query logging:

1. In the ARBORPATH\App\appname\dbname directory of Essbase, create a query log configuration file. The configuration file must be named dbname.cfg, where dbname matches the name of the database. For example, the query log configuration file for Sample Basic is basic.cfg.
2. In the configuration file, specify required and optional elements, using the syntax from the section Query Configuration File Syntax:
• The dimension for which you want to log queries (QUERYLOG [dimension_name]).
• Optional: The setting to log generation or level numbers for members of specified generations or levels in a dimension (QUERYLOG GENERATION generation-range or QUERYLOG LEVEL level-range).
• Optional: The setting to exclude logging of members from specified generations or levels in a dimension (QUERYLOG NONE GENERATION generation-range or QUERYLOG NONE LEVEL level-range).
• Optional: The setting to log Hybrid Analysis members for a specified dimension (QUERYLOG LOGHAMBRS ON | OFF).
• Optional: The location where the query log file is created (QUERYLOG LOGPATH path-expression).
• Optional: The format of the log file output (QUERYLOG LOGFORMAT CLUSTER | TUPLE).
• Optional: The size of the log file (QUERYLOG LOGFILESIZE n)
• Optional: The size of all log files (QUERYLOG TOTALLOGFILESIZE n).
• A setting to enable or disable query logging the next time the application starts (QUERYLOG ON | OFF).
3. Restart the database to accept the configuration settings. Restart after creating a file or changing any entries in a file.
4. After query logging is enabled, review the log entries in the query log file, dbname.qlg. For example, you can view the output of the log file to analyze how many times a certain member has been queried.

Query Configuration File Syntax

QUERYLOG [dimension_name]
QUERYLOG NONE GENERATION generation-range
QUERYLOG NONE LEVEL level-range
QUERYLOG GENERATION generation-range
QUERYLOG LEVEL level-range
QUERYLOG LOGHAMBRS ON | OFF
QUERYLOG LOGPATH path-expression
QUERYLOG LOGFORMAT CLUSTER | TUPLE
QUERYLOG LOGFILESIZE n
QUERYLOG TOTALLOGFILESIZE n
QUERYLOG ON | OFF

Generation-range and level-range values are represented in one of the following ways:
 

Generation-Range or Level-Range Value	Description
x	A specific generation or level number. For example, QUERYLOG NONE GENERATION 2 excludes generation 2 from query logging.
x-y	All generations or levels inclusive of number x through number y. For example, QUERYLOG GENERATION 1-3 or QUERYLOG LEVEL 1-3 includes generation or level numbers 1, 2, and 3.
-x	For generation-range, all generations within the range 1 through x. For level-range, all levels within the range 0 through x. For example, QUERYLOG GENERATION -2 includes generations 1 and 2. QUERYLOG LEVEL -3 includes levels 0, 1, 2, and 3.
x-	For generation-range, all generations within the range from number x through the highest generation. For level-range, all levels within the range from number x through the highest level. For example, QUERYLOG Level 1- includes levels 1, 2, 3 and so on up to the highest level.

Notes

• When query logging is enabled, queries to the database may be slower. Performance depends on how many members are being tracked and the size of the query.
• If the configuration file name does not match the name of the database or the configuration file is located in a place other than the ARBORPATH\App\appname\dbname directory, Essbase ignores query logging.
• You can place QUERYLOG settings in any order in the configuration file, but QUERYLOG [dimension_name] must precede any settings that specify Hybrid Analysis members or any setting that specify members by generation or level.
• If, in the configuration file, QUERYLOG ON is missing or if QUERYLOG OFF is set, query logging is disabled.
• If generation and level settings cause contradictions in the configuration file, the following precedence rules apply:
• generation numbers (highest priority)
• level numbers
• member names (lowest priority)
For example, if a member belongs to both level 1 and generation 2 and the settings QUERYLOG GENERATION 2 and QUERYLOG NONE LEVEL 1 are in the configuration file, the generation setting takes precedence, and members of generation 2 are logged by generation number.

Tips

• To view query log output easily, change the file extension .QLG to .XML, and then using the Internet Explorer or Netscape browser view the .XML file.
• If Essbase is not producing a query log file as expected, view the dbname.log file in the ARBORPATH\App\appname directory to search for query log messages.

Sample Query Log Configuration File

# Log the Product dimension
QUERYLOG [Product]
# Log Hybrid Analysis members of Product, if applicable
QUERYLOG LOGHAMBRS ON
# Log the Market dimension
QUERYLOG [Market]
# Log members of generation 2 of Market by generation number
QUERYLOG GENERATION 2
# Display log output in cluster format
QUERYLOG LOGFORMAT CLUSTER
# Create log file in C:\QUERYLOG\
QUERYLOG LOGPATH C:\QUERYLOG\
# Start a new log file after an individual log file size reaches 2 MB
QUERYLOG LOGFILESIZE 2
# Turn off query logging after the total size of all log files reaches 1024 MB (1 GB)
QUERYLOG TOTALLOGFILESIZE 1024
# Enable query logging
QUERYLOG ON

Sample Query Log Output

  <?xml version="1.0" encoding="UTF-8" ?> 
- <root>
  - <session>
     <bootuptime>Wed Jul 23 15:27:26 2002</bootuptime> 
   - <logsettings>
    - <dimensions>
     - <logdim name="Product">
     - <logdim name="Market">
        <spec>GENERATION 2</spec> 
      </logdim>
     </dimensions>
  - <othersettings>
     <logformat>cluster</logformat> 
     <logpath>C:\QUERYLOG\</logpath> 
   </othersettings>
   </logsettings>

Note

Sample Cluster Output

<query>
 <user>User1</user>
 <time>Tue Aug 13 12:29:49 2002</time>
 <subquery>
  <cluster size="2">
   <dim size="2">
    <member>100</member>
    <member>200</member>
   </dim>
   <dim size="1">
    <member>Market</member>
   </dim>
  </cluster>
 </subquery>
 <subquery>
 <cluster size="2">
  <dim size="1">
   <member>300</member>
  </dim>
  <dim size="2">
   <member>Market</member>
   <generation>2</generation>
  </dim>
 </cluster>
 </subquery>
 <elapsedtime>0.016 seconds</elapsedtime>
</query>

Sample Tuple Output

<query>
 <user>User1</user>
 <time>Tue Aug 13 12:28:14 2002</time>
 <subquery>
  <tuples>
   <tuple>
     <member>100</member>
     <member>Market</member>
   </tuple>
  </tuples>
 </subquery>
 <subquery>
  <tuples>
   <tuple>
    <member>200</member>
    <member>Market</member>
   </tuple>
  </tuples>
 </subquery>
 <elapsedtime>0.02 seconds</elapsedtime>
</query>

In previous Essbase releases, using DATACOPY on a dense dimension can create blocks populated with #MISSING. This is done deliberately in some instances, because most Essbase batch calculations operate only on existing data blocks. Therefore, DATACOPY is also used to ensure that Essbase creates all necessary data blocks prior to batch calculation.

But if the creation of #MISSING blocks is not required, you may want to avoid the increase in size of the index and page files, and the possibly slower performance that results. For example, a default calculation visits every #MISSING block.

To support that goal, Essbase now provides a SET COPYMISSINGBLOCK command that allows DATACOPY to avoid creating #MISSING blocks during the copy of data from a dense dimension.

Syntax

The default behavior is for the #MISSING blocks to be created (SET COPYMISSINGBLOCKS ON), to provide backward compatibility.

Notes

The enhanced DATACOPY command prevents new #MISSING blocks from being created when a DATACOPY (partial block copy) on a dense dimension is requested. It does not remove existing #MISSING blocks.

A message is added to the Essbase server log to indicate the number of data blocks being copied from the source data blocks. The number of #MISSING blocks skipped, if any, is also reported in Essbase server log.

Example

[Fri May 31 10:35:03 2002]Local/Test6/Test6/essexer/Info(1012576)
Datacopy command skipped creating [1] target data blocks with CopyMissingBlock OFF

Invalid Block Header Identification and Correction

Top

Essbase helps you assess the severity of invalid block header errors (IBH) and provides tools to repair the corruption indicated by the presence of some IBHs.

There are two types of IBH errors that can be corrected:

• Type mismatch, where the Essbase version number in a data block does not match the version number in the index entry. Type mismatch is often due to a corrupted data block header, a corrputed index entry, or the attempted migration of an unsupported version.
• Block key mismatch, where the block key does not match in locations where it should. Block key mismatches usually indicates a corrupted data block header or a corrupted index entry.

Finding IBH Errors

Syntax

appName and dbName are optional, but be sure to specify an application name if you specify a database name. You can substitute "xxxx" for either appName or dbName, or both. "xxxx" is a wildcard for the application name and database name.

percentage is the value of the percentage of IBHs reported relative to the number of level 0 blocks on disk. Once Essbase reaches the threshold, Essbase sends a message to the client requesting that the user rebuild the database, and shuts down. Valid values are whole numbers 0 through 100.

If you receive a message suggesting you rebuild a database, do so using procedures described in the Database Administrators Guide.

If messages are written to the client or server log indicating the presence of IBH errors, but the threshold that requires the database be rebuilt is not reached, you can either rebuild the database or you can find and fix the errors using instructions in the next section.

Fixing IBH Errors

• The Maxl command alter database dbName validate data to filename. The file name is the name of the client or server log file. For instructions, see alter database.


• Three C-API functions locate, retrieve, and fix IBH errors: EssLocateIBH, EssGetIBH, and EssFixIBH.

Operating System Errors

OK/INFO - 1006016 - Invalid block header: Illegal block type.
OK/INFO - 1006046 - A read from file [D:/ESSBASE\APP\Migr500\Basic\ess00001.pag], to address [0x05f71458] with handle [6] from offset [1081683835] for [992] bytes, failed with error [13] and O/S return code [23] after [-1] bytes.
OK/INFO - 1070121 - Current size of file
[D:/ESSBASE\APP\Migr500\Basic\ess00001.pag] is [2147475435] bytes.
OK/INFO - 1006050 - For transaction [Basic], the [3088] byte Input Transfer Buffer is at address [0x05f71458] and the [3088] byte Output Transfer Buffer is at address [0x026bf2b0].
ERROR - 1006004 - Unable to Read Information From Page File.
ERROR - 1241101 - Unexpected Essbase error 1006004.

In the example log output above, Essbase issued a read request at an offset of 1081683835 which is a valid offset based on the size of the page file. The request is to read 992 bytes starting from that offset. However, hardware problems cause the read request to fail, and the OS return code for failure is returned (13 in this example). In this situation, Essbase is unable to continue reading the page file, and the IBH diagnosis operation stalls.

Improved Exception Handling for Unix Platforms

Top

If OLAP Server shuts down abnormally and cannot restart, OLAP Server generates an exception log, .XCP, to help troubleshoot the problem. For Hyperion Essbase releases 6.5.1 and greater, on Unix platforms, Essbase also creates a core file with additional information about the exception. The location of the core file depends on the type of abnormal shutdown:

• If the application or database shut down abnormally, the core file is in $ARBORPATH/app/Sample/ESSSVR.date. The location of the core file is also specified in the application log. For example, if the Sample application shut down abnormally, the core file is hyperion/essbase/app/Sample/ESSSVR.Wed_Jun_10_22_49_33_2002/core.
• If OLAP Server shut down abnormally, the core file is in $ARBORPATH/ESSBASE.date. The location of the core file is also specified in the server log. For example, if OLAP Server shut down abnormally, the core file is hyperion/essbase/ESSBASE.Wed_Jun_10_22_49_33_2002/core.

If present, send both the core file and the .XCP file to Hyperion Technical Support to determine why the abnormal shutdown occurred. If you have old core files from previous abnormal shutdowns, you may remove them to free up disk space. Do not remove recent core files unless you are certain that you will not need to send them to Hyperion Technical Support.

Application Memory Manager

Top

Essbase enables memory management by providing controls on the maximum amount of memory an application can use. Essbase also writes messages to an application log as soon as the application's memory use exceeds 90% of the limit that you set. After the limit is met 100%, OLAP Server stops the application.

To enable OLAP Server to manage application memory use:

1. Create a new memory configuration file, or edit an existing memory configuration file, using the instructions in Memory Configuration File.
2. Save the memory configuration file in the ARBORPATH/bin directory.
3. Start the application. You must restart an application after you change its memory configuration file, because the application reads the memory configuration file only once, during start up.
4. Monitor the log.

Application is using [n] bytes of memory. It is more than 90 percent of the limit set in the memory config file.

If the application uses 100% of the memory as limited by the Memory Configuration File, OLAP Server writes this error message to the application log and stops the application:

Application is using [n] bytes of memory, and is requesting a new memory block of [n] bytes. The memory has exceeded the limit.

When the 90% warning messages appear in the log, the database administrator may wish to take corrective action:

• Increase the memory limit in the relevant memory configuration file and restart the application if more memory is available.
• Examine cache sizes and reduce the size if possible.
• If neither of these actions is possible or resolves the memory problem, work loads or applications may require additional adjustments or tuning.

Memory Configuration File

Name the file config.mem to control all applications on the OLAP Server, or name it config.mem.appName to control just one application. Because Essbase looks for the relevant application-specific memory configuration file before it looks for the server-wide file during application start-up, you can create one generic file (config.mem) to configure all the applications, and also create individual application memory configuration files (config.mem.appName) for applications that need different maximum memory settings.

Make sure the file is located in the ARBORPATH/bin directory.

Add the MEMORYLIMIT configuration setting to the configuration file, using this syntax:

MEMORYLIMIT n G | M

n is a whole number, the number of gigabytes or megabytes. Use G or M to indicate gigabytes or megabytes.

Recommended values:
 

Operating System	Recommended memory limit
Windows NT Windows 2000 without the 4 GB RAM option	2 G
Windows 2000 with the 4 GB RAM option	3 G
Solaris	3 G
HPUX	1741 M
AIX	2 G

Use these recommended values or, if lower, the amount of physical memory plus swap space available. For example, if a computer has only 2 GB of combined physical memory and swap space, and other applications on that computer require 1 GB, then the value of MEMORYLIMIT should be no more than 1 GB.

Example

This allows OLAP Server to use up to 2 GB memory for an application.

MEMORYLIMIT 1024 M

This allows 1 GB memory for an OLAP Server application.

Notes

• You can set MEMORYLIMIT to any whole number value, thus you can adjust OLAP Server to write a message to the application log after 90% of any particular memory value has been exceeded. For example, if you want a message written to the log after 1 GB of memory is exceeded, set MEMORYLIMIT to 1 G, and warnings are written once OLAP Server exceeds 90% of 1 GB.
• OLAP Server builds a cache of 48 MB on startup to handle allocations up to 64 KB each. If you notice a rise in memory requirements from releases prior to 6.5.1, this change in cache allocation may be the cause. The maximum size of this internal cache is 128 MB.

Copyright 2002 Hyperion Solutions Corporation.

All Rights Reserved.