IBM Support

Updates to IMS Database Utility Solution V2.1: IMS HALDB Toolkit User's Guide

Release Notes


Abstract

Updates that apply to IMS Database Utility Solution V2.1: IMS HALDB Toolkit User's Guide (SC27-8779-01)

Content

The most recent updates appear at the top of the list.

Update 1
Date of change: June 2020
Change description: Documentation changes by APAR PH22310. This APAR enhances IMS HALDB Toolkit to support the IMS management of ACBs for some batch functions and ISPF functions.
Topics: Changes apply to multiple topics.

------------------------------

Topic: Introduction to IMS HALDB Toolkit > IMS HALDB Toolkit overview > Considerations for the IMS management of ACBs

The descriptions have been modified as follows:

When the IMS management of ACBs is enabled, IMS HALDB Toolkit can refer to database definitions in the IMS catalog directory instead of the DBD library.

Start of changeWhen running batch functions (except a function to load logical children), IMS catalog definition is retrieved from either:End of change

  • The IMS Catalog Definition exit routine (DFS3CDX0) in the STEPLIB concatenation.
  • The DFSDFxxx PROCLIB member specified by the DFSDF(xxx) parameter in IHCSYSIN and the PROCLIB DD statement.

Start of changeA function to load logical children and ISPF functions only support the IMS Catalog Definition exit routine (DFS3CDX0).End of change

The following conditions must be satisfied to use IMS managed ACBs:

  • IBM IMS Tools Base for z/OS, Version 1 Release 6 or later must be installed.
  • The IMS catalog database must be registered to the RECON data sets.
  • The name of the IMS catalog database must be defined in the RECON record with the following DBRC command: CHANGE RECON CATALOG(name).

Start of changeThe following libraries must be in the STEPLIB concatenation of the IMS HALDB Toolkit job:

  • If the DFSMDA member with the TYPE=CATDSHLQ statement is used to specify the high-level qualifier of the IMS catalog system data sets, the library that contains the DFSMDA member must be in the STEPLIB concatenation of the IMS HALDB Toolkit job.
  • The SGLXLOAD library of IBM IMS Tools Base for z/OS, Version 1 Release 6 or later

The following libraries must be in the ISPLLIB of the CLIST for ISPF invocation when using the ISPF user interface:

  •  The SGLXLOAD library of IBM IMS Tools Base for z/OS, Version 1 Release 6 or later
  •  The IMS Catalog Definition exit routine (DFS3CDX0)
  •  IMS.RESLIBEnd of change

The following functions do not support the IMS management of ACBs:

  • Start of changeBatch functions: IHCUDBD, IHCWPSBL and HALDBLOADEnd of change 
  • HALDB without DBRC
  • Start of changeISPF functions:
    • 4  Convert from Full Function to HALDB
      • 5  Rebuild old DBD
      • 6  Rebuild old dataset allocation
      • 7  Rebuild old DBRC
      • 8  UNDO conversion
    • 5  Convert entire DBD library to HALDB
    • 8  Other Utilities
      • 1  Show DBD Source
      • 2  Reassemble DBDEnd of change

The following restrictions apply when the IMS catalog database is specified on the DBD parameter:

  • The IMS catalog is supported only by the ANALYZEPART function and the MAINTAIN function (when ONLINE(N)). No other function supports the IMS catalog.
  • IMS DD must be specified.

Start of changeIf you want to convert full-function databases in an IMS managed ACBs environment, new database definitions must exist in the IMS catalog staging data sets before running the IMS HALDB Toolkit job.

The following restrictions apply when converting full-function databases in an IMS managed ACBs environment:

  • When converting full-function databases by using the ISPF user interface, you must manually issue the IMPORT DEFN SOURCE(CATALOG) command to activate the pending database definition after the conversion.

For more information about converting full-function databases, see the following topics:

  • Converting to a HALDB > Converting to HALDB using CONVERT > Converting databases offline
  • Using the ISPF user interface > Converting to HALDB > Considerations for converting to HALDB
