Migrating from version 1.1 to HCL Z Asset Optimizer version 2.2 (Db2® database)

When you upgrade to HCL Z Asset Optimizer version 2.2 for Db2 database, there is no porting of data within the Repository database. New Db2 objects are defined to the Repository. The existing version 1.1 GKB database is dropped and re-created with the same database name for version 2.2.

Before you begin

Make a backup of your version 1.1 Repository database by running job HZASUT01 from your version 1.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 1.1 and version 2.2 are defined as 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 1.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 2.2 Usage Monitor job/started task (HZASUMON/HZAJMON) 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 (HZASUMON/HZAJMON) must continue to run with version 1.1 load library HZA.SHZAMOD1.

You can still migrate the repository and GKB databases to version 2.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 2.2 load library HZA.SHZAMOD1.
If you have multiple version 1.1 repositories sharing the same version 1.1 GKB database, you need to phase the migration process.

A version 2.2 repository must use a version 2.2 GKB.

A version 1.1 repository must use a version 1.1 GKB.
Note: Version 2.2 code fails when accessing a version 1.1 GKB database, due to newly defined version 2.2 tables and columns. Conversely, version 1.1 code fails when accessing a version 2.2 GKB database due to differences in version 2.2 table layouts.
For example, if you have version 1.1 repositories REP1, REP2, REP3, and REP4 sharing the same version 1.1 GKB, then migrate as follows:
- To migrate the first repository, REP1, in version 2.2 customization job, HZASCUST, create a new V2.2 GKB database. For example, GKB22.
  Customize parameters DBGKB and GKBZSCHM with different names from those used in version 1.1 GKB database. Repository parameter settings and values remain the same.
- Migrate REP1 and GKB database (GKB22) to version 2.2 at the same time. Operational jobs for repository REP1 must now reference the version 2.2 load library HZA.SHZAMOD1.
- The remaining REPs continue to run at version 1.1 with operational jobs still referencing the version 1.1 load library HZA.SHZAMOD1. These REPs continue to use the version 1.1 GKB database (for example, GKB11).
- Gradually migrate the remaining three repositories without creating another version 2.2 GKB (GKB22).
- Once all REPs are migrated and are using the version 2.2 GKB database (GKB22), the version 1.1 GKB (GKB11) database can be dropped.
If each repository has its own GKB, then migrate the Repository database, GKB database and HZA.SHZAMOD1 to version 2.2 all at the same time.
Perform housekeeping on the version 1.1 Repository database before you start your migration process.
1. HZASLDEL - If you have any obsolete LPARs in the repository, you should delete the obsolete LPARs by running job HZASLDEL.
2. HZASPDEL - 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, HZASPDEL. You need to define a date range for deletion and a sample SQL statement is provided in the job to list date ranges. HZASPDEL deletes modules based on any load libraries that have been marked deleted.
3. HZASUDEL - 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 &REPZSCHM.TUSEMTD 
GROUP BY FPERIOD ;
```
  Next, in the Usage Deletion job HZASUDEL, 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 HZASUDEL 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 1.1 Usage Monitor job/started task (HZASUMON/HZAJMON), but stop the Analyzer and do not run any version 1.1 operational jobs during the migration.

About this task

Perform these migration tasks for every Db2 Repository in your HCL Z Asset Optimizer environment.

Procedure

In HCL Z Asset Optimizer version 2.2, make a copy of the HZASCUST member in the HZA.SHZASAMP data set and modify the following parameters:
1. Set the value of the new DBTYPE parameter to DB2.
2. Set HZAINST to a different value to the one defined for the existing 1.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 1.1 JCLLIB/PARMLIB datasets .
3. Set the value of the SYS parameter to the same system that is defined for your existing version 1.1 Repository database.
4. Set the value of the DB parameter to the same value that is defined for your existing version 1.1 Repository database.
5. Set the value of the DBGKB parameter to the same value that is defined for your existing version 1.1 Global Knowledge Base (GKB) database.
  Note: Note: If you have multiple repositories sharing the same GKB database, you must use a different DBGKB name to create a new version 2.2 GKB database. See Migration planning and considerations.
6. Set the value of the REPZSCHM parameter to the same value that is defined for your version 1.1 Repository database.
7. Set the value of the GKBZSCHM parameter to the same value that is defined for your version 1.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 2.2 GKB database. See Migration planning and considerations
8. Set values of the remaining Db2 parameters (e.g. DBSSID, LOC) to the same values that are defined for your version 1.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-BP4.
Submit the HZASCUST job. DO NOT share members of JCLLIB/PARMLIB between V1.1 and V2.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. HZASMI01 - Submit the job to display the meta data of the version 1.1 Repository, LKB and LKU objects. Verify that the number of version 1.1 Db2 objects match the expected result. If the expected result does not match, DO NOT proceed to the next job, HZASMI02. Investigate why there are differences. Possible reasons are described in the comments section of the job. For comparison purposes, a list of expected tablespaces, tables, and indexes for V1.1/V2.2 are appended at the end of this job, after the // NULL statement, so the list will not appear in the job output. Upon successful completion of the job, proceed to the next job, HZASMI02.
  A condition code of 0 is expected.
2. HZASMI02 – 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 2.2. Upon successful completion of the job, proceed to the next job, HZASMI05.
  A condition code of 0 is expected.
3. HZASMI05 – Submit the job to populate data to the version 2.2 Repository database. Upon successful completion of the job, proceed to the next job, HZASMI0.
  A condition code of 0 is expected.
4. HZASMI01 - Submit the job to display the meta data of the newly migrated version 2.2 Repository, LKB and LKU objects. Verify that the number of version 2.2 Db2 objects match the expected result..
  A condition code of 0 is expected.
Backup version 2.2
1. HZASUT01 – run the version 2.2 job to backup all 48 Repository UTS.
2. HZASUT04 – Submit this job to run RUNSTATS for the version 2.2 repository.
HZASDB02 – Submit the job to drop and create a new GKB database and its dependent objects.
- If you are creating a new version 2.2 GKB database with different GKBDB/GKBZSCHM names, just submit the job. This creates a new version 2.2 GKB database and its dependent objects. Use this approach if you have multiple version 1.1 repositories sharing the same version 1.1 GKB database. See Migration planning and consideration
- If you are creating the version 2.2 GKB databse where the GKBDB/GKBZSCHM have identical names to version 1.1, then uncomment step //*DROPGKB. This will drop the version 1.1 GKB database and create a new version 2.2 GKB database with the same GKBDB/GKBZSCHM names as version 1.1.
  Version 2.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.
HZASGKBL – Submit the job to populate the newly created version 2.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 1.1 GKB level is not supported, as the table layouts are different.
A condition code of 0 is expected.
HZASGRTB – Optional. Submit the job to grant privileges to users that require SELECT access to newly created version 2.2 tables
Recovery – Depending on the point of failure, it is possible to run the version 1.1 recovery job, HZASUT02 (or equivalent in-house job).

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 ensures that all product identifications are up to date when you run the Inquisitor Import job, HZASIQIM. For each repository, run HZASIQIM for all LPARs before you run any Usage Import job, HZASUIMP. You can continue to use existing version 1.1 Inquisitor fully-scanned files as inputs for the version 2.2 HZASIQIM Inquisitor Import job.
For each repository, run the HZASIQIM job for every LPAR with setting of FULLREMATCH=Y. For performance reasons, exclude the Aggregator job step, except for the last HZASIQIM job. Read the comments in the "Performance consideration" section of job HZASIQIM before you proceed.
For the last HZASIQIM job, update the Aggregator jobstep with COUNTUSAGEFULL=Y. For example:
```
//AGGR EXEC HZAJSQLE,PROG=HZACTLAG,TPARAM=HZASAGP1
//USERPARM DD *
COUNTUSAGEFULL=Y
                    
