IBM Support

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

Product Documentation


Abstract

Updates that apply to IMS Database Solution Pack V2.1: IMS HALDB Toolkit User's Guide (SC19-4102-02).

Content

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


Update 8

Date of change: April 2019

Change description: User's guide updates.

Topic: Reference

The following new topic has been added:

image-20180716101203-34

Performance tips and considerations

Use the following information to learn the techniques for improving the performance of ANALYZEPART, CONVERT, and MAINTAIN function jobs.

Generally, the performance of an IMS HALDB Toolkit job is not affected by IHCSYSIN command parameters. However, you can improve the IMS HALDB Toolkit job performance by tuning the processes of other IMS tools products that IMS HALDB Toolkit calls. Such IMS tools products include IMS High Performance Unload, IMS High Performance Load, and IMS High Performance Image Copy.

The following table summarizes the IMS tools products that IMS HALDB Toolkit functions call.

IMS Tools product ANALYZEPART CONVERT MAINTAIN
IMS HP Unload X X X
IMS HP Load - X X
IMS HP Image Copy
- X X

Improving the performance of the unload process (IMS HP Unload)

If IMS High Performance Unload is used for unloading data, you can tune and improve the performance of the unload process. To do so, create an IMS High Performance Unload default option table (FABHOPT) with HSSROPT control statements that improve the performance of the HSSR Engine and concatenate the FABHOPT to the STEPLIB DD of the IMS HALDB Toolkit JCL job.

For more information about creating an IMS High Performance Unload default option table, see the topic "Site default options" in the IMS High Performance Unload User's Guide.

Improving the performance of the load process (IMS HP Load)

If IMS High Performance Load is used for loading data, you can tune and improve the performance of the load process. To do so, provide IMS High Performance Load control statements with the following methods:
  • Specify RELOAD.xxxx parameters in the IHCSYSIN DD. RELOAD.xxxx parameters are applied to the load process as FRRIN control statement keywords to control the behavior of the load processing.
  • Create an IMS High Performance Load default option table (HPSROPT) with FRRIN control statements that improve the performance of the load processing and concatenate the HPSROPT to the STEPLIB DD of the IMS HALDB Toolkit JCL job.
HPSROPT, if concatenated to the STEPLIB DD, is always referred to. All RELOAD.xxxx parameters in IHCSYSIN DD and applicable FRRIN control statement keywords in HPSROPT are applied to the load process. If the same parameter is present in both IHCSYSIN DD and HPSROPT, for example, RELOAD.HPIO(YES) in IHCSYSIN DD and HPIO=N in HPSROPT, the parameter in IHCSYSIN is applied.

For more information about creating an IMS High Performance Load default option table, see the topic “Setting installation default options” in the I MS High Performance Load User’s Guide.

Improving the performance of the image copy process (IMS HP Image Copy)

If IMS High Performance Image Copy is used for creating image copies, you can tune and improve the performance of the image copy process. To do so, provide IMS High Performance Image Copy control statements with the following methods:
  • Specify IC.xxxx parameters in the IHCSYSIN DD. IC.xxxx parameters are applied to the image copy process as ICEIN control statement keywords to control the behavior of the image copy processing.
  • Create an IMS High Performance Image Copy default option table (FABJGLI0) with ICEIN control statements that improve the performance of the image copy processing and concatenate the FABJGLI0 to the STEPLIB DD of the IMS HALDB Toolkit JCL job.
FABJGLI0, if concatenated to the STEPLIB DD, is always referred to. All IC.xxxx parameters in IHCSYSIN DD and applicable ICEIN control statement keywords in FABJGLI0 are applied to the load process. If the same parameter is present in both IHCSYSIN DD and FABJGLI0, for example, IC.VIC(Y) in IHCSYSIN DD and VIC=N in FABJGLI0, the parameter in IHCSYSIN is applied.

For more information about creating an IMS High Performance Image Copy default option table, see the topic “Setting default values for the FABJMAIN program” in the IMS High Performance Image Copy User’s Guide.
end of change



