Cross-Platform Migration for Content Manager

Abstract

This document discusses how to perform cross-platform migration for Content Manager.

Contents


Because of changing business requirements, there may be a need to migrate from an earlier Content Manager system to a new version using a different platform. For example, you may want to migrate a Content Manager for z/OS V7 system to a Content Manager for Multiplatforms V8.2 system. Although there is not an official IBM-supported migration utility available to do this task, we recommend the following approach, used as is:
  1. Migrate the data from the source platform to the target platform.
  2. Using the official migration tool, migrate the earlier version of Content Manager system (DB2 data only) that is now on the target system to the latest version of Content Manager.

For example, if you need to migrate Content Manager V7 for z/OS to Content Manager V8.2 for AIX, we recommend the following migration path:
  1. Migrate Content Manager V7 data from z/OS to AIX.
  2. Migrate Content Manager from V7 to V8.2 on AIX.

The reasons for this approach are the following:
  • When performing data migration from a source platform to a target platform for earlier Content Manager data, it involves less database tables. It is therefore easier to perform the data migration. Of course, this is only applicable when dealing with Version 7 to Version 8 Content Manager cross-platform migration.
  • This approach does not require a running version of the latest Content Manager on the source platform; you only need to move the DB2 data to the target system.

The rest of this document describes how to migrate the Content Manager data from the source platform to the target platform. We cover the Library Server data migration from z/OS to AIX. This process is also applicable for a migration from AIX to z/OS, and for a migration between z/OS and Windows platforms. We only address the Library Server migration. If there is a need to move the Resource Manager(s) from or to z/OS, this requires customized export and import routines that are beyond the scope of this document.

Cross-platform Content Manager data migration process overview
The following figure shows the general migration flow when migrating from a Library Server on a z/OS to AIX or vice versa.


Migration flow

As shown above, the migration process includes the following steps:
  1. Install the Library Server on the target system.
  2. Drop referential integrity constructs (RIs) of the Library Server database.
  3. Unload the data from the source system.
  4. Move the data to the target system.
  5. Import data onto the target system.
  6. Create referential integrity constructs (RIs) onto the target system.
  7. Perform bind.
  8. Create access modules.
  9. Test target system.

Important: The migration process we describe here is from the result of practical lab exercises performed when writing the associated IBM Redbook. The described method of moving a Library Server from one system platform to another is not officially supported by IBM. You should use the information on an "as is" base. We provide this information to give you a general understanding of what to do when you encounter this migration requirement. You should contact your IBM service representative if you need to perform this type of migration.

Migration considerations and preparation
Prior to addressing each step in the migration process flow, you need to consider all of the migration-related issues, and plan and prepare for the migration. The issues you need to consider include available disk space, system backup, and time available for the migration process. Although we are only migrating the Library Server database, the files generated from unloading the Library Server data can easily go up to gigabytes. This, in turn, may have an impact on the time needed to run the migration task. Some of the questions you should ask yourself include:
  • Do I have enough disk space to do this migration?
  • Do I have enough time to do it without impacting the production system?
  • If I am doing this during the prime time, how will this impact the production system?
  • Do I have a set of test suites to validate the migration?
  • How long does it take me to validate that the migration is successful?
Make sure you ask enough questions, plan ahead for the possible problems, and know how to handle them.

Step 1: Install Library Server on target system
This involves installing the Library Server to your target system and setting up all the necessary environment variables. This includes setting up the correct path to your stored procedure programs, which are stored in the ICMSTSysControl table.

Important:
  • The user ID used to install the Library Server must be the root user ID.
  • The database schema of the Library Server database on AIX must be the same as on z/OS.
  • The database name of the Library Server database on AIX must be the same as on z/OS.
  • The user ID used as administration user on the z/OS must be a DB2ADMIN user on the AIX machine.

After the database is created, run the DB2LOOK command to create the DDL for this database from the DB2 command window:
    db2look -d <db name> -e > ls.ddl
Where
    <db name> is the Library Server database.
    > ls.ddl pipes the output to ls.ddl. You can use any name for the output file.

