Migrating DB2 OLAP Server

This section describes how to upgrade from an earlier version of DB2 OLAP Server to DB2 OLAP Server Version 8.2 on the same computer and describes what occurs during the upgrade process.

Supported API Versions

Programs compiled with the Version 8.2 Application Programming Interface do not work with earlier server releases. DB2 OLAP Server API programs compiled with header files from a specific release must use the libraries from the same release. For example, if the header files are from V7.1, you cannot use V8.1 run-time libraries. If your header files were from V8.1, you cannot use V8.2 runtime libraries.

Table 29 describes compatibility among API, runtime library, and Analytic Server versions.

Table 29. API Compatibility
API Header Files Runtime Libraries Analytic Server
DB2 OLAP Server V8.1 (Essbase 6.5.x) DB2 OLAP Server V8.1 (Essbase 6.5.x)
  • DB2 OLAP Server V8.1 (Essbase 6.5.x)
  • DB2 OLAP Server V8.2 (Essbase 7.x)
DB2 OLAP Server V8.2 (Essbase 7.1.x) DB2 OLAP Server V8.2 (Essbase 7.1.x)
  • DB2 OLAP Server V8.1 (Essbase 6.5.x)
  • DB2 OLAP Server V8.2 (Essbase 7.x)

Upgrading applications that use APIs

DB2 OLAP Server V8.2 (Essbase Release 7.1) introduces aggregate storage databases, which support multi-million member outlines. Compared to block storage databases, the number of members in aggregate storage databases may be several times larger. As a result, certain precautions are necessary when you upgrade applications that use APIs that retrieve members from the server. For detailed information on the necessary precautions, see the section on migration in the Analytic Services API Reference.

Compatibility of non-Unicode applications between client and server software

V8.2 provides backward compatibility with earlier clients. This includes V8.1 (Essbase 6.5.x) and later of Application Manager, the Spreadsheet Add-in, and the MaxL Shell. It does not include Administration Services.

For information about release compatibility with Administration Services, see the Administration Services Installation Guide .

Understanding input/output defaults and upgrading

Read this section before upgrading to understand the two I/O access modes available, and how OLAP databases are affected by an upgrade in terms of cache sizes and the I/O access modes.

Determining which I/O access mode to use

Buffered I/O uses the buffer cache of the file system. Direct I/O bypasses the file system buffer cache and is able to provide faster response time and more potential to optimize cache sizes. Your databases might be using buffered I/O or direct I/O.

V8.2 (Essbase 7.x) and V8.1 (Essbase 6.5.x) databases use buffered I/O by default, unless essbase.cfg contains the setting DIRECTIO TRUE. When upgraded to V8.2, all V8.1 databases use the I/O access mode that was used in that release. The I/O access mode for any database can be changed, using the database settings.

The DIRECTIO setting is server-wide, and affects all databases. With Version 8, the access mode specified by DIRECTIO is only read once for each database, after upgrading or first creation of a database. Thereafter, the I/O access mode must be changed per database using the database settings.

Changing or preserving the I/O access mode

The I/O access mode is a database setting stored in the security file, rather than a server-wide essbase.cfg file setting that affects all databases. The essbase.cfg configuration-file setting DIRECTIO TRUE|FALSE is maintained for backward compatibility with V8.1. It is also used to provide a default value for newly created databases and for databases that are upgraded from an earlier release.

If a DIRECTIO setting exists in the essbase.cfg file at upgrade time, only newly created or upgraded databases will be affected by the setting. DB2 OLAP Server reads the I/O access mode specification from essbase.cfg once for each database, and copies that information to the security file (essbase.sec). Thereafter, if you want to change the I/O access mode used by any database, you must change it at the database level using the database setting.

The I/O access mode can be set from Administration Services Console, MaxL (alter database set io_access_mode), or programmatically using the Analytic Services Application Programming Interface.

If you set a database to use direct I/O, DB2 OLAP Server will attempt to use direct I/O the next time the database is started. If direct I/O is not available on the platform at the time the database is started, DB2 OLAP Server will use buffered I/O, which is the default. However, DB2 OLAP Server stores the I/O access mode you selected as a setting in the security file, and will attempt to use that I/O access mode each time the database is started.

Understanding how cache sizes are affected by an upgrade

When you upgrade, your cache sizes for existing databases will not change. If you are currently using the default I/O access mode (direct), your cache sizes for existing databases are probably large, because direct I/O requires larger cache sizes. If, after you upgrade, you plan to use the default I/O access mode (buffered), you should reduce the cache size settings before upgrading or before you start the upgraded database.

The following list explains default cache sizes for upgrading DB2 OLAP Server databases, for each I/O access mode:

To override the defaults after upgrading, change the database settings or properties before you start the upgraded database for the first time.

For more information on buffered I/O and direct I/O, see the Database Administrator's Guide.

Upgrading databases to Version 8.2

This section provides migration details and tells you how to upgrade databases from earlier versions of DB2 OLAP Server to Version 8.2.

When does DB2 OLAP Server migrate the files?

