****************************************************
*       _   __  _____   ______                     *
*      / | / / / ___/  / ____/                     *
*     /  |/ /  \__ \  / __/                        *
*    / /|  /  ___/ / / /___                        *
*   /_/ |_/  /____/ /_____/     index migration    *
*                               readme             *
*                                                  *
****************************************************

DB2 Net Search Extender indexes built under 32-bit DB2 instances 
are not compatible with 64-bit instances. Trying to search on 
an index, or to update an index, that was built under a 32bit 
instance in a 64bit DB2 instance always results in an error message 
preventing the operation from completion.

To avoid that indexes have to be rebuilt completely, we offer a tool
to migrate the indexes offline. 
The migration affects only a small number of metadata files, and
is therefore performed quickly, and without large amounts of data 
movement.

To perform this migration, execute the shellscript which is delivered 
within this package.

Information about the usage of the shellscript can be found below.


Planning:
=========

Index migration has to be performed prior to a 32 to 64bit migration
of the instance and the databases that has to precede the V8 to V9 migration.
The current migration tool does not support a migration of indexes
restored in an already migrated V9 instance.

The sequence of steps for migrating a V8 32bit instance with NSE indexes
to a V9 64bit instance is therefore:
- migrate NSE indexes from 32 to 64 bit
- migrate the DB2 V8 instance from 32 to 64 bit
- migrate the DB2 instance from V8 to V9
- migrate the NSE instance metadata in the V9, using db2extmdb

For DB2 V8 32bit AIX environments:
==================================

* logon as the DB2 instance owner
* extract the NSE_32_64_Idx_Migr_Tool_AIX_SOL.tar.gz archive 
* cd into the NSE_32_64_Idx_Migr_Tool_AIX_SOL directory
* make sure that: - DB2 is up and running
                  - NSE is stopped
				  - no other processes try to get an exclusive lock 
				    on the index files located in the index directory
					(where the index directories are located, was decided
					 when the index was created)

* run /usr/sbin/slibclean to clear the AIX library cache. This is
  necessary, to avoid conflicts between installed NSE libraries and libraries of the
  same name in the NSE_32_64_Idx_Migr_Tool_AIX_SOL directory. Depending on your system 
  configuration you may have to have root authority to be able to run slibclean.

* run the shellscript ctemigridx.sh:
  the script can be run in two different modes. 
  The first mode takes a database name as argument, and automatically determines all
  existing indexes in that database and offers to migrate them all at once, or selectively.
  - Mode 1: ./ctemigridx.sh -dbname <database-name>
  
  Mode 1 will establish a database connection and queries all data that is needed
  from the NSE database tables. After that it shows a list of indexes that are ready
  to get migrated. You can choose one index or all listed indexes. Adding the "-check"
  parameter to the command, will perform all the necessary steps without the migration.
  Example: ./ctemigridx.sh -dbname sample
  
  Mode 2 can be used to migrate a particular index, if you know the indexname already, and 
  want to target the migration of this index. This mode is useful if you have a large 
  number of indexes, and want to avoid going through a long menu of indexes. It also comes
  handy if you are running repeated tests with an individual index. 
    
  - Mode 2: ./ctemigridx.sh -i <index identifier> -p <index directory> [-showmap]
  
  for example:
  ./ctemigridx.sh -i IX123456 -p /home/user/sqllib/db2ext/indexes
  
  The index directory has to be specified in the same way as it is used at index creation time.
  The index directory always has a NODE0000 subdirectory which then contains the index itself.
  Currently the script only supports single-node-systems.
  
  If you add the "-showmap" flag, the logfile will show a dump of the migrated index attribute
  (sections and attributes) for additional verification purposes.
  
  ./ctemigridx.sh -i IX123456 -p /home/user/sqllib/db2ext/indexes -showmap
  
* When the Net Search Extender index migration is done, some *.32 files can be found in the 
  index directory. According to the indexes that has/have been migrated these new files can be
  found:
  
  - IX123456.as.32 (Backup of the old 32 bit IX123456.as file)
  - IX123456.an.32 (Backup of the old 32 bit IX123456.an file)
  - IX123456.tf.32 (Backup of the old 32 bit IX123456.tf file)
  
  The migration uses a temporary work directory that is created during migration, if it is not
  already present. In case it is not there, a TMP_IX123456 directory can be found inside 
  the Net Search Extender index directory.
  After verification of the 64 bit Net Search Extender index(es), the *.32 files can be removed or
  transfered to another location in terms a backup.
  
* After this, index migration is complete, and the user can proceed to perform the instance 
  migration to 64 bit as described in the DB2 doumentation.

For DB2 V8 32bit Solaris environments:
====================================== 

All steps are identical to the ones that need to be done for AIX, only the slibclean step is 
not needed. slibclean does not exist on Solaris.


Current Limitations:
====================
Its not recommended to do database migration by restoring it from the backup image.The
sequence of steps mentioned in Planning section should be strictly followed.