IBM Support

Updates to IMS Database Reorganization Expert for z/OS V4.1 USer's Guide

Product Documentation


Abstract

Updates that apply to IMS Database Reorganization Expert V4.1 User's Guide (SC19-1137-06).

Content

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

Update 5

Date of change: June 2019

Change description: Documentation changes by APAR PH11352. The default value for the EXTENT control statement of the IPR Reload utility has been changed. Also, the default value for the EXTENT control statement can be specified in the Installation Default Option Table (HPSCOPTI).

Topics: Changes apply to multiple topics.

==========

Topic: Reorganizing a database in one job step > Smart Reorg control statements > Control statements for the Reload task

Values for the EXTENT keyword have been updated as follows:

Table. Control statements for the Reload task

(Table 27 in PDF)

Keyword Acceptable values Default Description
... ... ... ...
DBRLBUF 1 - 999 150 (for VSAM), 45 (for OSAM) ...
EXTENT 1 - 120 120 ...
FRSPC YES or NO YES ...
... ... ... ...

==========

Topic: Reloading a database > IPR Reload control statements > Overview of the IPR Reload control statements

The default value for the EXTENT keyword has been updated as follows:

Table. IPR Reload utility control statements for process control

(Table 74 in PDF)

Keyword Accepted values Default Description
... ... ... ...
EXTENT 1 - 120 120 ...
... ... ... ...

==========

Topic: Reloading a database > IPR Reload control statements > EXTENT control statement

This topic has been updated as follows:

Specifies the maximum number of extensions of the OSAM data set that can be created.

When IPR Reload detects an extension number that is greater than the EXTENT control statement value, IPR Reload issues message HPSR3739E and ends abnormally:

  • If HPIO=YES, IPR Reload checks the extension number during the reorganization. It checks the number every time an extent is allocated. The job could end abnormally during the reorganization.
  • If HPIO=NO, IPR Reload checks the extension number after the reorganization. The job ends abnormally only after the reorganization.

This control statement is optional. The default is EXTENT=120. If the job is run under IMS V13 or earlier, EXTENT=60 is applied.

image 1280

nnn

Specifies a left-aligned decimal number in the range of 1 - 120.

If you are using IMS V13 or earlier, the maximum value is limited to 60.

If the OSAM data set is created on EAV, this control statement is ignored.

Tip: You can change the default value of this control statement by creating an Installation Default Option Table (HPSCOPTI). For more information, see "Setting installation default options".

==========

Topic: Reloading a database > IPR Reload reports > HPSOUT data set > Default Option Tables report

Report example has been replaced with the following figure:

Figure. Default Option Tables report

(Figure 185 in PDF)

image 1279

==========

Topic: Reference > Setting installation default options > How to code HPSCOPT macro statements

EXTENT control statement has been added as follows:

image 1281

The identifier of each utility and the option keywords that are supported by the utility are as follows:

 ...

DRIVRL

This parameter identifies the Reload task under the Smart Reorg Driver. This parameter supports the following values:

 
  • COMPAUTH
  • EXTENT
  • ILEDATAC
  •   ...

...

RELOAD

This parameter identifies the IPR Reload utility. This parameter supports the following values:

  •   ...
  • DECODEDBD
  • EXTENT
  • GDGBASE
  •   ...

Update 4

Date of change: June 2019

Change description: Documentation changes by APAR PH12332. This APAR enhances the Smart Reorg utility to support conditional unload. When conditional unload is enabled, the Smart Reorg utility only unloads the database without reorganizing the database. It can also pass a specific return code to the succeeding job step so that the database is reorganized in the succeeding job step.

Topics: Changes apply to multiple topics.

==========

Topic: Reorganizing a database in one job step > Conditional Reorganization Support Service > What is the Conditional Reorganization Support Service?

This topic has been updated as follows:

...

  1. First evaluation phase
    ...
  2. Reorganization phase
    ...
  3. Second evaluation phase
    ...
  4. Reporting phase
    ...
 

When a Smart Reorg job is run in Conditional Reorganization mode, optionally the Smart Reorg job can create an unload data set without reorganizing the database. When this happens, a specific return code is passed to the succeeding job step to run the database reorganization in the succeeding job step.

When a Smart Reorg job is run in Diagnosis-only mode, the job goes through only the first evaluation phase and the reporting phase.

...

==========

Topic: Reorganizing a database in one job step > Smart Reorg control statements > Control statements for the Smart Reorg Driver > CONDREORG control statement