DB2 OLAP Server migrates databases when the database is started. By default, a database is set to start when its application starts. The OLAP kernel checks for files resulting from previous unsuccessful migrations, restarting the migration if necessary.

DB2 OLAP Server migrates the ESSxxxx.IND, dbname.ESM, and the dbname.TCT files when the database is started. DB2 OLAP Server migrates the ESSxxxx.PAG file as data blocks are accessed; hence, the .PAG file migrates when you run the VALIDATE command after starting the database. After the kernel files are migrated, they are not backwards-compatible with the earlier release.

Steps for upgrading databases to Version 8.2

The following steps explain how to upgrade to Version 8.2 from an earlier release on the same computer. To move databases to another computer without upgrading, see Moving applications and databases to another computer. To upgrade and migrate databases to another computer, see Upgrading and moving applications and databases at the same time.

After migration, you can restore databases from earlier releases only from backups. Therefore, be sure to back up databases before starting to upgrade.

To upgrade to Version 8.2 on the same computer, proceed in the following order for each database:

  1. Run the alter database validate command in MaxL against the database.

    If the command returns errors, revert to a backup that is free of those errors.

  2. Back up all application files, database files, and the security file.
  3. If you are using LROs in a production environment, run the LISTLINKEDOBJECTS command in ESSCMD before upgrading. This command returns a list of LROs contained in the databases.
  4. Stop the Analytic Server and Integration Server, if they are is running.
  5. If you are installing over an existing Analytic Services installation, uninstall the existing release before installing V8.2.

    Uninstalling will not remove the app folders, existing applications, the essbase.sec file, or the essbase.cfg file.

    If you are upgrading on UNIX, you might need to uninstall manually. Back up the installation directory and then remove it before installing V8.2. After removing the installation directory, install Version 8.2, recreate applications and databases, and restore from the backup.

  6. Install DB2 OLAP Server Version 8.2 to the same directory as the earlier DB2 OLAP Server installation.
  7. Start the DB2 OLAP Server Agent (ESSBASE.EXE ).

    If you want to change database settings, this is a convenient point at which to do so. If you change the settings now, you will not have to restart the database to make the settings effective. See Determining which I/O access mode to use for information on the default settings.

  8. Select a database or load an application.
  9. Run the VALIDATE command in ESSCMD against the migrated database. VALIDATE prompts you to specify a name for the error log file that it will use.
  10. If the validation returns only LRO-related errors to the log file after upgrading, you must restore data from the earlier backup and re-create the LROs:
    1. Either restore data from a backup of the database that does not contain LROs, or reload from a database export.
    2. Restart the database in DB2 OLAP Server Version 8.2.

      DB2 OLAP Server migrates the database to Version 8.2 format if the database was restored.

    3. Run the alter database validate command in MaxL against the upgraded database.
    4. Re-create the LROs, using the LISTLINKEDOBJECTS output as a guide. You may need to review the output from LISTLINKEDOBJECTS manually to verify its completeness.
  11. Upon successful completion, unload the database and then back up the Version 8.2 database files.

Moving applications and databases to another computer

To move databases to a different computer, or to upgrade to Version 8.1 on a different computer manually, proceed in the following order for each database:

  1. Run the alter database validate command in MaxL against the database you will migrate.

    If the validation returns errors, revert to a backup that is free of those errors.

  2. Back up all application files, database files, and the security file on the source server (that is, the server from which you are migrating).
  3. Install DB2 OLAP Server on the target server computer.
  4. Copy the ESSBASE.CFG file from the \BIN directory on the source OLAP server to the same directory on the target OLAP server using the file system.
  5. On the target OLAP server, define disk volumes. To allocate a new volume, use alter database statement in MaxL and follow the prompts.

    Consider carefully how you configure your disk volumes. Any changes you make to your disk volumes settings after you have loaded data on the new OLAP Server are reflected only in new data loads; changes are not retroactive.

  6. Use the Migration Wizard in Administration Services to move the application to the target Analytic Server computer.

    The names of the applications and database you create do not need to be the same as the ones on the source server. However, if you make changes to the names, make sure that these changes are reflected as necessary in script files, spreadsheet macros, and API-based applications. In addition, make sure that these changes are clearly communicated to the user base.

    CAUTION:
    Do not move the application directory to the target server through a file transfer via the operating system or via FTP.
  7. Move any ESSCMD or MaxL scripts to the target server using the file system or via FTP. You can use the MaxL ESSCMD-to-MaxL script conversion utility.
  8. Export data from the application on the source server in one of the following ways:
  9. Import data to the new application on the target server.
  10. Recalculate your database if:
  11. Repeat these steps for all other databases on the source server that you want to migrate to the new server.
  12. Migrate security information by recreating user filters, groups, and permissions on the new server.
    CAUTION:
    Moving the security file (ESSBASE.SEC and its backup ESSBASE.BAK) between computers is not recommended or supported.

Upgrading and moving applications and databases at the same time

When you upgrade to a new release of DB2 OLAP Server, you may want to do so on a different computer. You have two options for upgrading and moving at the same time:

To move applications and databases to a different computer, use the Administration Services Migration Wizard. See the Administration Services Online Help for detailed information and instructions.