Update 7
Date of change: May 2018
Change description: Documentation change by APAR PI96822.

Topic: Troubleshooting > Messages and codes > Batch messages

The following new message has been added:

IHC01023E Unsupported level of IMS is being used

Explanation: IMS HALDB Toolkit is run under an unsupported version of IMS.
System action: Processing stops.
User response: Run IMS HALDB Toolkit with a supported version of IMS.


Update 6
Date of change: April 2018
Change description: Documentation change by APAR PI95128. The CONVERT and MAINTAIN functions support the GDGLIMIT parameter, which controls the number of maximum data sets that can be associated with a GDG.
Topics: Changes apply to multiple topics.

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

GDGLIMIT parameter has been added to the following table:

Table. CONVERT command parameters
(Table 8 in PDF)
Parameter
Requirement
Description
... ... ...
FSPF Optional ...
GDGLIMIT Optional Specifies the maximum number of GDG (generation data group) data sets that can be associated with the GDG. This value is used only when the GDG base does not exist and a GDG is created during the job,
IMS HALDB Toolkit uses the value specified for this parameter when a GDG is requested for image copy data sets.
If you specify one of the following parameters, the existence of a GDG base is verified before the image copy data set is allocated:
    • ICTRLR(1) to request that image copy data sets are GDGs
    • &GDG is specified on the IC1DSN or IC2DSN parameter to request that image copy data sets are GDGs
If a GDG base does not exist, IMS HALDB Toolkit automatically defines one using the GDGLIMIT parameter value to control the number of generations to keep.

Format: (1 - 255)
Default value: 20
... ... ...

IC1DSN parameter has been updated as follows:

IC1DSN
...
&JOBNAME
  • Name of this job.
...
...
&TIME2
  • ...
&GDG
  • The identifier for the GDG data set.
    If specified, &GDG must be the last value on the IC1DSN parameter.
where:
    • yyyy is the 4-digit year
    • ...
Topic: Maintaining HALDBs > Maintaining HALDB using MAINTAIN > MAINTAIN command parameters

GDGLIMIT parameter has been added to the following table:

Table. MAINTAIN command parameters
(Table 12 in PDF)
Parameter
Requirement
Description
... ... ...
FSPF Optional ...
GDGLIMIT Optional Specifies the maximum number of GDG (generation data group) data sets that can be associated with the GDG. This value is used only when the GDG base does not exist and a GDG is created during the job,
IMS HALDB Toolkit uses the value specified for this parameter when a GDG is requested for image copy data sets.
If you specify one of the following parameters, the existence of a GDG base is verified before the image copy data set is allocated:
    • ICTRLR(1) to request that image copy data sets are GDGs
    • &GDG is specified on the IC1DSN or IC2DSN parameter to request that image copy data sets are GDGs
If a GDG base does not exist, IMS HALDB Toolkit automatically defines one using the GDGLIMIT parameter value to control the number of generations to keep.

Format: (1 - 255)
Default value: 20
... ... ...
IC1DSN parameter has been updated as follows:

IC1DSN
...
&JOBNAME
  • Name of this job.
...
...
&TIME2
  • ...
&GDG
  • The identifier for the GDG data set.
    If specified, &GDG must be the last value on the IC1DSN parameter.
where:
    • yyyy is the 4-digit year
    • ...
Topic: Troubleshooting > Messages and codes > Batch messages

The following new message has been added:

IHC01206I A GDG base entry is being created. NAME: GDG_base, LIMIT: nnn

Explanation: The IDCAMS utility is creating a GDG base entry. GDG_base shows the name of the GDG base entry data set, and nnn shows the maximum number of data sets that can be associated with the GDG.
System action: None.
User response: None. This message is informational.



Update 5
Date of change: January 2018
Change description: Documentation change by APAR PI90471. This APAR enables IMS HALDB Toolkit to use the HD Reorganization Reload utility (DFSURGL0) to load PSINDEX databases even when IMS High Performance Load modules exist in the combined load library of IMS Database Solution Pack in STEPLIB.
Topics: Changes apply to multiple topics.

