IBM Support

Updates to IMS High Performance Image Copy V4.2 User's Guide

Product Documentation


Abstract

Updates that apply to IMS High Performance Image Copy V4.2 User's Guide (SC19-2756-02).

Content

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


Update 11

Date of change: May 2019

Change description: User's Guide updates. An attention has been added to alert a condition where the oldest GDG data set gets deleted even when IMS HP Image Copy fails to create image copies. Also, descriptions for output data set naming convention have been updated.

Topics: Changes apply to multiple topics.

==========

Topic: Running IMS HP Image Copy

The following new topic has been added:


Considerations for dynamically allocating output image copy data sets

If generation data group (GDG) is enabled, the oldest generation data set is deleted when the maximum number of generation data sets is reached. This is true even when the Image Copy function or the Create Image Copy function fails to create successfully image copies. For more information, see "Attention: Oldest GDG data set may be deleted".

==========

Topic: Running IMS HP Image Copy > Allocating data sets dynamically > Output image copy data sets

This topic has been updated as follows:

IMS HP Image Copy can allocate output image copy data sets dynamically in both the Image Copy function and the Create Image Copy function.

...

The output type can be selected by the ICOUT and the STACK keyword. Either the ICOUT or the STACK keyword is required to use the Image Copy function and Create Image Copy function.

Attention: Oldest GDG data set may be deleted
IMS HP Image Copy does not support the DELETE subparameter of the z/OS DISP parameter. The DELETE subparameter of the z/OS DISP parameter is one of the abnormal termination (conditional) disposition subparameters that deletes data sets when a job or process terminates abnormally. Therefore, once the output image copy data sets are dynamically allocated in an IMS HP Image Copy job, the allocated output image copy data sets remain regardless whether the job ends successfully or ends abnormally without creating image copies successfully. If the output image copy data sets are allocated as generation data sets (GDS) of generation data group (GDG) and if the maximum allowable number of active generation data sets is reached by the latest output image copy data set that IMS HP Image Copy dynamically allocated – regardless whether the data set is a successful image copy data set or incomplete image copy data set – the oldest generation data set in the GDG is uncataloged and deleted.


==========
Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > ICDALLOC keyword


The following note has been added to the end of this topic:


Attention: If output image copy data sets are dynamically allocated as generation data group (GDG) data sets, the oldest generation data set is deleted when the maximum number of generation data sets is reached. This is true even when the Image Copy function or the Create Image Copy function fails to create successfully image copies. For more information, see "Attention: Oldest GDG data set may be deleted".

==========

Topic: Running IMS HP Image Copy > Allocating data sets dynamically > Output image copy data sets > Using the ICOUT keyword 

This topic has been updated as follows:

Naming convention

When IMS HP Image Copy dynamically allocates an output image copy data set, it determines the name of the output data set based on the naming template or the value of the ICNMRULE keyword.
  • If the data set naming template is defined and no ICNMRULE keyword is supplied, the data set name is generated based on the naming template.
  • If both the data set naming template is defined and an ICNMRULE keyword is supplied, the data set name is generated based on the naming template.
  • If neither the data set naming template nor the ICNMRULE keyword is supplied, ICNMRULE=N is applied and the data set name is generated following the ICNMRULE=N naming convention.
  • If only the ICNMRULE keyword is supplied, the data set name is generated following the ICNMRULE naming convention.

Data set names generated from the ICNMRULE keyword naming convention:
If ICNMRULE=Y: ichlq.ICn.dbdname.ddnameDyyddd.Thhmmss
If ICNMRULE=N: ichlq.ICn.dbdname.ddname
...
First, IMS HP Image Copy tries to dynamically allocate the output data set with a data set displacement of OLD. If the data set is not found, IMS HP Image Copy dynamically then allocates the output data set with a displacement of NEW. You
can control whether to catalog the data set name by name or not, by using the ICCAT parameter.


==========

Topic: Running IMS HP Image Copy > Allocating data sets dynamically > Output image copy data sets > Using stacked image copy data set