For more information about maintaining a database, see "MAINTAIN example: Maintaining a database when the IMS management of ACBs is enabled".End of change
------------------------------

Topic: Converting to a HALDB > Converting to HALDB using CONVERT > CONVERT data flow

Figure "CONVERT data flow" has been updated as follows:

Figure. CONVERT data flow
(Figure 5 in PDF)

Start of change

ihcd0002

End of change
------------------------------

Topic: Converting to a HALDB > Converting to HALDB using CONVERT > Converting databases offline

The following topic has been updated as follows:

You can convert full-function databases offline by using the CONVERT command.

About this task

Databases must be offline to use this method. You must manually /DBR your databases before running the conversion job.

Start of changeWhen the IMS management of ACBs is enabled:

  • New database definitions must exist in the IMS catalog staging data sets before running the IMS HALDB Toolkit job.
  • The shadow database is unloaded by using the active database definition obtained from the IMS catalog directory data sets, then reloaded by using the pending database definition obtained from the IMS catalog staging data sets.End of change

Restriction: Databases with logical relationships (except for indexes) are not supported.

Procedure

  1. Start of changeWhen the IMS management of ACBs is enabled, prepare the IMS catalog staging data sets. You can refer to the examples in "CONVERT example: Preparing a staging data set before converting a database when the IMS management of ACBs is enabled".End of change
  2. Locate the sample JCL for this task in the SIHCSAMP file, member IHCECVTN.
  3. Specify the JCL DD statements. ...
  4. Specify the CONVERT command parameters. ...
    ...
    "CONVERT example: Specifying the key ranges for partitions"
    "Start of changeCONVERT example: Converting a database when the IMS management of ACBs is enabled"End of change 

  5. Manually /DBR your databases before running the conversion job.
  6. After the conversion process is complete...

  :

------------------------------

Topic: Converting to a HALDB > Converting to HALDB using CONVERT > CONVERT DD statements

PROCLIB DD has been added and IMS DD has been changed as follows:

Table. DD statements and record format for the CONVERT command

(Table 7 in PDF)

DDname Use Format Need
... ... ... ...
IMS Input Same as IMS Start of changeOptionalEnd of change
IMSDALIB Input Same as IMS ...
Start of changePROCLIB Input Same as IMS OptionalEnd of change
RECONx Input/Output Same as IMS ...
... ... ... ...

...

IMS

Start of changeThis statement is required only if the IMS management of ACBs is not enabled.End of change

The statement describes the library that contains the DBDs of the database that you are processing.

This data set must reside on DASD.

Start of changeWhen the IMS management of ACBs is enabled, IMS HALDB Toolkit ignores the IMS DD statement.End of change

Start of changePROCLIB

This statement is optional. The statement points to the IMS.PROCLIB data set. If DFSDF(ddd) is specified in the IHCSYSIN data set, you must specify this DD statement and ensure that the DFSDFddd member exists in the IMS.PROCLIB data set. End of change

------------------------------

Topic: Converting to a HALDB > Converting to HALDB using CONVERT > CONVERT command parameters

CONVERT command parameters have been modified as follows:

Table. CONVERT command parameters

(Table 8 in PDF)

Parameter Requirement Description
ACBGEN Optional

Specifies to run the ACBGEN process during the takeover phase. This parameter is effective for offline conversion.

Start of changeWhen IMS manages the ACBs (ACBMGMT=CATALOG), ACBGEN(N) is forced. End of change

Format
(Y | N)
Default value
N

... ... ...
DBDBACKUP Optional

Backs up the existing DBD to a specified library.

This parameter includes a DDNAME that must be included in the JCL.

Start of changeWhen IMS manages the ACBs (ACBMGMT=CATALOG), this parameter is ignored.End of change

Format
(ddname)
Default value
None.

DBDCOPY Optional

Copies the new DBD to your DBD library.

If NEWDBD is not specified, DBDCOPY is set to Y.