Topic: Introduction to IMS HALDB Toolkit > IMS HALDB Toolkit overview > Usage and Restrictions

The database limitations section has been modified as follows:

Database limitations
...
The MAINTAIN function processes PSINDEXes only when the PSINDEX is offline.
Topic: Maintaining HALDBs > Maintaining HALDB using MAINTAIN > MAINTAIN DD statements

Explanation for DFSRESLB DD has been modified as follows:

DFSRESLB
  • This statement is optional. The statement points to an authorized library that contains IMS SVC modules.
    IMS HALDB Toolkit dynamically allocates this DD if you do not provide it.
    Even if IMS High Performance Load modules are found in the combined load library of IMS Database Solution Pack in the STEPLIB concatenation, when the MAINTAIN function processes PSINDEXes, the function uses DFSURGL0 (HD Reorganization Reload utility) in this library to reload PSINDEXes.
Topic: Troubleshooting > Messages and codes > Batch messages

The following new message has been added:


IHC01205E DFSRESLB DD is required to MAINTAIN PSINDEX.

Explanation: When the MAINTAIN function processes PSINDEXes, the function uses DFSURGL0 (HD Reorganization Reload utility) in the DFSRESLB DD to reload databases. Because the DFSRESLB DD statement is not coded in the JCL, IMS HALDB Toolkit attempted to dynamically allocate the DFSRESLB DD statement using the IMS RESLIB library. However, the IMS RESLIB library containing IMS SVC modules was not found in the STEPLIB concatenation so IMS HALDB Toolkit did not allocate the DFSRESLB DD statement.
System action: Processing terminates.
User response: Specify the IMS RESLIB library containing IMS SVC modules to the STEPLIB DD statement or the DFSRESLB DD statement and rerun the job.



Update 4
Date of change: November 2017
Change description: Documentation change by APAR PI87941. This APAR enhances the ANALYZEPART function to support unload data sets as input for simulation.

Topic: Simulating HALDBs > Simulating HALDB using ANALYZEPART > ANALYZEPART data flow

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

Figure. ANALYZEPART data flow
(Figure 1 in PDF)


Topic: Simulating HALDBs > Simulating HALDB using ANALYZEPART

The following new topic has been added after "Simulating repartitioning of a HALDB":

Simulating conversion or repartitioning using unloaded data sets as input

You can use unloaded data sets of a full-function database to simulate conversion from a full-function database to a HALDB, or unloaded data sets of a HALDB to simulate repartitioning of a HALDB.

About this task
Instead of supplying a full-function database or a HALDB as input for the ANALYZEPART function, you can supply unloaded data sets of a full-function database or of a HALDB and simulate the effect of database conversion or repartitioning.
Restriction: When you simulate conversion from a full-function database to a HALDB by supplying unloaded data sets as input, the ANALYZEPART function processes only the primary DBD that is specified on the DBD parameter. It does not process any secondary index databases.