This topic has been updated as follows:

When the STACK keyword is specified, the output image copy data set is created as a stacked data set.

...

When the stacked data set is requested, IMS HP Image Copy dynamically allocates a dummy data set first. The dummy data set is not allocated for the real data set, but it is used for controlling the stacking of the data sets internally. If you control
the data set name by using the tape control program, you need to take the dummy data set into consideration.

If a data set naming template is not defined, the name of the output image copy data set is determined as follows:
ichlq.ICn.dbdname.ddname
where:
ichlq:  Specified with the ICHLQ keyword.
n:  1 or 2 indicating a primary or a secondary copy.
dbdname: The DBD name or partition DBD name of the database to be copied.
ddname: The DD name of the target data set group or area to be copied.
yyddd:  Date.
hhmmss: Time stamp.


Update 10

Date of change: November 2018

Change description: Documentation changes by APAR PH04608. This APAR corresponds to IMS V15 APAR PI83450.

Topic:  Troubleshooting > Messages and codes >  Messages


The following new messages have been added:


FABJ3943E  A SYSTEM ABEND WAS DETECTED BECAUSE INCORRECT SVC NUMBER nnn IS USED.
SUBSYSTEM RECORD SSID=ssid MAY REMAIN IN DBRC.


Explanation: The system detected an incorrect type 2 supervisor call (SVC) number (nnn). The type 2 SVC number that is defined in the IMS Installation Defaults module (DFSIDEF0) does not match the SVC number in the IMS system. The SUBSYS record for the IMS subsystem ID (ssid) might remain in the DBRC RECON data sets.

System action: The Image Copy function terminates with ABEND U3943.

User response: Specify a correct type 2 SVC number by using the DFSIDEF macro of the DFSIDEF0 module and rebuild the DFSIDEF0 module. Also, run the LIST.SUBSYS SSID(ssid) command of DBRC and check whether the subsystem record exists or not. If the record remains in the DBRC RECON data sets, delete the record by issuing the following commands:

  • CHANGE.SUBSYS SSID(ssid) STARTRCV
  • CHANGE.SUBSYS SSID(ssid) ENDRECOV
  • DELETE.SUBSYS SSID(ssid)

---

FABJ3974E Module module CANNOT BE LOADED. RC=nnnnnnnn


Explanation: The indicated load module exists in one of the loadable libraries but it cannot be loaded.  

System action: Program FABJMAIN issues a user error abend code of 3974.

User response: Contact IBM Software Support.


Update 9

Date of change: September 2018

Change description: Documentation change by APAR PH02047.

Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > SENSOR_HOME keyword

A restriction item has been added as follows:

The SENSOR_HOME keyword specifies whether to collect the data elements that are related to root segment distribution and store them in the Sensor Data repository of IMS™ Tools KB. This keyword is effective only for full-function databases.

...

Usage notes:

The data elements that are additionally collected when SENSOR_HOME=Y are useful factors for determining the need of database reorganization. For more information about these data elements, see the topic "GLOBAL command keywords for FF Stand-alone DB Sensor" in the IMS Solution Packs Database Sensor User's Guide.

  • This keyword is effective when SENSOR=Y is specified. SENSOR_HOME=Y is ignored if SENSOR=N is specified or if the SENSOR keyword is not specified.
  • If the key compression option of the Segment Edit/Compression exit routine is specified for the root segment, these additional data elements are not collected even when SENSOR_HOME=Y is specified.
  • If you specify RMNAME=(rand,rap,0,bytes) or if you omit the third operand of the RMNAME parameter in the DBD macro, the number of root addressable area (RAA) blocks is defined as zero in the HDAM or PHDAM DBD. In this case, these data elements are not collected even when SENSOR_HOME=YES is specified.
  • When SENSOR_HOME=Y, even if HOMECHK=N is specified, DB Sensor runs as if HOMECHK=(YES,-10,+10) is specified.



Update 8
Date of change: May 2018
Change description: Documentation change by APAR PI97295. Changes to the messages section.
Topic: Troubleshooting > Messages and codes > Messages