The output file (in our example, ls.ddl) is a DDL file for the database, including all the tablespaces, tables, index, and referential integrity information for that database. The output is stored in a plain text file and can be used as input for other commands. Use only the last part of the output file, starting after the word “foreign.” When you perform a search for the word “foreign” in the output file, you can find all the referential integrity construct definitions. These definitions must be rebuilt in a later step of the migration. For this purpose we used this part of the output file of DB2LOOK.

The following is a DDL file sample:

-- DDL Statements for foreign keys on Table "ICMADMIN"."ICMSTPRIVSETS"

ALTER TABLE "ICMADMIN"."ICMSTPRIVSETS"
ADD CONSTRAINT "SQL020802165247620" FOREIGN KEY
("PRIVSETCODE")
REFERENCES "ICMADMIN"."ICMSTPRIVSETCODES"
("PRIVSETCODE")
ON DELETE CASCADE
ON UPDATE NO ACTION;

Step 2: Drop referential integrity constructs of LS database
This involves dropping the referential integrity constructs (RIs) of the Library Server (LS) database. Without the referential integrity constructs, you can load the data with the DB2MOVE IMPORT utility; otherwise, you get errors during the import.

To generate a list of the existing RIs, perform the following DB2 select statement against the database from the DB2 command window:
    db2 select tbname, relname, refkeyname from sysibm.sysrels > sysrel.txt

You should get a list of the existing RIs for the Library Server database. The following is a sample output of the select statement, with table name (TBNAME), referential integrity (RELNAME), and reference column name (REFKEYNAME):

TBNAME RELNAME REFKEYNAME
--------------------------- ------------------ -------------------
ICMSTPRIVSETS SQL030925164851180 ICMSTPRIVSETCODES
ICMSTPRIVSETS SQL030925164851210 ICMSTPRIVDEFS
ICMSTPRIVGROUPS SQL030925164852210 ICMSTPRIVGROUPCODE
ICMSTPRIVGROUPS SQL030925164852230 ICMSTPRIVDEFS
ICMSTDOMAINPRIVSET SQL030925164852790 ICMSTADMINDOMAINS
ICMSTDOMAINPRIVSET SQL030925164852810 ICMSTPRIVSETCODES

Save the list in a file. For example, you can pipe the select statement output to a file, sysrel.txt. Edit the file so that it includes the drop statements for all the RIs. The following is a sample of the RI drop file:

ALTER TABLE ICMSTPRIVSETS DROP CONSTRAINT SQL030925164851180;
ALTER TABLE ICMSTPRIVSETS DROP CONSTRAINT SQL030925164851210;
ALTER TABLE ICMSTPRIVGROUPS DROP CONSTRAINT SQL030925164852210;
ALTER TABLE ICMSTPRIVGROUPS DROP CONSTRAINT SQL030925164852230;
ALTER TABLE ICMSTDOMAINPRIVSET DROP CONSTRAINT SQL030925164852790;
ALTER TABLE ICMSTDOMAINPRIVSET DROP CONSTRAINT SQL030925164852810;

Run the RI drop file to drop all the referential integrity of the database.

Step 3: Unload data on source system
Use the DB2MOVE EXPORT command to unload the data from the z/OS DB2. This utility gets the data and the database definition from the source z/OS database and stores it, together with the restoring information, in files. You can run the utility from a Windows workstation. Make sure you connect this workstation with the z/OS DB2. The DB2MOVE is also available on AIX. Execute the DB2MOVE EXPORT command from DB2 command window as follows:
    db2move <db name> export -tc <table-creators> -tn * -sn <schema-names> -u <user ID> -p <password>
Where:
    <db name> is the Library Server database.
    <table-creators> is the creator of the tables.
    <schema-names> is the schema name of the Library Server database.
    <user ID> is user ID with administration rights on the Library Server Database.
    <password> is the valid password of the user ID.

The following is a sample output of what happens when you execute the DB2MOVE EXPORT command:

***** DB2MOVE *****

Action: EXPORT

Start time: Fri Sep 26 14:54:47 2003

Exporting tables created by: ICMADMIN;

All table names beginning with: *;
Server: DB2 for MVS V7.1.1

