Migrating from version 8.1 to Version 8.2 (Db2 database)

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

Before you begin

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

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

Migration planning and consideration:

All table spaces from version 8.1 are migrated to version 8.2 partition-by-growth Universal Table Spaces (UTS). These UTS are defined as ‘COMPRESS YES’. All indexes are also defined as ‘COMPRESS YES’ with the BP8K0 as the default buffer-pool.
If you prefer to define some table spaces as partition-by-range UTS, you need to customize some PARMLIB members, before the migration.
If your existing version 8.1 Repository database (including LKB/LKU) still use the original table space definitions (segmented non-UTS), then you can use the migration jobs listed below for the migration.
If your existing version 8.1 Repository database (including LKB/LKU) already have some or all table spaces reconfigured as UTS, then you need to review and decide which migration jobs are required for the migration. After migration you need to customise version 8.2 JCLLIB/PARMLIB members to reflect your preferred table space names.
If your existing version 8.1 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 version 8.2 Usage Monitor job/started task (HSISUMON/HSIJMON) requires a minimum level of z/OS V2.3 or later. It will fail if run in z/OS V2.2 or earlier.
Note: If your repository is located on an LPAR running at z/OS V2.2 or earlier, the Usage Monitor job/start task (HSISUMON/HSIJMON) must continue to run with version 8.1 load library hsi.SHSIMOD1. You can still migrate the repository and GKB databases to version 8.2 (depending on types of deployment scenarios described later in the list). Once you have upgraded to z/OS V2.3 or later, you can then run the Usage Monitor with the version 8.2 load library hsi.SHSIMOD1.
If you have multiple version 8.1 repositories sharing the same version 8.1 GKB database, you need to phase the migration process.
A version 8.2 repository must use a version 8.2 GKB.
A version 8.1 repository must use a version 8.1 GKB.

Note: Version 8.2 code fails when accessing a version 8.1 GKB database, due to newly defined version 8.2 tables and columns. Conversely, version 8.1 code fails when accessing a version 8.2 GKB database due to differences in version 8.2 table layouts.
For example, if you have version 8.1 repositories REP1, REP2, REP3, and REP4 sharing the same version 8.1 GKB, then migrate as follows:
- To migrate the first repository, REP1, in version 8.2 customization job, HSISCUST, create a new V8.2 GKB database. For example, GKB82.
  Customize parameters DBGKB and GKBZSCHM with different names from those used in version 8.1 GKB database. Repository parameter settings and values remain the same.