The following message has been modified:

FABJ0305W THE CREATED IMAGE COPY DATA SET IS NOT CATALOGED.

Explanation: An image copy data set was created on the tape device. However, this image copy data set was not cataloged.
System action: IMS HP Image Copy continues processing. If a value is specified for the CATLGERROR keyword in the HPSRETCD DD statement, IMS HP Image Copy changes the job-step return code to that value.
User response: Ensure that the catalog definition is correct and catalog the image copy data set manually. If the problem persists, report the return code and reason code from the catalog process to your system administrator.
Tip: This message indicates a warning condition but the return code is RC=00. If you want a different return code to alert you of this condition, specify CATLGERROR=rc in the HPSRETCD DD statement.

===
The following new message has been added:

FABJ0307W THE CREATED IMAGE COPY DATA SET IS NOT CATALOGED BECAUSE THE SAME DATA SET NAME ALREADY EXISTS IN THE CATALOG AS CSIETYPE=x.

Explanation: An image copy data set was created on the tape device. However, this image copy data set was not cataloged because a data set with the same name already exists in the catalog. CSIETYPE identifies the type of the data set that already exists in the catalog.
x:

B: The base entry of the generation data group (GDG)
C: VSAM cluster
D: Data component of VSAM data set
G: Alternate indexes
I: Index component of a VSAM key-sequenced data set
L: Automated tape library (ATL)
R: File path
U: User catalog connector entry
W: ATL volume entry
X: Alias

System action: IMS HP Image Copy continues processing. If a value is specified for the CATLGERROR keyword in the HPSRETCD DD statement, IMS HP Image Copy changes the job-step return code to that value.
User response: Complete either of the following steps:
  • Ensure that the image copy data set name is correct and catalog the image copy data set manually after deleting the existing entry in the catalog.
  • Rerun the job with the IMS HP Image Copy data set naming template enabled so that the new image copy data set is created with a different data set name. The default process return code for the catalog process is RC=00 even if a catalog error is detected. If you want to change the return code, specify CATLGERROR=rc in the HPSRETCD DD statement and rerun the job.



Update 7
Date of change: March 2018
Change description: Documentation changes by APAR PI95184. This APAR enhances the Image Copy function to:

  • Support the large block interface (LBI)
  • Change the handling of Fast Path secondary indexes

Topics: Changes apply to multiple topics.

Topic: Running IMS HP Image Copy > Taking image copies > Considerations for the Image Copy function

"Considerations for Fast Path secondary indexes" section has been updated as follows:

Considerations for Fast Path secondary indexes
When you create image copies of Fast Path secondary indexes, the following considerations apply:
  • The area data set that uses the secondary index database must be processed in the same job step. However, if FPINDEX=YES is defined in the DBD of the index database, the area data set does not have to be processed in the same job step.
  • The IDXSRCH=Y option must be used.
  • When FPINDEX=YES is not specified in the DBD and the area data set that uses the secondary index database is not processed in the same job step, IMS HP Image Copy treats the index database as a full-function index database. If HDPC=Y is specified, the HASH Check process terminates abnormally.
  • DEDB HASH Pointer Check cannot process Fast Path secondary indexes.
Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords

The following new keyword has been added:

LBI keyword
The LBI keyword specifies whether the Image Copy function uses the large block interface (LBI), which allows block sizes that are greater than 32 KB, when it dynamically allocates output image copy data sets on a tape device. If the output device is not a tape, this keyword is ignored.

Statements that support this keyword
  • GLOBAL statement
Site default option
  • Supported
Related keyword
  • None.
Format

Y

Uses the LBI when creating the output image copy data sets.

N

Does not use the LBI when creating the output image copy data sets.

Default value
  • LBI=N
Usage notes:
  • The LBI is applied only when the output device is a tape, including virtual tape. If the output device is DASD, LBI=Y is ignored.
  • When the LBI is applied, the block size of the output data sets is larger than 32,760 bytes.