Start of changeWhen IMS manages the ACBs (ACBMGMT=CATALOG), DBDCOPY(N) is forced.End of change

Format
(Y | N)
Default value
Y

... ... ...
DBRCBACK ... ...
Start of changeDFSDF Optional

Specifies the 3-character suffix of the DFSDFxxx member of the IMS PROCLIB data set that contains the settings and attributes of the IMS catalog.

The specified member is used when the following two conditions are met:

? IMS manages the ACBs (ACBMGMT=CATALOG).

? The IMS Catalog Definition exit routine (DFS3CDX0) is not used.

Ensure that the CATALOG section of the DFSDFxxx member specifies CATALOG=Y, ACBMGMT=CATALOG, and the alias name for the IMS catalog.

Format
(ddd)
Default value
None.End of change

DSG1 ... ...
... ... ...
IMSID Optional

Specifies the IMS ID to use when updating the IMS Library Integrity Utilities partition description.

Start of changeIMSID must be specified when the IMS catalog is enabled by the IMS Catalog Definition exit routine and IMSID is referred to in the exit routine.End of change

Format
(nnnn)
Default value
If omitted, the default is obtained from the current SDFSRESL (DFSVC000).

... ... ...
NEWDBD Optional

Specifies the DDNAME of the data set that contains the changed HALDB DBDs. This parameter is a DDNAME, which must be included in the JCL.

If NEWDBD is not specified, a temporary data set is used. DBDCOPY is then reset to Y.

Start of changeWhen IMS manages the ACBs (ACBMGMT=CATALOG), this parameter is ignored.End of change

Format
(ddname)
Default value
None.

... ... ...
------------------------------

Topic: Converting to a HALDB > Converting to HALDB using CONVERT > CONVERT examples

The following new topic has been added after “CONVERT example: Specifying the key ranges for partitions”:

Start of change

CONVERT example: Preparing a staging data set before converting a database when the IMS management of ACBs is enabled

This example shows JCL statements to prepare a staging data set before converting a database in an IMS managed ACBs environment.

Figure xx. Sample JCL stream to prepare a staging data set before converting a database in an IMS managed ACBs environment

Step 1: Generate HALDB DBD source

  • To generate DBD source for the converted HALDB, specify the DBDSOURCE parameter to the ANALYZEPART command.
  • The DFSDF(CAT) parameter in IHCSYSIN and the PROCLIB DD statement specify the DFSDFCAT PROCLIB member that contains the IMS catalog definition.
  • If you include the IMS Catalog Definition exit routine (DFS3CDX0) in the STEPLIB concatenation, you do not need to specify the DFSDF parameter and the PROCLIB DD statement.
  • The SGLXLOAD library of IMS Tools Base must be in the STEPLIB concatenation.
  • The library containing the DFSMDA member with TYPE=CATDSHLQ statement must be in the STEPLIB concatenation if the DFSMDA member is used to specify the high-level qualifier of the IMS catalog system data sets.    
  • The IMS DD statement is not needed.

Step 2: Run the DBDGEN utility

  • Run the DBDGEN utility by using the DBD source generated in step 1 as input.
  • You can use a temporary DBDLIB.

Step 3: Run the ACBGEN utility

  • Run the ACBGEN utility to generate ACB members, which will be used as input for the IMS Catalog Populate utility.

Step 4: Create a staging data set

  • To create a staging data set, run the IMS Catalog Populate utility. For details, see the topic "IMS Catalog Populate utility (DFS3PU00)" in IMS System Utilities.
End of change
------------------------------

Topic: Converting to a HALDB > Converting to HALDB using CONVERT > CONVERT examples

The following new topic has been added after “CONVERT example: Preparing a staging data set before converting a database when the IMS management of ACBs is enabled”:

Start of change

CONVERT example: Converting a database when the IMS management of ACBs is enabled

This example shows JCL statements to convert a database in an IMS managed ACBs environment.