- Migrate REP1 and GKB database (GKB82) to version 8.2 at the same time. Operational jobs for repository REP1 must now reference the version 8.2 load library hsi.SHSIMOD1.
- The remaining REPs continue to run at version 8.1 with operational jobs still referencing the version 8.1 load library hsi.SHSIMOD1. These REPs continue to use the version 8.1 GKB database (GKB81).
- Gradually migrate the remaining three repositories without creating another version 8.2 GKB (GKB82).
- Once all REPs are migrated and are using the version 8.2 GKB database (GKB82), the version 8.1 GKB (GKB81) database can be dropped.
If each repository has its own GKB, then migrate the Repository database, GKB database and hsi.SHSIMOD1 to version 8.2 all at the same time.
Housekeeping:
Perform housekeeping on the version 8.1 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 biggest 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 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 ;
```
  Next, in the Usage Deletion job HSISUDEL, select the date range for deletion. Follow the instructions in the job – if you have never deleted before, you should delete Usage records in increments. Do it for all LPARs. 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 version 8.1 Usage Monitor job/started task (HSISUMON/HSIJMON), but stop the Analyzer and do not run any version 8.1 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 IBM Z Software Asset Management version 8.2, 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.1 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 version 8.1 JCLLIB/PARMLIB datasets.
3. Set the value of the SYS parameter to the same system that is defined for your existing version 8.1 Repository database.
4. Set the value of the DB parameter to the same value that is defined for your existing version 8.1 Repository database.
5. Set the value of the DBGKB parameter to the same value that is defined for your existing version 8.1 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 version 8.2 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 version 8.1 Repository database.
7. Set the value of the GKBZSCHM parameter to the same value that is defined for your version 8.1 GKB database.
  Note: If you have multiple repositories sharing the same GKB database, you must use a different GKBZSCHM name to create a new version 8.2 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 version 8.1 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 V8.1 and V8.2. 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. HSISWS01 - Submit the job to verify whether all database changes have been applied. The comments section in the job describes a list of version 8.1 PTFs where database changes for the Repository must be applied. Also, this job verifies whether there are records in the TUSEMTD table with column FHWID having values of 0 (zero).
  DO NOT proceed to the next job, HSISWS02, until all database changes for version 8.1 have been applied. OA56618/UJ00637 is the last PTF from version 8.1 where database changes need to be applied. This PTF requires significant effort in implementation due to changes in the largest table - TUSEMTD.
  
  To fix records in the TUSEMTD table with column FHWID having values of 0 (zero), refer to 'Additional instructions' in the technote at this web address: https://www.ibm.com/support/pages/hold-act-ptf-uj00637
  
  A condition code of 0 is expected.
2. HSISWS02 - Submit the job to display the meta data of the version 8.1 Repository, LKB and LKU objects. Verify that the number of version 8.1 Db2 objects match the expected result. If the expected result does not match, DO NOT proceed to the next job, HSISWS03. 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, HSISWS03.
  A condition code of 0 is expected.
3. HSISWS03 – Submit the job to alter table spaces (table spaces defined with single tables) to UTS, table spaces and indexes defined with ‘COMPRESS YES’. Upon successful completion of the job, proceed to the next job, HSISWS04.
  A condition code of 0 is expected.
4. HSISWS04 – Submit the job to reorg the 3 largest table spaces - TUSEMTD, TMODULE and PRODUCT_USE_DETAIL, so as to instantiate these table spaces to UTS. Upon successful completion of the job, proceed to the next job, HSISWS05.
  A condition code of 4 is expected.
5. HSISWS05 – Submit the job to reorg the remaining 20 table spaces, so as to instantiate these table spaces to UTS. Upon successful completion of the job, proceed to the next job, HSISWS06.
  A condition code of 4 is expected.
6. HSISWS06 – Submit the job to drop primary keys and indexes of version 8.1 tables that were defined under shared segmented table spaces. Upon successful completion of the job, proceed to the next job, HSISWS07.
  A condition code of 0 is expected.
7. HSISWS07 – Submit the job to create 15 new UTS, new tables with names suffixed with _V82, and indexes. These 15 tables in version 8.1 share 3 segmented table spaces. Upon successful completion of the job, proceed to the next job, HSISWS08.
  A condition code of 0 is expected.
8. HSISWS08 – Submit the job to copy data from 15 tables of version 8.1 to the newly defined tables suffixed with _V82 from step (g). Upon successful completion of the job, proceed to the next job, HSISWS09.
  A condition code of 0 is expected.
9. HSISWS09 – Submit the job to drop version 8.1 segmented table spaces (shared by 15 tables), a deprecated table space, and rename tables suffixed with _V82 to their original names. Once this job is run where the version 8.1 table spaces are dropped, there is no fall back to the 15 V8.1 tables. Upon successful completion of the job, proceed to the next job, HSISWS10.
  A condition code of 0 is expected.
10. HSISWS10 – Submit the job to drop LKB indexes, creates new LKB/LKU UTS, new tables with names suffixed with _V82, and indexes. Upon successful completion of the job, proceed to the next job, HSISWS11.
  A condition code of 0 is expected.
11. HSISWS11 – Submit the job to copy LKB/LKU data of version 8.1 to the newly defined tables from step (j). Upon successful completion of the job, proceed to the next job, HSISWS12.
  A condition code of 0 is expected.
12. HSISWS12 – Submit the job to drop version 8.1 LKB/LKU segmented table spaces and rename tables suffixed with _V82 to their original names. Once this job is run where the version 8.1 LKB/LKU table spaces are dropped, there is no fall back to V8.1 LKB/LKU data. Upon successful completion of the job, proceed to the next job, HSISWS15.
  A condition code of 0 is expected.
13. HSISWS15 – At this point, all Repository and LKB/LKU objects, and data have been migrated to V8.2.
  Submit the job to update the Repository database, define new Db2 objects, add new columns and modify existing columns. These are required for new functions in version 8.2. Upon successful completion of the job, proceed to the next job, HSISWS16.
  
  A condition code of 0 is expected.
14. HSISWS16 – Submit the job to populate data to the version 8.2 Repository database. Upon successful completion of the job, proceed to the next job, HSISWS02.
  A condition code of 0 is expected.
15. HSISWS02 - Submit the job to display the meta data of the newly migrated version 8.2 Repository, LKB and LKU objects. Verify that the number of version 8.2 Db2 objects match the expected result.
  A condition code of 0 is expected.
Backup version 8.2.
1. HSISUT01 – run the version 8.2 job to backup all 46 Repository UTS
2. HSISUT04 – Submit this job to run RUNSTATS for the version 8.2 repository
HSISDB02 – Submit the job to drop and create a new GKB database and its dependent objects.
- If you are creating a new version 8.2 GKB database with different GKBDB/GKBZSCHM names, just submit the job. This creates a new version 8.2 GKB database and its dependent objects.
  Use this approach if you have multiple version 8.1 repositories sharing the same version 8.1 GKB database. See Migration planning and consideration, step 6.
- If you are creating the version 8.2 GKB databse where the GKBDB/GKBZSCHM have identical names to version 8.1, then uncomment step //*DROPGKB. This will drop the version 8.1 GKB database and create a new version 8.2 GKB database with the same GKBDB/GKBZSCHM names as version 8.1.
  Version 8.2 GKB has new tables, new columns, and columns with expanded column sizes.
- Upon successful completion of the job, proceed to the next job.
A condition code of 0 is expected.
HSISGKBL – Submit the job to populate the newly created version 8.2 GKB database.
A GKB level is shipped with this migration. To download the latest GKB level, refer to topic Updating the Global Knowledge Base .
Note: Using a version 8.1 GKB level is not supported, as the table layouts are different.
A condition code of 0 is expected.
HSISGRTB – Optional. Submit the job to grant privileges to users that require SELECT access to newly created version 8.2 tables.
Recovery – It is only possible to run the version 8.1 recovery job, HSISUT02 (or equivalent in-house job), for failures in jobs HSISWS04 and HSISWS05.

What to do next

After migration, use the following approach to manage the implementation to the new 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 job, HSISUIMP. You can continue to use existing version 8.1 Inquisitor fully-scanned files as inputs for the version 8.2 HSISIQIM Inquisitor Import job.
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 job 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 job step.
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 job step. This is because product identifications may not be up to date.
For each repository, run the HSISUIMP job for every LPAR. For performance reasons, exclude the Aggregator job step, except for the last HSISUIMP job. Please read the comments in the "Performance consideration" section of job HSISUIMP job before you proceed.
1. 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 job step.
2. After running the last HSISUIMP job, in the Aggregator jobstep, set COUNTUSAGEFULL=N (the default setting).
3. Repeat steps 6 to 6b for the next repository.
Configure APF authorization for the version 8.2 hsi.SHSIMOD1 load library.
When the version 8.2 Inquisitor scans and Usage Monitors are ready for use, you can run 8.2 operational jobs and discontinue version 8.1 tasks.
1. Review the settings in the Inquisitor scan jobs, before submissions:
  HSISINQU – PLX=N,PACK=0 (default)
  HSISINQZ – PACK=0 (default)
2. Before starting HSISUMON, review parameters:
  PARMLIB member HSISMNPM – different parameters and default values.
  Note: Usage Monitor job HSISUMON requires z/OS version 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.