EXPORT: 4 rows from table "ICMADMIN"."ICMUT01000001"
EXPORT: 4 rows from table "ICMADMIN"."ICMSTACCESSCODES"
EXPORT: 5 rows from table "ICMADMIN"."ICMSTCOLLNAME"
EXPORT: 1 rows from table "ICMADMIN"."ICMSTACCESSLISTS"
EXPORT: 400 rows from table "ICMADMIN"."ICMSTCOMPILEDACL"
EXPORT: 97 rows from table "ICMADMIN"."ICMSTCOMPILEDPERM"
EXPORT: 121 rows from table "ICMADMIN"."ICMSTATTRDEFS"
EXPORT: 84 rows from table "ICMADMIN"."ICMSTATTRGROUP"
EXPORT: 23 rows from table "ICMADMIN"."ICMSTCOMPDEFS"
EXPORT: 380 rows from table "ICMADMIN"."ICMSTCOMPATTRS"
EXPORT: 3 rows from table "ICMADMIN"."ICMSTCOMPATTRSFK"
EXPORT: 23 rows from table "ICMADMIN"."ICMSTCOMPVIEWDEFS”

The exported files resulting from the DB2MOVE EXPORT command are in IXF format. The IXF format is a preferred DB2 interchange format. When using this, we do not have to perform additional data conversion (such as from EBCDIC to ASCII), because this is done automatically.

Tip: To estimate the size of the output-.IXF files, you should run a test with your real data. We do not provide any formula here since there are too many dependencies that can affect the calculation and we do not have a way to accommodate them.

Note: The user ID that is connected to the host database needs to have the correct level of authority to bind plans (BINDADD, BIND).

Step 4: Move data to target system
Move the data to the target system. If you are running the DB2MOVE IMPORT from the same workstation, you do not need to move the data. Within the same Windows workstation, you can connect it to the z/OS system, unload the data, connect it to the AIX system, and run the import routine directly from the workstation. If you have a large database, for performance reasons, you may want to bring the data to the target system, and then run the import routine.

Step 5: Import data on target system
To import data onto the target system, use the DB2MOVE IMPORT REPLACE_CREATE command. With this option, during the data import, the tables that are not already defined on the Library Server database are created automatically. Execute the DB2MOVE IMPORT command from DB2 command window as follows:
    db2move <db name> import -io replace_create -u <user ID> -p <password>
Where:
    <db name> is the Library Server database.
    <user ID> is the user ID with administration rights on the Library Server database.
    <password> is the valid password of the user ID.

Important: Before starting with the data import, remove the control statement for table ICMSTSysControl from the DB2MOVE control file.
After you create and load the tables, it may be necessary to update the ICMSTSysControl table of your Library Server database. Compare the values from your z/OS table with the one on the AIX server. Do not touch the path entries and the decoded columns. You may find a difference in the System Flag column, which is set to 32 on the AIX. This is correct. Make sure that the Library Server ID on your AIX is set to the same value as on the z/OS. Otherwise nothing will work.

Step 6: Create referential integrity constructs of LS database
After successfully loading the data into the tables, you need to rebuild the referential integrity constructs (RIs) of the Library Server (LS) database. To do this, use the DDL generated by the DB2LOOK after installing the Library Server database.

Note: Run only the last part of the DDL, which generates the RIs. Search for “foreign” in the DDL to find where this section begins.

The following shows a sample file that is used to create referential integrity:

-- This CLP file was created using DB2LOOK Version 7.2
-- Timestamp: Mon Sep 29 20:34:16 2003
-- Database Name: MVSLSDB
-- Database Manager Version: DB2/6000 Version 7.2.8
-- Database Codepage: 819

-- DDL Statements for foreign keys on Table "ICMADMIN"."ICMSTPRIVSETS"

ALTER TABLE "ICMADMIN"."ICMSTPRIVSETS"
ADD CONSTRAINT "SQL030929202519390" FOREIGN KEY
("PRIVSETCODE")
REFERENCES "ICMADMIN"."ICMSTPRIVSETCODES"
("PRIVSETCODE")
ON DELETE CASCADE
ON UPDATE NO ACTION;