Update 6
Date of change: October 2017
Change description: User's guide update. Description of the TOIAUTO keyword has been updated.

Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > TOIAUTO keyword

Descriptions of the LOCAL and the GLOBAL parameters have been updated as follows:
...
LOCAL

Issue the /DBRECOVERY, /DBDUMP, and /START commands to each subsystem independently.

  • A /DBRECOVERY or /DBDUMP command is issued only to each subsystem that allocates the database, the area, or the HALDB partition in exclusive mode or update mode.
  • A /START command is issued to each subsystem to which IMS HP Image Copy issued the /DBRECOVERY or the /DBDUMP command.

LOCAL is the default.

Note: If LOCAL is applied, IMS HP Image Copy identifies all the subsystems that allocate the database, the area, or the HALDB partition in exclusive mode or update mode and issue the IMS commands to those subsystems that were identified. If no subsystems match these criteria, IMS commands are not issued to any of the subsystems. If you want IMS HP Image Copy to always issue the /DBRECOVERY or the /DBDUMP command regardless of the condition, specify the GLOBAL parameter.


GLOBAL

Issue the /DBRECOVERY, /DBDUMP, and /START commands with the GLOBAL keyword for the database or the area, which means that these IMS commands apply to all online subsystems that share the database, the area, or the HALDB partition.



Update 5
Date of change: November 2016
Change description: Documentation changes by APAR PI71145. The default value for the number of tasks that can run in parallel in Image Copy jobs has been changed.
Topics: Changes apply to multiple topics.

Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > GRPLIM keyword

The default value for nnn has been changed to 15, and mm to 5.

Format

nnn

The left-aligned maximum number of tasks in the GROUP. Valid value is 0 - 253. When the specified value is 0, it means GRPLIM=253. The default value is 15.

mmm

The left-aligned maximum number of tasks in the GROUP for the Offload Copy process. Valid value is 0 - 64. When the specified value is 0, it means GRPLIM=(,64). The default value is 5.


Default value
  • GRPLIM=(15,5)
Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > SHDWTCTL keyword

The default value has been changed to 15.

Format

nn

The maximum number of shadow data set creation tasks that can run in parallel. The valid value of nn is in the range of 0 - 64.
When the specified value is 0, it means SHDWTCTL=64.

Default value
  • SHDWTCTL=15

Usage note
A shadow data set is created by the COPY command of DFSMSdss or EMC TimeFinder when the COPY or FDUMP process of Advanced Image Copy Services is used. You might need to adjust appropriate SHDWTCTL value in your system environment not to exceed its capacity.
Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > TASKCTL keyword

The default value for nnn has been changed to 15, and mm to 5.

Format

nnn

The maximum number of IC tasks that can run in parallel.
The value must be in the range of 0 - 253. When the specified value is 0, it means TASKCTL=253. The default value is 15.

When the specified DBDS is a HALDB and the database is flagged as ONLINE REORG CAPABLE in DBRC, IMS HP Image Copy automatically determines the ACTIVE DBDS and uses the active DBDS ddname as its input.

mm

The maximum number of tasks that can run in parallel for creating the secondary image copy data set and running HASH Check. This parameter is effective when the COPY process of Advanced Image Copy Services is used. The value must be in the range of 0 - 64. When the specified value is 0, it means TASKCTL=(,64). The default value is 5.

Default value
  • TASKCTL=(15,5)



Update 4
Date of change: November 2016
Change description: User’s guide update.
Topics: Change applies to multiple topics.

IMS Solution Packs Database Sensor User’s Guide is now renamed to IMS Solution Packs Data Sensor User’s Guide. To accommodate this change, references to “IMS Solution Packs Database Sensor User’s Guide” have been changed to “IMS Solution Packs Data Sensor User’s Guide”.



Update 3
Date of change: September 2016
Change description: Documentation changes by APAR PI69169. This APAR enhances IMS HP Image Copy to support EMC TimeFinder in Create Image Copy (CRC) function jobs.
Topics: Changes apply to multiple topics.

Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > DATA_MOVER keyword

