Migrating from IBM Z Software Asset Management 8.2 to IBM Z Software Asset Management 8.3 (Db2 database)

When you upgrade to IBM Z Software Asset Management 8.3 for Db2® database, there is porting of data within the Repository database. New Db2 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.

Before you begin

Make a backup of your 8.2 Repository database by running job HSISUT01 from your 8.2 JCLLIB, or equivalent in-house backup job.

Make a backup or rename your JCLLIB and PARMLIB data sets.

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 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.
Note: If your repository is located on an LPAR running at z/OS 2.2 or earlier, the Usage Monitor job/start task (HSISUMON/HSIJMON) must continue to run with IBM Z Software Asset Management 8.2 load library hsi.SHSIMOD1.
You can still migrate the repository and GKB databases to IBM Z Software Asset Management 8.3 (depending on types of deployment scenarios described later in the list). Once you have upgraded to z/OS 2.3 or later, you can then run the Usage Monitor with the 8.3 load library hsi.SHSIMOD1.
If you have multiple 8.2 repositories sharing the same 8.2 GKB database, you need to phase the migration process.
- An 8.3 repository must use an 8.3 GKB.
- An 8.2 repository must use an 8.2 GKB.
Note: IBM Z Software Asset Management 8.3 code fails when accessing an 8.2 GKB database, due to newly defined 8.3 objects.
For example, if you have 8.2 repositories REP1, REP2, REP3, and REP4 sharing the same 8.2 GKB, then migrate as follows:
- To migrate the first repository, REP1, in 8.3 customization job HSISCUST, create a new 8.3 GKB database. For example, GKB83:
  - Customize parameters DBGKB and GKBZSCHM with different names from those used in 8.2 GKB database. Repository parameter settings and values remain the same.
- Migrate REP1 and GKB database (GKB83) to 8.3 at the same time. Operational jobs for repository REP1 must now reference the 8.3 load library hsi.SHSIMOD1.
- The remaining REPs continue to run at 8.2, with operational jobs still referencing the 8.2 load library hsi.SHSIMOD1. These REPs continue to use the 8.2 GKB database (GKB82).
- Gradually migrate the remaining three repositories without creating another 8.3 GKB (GKB83).
- Once all REPs are migrated and are using the 8.3 GKB database (GKB83), the 8.2 GKB (GKB82) database can be dropped.
If each repository has its own GKB, then migrate the Repository database, GKB database, and hsi.SHSIMOD1, to 8.3, all at the same time.
Housekeeping:
Perform housekeeping on the 8.2 Repository database before you start your migration process. This should reduce 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, and it contains 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, 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 Db2® Repository in your IBM Z Software Asset Management environment.

Procedure

In 8.3, make a copy of the HSISCUST member in the hsi.SHSISAMP data set and modify the following parameters:
1. Set the value of the new DBTYPE parameter to DB2.
2. Set HSIINST to a different value to the one defined for the existing 8.2 system. This will ensure that the JCLLIB/PARMLIB datasets are created with different names. As stated in the section, “Before you begin”, 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 DB parameter to the same value that is defined for your existing 8.2 Repository database.
5. Set the value of the DBGKB parameter to the same value that is defined for your existing 8.2 Global Knowledge Base (GKB) database.
  
  Note: If you have multiple repositories sharing the same GKB database, you must use a different DBGKB name to create a new 8.3 GKB database. See Migration planning and consideration, step 6.
6. Set the value of the REPZSCHM parameter to the same value that is defined for your 8.2 Repository database.
7. Set the value of the GKBZSCHM parameter to the same value that is defined for your 8.2 GKB database.
  
  Note: If you have multiple repositories sharing the same GKB database, you must use a different GKBZSCHM name to create a new 8.3 GKB database. See Migration planning and consideration, step 6.
8. Set values of the remaining Db2 parameters (e.g. DBSSID, LOC) to the same values that are defined for your 8.2 Repository database.
9. The default value for the BPIX parameter is set to BP8K0 and must be activated before usage. Compressed indexes require Bufferpools to be defined with BP8K0-BP8K9, BP16K0-BP16K9, or BP32K-BP32K9. It cannot be BP0-BP49.
Submit the HSISCUST job. DO NOT share members of JCLLIB/PARMLIB between 8.2 and 8.3. Some member names may be the same, but the contents differ.
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. HSISVS21– 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, HSISVS22. 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, HSISVS22.
  
  A condition code of 0 is expected.
2. HSISVS22– Submit this job to update the Repository database, define new Db2 objects, add new columns, and modify existing columns. These are required for new functions in 8.3. Upon successful completion of the job, proceed to the next job, HSISVS25.
  A condition code of 0 is expected.