Procedure
  • 1. Prepare the unloaded data sets. If you already have unloaded data sets, make sure your unloaded data sets satisfy the following requirements:
        • The ANALYZEPART function reads all data in the unloaded data sets that you specify on the DFSUINPT DD statement. If your unloaded data sets contain all the data of a HALDB and you want the ANALYZEPART function to process only some partitions, you must split the unloaded data sets so that the unloaded data sets that you specify on the DFSUINPT DD statement contain only the data of partitions that you want to process. You can do so by using the split unload file utility. For more information, see "Example 4: Split unloaded data sets and simulate repartitioning of a HALDB".
        • If the data in the unloaded data sets is masked and the original database uses unique keys, you must mask the unloaded data sets by using different unique values. The ANALYZEPART function does not check for duplicate keys. If duplicate keys exist in the unloaded data sets, the result of simulation might not be as expected.
        • If the database contains compressed segments (in other words, if the SEGM statements of the DBDGEN utility has a COMPRTN keyword), use the FABHURG1 utility of IBM IMS High Performance Unload for z/OS to create the unloaded data sets. You must specify the DECN control statement for the FABHURG1 utility to create unloaded data sets that the ANALYZEPART function can read. For more information, see the topic "FABHURG1 unload utility" in the IMS High Performance Unload User's Guide.
    2. Locate the sample JCL members in the SIHCSAMP file, members IHCEMAIx.
    3. Specify the JCL DD statements. For a list of DD statements, see "ANALYZEPART DD statements".
      • A) Specify a DFSUINPT DD statement and code the names of all the unloaded data sets on the statement.
        B) Specify other JCL DD statements.
    4. Specify the ANALYZEPART command parameters. For a list of ANALYZEPART command parameters, see "ANALYZEPART command parameters". For examples, see "ANALYZEPART example: Using unloaded data sets as input".
      • A) Specify the INPUT(UNLOAD) parameter. This parameter requests the ANALYZEPART function to read data from unloaded data sets.
        B) If the unloaded data sets contain data from a HALDB, specify the partitions to simulate with the PARTLIST parameter or the PARTITION parameter. The ANALYZEPART function does not check the consistency of partitions against the unloaded data sets specified on the DFSUINPT DD statement. If there is inconsistency between the partitions and data in the unloaded data sets, the result of simulation might not be as expected.
        C) Specify other ANALYZEPART command parameters.
    • When unloaded data sets are provided as input, the ANALYZEPART function ignores the following parameters:
        • Parameters related to secondary index databases (INDPART, INDPRIM, INDSIZE)
        • READINT parameter
Topic: Simulating HALDBs > Simulating HALDB using ANALYZEPART > ANALYZEPART DD statements

DFSUINPT DD has been added as follows:

Table. DD statements and record format for the ANALYZEPART command
(Table 3 in PDF)
DD name Use Format Need
original_dbds
DFSUINPT Input Same as IMS Conditionally required

...

DFSUINPT
This statement is required when you supply unloaded data sets as input. The statement specifies one or more data sets that contain unloaded data of a full-function database or of a HALDB.
The supported format of the unloaded data sets is HD unload format. The ANALYZEPART function processes all the data sets that are specified on this DD statement and all the data inside the data sets.
For more information about supplying unloaded data sets as input, see the following topics:
    • "Simulating conversion or repartitioning using unloaded data sets as input"
    • "ANALYZEPART example: Using unloaded data sets as input"
Topic: Simulating HALDBs > Simulating HALDB using ANALYZEPART > ANALYZEPART command parameters

INPUT parameter has been added to the following table:

Table. ANALYZEPART command parameters
(Table 4 in PDF)
Parameter Requirement Description
INITPART Optional
INPUT Optional Specifies that the input is unloaded data sets.
Code the DFSUINPT DD to specify the unloaded data sets.

Format: (UNLOAD)
Default value: None
Topic: Simulating HALDBs > Simulating HALDB using ANALYZEPART > ANALYZEPART examples

The following new topic has been added:

ANALYZEPART example: Using unloaded data sets as input

If you want to use unloaded data sets as input for the ANALYZEPART function, specify the unloaded data sets on the DFSUINPT DD statement and specify the INPUT(UNLOAD) parameter.

Subsections:
    • "Example 1: Simulate conversion to a HALDB"
    • "Example 2: Simulate repartitioning of a HALDB (all partitions)"
    • "Example 3: Simulate repartitioning of a HALDB (one partition)"
    • "Example 4: Split unloaded data sets and simulate repartitioning of a HALDB"

Example 1: Simulate conversion to a HALDB
To simulate conversion of a full-function database to a HALDB, add the DFSUINPT DD statement and the INPUT(UNLOAD) parameter.
In this example:
    • DFSUINPT DD statement specifies the unloaded data set.
    • INPUT(UNLOAD) parameter specifies to read input data from the unloaded data set.
    • PARTNUM(3) parameter specifies to convert the database into a HALDB with three partitions.