```
Run the last HZASIQIM job with COUNTUSAGEFULL=Y for the Aggregator job step
After running the last HZASIQIM 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, HZASUIMP, you must run the Inquisitor Import job, HZASIQIM, for all LPARs (as described in step 1). Failure to complete running the Inquisitor Import job (HZASIQIM) for all LPARs before your start running Usage Import (HZASUIMP) could result in errors during the Aggregator job step due to product identifications not being up to date.

For each repository, run the HZASUIMP job for every LPAR. For performance reasons, exclude the Aggregator job step, except for the last HZASUIMP job. Read the comments in the "Performance consideration" section of job HZASUIMP job before you proceed.
1. For the last HZASUIMP job, update the Aggregator jobstep with COUNTUSAGEFULL=Y. For example:
```
//AGGR EXEC HZAJSQLE,PROG=HZACTLAG,TPARAM=HZASAGP1
//USERPARM DD *
COUNTUSAGEFULL=Y
                            
```
  Run the last HZASUIMP job with COUNTUSAGEFULL=Y for the Aggregator job step
2. After running the last HZASUIMP 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 2.2 HZA.SHZAMOD1 load library.
When the version 2.2 Inquisitor scans and Usage Monitors are ready for use, you can run 2.2 operational jobs and discontinue version 1.1 tasks.
1. Review the settings in the Inquisitor scan jobs, before submissions:
  HZASINQU – PLX=N,PACK=0 (default)
  HZASINQZ – PACK=0 (default)
2. Before starting HZASUMON, review parameters:
  PARMLIB member HZASMNPM – different parameters and default values.
  Note: Usage Monitor job HZASUMON requires z/OS version 2.3, or later.
3. HZASZCAT – different parameters and default values:
  Parameters 'JNM=Y,UID=Y,JAC=Y' are now the default.
4. HZASIQIM – parameter COUNTUSAGE = N is now the default.
5. HZASUIMP – parameter COUNTUSAGE = N is now the default.