Figure xx. Sample JCL stream to convert a database in an IMS managed ACBs environment
  • The DFSDF(CAT) parameter in IHCSYSIN and the PROCLIB DD statement specify the DFSDFCAT PROCLIB member that contains the IMS catalog definition.
  • If you include the IMS Catalog Definition exit routine (DFS3CDX0) in the STEPLIB concatenation, you do not need to specify the DFSDF parameter and the PROCLIB DD statement.
  • The SGLXLOAD library of IMS Tools Base must be in the STEPLIB concatenation.
  • The library containing the DFSMDA member with TYPE=CATDSHLQ statement must be in the STEPLIB concatenation if the DFSMDA member is used to specify the high-level qualifier of the IMS catalog system data sets.    
  • The IMS DD statement is not needed.
End of change
------------------------------

Topic: HALDB utilities > Using DBRC enhancement utilities > Cloning DBRC definitions for test environments

The following figure has been updated as follows:

Figure. Sample JCL from member IHCECLON (Part 2 of 2)
(Figure 17 in PDF)

Start of change

End of change
------------------------------

Topic: HALDB utilities > Using DBRC enhancement utilities > Copying HALDBs to a different IMS system > Copying HALDBs by using an image copy

The following figure has been updated as follows:

Figure. Sample JCL from member IHCECOPY
(Figure 18 in PDF)

Start of change

End of change

------------------------------

Topic: HALDB utilities > Using DBRC enhancement utilities > Copying HALDBs to a different IMS system > Copying HALDBs by using DFSMSdss

The following figure has been updated as follows:

Figure. Sample JCL from member IHCEDFDS (Part 1 of 2)
(Figure 19 in PDF)

Start of change

End of change
------------------------------

Topic: Application support > Loading logical children (PROCOPT=L)

The following topic has been updated as follows:

...

IMS HALDB Toolkit improves this situation by allowing these load segments with the following restrictions:

? The logical child segment must contain the LPCK in the IO area.

? The application will receive a BB status code.

The segments (1 child and dependents) are inserted later.

? JCL is structured as follows:

  • Step 1 is the load program. File DFSURWF1 is used to store the delayed segments.
  • Step 2 is prefix update. This step inserts all delayed segments. All WF1 data sets created by step 1 must be included in the DFSURWF3 file.

? You must change your JCL as follows:

  • Use IHCWRC00 instead of DFSRRC00 to accommodate steps 1 and 2
  • Include the SIHCLOAD target load library in the STEPLIB

? Start of changeWhen the IMS management of ACBs is enabled:

  • The IMS Catalog Definition exit routine (DFS3CDX0) must be specified in the STEPLIB concatenation in both steps 1 and 2. The DFSDF and IMSID parameters are not supported.
  • IMS HALDB Toolkit ignores the IMS DD statement. End of change

At the end of the load (prefix update), all databases are labeled IC needed unless they are defined as NONRECOV. 

------------------------------

Topic: Using the ISPF user interface > Setting up the environment for the ISPF user interface > Starting the ISPF user interface

The following procedure has been added:

Procedure

  • Issue the following command to start the ISPF user interface:
    ex 'your.CLIST(IHCCHAL)'
  • Start of changeWhen the IMS management of ACBs is enabled, issue the following command to start the ISPF user interface:
    ex 'your.CLIST(IHCCHALC)' End of change

    The IMS HALDB Toolkit main menu panel is displayed:

------------------------------

Topic: Using the ISPF user interface > Setting up the environment for the ISPF user interface > Creating an IMS environment

The procedure has been modified as follows:

Procedure

  :

  :

5. On this panel make the following specifications:

  :

The Data sets panel is displayed.

Figure. Data sets panel
(Figure 69 in PDF)

Start of change

End of change

6. From the Data Sets panel, specify the data sets to use when generating the JCL.

Start of changeWhen the IMS management of ACBs is enabled, the following libraries must be specified in the RESLIB:

  •  The SGLXLOAD library of IBM IMS Tools Base for z/OS, Version 1 Release 6 or later
  •  The IMS Catalog Definition exit routine (DFS3CDX0)