A note item has been added as follows:

Notes:

  • ...
  • If PSINDEXBLD=YES...
  • To create an unload data set without reorganizing the database, specify UNLOADONLY=YES with CONDREORG=YES or CONDREORG=YES,REORGDIAG.
    For more information, see "UNLOADONLY control statement" and "Example 16: Conditionally reorganizing a database in separate job steps".

==========

Topic: Reorganizing a database in one job step > Smart Reorg control statements > Control statements for the Smart Reorg Driver > RC_CHANGE control statement

New value, POLICY.ACTION.REORG, has been added as follows:

Specifies the return code of the Smart Reorg utility that is returned when a specific event is detected during Smart Reorg utility processing.

This control statement is optional. The default is RC_CHANGE=NONE. 

               .-NONE------------.   
>>-RC_CHANGE=--+-(event_name,rc)-+----------------------------><

event_name

Specifies the name of the event to be detected in Smart Reorg utility processing. The following event name can be specified:

  • POLICY.EXCEPTIONS.CRITICAL

This event specifies a condition where one or more critical-level exceptions exist in the database. This parameter must be specified with CONDREORG=YES, CONDREORG=YES,REORGDIAG, or CONDREORG=YES,DIAGONLY.

If the Smart Reorg utility performs a database reorganization, it returns the specified return code when it detects one or more critical-level exceptions in the reorganized database.

  • POLICY.ACTION.REORG

This event specifies a condition where a database reorganization is needed for the database or for one or more HALDB partitions, and reorganization is not performed yet. This parameter can be specified with CONDREORG=YES,DIAGONLY. However, if UNLOADONLY=YES is specified, this parameter can be specified with CONDREORG=YES or CONDREORG=YES,REORGDIAG. For an example, see "Example 16: Conditionally reorganizing a database in separate job steps".

rc
Specifies the return code for the Smart Reorg utility that will be issued when the event is detected. The maximum value is 99, and the minimum value is 1.

NONE
Does not change the return codes. The default return codes of the Smart Reorg utility are used.

You can specify multiple RC_CHANGE control statements, one for each event.  If two or more events are detected, the largest return code is returned.

==========

Topic: Reorganizing a database in one job step > Smart Reorg control statements > Control statements for the Smart Reorg Driver > STARTDB control statement

This topic has been updated as follows:

In the following cases, the /STA DATABASE command is not issued even if STARTDB=YES is specified:

  • ...
  • In Conditional Reorganization mode, CONDREORG=YES is specified with UNLOADONLY=YES and the CRSS determines that the database reorganization is necessary. In this case, the Smart Reorg utility expects a database reorganization to occur in the succeeding job step.

==========

Topic: Reorganizing a database in one job step > Smart Reorg control statements > Control statements for the Smart Reorg Driver

The following new topic has been added:

UNLOADONLY control statement

Specifies to run only the Unload task to create an unload data set without reorganizing the database.

This control statement is optional. The default is UNLOADONLY=NO.

 image 1272 

NO 

Both the Unload task and the Reload task are called to reorganize the database.

YES

Only the Unload task is called to create an unload data set. The Reload task and any other reorganization-related tasks are not called. Shadow data sets are not used.

  • The DFSURGU1 DD statement is required for the unload data set.
  • You can specify the format for the unload data and a user exit routine by providing the OUTPUT control statement in the (UNLOAD) block of the HPSIN control statements. For example:
    (UNLOAD)
      OUTPUT=DFSURGU1,*HD,(MYEXIT,B)
    If the OUTPUT control statement is omitted, OUTPUT=DFSURGU1,*HD is used. For more information, see "OUTPUT control statement".
  • The database must be in the read-only state during unload. To set the database to the read-only state, specify DBRCAUTHCMD=YES, IMSCMD=YES,TOSI, and STARTDB=YES.  For more information, see "DBAUTHCMD control statement", "IMSCMD control statement", and "STARTDB control statement".

You can specify UNLOADONLY=YES in Unconditional Reorganization mode and Conditional Reorganization mode. 

  • When CONDREORG=YES is specified, an unload data set is created only when the CRSS determines that the database reorganization is necessary. For HALDB, an unload data set is created for the partitions that require reorganization.
  • When CONDREORG=YES,REORGDIAG is specified, an unload data set is always created regardless of the results from CRSS policy evaluation. For HALDB, an unload data set is created for all partitions.
  • When CONREORG=YES,DIAGONLY is specified, the Unload task is not called and, therefore, unload data set is not created.