Example 2: Simulate repartitioning of a HALDB (all partitions)
To simulate repartitioning of all the partitions in a HALDB, use the following example.
In this example:
    • DFSUINPT DD statement specifies the unloaded data set. The unloaded data set contains all the data from all the partitions.
    • INPUT(UNLOAD) parameter specifies to read input data from the unloaded data set.
    • PARTITION(*) specifies to process all the partitions in the HALDB.
    • PARTSIZE(2048) specifies to create partitions each with a size of 2048 MB.
    • DBRCOUT parameter and dbrcout DD specify to generate DBRC commands for repartitioning.

Example 3: Simulate repartitioning of a HALDB (one partition)
To simulate repartitioning of one partition into two partitions, use the following example.
In this example:
    • DFSUINPT DD statement specifies the unloaded data set. The unloaded data set contains all the data of the partition.
    • INPUT(UNLOAD) parameter specifies to read input data from the unloaded data set.
    • PARTLIST(part1) specifies to process only one partition.
    • PARTNUM(2) specifies to simulate repartitioning into two partitions.

Example 4: Split unloaded data sets and simulate repartitioning of a HALDB
If you have an unloaded data set that contains data of all partitions and you want to simulate only some partitions, split the unloaded data set by using the split unload file utility before you simulate repartitioning with the ANALYZEPART function.

In this example, you have an unloaded data set that contains all the data from a HALDB that has three partitions (part1, part2, and part3). You want to simulate repartitioning of two partitions (part1 and part2).
  • Step 1: Splitting unloaded data set
    Use the split unload file utility to split the unloaded data set into multiple unloaded data sets. This utility splits unloaded data sets into single partition unloaded data sets. For more information about the split unload file utility, see "Splitting an unload file into single partition files".
    The following JCL example is for the split unload file utility. In this example:
        • DFSUINPT DD statement specifies the unloaded data set that contains all the data of a HALDB that has three partitions.
        • part1Z, part2Z and part3Z DD statements specify the output data sets, which are single partition unloaded data set for each partition.

    Step 2: Simulate repartitioning of two partitions
    Specify the unloaded data sets for part1 and part2 generated by the split unload file utility and run the ANALYZEPART function.
    In this example:
        • your.hd.part1.unload.dataset on the DFSUINPT DD contains unloaded data of partition part1.
        • your.hd.part2.unload.dataset on the DFSUINPT DD contains unloaded data of partition part2.
        • INPUT(UNLOAD) parameter specifies to read input data from the unloaded data sets.
        • PARTLIST(part1,part2) specifies to process two partitions.
        • PARTNUM(3) specifies to simulate repartitioning into three partitions.
Topic: Splitting an unload file into single partition files > IHCUSPLT DD statements

PARTxxZ DD statement has been changed to partition_nameZ DD statement:

Table. DD statements and record format for the IHCUSPLT command
(Table 21 in PDF)
DD name Use Format Need
partition_nameZ Output Required

PARTxxZ partition_nameZ
  • These statements are required. Each of these statements defines the HD unload file for each partition. The DD names for the single partition HD unload files are constructed using the partition name appended with a Z.
Topic: Reference > Sample reports > IHCLIST data set

The table has been updated as follows:
Function Reports
ANALYZEPART
    • Collect DBDs report
    • Runtime Options In Effect report
    • Unload report (Not printed when the input data is unloaded data sets)
CONVERT



Update 3
Date of change: August 2017
Change description: Documentation change by APAR PI85067. This APAR changes the description of parameter ICTRLR.
Topics: Changes apply to multiple topics.

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

Description of parameter ICTRLR has been modified as follows:

Specifies whether to use another final suffix qualifier for image copy data sets.
Format: (1 - 6)
The ICTRLR parameter specifications render the following final suffix qualifiers:
ICTRLR(1)
  • GDG
ICTRLR(2)
  • Dyymmdd.Thhmmss
ICTRLR(3)
  • Dmmddyy.Thhmmss
ICTRLR(4)
  • Dddmmyy.Thhmmss
ICTRLR(5)
  • None.
ICTRLR(6)
  • Dyyddd.Thhmmss