Figure xx. Data sets panel when the IMS management of ACBs is enabled

End of change

If the RECONs are not located in either the RESLIB or MDALIB data sets, you can specify them explicitly with option 4. Otherwise, the Specify RECON Data set names panel is skipped.

  :

8. Specify the RECON data set names to use and press Enter.

The DBD Libraries panel is displayed.

Figure. DBD Libraries panel
(Figure 71 in PDF)

Start of change

image 2964

End of change

9. Specify the DBD load libraries to use and press Enter.

Start of changeWhen the IMS management of ACBs is enabled, do not specify the DBD load libraries to use and press Enter.

Figure xx. DBD Libraries panel when the IMS management of ACBs is enabled

End of change

The DBD Conversion Rules panel is displayed.

  :

  :

------------------------------

Topic: Using the ISPF user interface > Processing a project > Creating and submitting JCL

The following topic has been updated as follows:

When all questions have been answered regarding how to process a conversion project, IMS HALDB Toolkit creates JCL and presents an ISPF panel for you to submit it.

Start of changeWhen the IMS management of ACBs is enabled, //IMS DD is not generated.End of change

About this task

  :

------------------------------

Topic: Using the ISPF user interface > Converting to HALDB > Considerations for converting to HALDB

The following topic has been updated as follows:

The following considerations apply when you convert to a HALDB by using the ISPF user interface.

  :

  :

You can also choose to select the partition boundaries again. In this case, the partition definition from the PDB is ignored and the database is treated in the same way as any full-function database.

Start of changeConsiderations for converting to HALDB when the IMS management of ACBs is enabled:

  • New database definitions must exist in the IMS catalog staging data sets before running the ISPF user interface.
  • The shadow database is unloaded by using the active database definition obtained from the IMS catalog directory data sets, then reloaded by using the pending database definition obtained from the IMS catalog staging data sets.
  • JCL for DBDGEN is not generated because the pending database definition obtained from the IMS catalog staging data sets is used.
  • JCLs for image copy are not generated because the image copy utility does not support the pending database definition obtained from the IMS catalog staging data sets. You must take an image copy manually after the conversion.End of change
------------------------------

Topic: Using the ISPF user interface > Converting to HALDB > Converting to HALDB using the ISPF user interface

The procedure has been modified as follows:

You can use the ISPF user interface to convert your full-function databases to HALDB.

Procedure

1. Start of changeWhen the IMS management of ACBs is enabled, create the IMS catalog staging data sets. You can refer to the examples in "CONVERT example: Preparing a staging data set before converting a database when the IMS management of ACBs is enabled".End of change

2. To display the DBD Conversion Selection panel, select option 1 (Continue with Current Project) from the Project Work panel. If you did not select DBDs, or if you cleared the project data set, this step is necessary.   

3. Select one of the provided DBD libraries, or enter a specific DBD library and press Enter to see a list of DBDs.

Start of changeWhen the IMS management of ACBs is enabled, no DBD library is displayed. Press Enter without selecting or specifying a DBD library.End of change

All DBDs and related databases must be converted together. You must select, at minimum, the primary DBD.

Figure. DBD Conversion Selection panel
(Figure 117 in PDF)

Start of change

End of change

Start of change

Figure xx. DBD Conversion Selection panel when the IMS management of ACBs is enabled

4. Select the primary DBD to be converted; related DBDs are automatically added to the list.

  :

7.Continue processing the project as described in “Processing a project".

8.Start of changeWhen the IMS management of ACBs is enabled, issue the IMPORT DEFN SOURCE(CATALOG) command to activate the new database definition.End of change

9.Start of changeWhen the IMS management of ACBs is enabled, take an image copy manually.End of change

10.After the conversion process is complete...

------------------------------

Topic: Using the ISPF user interface > Maintaining HALDB > Selecting DBDs for maintenance

The procedure has been modified as follows:

If you select option 1 on the Split or Consolidate HALDB Partitions panel, you are asked to select the DBD.

About this task