For an example, see "Example 16: Conditionally reorganizing a database in separate job steps".

==========

Topic: Reorganizing a database in one job step > Smart Reorg control statements > Control statements for the Unload task

Description of OUTPUT has been updated as follows:

Table. Control statements used for controlling Unload function

(Table 24 in PDF)

Keyword Acceptable values Default Description
... ... ... ...
OUTPUT (See OUTPUT control statement) SYSUT2,*HD Specifies the characteristics of the output data sets to be created and the optional user exit routine for the output.

The default DD name SYSUT2 has a special meaning; the data written into SYSUT2 is passed to the Reload task. For the DD name SYSUT2, only the *HD unload record format is allowed.
If UNLOADONLY=YES is specified in the (REORG) block, the default DD name is DFSURGU1. SYSUTn (n=2,3,4) is not supported.

See OUTPUT control statement.

... ... ... ...
==========

Topic: Reorganizing a database in one job step > Smart Reorg examples

The following new example has been added:

Example 16: Conditionally reorganizing a database in separate job steps

This example shows JCL streams to evaluate a HIDAM database and, if the database requires a reorganization, create an unload data set and run the reorganization in the succeeding job step.

In this example:

  • The database is evaluated by Conditional Reorganization Support Service (CRSS). If the database needs to be reorganized, the Smart Reorg utility calls the Unload task to create an unload data set and returns a specific return code, which will be passed to the succeeding job step.
  • If a specific code is returned in the first job step, the data sets of the database and its secondary indexes are deleted and newly defined. The database is reorganized in one job step by the Smart Reorg utility, which calls the Reload task, the Index Build task, and the Image Copy task.

Figure. Sample JCL stream to diagnose a database and conditionally unload the database

image 1270

  • CONDREORG=YES and UNLOADONLY=YES specify to diagnose the database and unload the database if the database needs to be reorganized.
    If CONDREORG=YES,REORGDIAG is specified instead of CONDREORG=YES, the database is always unloaded regardless of the evaluation result.
  • The DFSURGU1 DD statement specifies the output unload data set. 
  • RC_CHANGE=(POLICY.ACTION.REORG,22) specifies that return code 22 is returned if the database requires reorganization.
  • The database must be in the read-only state while it is being unloaded. DBRCAUTHCMD=YES specifies to issue the DBRC commands and IMSCMD=YES,TOSI specifies to issue IMS commands automatically.
  • CHECKREC=YES in the (UNLOAD) block is required to pass certain information to the Reload task called in the succeeding job step.

Figure. Sample JCL stream to reorganize the database depending on the return code from the previous step

image 1271

  • The two job steps are processed when the return code from the CONDUNLD job step indicates that the database requires a reorganization.   
  • Before starting the Smart Reorg step, the original database data sets are deleted and defined. The shadow data sets are not used.
  • REORGINPUT=ULDS specifies to reload the database using the unload data set that the DFSUINPT DD statement specifies.
  • INDEXBUILD=YES and IC=YES specify to call the Index Builder task and the Image Copy task. 
  • IMSCMD=YES,TOSI specifies to issue IMS /DBR commands and STARTDB=YES specifies to issue IMS /STA commands automatically.

==========

Topic: Troubleshooting > Messages and codes > Messages > HPSG messages

The following new message have been added:

HPSG0253E INCORRECT EVENT OR RC IN RC_CHANGE STATEMENT

Explanation:  An invalid event name or return code is specified for the RC_CHANGE control statement. The event name must be either POLICY.ACTION.REORG or POLICY.EXCEPTIONS.CRITICAL. The return code must be in the range of 1 to 100.  If RC_CHANGE=NONE is specified, a return code value cannot be specified.

System action: The Smart Reorg utility ends with a return code of 8.

User response: Correct the RC_CHANGE control statement error, and rerun the job.

---

 

HPSG0456W UNABLE TO ISSUE /STA BECAUSE REORGANIZATION IS NEEDED

Explanation:  The Conditional Reorganization Support Service (CRSS) determined that the database needs to be reorganized, but the database is not reorganized yet because UNLOADONLY=YES is specified. The /STA DATABASE command is not issued even though STARTDB=YES is specified.

System action: The Smart Reorg utility ends with a return code of 4.

User response: Run a database reorganization after this job step. 

---