Default value: 2
Topic: Maintaining HALDBs > Maintaining HALDB using MAINTAIN > MAINTAIN command parameters

Description of parameter ICTRLR has been modified as follows:

Specifies whether to use another final suffix qualifier for image copy data sets.
Format: (1 - 6)
The ICTRLR parameter specifications render the following final suffix qualifiers:
ICTRLR(1)
  • GDG
ICTRLR(2)
  • Dyymmdd.Thhmmss
ICTRLR(3)
  • Dmmddyy.Thhmmss
ICTRLR(4)
  • Dddmmyy.Thhmmss
ICTRLR(5)
  • None.
ICTRLR(6)
  • Dyyddd.Thhmmss
Default value: 2



Update 2
Date of change: May 2017
Change description: User's guide update.
Topics: Changes apply to multiple topics.

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

Description of parameter IC1DSN has been modified as follows:

This parameter provides an alternative to using the ICHLQ, ICID, ICMID, and ICTRLR parameters to specify the data set name for an image copy.

Format: (dsname)
The data set name can contain variables. To specify a variable, use an ampersand (&) and enclose the variable in periods (.) .

The following variables are supported:
 ...
Topic: Converting to a HALDB > Converting to HALDB using CONVERT > IMS Online Reorganization Facility commands for CONVERT

Command OPTID has been added to the following list:

When performing conversion tasks online by using the CONVERT command, you can use commands provided by IMS Online Reorganization Facility.
For detailed explanations of the following commands, see the IMS Database Solution Pack IMS Online Reorganization Facility User's Guide.
    • DELETE
    • TAKEOVER
    • TAKEOVER.WINDOW
    • RESTART
    • FEOV
    • OPTID
Topic: Maintaining HALDBs > Maintaining HALDB using MAINTAIN > MAINTAIN command parameters

Description of parameter IC1DSN has been modified as follows:

This parameter provides an alternative to using the ICHLQ, ICID, ICMID, and ICTRLR parameters to specify the data set name for an image copy.

Format: (dsname)
The data set name can contain variables. To specify a variable, use an ampersand (&) and enclose the variable in periods (.) .

The following variables are supported:
 ...
Topic: Maintaining HALDBs > Maintaining HALDB using MAINTAIN > IMS Online Reorganization Facility commands for MAINTAIN

Command OPTID has been added to the following list:

When performing maintenance tasks online using the MAINTAIN command, you can use commands provided by IMS Online Reorganization Facility.

For detailed explanations of the following commands, see the IMS Database Solution Pack IMS Online Reorganization Facility User's Guide.
    • DELETE
    • TAKEOVER
    • TAKEOVER.WINDOW
    • RESTART
    • FEOV
    • OPTID



Update 1
Date of change: March 2017
Change description: User's guide update.

Topic: Troubleshooting > Messages and codes > Batch messages

Explanation and user response sections of message IHC01048I have been modified as follows:

IHC01048I Partition selection size set to 2048MB

Explanation: Simulation, conversion, or maintenance of a HALDB was requested, specifying a fixed number of target
partitions. However, one of the following conditions occurred:
ANALYZEPART
  • The size of the partitions would exceed 8 GB.
CONVERT
  • The size of the partitions would exceed 4 GB.
MAINTAIN
  • For a VSAM or OSAM HALDB whose maximum data capacity is 4 GB, the size of the partitions would exceed 4 GB.
  • For an OSAM HALDB whose maximum data capacity is 8 GB, the size of the partitions would exceed 8 GB.
System action: The selection of a fixed number of partitions is ignored. Processing continues with partition size set to 2 GB. This increases the number of partitions beyond the requested number.
User response: None. The simulation, conversion, or maintenance is valid. It is not necessary to restart with a different parameter.

Publication Number

SC19-4102-02

Copyright Date

2002, 2017

Document information

More support for: IMS Tools

Component: IMS Database Solution Pack: IMS HALDB Toolkit

Software version: 2.1.0

Operating system(s): z/OS

Reference #: 7049542

Modified date: 05 April 2019