3. HSISVS25– Submit this job to verify database objects implemented in the previous job, HSISVS22, have been applied successfully. Upon successful completion of the job, proceed to the next job, HSISVS21.
  A condition code of 0 is expected.
4. HSISVS21– Resubmit this job to display the meta data of the newly migrated 8.3 Repository LKB and LKU objects. Verify that the number of 8.3 database objects match the expected result.
  
  A condition code of 0 is expected.
Backup 8.3
1. HSISUT01– run the 8.3 job to backup all 52 Repository UTS.
2. HSISUT04– submit this job to run RUNSTATS for the 8.3 repository.
HSISDB02– Submit this job to drop and create a new GKB database and its dependent objects.
- If you are creating a new 8.3 GKB database with different GKBDB/GKBZSCHM names, just submit the job. This creates a new 8.3 GKB database and its dependent objects. Use this approach if you have multiple 8.2 repositories sharing the same 8.2 GKB database. See Migration planning and consideration, step 6.
- If you are creating the 8.3 GKB database where the GKBDB/GKBZSCHM have identical names to 8.2, then uncomment step //*DROPGKB. This will drop the 8.2 GKB database and create a new 8.3 GKB database with the same GKBDB/GKBZSCHM names as 8.2.
  IBM Z Software Asset Management 8.3 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 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.
HSISGRTB– Optional. Submit this job to grant privileges to users that require SELECT access to newly created 8.3 tables.
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

After migration, use the following approach to manage the implementation to the latest version:

You must apply the latest GKB update. This will ensure that all product identifications are up to date when you run the Inquisitor Import job, HSISIQIM. For each repository, run HSISIQIM for all LPARs before you run any Usage Import (HSISUIMP) jobs . You can continue to use existing 8.2 Inquisitor fully-scanned files as inputs for the 8.3 HSISIQIM Inquisitor Import job.
Note: Job HSISIQIM will fail if the GKB level used is older than 12 months.
For each repository, run the HSISIQIM job for every LPAR with setting of FULLREMATCH=Y. For performance reasons, exclude the Aggregator job step, except for the last HSISIQIM job. Please read the comments in the "Performance consideration" section of job HSISIQIM before you proceed.
For the last HSISIQIM job, update the Aggregator jobstep with COUNTUSAGEFULL=Y. For example:
```
//AGGR EXEC HSIJSQLE,PROG=HSICTLAG,TPARAM=HSISAGP1
//USERPARM DD *
COUNTUSAGEFULL=Y
```
Run the last HSISIQIM job with COUNTUSAGEFULL=Y for the Aggregator jobstep.
After running the last HSISIQIM job, in the Aggregator jobstep, set COUNTUSAGEFULL=N (the default setting).
Repeat steps 1 to 4 for the next repository.
Before you run any Usage Import job, HSISUIMP, you must run the Inquisitor Import job, HSISIQIM, for all LPARS (as described in step 1). Failure to complete running the Inquisitor Import job (HSISIQIM) for all LPARs before you start running Usage Import (HSISUIMP) could result in errors during the Aggregator jobstep due to the product identifications not being up-to-date.
1. For each repository, run the HSISUIMP job for every LPAR. For performance reasons, exclude the Aggregator jobstep, except for the last HSISUIMP job. Please read the comments in the "Performance consideration" section of job HSISUIMP before you proceed.
2. For the last HSISUIMP job, update the Aggregator jobstep with COUNTUSAGEFULL=Y. For example:
```
 //AGGR EXEC HSIJSQLE,PROG=HSICTLAG,TPARAM=HSISAGP1
 //USERPARM DD *
 COUNTUSAGEFULL=Y
```
  Run the last HSISUIMP job with COUNTUSAGEFULL=Y for the Aggregator jobstep.
3. After running the last HSISUIMP job in the Aggregator jobstep, set COUNTUSAGEFULL=N (the default setting).
4. Repeat steps 6a through 6c for the next repository.
Configure APF authorization for the 8.3 hsi.SHSIMOD1 load library.
You can run 8.3 operational jobs and discontinue 8.2 tasks once the 8.3 Inquisitor scans and Usage Monitors are ready for use.
1. Review the settings in the Inquisitor scan jobs, before submissions:
  HSISINQU – PACK=1 (default)
  HSISINQZ – PACK=1 (default)
2. Before starting HSISUMON, review parameters:
  PARMLIB member HSISMNPM – different parameters and default values.
  Note: Usage Monitor job HSISUMON requires z/OS 2.3, or later.
3. HSISZCAT – different parameters and default values:
  Parameters 'JNM=Y,UID=Y,JAC=Y' are now the default.
4. HSISIQIM – parameter COUNTUSAGE = N is now the default.
5. HSISUIMP – parameter COUNTUSAGE = N is now the default.