The explanation sections of the following messages have been updated:

HPSG2319I   EVENT "event_name" IS DETECTED AND RC_CHANGE WILL BE APPLIED

Explanation: The event that was specified by the RC_CHANGE control statement is detected. The return code of the Smart Reorg utility is changed as specified on the RC_CHANGE control statement.

The event that is indicated by event_name is:

     
POLICY.EXCEPTIONS.CRITICAL Critical-level exceptions remain in the database.
POLICY.ACTION.REORG The database requires a reorganization.

System action: ...

User response: ...

---

HPSG0010W process_option ENDED FOR DATABASE dbdname (RC=04, RSN=xxxxxxxx)

Explanation: ...

Reason code  Meaning

...
 

40100018  The automated /STA command is not issued. See message HPSG0456W.

...

System action: ...

User response: ...

---

HPSG0111E PRE-PRODUCT ERROR (reason); PROD=prodname


Explanation: ...

Reason code  Meaning

...
01000008       IMS HP Unload V1 with APAR PH12333 is required.

...

System action: ...

User response: ...


Update 3

Date of change: June 2019

Change description: Documentation change by APAR PH11511. This APAR enhances the FF Database Sensor to support encrypted VSAM ESDS database data sets.

Topic: Reorganizing a database in one job step >  Smart Reorg control statements > Control statements for the Smart Reorg Driver > SPACEALLOC control statement

A new item has been added to the Notes section as follows:

Notes:

  • If a new or reusable data set with the shadow name is not found, the Smart Reorg utility generates the commands for allocation.
  • If the original data set is not SMS-managed, and the old data set with the shadow name remains1, the volume list is derived from the old shadow data set. If the old shadow data set is not found, the volume list is derived from the original data set. You should take care whether there is enough available space on the volumes.
  • If the original data set is SMS-managed, the number of volumes and the SMS classes are derived from the original data set and the volumes are assigned by SMS.
  • To encrypt data sets with z/OS data set encryption, the original data sets must be associated to a SMS data class that has an encryption key label.
  • The primary space quantity for an OSAM shadow data set is determined by adding up the space allocated in the first three extents of the original data set. Therefore, the space allocated for the shadow data set might not match the space that was specified for the original data set.
  • If you specify CONDREORG=YES and if the Smart Reorg utility did not reorganize the database, shadow data sets are not deleted or allocated even if you specify SPACEALLOC=YES or SPACEALLOC=YES,FORCE.


Update 2

Date of change: May 2019

Change description: Documentation changes by APAR PH09434. By this APAR, new parameters, which specify the access intent of the database, are added to the STARTDB control statement.

Topics: Changes apply to multiple topics.

==========

Topic: Reorganizing a database in one job step > Smart Reorg control statements > Control statements for the Smart Reorg Driver > STARTDB control statement



New parameters have been added as follows:


Specifies whether a /START DB command is issued automatically after the completion of the post-reorganization processing.

This control statement is optional. The default is STARTDB=NO.

image-20190527094405-1

STARTDB=YES must be specified together with NAMESWAP=YES, IMSCMD=YES,TOSI, and TOSIXCFGRP=.

If STARTDB=YES is specified, Smart Reorg utility sends the following command to the IMS online subsystems, to which the /DBR command has been issued by Smart Reorg utility:

START DB dbname LOCAL DBALLOC

The second parameter of the STARTDB control statement, which is the access option and is applied as the value of the ACCESS parameter of the /START DB command, is optional and it specifies the access intent RO, RD, UP, or EX.

If the job is run for a HALDB, the /START DB command is issued for the HALDB master and HALDB partitions. If the second parameter is omitted, the ACCESS parameter is omitted and the /START DB command is issued only for HALDB partitions.

Restrictions:
  • The access option of the STARTDB control statement and the GLOBAL option of the IMSCMDOPT control statement are mutually exclusive.
  • In the following cases, the /START DB command is not issued even if STARTDB=YES is specified.
    • The reorganization processing fails.
    • The name swapping process or DBRC notification processing fails.
    • The NEWDBD control statement is specified.
    • The prefix resolution and update processing for non-HALDB is not done for logical relationships.
    • The secondary indexes building for non-HALDB is not done.
    • For HALDBs, either the ILDS is not built or the PSINDEX is not built.
    • The Image Copy Needed (ICNEEDED) flag is on.

Tip: You can change the option parameters for the /STA commands by using the IMSCMDOPT control statements. For more information, see IMSCMDOPT control statement.