This topic has been updated as follows:

The DATA_MOVER keyword defines the data mover utility for Advanced Image Copy Services.

This keyword is applicable to the following processes:
  • FDUMP and COPY processes of Advanced Image Copy Services.
  • Physical copy process (CRCTYPE=P) of the Create Image Copy function, when the format of input image copy data set is Fast Recovery image copy format.
  • Recovery function, when the format of input image copy data set is Fast Recovery image copy format.

Statements that support this keyword
  • GLOBAL statement

Site default option
  • Supported

Related keyword
  • “FASTIC keyword”

Format
...
  • ADRDSSU
    Uses DFSMSdss for the processes of Advanced Image Copy Services. ADRDSSU is the default value.
    If both the input database data set and the output image copy data set use EMC DASD, specifying DATA_MOVER=ADRDSSU causes the IMS HP Image Copy job to end with an error.
  • EMCSNAP
    Uses EMC TimeFinder for the Advanced Image Copy Services process. EMC TimeFinder creates a snap copy of the data set. EMC TimeFinder must be set up to use this option. Otherwise, the job ends with an error.

Default value
  • DATA_MOVER=ADRDSSU

Related reference:
  • "CRCTYPE keyword"
  • “FASTIC keyword”
  • ...
  • ...
Topic: Troubleshooting > Messages and codes > Messages

The following two messages have been deleted.

FABJ4161W MAXIMUM ALLOWED NUMBER OF OUTPUT DATASET(S) EXCEEDED,

ALLOWED:xxxxxxxx
SPECIFIED:yyyyyyyy


Explanation: The specified value for the number of output data set is larger than that is allowed. The exceeded output data sets will not be processed.
System action: IMS HP Image Copy continues processing.
User response: None.
---
FABJ4163E FLASH IMAGE COPY FAILED BECAUSE xxxxxxxxxx

Explanation: Flash image copy failed or was not attempted and ended with the reason xxxxxxxxxx.
System action: IMS HP Image Copy stops processing with a return code of 8.
User response: Review the messages, correct the error, and rerun the job.

The following three messages have been added:

FABJ4223E ERROR OCCURRED FOR THE FOLLOWING DATASET

SOURCE DSN: input_data_set_name
[TARGET DSN: output_data_set_name]


Explanation: IMS HP Image Copy encountered an error while processing a data set during the DFSMSdss API process or the EMC TimeFinder API process.
System action: The image copy process fails.
User response: Check the DFSMSdss message or the EMC TimeFinder message that is related to input and output data sets.

---

FABJ4294I HP IMAGE COPY RETURN FROM EMCSNAP [RC=00000004]

Explanation: IMS HP Image Copy received control from EMCSNAP.
System action: IMS HP Image Copy continues processing.
User response: None. This message is informational.

---

FABJ4295E HP IMAGE COPY RETURN FROM EMCSNAPI RC=nnnnnnnn FOR

[DBD=dbdname DDN=ddname | DBD=master_dbdname PART=partition_name DDN=ddname | DBD=dbdname AREA=areaname]



Explanation: IMS HP Image Copy received an error from EMCSNAP of EMC TimeFinder. RC indicates the return code from EMCSNAP.
System action: The image copy process fails.
User response: Review the messages, correct the error, and rerun the job.



Update 2
Date of change: September 2016
Change description: Documentation changes by APAR PI63757. This APAR enhances Advanced Image Copy Services to support IMS Online Reorganization Facility. You can create image copies in Fast Recovery image copy format in IMS Online Reorganization Facility jobs.
Topics: Changes apply to multiple topics.

Topic: Running IMS HP Image Copy > IMS HP Image Copy reports > Image Copy Dump Process report

This topic has been updated as follows:

ICTIME
  • The time stamp of the image copy start time. This item is not reported when IMS HP Image Copy is started by IMS Online Reorganization Facility.
USID
  • The update set identifier of the database or area when the reorganization occurred. This item is not reported when processed as DBRC=N or IMS HP Image Copy is started by IMS Online Reorganization Facility.