DBDs are extracted from the RECON.

The HALDB DBDs panel is displayed.

Select the DBD to be processed. Only one DBD can be selected at-a-time.

Figure. Selecting HALDB DBDs
(Figure 122 in PDF)

The panel is displayed for selecting the DBD library which contains the selected DBD, as shown in the following example.

Select the appropriate DBD library or type the data set name. The DBD library you choose will be associated with the project.

Start of changeWhen the IMS management of ACBs is enabled, no DBD library is displayed. Press Enter without selecting or specifying a DBD library.End of change

Figure. Selecting HALDB DBD library
(Figure 123 in PDF)

Start of change

End of change
Start of change
Figure xx. Selecting HALDB DBD library when the IMS management of ACBs is enabled
image 2972
End of change
The next step is to select a partition.
------------------------------

Topic: Reference > Sample reports > IHCLIST data set > HALDB Analyzer report

The following figures have been changed to expand the space for Exception details value:

Start of change
Figure 141. HALDB Analyzer report (Part 2 of 6)

image 3008
End of change

Start of change
Figure 142. HALDB Analyzer report (Part 3 of 6)


End of change

Start of change
Figure 143. HALDB Analyzer report (Part 4 of 6)


End of change

Start of change
Figure 144. HALDB Analyzer report (Part 5 of 6)


End of change

Start of change
Figure 145. HALDB Analyzer report (Part 6 of 6)


End of change

------------------------------

Topic: Reference > Contents of the sample library file (SIHCSAMP)

A new member IHCCHALC has been added as follows:

This reference topic provides descriptions for the contents of the IMS HALDB Toolkit sample library file (SIHCSAMP).

The following members are included in sample library SIHCSAMP:

IHCCHAL

This member provides the sample skeleton CLIST for ISPF invocation.

Requirement: The ISPF data set names must match the target library names.

Start of change

IHCCHALC

This member provides the sample skeleton CLIST for ISPF invocation.

When the IMS management of ACBs is enabled, you must use this CLIST to start the ISPF user interface, and specify ACBMGMT=CATALOG in the IMS Catalog Definition exit routine (DFS3CDX0).

When the IMS management of ACBs is not enabled, ISPF is generally invoked using IHCCHAL. However, when you specify ACBMGMT=ACBLIB in the IMS Catalog Definition exit routine (DFS3CDX0), you can also use the CLIST provided by IHCCHALC to start the ISPF user interface.   

Requirement: The ISPF data set names must match the target library names.

End of change

IHCCHAL1

This member provides the skeleton CLIST for invocation from control suite.

...

------------------------------

Topic: Troubleshooting > Messages and codes > Batch messages

The following new messages have been added:

---

Start of change

IHC01707I NEWDBD will be obtained from catalog staging data set

Explanation

The new DBD will be obtained from the IMS catalog staging data set. 

System action

None.

User response

None. This message is informational.

End of change

---

Start of change

IHC01708W IMPORT DEFN SOURCE(CATALOG) is required

Explanation

IMS HALDB Toolkit converted the database using the new database definition obtained from the IMS catalog staging data set, but the staging data sets are not activated in online IMS subsystems.

System action

Processing continues.

User response

Perform these steps to complete the DBD change:

1. Issue the IMPORT DEFN SOURCE(CATALOG) command to activate the new database definition in online IMS subsystems.

2. If the Integrity Checker utility of IMS Library Integrity Utilities is active in your environment, use the LICON utility and re-create the RDE.

3. Turn off the prohibit authorization flag and bring the database back online.

End of change

---

Publication Number

SC27-8779-01

[{"Business Unit":{"code":"BU054","label":"Systems w\/TPS"},"Product":{"code":"SSCCH2E","label":"IMS Database Utility Solution for z\/OS"},"ARM Category":[],"Platform":[{"code":"PF035","label":"z\/OS"}],"Version":"2.1.0","Edition":"SC27-8779-01"}]

Document Information

Modified date:
23 June 2020

UID

ibm16198771