ALTER TABLE "ICMADMIN"."ICMSTPRIVSETS"
ADD CONSTRAINT "SQL030929202519430" FOREIGN KEY
("PRIVDEFCODE")
REFERENCES "ICMADMIN"."ICMSTPRIVDEFS"
("PRIVDEFCODE")
ON DELETE RESTRICT
ON UPDATE NO ACTION;

To run this sample file, use the following DB2 command in the DB2 command window:
    db2 -xvf <sample file name>

Step 7: Bind plans
First, you have to bind the plans for the DB2 connect. Use the DB2 Client Configuration Assistant to bind the plans. You then need to bind the Content Manager plans on AIX. Use the script that comes with the installation. The bind script name is icmbindlsdb.sh. It is located in the /usr/lpp/icm/config directory.

The following is a screen captures of binding the Content Manager plan on AIX.

Binding Content Manager plan on AIX

Step 8: Create access modules
You need to create the access modules for the item types. Up to this point, we only migrated the DB2 data. There is still a need to generate the static access module.
To create all the access modules again, run the following command against the AIX Library Server database:
    JAVA TRebuildCompTypeICM <db alias> <user ID> <password> <schema-name> <output file>
Where:
  • <db alias> is the alias of the Library Server database.
  • <user ID> is the user ID with administration rights on the Library Server Database.
  • <password> is the valid password of the user ID.
  • <schema-name> is the schema of the Library Server database.
  • <output file> is the name of an output file to write messages into (messages produced by the command).
You can run this command from the System Administration Client workstation or from the AIX server.

Note: If you are running the program from your System Administration Client workstation, the AIX Library Server database must be registered.

Step 9: Test target system
You need to validate the migration process by testing the AIX Library Server that is connected to the z/OS Resource Manager. Before you can view an object, you have to send a new encryption key to the Resource Manager. After this action, you can store and retrieve new objects, and also retrieve the objects that have been stored on the z/OS system earlier.

To set a new encryption key, do the following:
  1. Start the System Administration Client.
  2. Expand the Library Server database (ICMNLSDB) —> Library Server Parameters —> Configurations.
  3. From the right-hand panel, double-click Library Server Configuration.
  4. Click Refresh encryption key.
  5. You will receive a warning message saying that it is recommended that you only do this at the least traffic time. The warning message prompts you to continue. Click Yes and the key is refreshed. There will not be any confirmation message specifying that it is completed; but the encryption key is refreshed.

Summary
There are nine steps involved in the migration of a Library Server from z/OS to AIX. We recommend that you use these nine steps as a general migration process flow. In principal, regardless of what the source system platform is and what the target system platform is, the steps involved are generally the same. They may differ slightly in the set up of the user IDs and user rights, the way the servers are installed, and how to perform tasks such as binding of DB2 plans. You need to work with the system administrators to work out the details. Because the process requires mostly standard DB2 tools, it is important to be aware of the current versions of DB2 on your systems. As a general rule, DB2 servers are compatible with the lower versions of the clients, but not vice versa. For example, Version 8 DB2 server can work with Version 7 DB2 client; however, you cannot use a Version 8 DB2 client with a Version 7 DB2 server.

Note: The database structure of the Content Manager for Multiplatforms and the one for z/OS are really identical. The layout and the data itself are also identical. Otherwise, the migration would not have worked.

When you plan for a migration involving a large Library Server database, pay special attention to the time it may take for you to complete the task and the available disk space. You want to make sure you have adequate time to convert all of them. There may also be some problems that are environment dependent. For example, a decimal point may mean a comma in one system and an actual decimal point in another system. Language conversions may vary as well.

Special Notices

This material has not been submitted to any formal IBM test and is published AS IS. It has not been the subject of rigorous review. IBM assumes no responsibility for its accuracy or completeness. The use of this information or the implementation of any of these techniques is a client responsibility and depends upon the client's ability to evaluate and integrate them into the client's operational environment.

Profile

Publish Date
22 December 2003


Rating: Not yet rated


Author(s)

IBM Form Number
TIPS0350