==========

Topic: Troubleshooting > Messages and codes > Messages > HPSG messages

The following new message has been added:

HPSG0252E ACCESS OPTION IN STARTDB STATEMENT IS NOT ALLOWED WHEN /STA DB GLOBAL

Explanation: The access option of the STARTDB control statement cannot be specified when the GLOBAL option of the IMSCMDOPT control statement is enabled for the /STA command.
System action: The Smart Reorg utility ends with a return code of 8.
User response: Remove the access option of the STARTDB control statement, or specify the LOCAL option for the IMSCMDOPT control statement for the /STA command.
==========

Topic: All applicable topics.

All mentions of "/STA DATABASE" have been changed to "/START DB".




Update 1
Date of change: February 2019
Change description: Documentation changes by APAR PH07025. This APAR enhances the IPR Unload utility to print statistics about twin chained segments in the Segment Statistics report.
Topic: Unloading a database > IPR Unload reports > Segment Statistics report

This topic has been updated as follows:

This report contains information about the segments in databases by segment type.
This report does not show the segment types of a virtual logical child.
For HDAM, PHDAM, or HISAM databases, information about the segments in the overflow area or the overflow data set is shown by segment type under SEGMENT IN OVERFLOW STATISTICS. For HALDBs, this report is shown for each partition.
In addition to the basic information about segments, this report contains the following sections.

Variable Length Segment Statistics section
When there is any variable-length segment in a database, this section is produced as part of the Segment Statistics report. When there is no variable-length segment, this section is not printed. For HISAM databases, this section is not printed because no segment split occurs for variable-length segments.
This section shows—for each segment type—information about segments of variable-length segments (including compressed fixed-length segments).
This section does not show the segment types of virtual logical child or fixed-length segments.

Variable Length Segment Split Statistics section
When there is any variable-length segment in a database, this section is produced as part of the Segment Statistics report. When there is no variable-length segment, this section is not printed. This section shows—for each segment type—information about segments of split variable-length segments (including compressed fixed-length segments).
This section does not show the segment types of virtual logical child or fixed-length segments.

Twin Segment Statistics section
This section is always produced as a part of the Segment Statistics report. This section is not printed for HISAM and SHISAM databases.
This section shows statistics about twin chained segments.

The following figures show examples of Segment Statistics reports.

The following figure shows an example Segment Statistic report of a case in which the following conditions are met in a HIDAM database:
  • There is no split segment
  • There are variable-length segments
  • There is no segment type for which a Segment Edit/Compression routine is specified


Figure. Segment Statistics report for a HIDAM database (The IPR Unload utility)
(Figure 153 in PDF)
image-20190201095408-1

The following figure shows an example Segment Statistic report of a case in which the following conditions are met in a PHDAM database:

  • There are split segments
  • There are variable-length segments
  • There is a segment type for which a Segment Edit/Compression routine is specified
  • DECOMPRESS=NO is specified

Figure. Segment Statistics report for a PHDAM database (The IPR Unload utility)

(Figure 154 in PDF)

image-20190201095650-2


The following figure shows an example Segment Statistic report of a case in which the following conditions are met in a HISAM database:
  • There are variable-length segments
  • There is a segment type for which a Segment Edit/Compression routine is specified
  • DECOMPRESS=YES is specified

...

The meaning of the fields in the Segment Statistics report is as follows:
...

<<< VARIABLE LENGTH SEGMENT SPLIT STATISTICS >>>
SEGMENT
...
TWIN SEGMENT STATISTICS
The twin chain statistics section provides statistics about twin chained segments:
SEGMENT
The name of the segment.
NUMBER OF CHAINS
The total number of twin chain occurrences for the segment type. N/A is shown if a twin pointer is not defined for the segment.
MAX CHAIN LENGTH
The maximum length of the twin chains.
AVG CHAIN LENGTH
The average length of the twin chains.

Publication Number

SC19-1137-06

Copyright Date

2001, 2019


Cross reference information
Product Component Platform Version Edition
IMS Tools IMS Database Solution Pack z/OS 2.1.0, 2.2.0
IMS Tools IMS Database Utility Solution z/OS 1.1.0, 2.1.0

Document information

More support for: IMS Tools

Component: IMS Database Reorganization Expert

Software version: 4.1.0

Operating system(s): z/OS

Reference #: 0869956

Modified date: 28 June 2019