Migrating from IBM Z Software Asset Management 8.2 to IBM Z Software Asset Management 8.3.1 (SQLite database)

When you upgrade to IBM Z Software Asset Management 8.3.1 for SQLite database, there is some porting of data within the Repository database. New SQLite objects are defined in the Repository. The existing 8.2 GKB database is dropped and re-created with the same database name for 8.3.1.

Before you begin

Make a backup of your 8.2 Repository database by running job HSISUT01 from your 8.2 JCLLIB.

Make a backup or rename your JCLLIB and PARMLIB data sets. IBM Z Software Asset Management 8.3.1 uses the same dataset names for JCLLIB and PARMLIB.

Migration planning and consideration:

If your existing 8.2 Repository database (including LKB/LKU) and GKB use different schema names, then you need to modify the migration jobs to suit your site requirements.
The 8.3.1 Usage Monitor job/started task (HSISUMON/HSIJMON) requires a minimum level of z/OS 2.3 or later. It will fail if run in z/OS 2.2 or earlier.
Each SQLite repository with its own GKB and also its own hsi.SHSMOD1 load library should all be migrated to 8.3.1 at the same time. An 8.3.1 hsi.SHSIMOD1 load library cannot be used by an 8.2 repository.
Housekeeping:
Perform housekeeping on the 8.2 Repository database before you start your migration process. This reduces the time required to migrate all the data.
1. HSISLDEL - If you have any obsolete LPARs in the repository, you should delete the obsolete LPARs by running job HSISLDEL.
2. HSISPDEL - TMODULE is one of the largest tables containing modules of which a huge percentage are in-house programs. To delete obsolete modules (especially in-house programs), refer to job HSISPDEL. You need to define a date range for deletion, and a sample SQL statement is provided in the job to list date ranges. HSISPDEL deletes modules based on any load libraries that have been marked as deleted.
3. HSISUDEL - TUSEMTD is the largest table. Performing housekeeping on this table should be part of best practices. To determine the status of this table, run the following SQL statement:
```
SELECT FPERIOD, COUNT(*) FROM &RESPZSCHM.TUSEMTD GROUP BY FPERIOD ;
```
  Following, in the Usage Deletion job HSISUDEL, select the date range for deletion. Follow the instructions in the job. If you have not used deletion before, you should delete Usage records in increments. Do this for all LPARs. Then run the SQL statement again to check the number of outstanding records in TUSEMTD.
  A good guideline on the number of records to be retained is to run HSISUDEL monthly for all LPARs with a fixed set of parameter settings:
```
KEEPDETAIL=3 (or 6)
KEEPAGGR=12
```
  This will retain detailed Usage records for the current month and the previous 3 (or 6) months, and summarized records for the current month and the previous 12 months.
Continue to run your 8.2 Usage Monitor job/started task (HSISUMON/HSIJMON), but stop the Analyzer, and do not run any 8.2 operational jobs during the migration.

About this task

Perform these migration tasks for every SQLite Repository in your IBM Z Software Asset Management environment.

Procedure

In IBM Z Software Asset Management 8.3.1, make a copy of the HSISCUST member in the hsi.SHSISAMP data set and modify the following parameters:
1. Set the value of the DBTYPE parameter to SQLITE.
2. Set HSIINST to the same value as the one defined for the existing 8.2 system. As stated in the section, “Before you begin”, it is imperative that you either backup or rename copies of 8.2 JCLLIB/PARMLIB datasets.
3. Set the value of the SYS parameter to the same system that is defined for your existing 8.2 Repository database.
4. Set the value of the REPZSCHM parameter to the same value that is defined for your 8.2 Repository database.
5. Set the value of the new GKBZSCHM parameter to the same value that is defined for your 8.2 GKB database
6. Set the value of the SQLTZFS parameter to the same value that is defined for your 8.2 zFS linear VSAM data set
7. Set the value of the SQLTPATH parameter to same value that is defined for your 8.2 path of the z/OS UNIX for Systems Services directory
Submit the HSISCUST job. The JCLLIB/PARMLIB datasets created use the same names as those created in 8.2. The same dataset names for JCLLIB/PARMLIB must be used in 8.3.1 because of the relationships between the high level qualifier HSIINST parameter and the SQLTZFS/SQLTPATH parameters.
1. SQLTZFS = '&HSIINST..&SYS..ZFS'
2. SQLTPATH = '/u/tadz/&SQLTZFS'
Edit and update jobs in the JCLLIB library and parameters in the PARMLIB library if there are special site requirements.
Run the following migration jobs:
1. HSISYS21– Submit this job to display the meta data of the 8.2 Repository, LKB and LKU objects. Verify that the number of 8.2 database objects match the expected result. If the expected result does not match, DO NOT proceed to the next job, HSISYS22. Investigate why there are differences. Possible reasons are described in the comments section of the job. Upon successful completion of the job, proceed to the next job, HSISYS22.
  A condition code of 0 is expected.
2. HSISYS22– Submit this job to update the Repository database, define new database objects, add new columns, and modify existing columns. These are required for new functions in 8.3.1. Upon successful completion of the job, proceed to the next job, HSISYS23.
  A condition code of 0 is expected.
3. HSISYS23– Submit this job to rename 8.2 tables to names suffixed with _OLD, create new tables, and copy data from the renamed tables to the newly created tables. Upon successful completion of the job, proceed to the next job, HSISYS24.
  A condition code of 0 is expected.
4. HSISYS24– Submit this job to drop the _OLD tables created in the previous job, HSISYS23. Upon successful completion of the job, proceed to the next job, HSISYS25.
  A condition code of 0 is expected.
5. HSISYS25– Submit this job to verify database objects implemented in job HSISYS22 have been applied successfully. Upon successful completion of the job, proceed to the next job, HSISYS21
  A condition code of 0 is expected.
6. HSISYS21– Resubmit this job to display the meta data of the newly migrated 8.3.1 Repository LKB and LKU objects. Verify that the number of 8.3.1 database objects match the expected result.
  A condition code of 0 is expected.
HSISDB02– Submit this job to drop and create a new GKB database and its dependent objects. Before submitting this job, uncomment step //*DROPGKB. This will drop the 8.2 GKB database and create a new 8.3.1 GKB database. IBM Z Software Asset Management 8.3.1 GKB has one new column (FGADATE) in the GKB/GKU TVERSION table. Upon successful completion of the job, proceed to the next job.
A condition code of 0 is expected.
HSISGKBL– Submit this job to populate the newly created 8.3.1 GKB database.
A GKB level is shipped with this migration. To download the latest GKB level, see Updating the Global Knowledge Base.
Note:
Using an 8.2 GKB level does not have data to populate the new column (FGADATE) in the GKB/GKU TVERSION table, therefore the job will fail. See example of error in topic "Post Migration errors".
A condition code of 0 is expected.
Backup 8.3.1
1. HSISUT01– run the 8.3.1 job to backup the SQLite database.
Recovery
1. If failures occur during the migration, and a recovery is required, run the 8.2 job, HSISUT02 to recover using the backup copy created just before the start of migration.

What to do next

See section "What to do next" in topic "Migrating from 8.2 to 8.3.1.