RUNTIME
  • The registered RUNTIME in the IC record of DBRC. This item is not reported when processed as DBRC=N or IMS HP Image Copy is started by IMS Online Reorganization Facility.
STOPTIME
  • The registered STOPTIME in the IC record of DBRC. This item is not reported when processed as DBRC=N or IMS HP Image Copy started by IMS Online Reorganization Facility.
Topic: Running IMS HP Image Copy > IMS HP Image Copy reports > Image Copy Process Summary report

Image Copy Process by Database section
IC REG

The result of image copy registration processing that is done to the DBRC RECON for the database.
REG

  • Registered successfully.

BYP

  • Registration is bypassed because of errors.

N/A

  • IMS HP Image Copy did not register the image copy.
Topic: Creating image copies in other IMS Tools product jobs > IMS Online Reorganization Facility

The following table has been updated with new keywords:

Supported keywords and default values for the image copy process
...
Table. Supported keywords and default values for IMS Online Reorganization Facility
(Table 55 in PDF)
Keyword
Can be specified in ICEIN GLOBAL statement?
Can be specified in ICEIN IC or AIC statement?
Acceptable values
System default
Topics
... ... ... ... ... ...
DSNTYPE Yes Yes LARGE|BASIC BASIC DSNTYPE keyword
... ... ... ... ... ...
ICHLQn Yes Yes None ICHLQn keyword
... ... ... ... ... ...
ICOUT Yes Yes One of the following formats:
Note 2
      • ddname
      • (dd1,dd2)
      • *
      • (*,*)
      • (*,%STACK)
* ICOUT keyword
... ... ... ... ... ...
SHDWDELETE Yes No EACH|ALL EACH SHDWDELETE keyword
SHDWHLQ Yes No shdwhlq.SHDW.dbdname.ddname
or
name_expression
shdwhlq.SHDW.dbdname.ddname SHDWHLQ keyword
SHDWHLQ Yes Yes hlq None SHDWHLQ keyword
SHDWMGMTCL Yes Yes mgmt-class-name None SHDWMGMTCL keyword
SHDWSTORCL Yes Yes store-class-name None SHDWSTORCL keyword
SHDWVOLSER Yes Yes volser
or
(volser1,volser2,...)
None SHDWVOLSER keyword
... ... ... ... ... ...
Notes:
:
2. %NO is not supported for the ICOUT keyword. If specified, the job ends due to ICEIN control statement error.
:



Update 1
Date of change: September 2016
Change description: User's guide updates.

Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > ICHLQ2 keyword

This topic has been updated as follows:

The ICHLQ2 keyword specifies the data set name prefix for the image copy data set.

If the DSN2 keyword is specified, IMS HP Image Copy refers to the symbolic parameter $ICHLQ2 to assign the data set name prefix. If the DSN2 keyword is not specified, IMS HP Image Copy uses the high-level qualifier (hlq) that the ICHLQ2 keyword specifies for the prefix of the secondary image copy data set.

You can use data set name prefix when you request dynamic allocation of the output image copy data set.
Topic: Running IMS HP Image Copy > Control statements and keywords > ICEIN control statement keywords > ICHLQn keyword

This topic has been updated as follows:

The ICHLQn keyword specifies the data set name prefix for the image copy data set.

If the DSNn keyword is specified, IMS HP Image Copy refers to the symbolic parameter $ICHLQn to assign the data set name prefix. If the DSNn keyword is not specified, IMS HP Image Copy uses the high-level qualifier (hlq) that the ICHLQn keyword specifies for the prefix of the nth image copy data set.

Publication Number

SC19-2756-02

Original Publication Date

2016-09-08


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
IMS Tools IMS Fast Path Solution Pack z/OS 1.3.0
IMS Tools IMS Recovery Solution Pack z/OS 1.1.0, 2.1.0

Document information

More support for: IMS Tools

Component: IMS HP Image Copy

Software version: 4.2.0

Operating system(s): z/OS

Reference #: 7048732

Modified date: 20 May 2019