Reference: ADD IC() command

You can use the ADD IC() command for invoking IMS High Performance Image Copy. The syntax and use are described here.

Any parameters specified on the ADD IC() command override those parameters that were specified on the UTILGBL() control statement.

There are also parameters for this auxiliary utility that can only be specified on the UTILGBL() control statement.

For a list and description of those parameters, refer to Reference: Utility control statements.

Syntax for ADD IC() command

The basic format of the ADD command is described in Parameters for ADD command. This section shows the syntax for those parameters that are associated with the IMS High Performance Image Copy usage.

Parameter reference for ADD IC() command

The use of the IC() keyword on the ADD command indicates that an image copy is to be created for each recovered database.

Attention: No image copy of any database or index is created unless the IC() keyword is specified on the ADD command. Specifying only IB(ICNDX(YES)) on the ADD command does not create an image copy.

If you specify OUTPUT(ICR) then an incremental image copy is produced using the prior image copy and archived logs or change accumulation data sets as input. The production database is not accessed and no database data sets are recovered.

If you specify OUTPUT(DUP), any IC statement is ignored and DBRC is unaffected.

Use this keyword with the ADD DB(dbname) command to indicate that an image copy is to be run for the recovered database. No other functions of IMS High Performance Image Copy (such as CIC, CRC) are allowed, nor are parallel processes, such as AIC.

When you specify the OUTPUT(ICR) option, the incremental image copy that is created might be batch or concurrent. A concurrent image copy is created when only a subset of the required logs are available. The time stamp that is used to register the image copy to DBRC is the latest stop time of all the log data sets that were used as input. It is not necessary to stop the database for an incremental image copy.

The following reference shows the IMS High Performance Image Copy options that can be specified on the IC keyword and used by the IMS Database Recovery Facility interface to IMS High Performance Image Copy.

COMP(Y | N)

This parameter specifies whether the Image Copy function is to compress the output image copy data.

Y: Specifies that the output image copy data is to be compressed by the Image Copy function.
N: Specifies that the output image copy data is not to be compressed by the Image Copy function.
The value N is the default.

COMPRTN(routine)

This parameter specifies the name of the compression routine that the Image Copy function invokes to compress the output image copy data.

Note: When the IDRC feature is installed and is active on the native tape drive, software compression is suppressed for the IC1 and IC2 output data sets when the compression is not FABJCMP2.

The setting for routine can have the following meanings:

routine

The name of the compression routine. IMS High Performance Image Copy provides four compression exit routines: FABJCMP1, FABJCMP2, FABJCMP3, and FABJCMP4.

Specify one of these compression routines to be called by the Image Copy function.

If the COMP=Y keyword is specified without the COMPRTN= keyword, FABJCMP1 is used as the default.

The same compression routine is automatically called by the Database Recovery function to extract the compressed data.

Attention: If you want to create a compressed image copy data set for a DEDB that has an SDEP segment, you must use FABJCMP4. FABJCMP1, FABCMP2, and FABJCMP3 cannot be used for a DEDB that has an SDEP segment.

IMS High Performance Image Copy provides the following compression routines:

FABJCMP1: Does repeated character compression.
Free space can also be compressed.
FABJCMP2: Does only free space compression.
Segmented data is not compressed.
FABJCMP3: Does repeating-characters compression of the z/OS® program compression method.
Free space might also be compressed.
FABJCMP4: Does repeating-characters compression of the z/OS program compression method.
This routine runs the block compression, which does not distinguish between the data portion, free space, and unused space in the database.

DATACLAS(data-class-name)

This parameter specifies the name of the data class for the new SMS managed image copy output data sets that are dynamically allocated.

data-class-name: The name of the data class to be used for allocating the data set.
The name that you define is one-to eight-characters.

This parameter does not have a default.

DSNTYPE(BASIC | LARGE)

This parameter specifies whether the Image Copy can be allocated as Large Format data sets or Basic Format data sets.

More detail information for Large Format data sets is shown in the z/OS DFSMS Using Data Sets.

BASIC: Specifies that the Image Copy function allocates Image Copy data sets as Basic Format data sets. BASIC is the default.
LARGE: Specifies that the Image Copy function allocates Image Copy data sets as Large Format data sets.

EXPDT(yyyyddd | yyddd)

This parameter specifies the expiration date of the output image copy data set.

yyyyddd or yyddd

The expiration date of the output image copy.

The date format must comply with the DFSMS format (the Julian calendar format).

This parameter does not have a default.

ICBUF(nnn)

This parameter specifies the number of buffers to be used to access the output image copy data set.

The value specified for ICBUF is used for BUFNO of QSAM DCB.

nnn

The left-aligned number of buffers that are used to access the output image copy data set.

Applicable values can range from 0 – 255.

The default value is 50.

ICCAT( Y | N)

This parameter specifies whether the Image Copy function is to catalog the output image copy data set.

Y: Catalogs the output image copy data set.
This is the default.
N: Does not catalog the output image copy data set.

ICHLQ(hlq | hlq1 , hlq2)

This parameter specifies the data set name prefix of the image copy data set.

hlq: The data set name prefix of the output image copy data set for the Image Copy function or it symbolizes a value in &ICHLQ.
hlq1: The data set name prefix of the primary output image copy data set for the Image Copy function or it symbolizes a value in &ICHLQ.
hlq2: The data set name prefix of the secondary output image copy data set for the Image Copy function or it symbolizes a value in &ICHLQ2.
Note: The hlq2 parameter and ICHLQ2= cannot be specified together.

When you use the default ICOUT naming (ICNMRULE=N), specify a data set name prefix containing 33 or fewer characters. This prefix is used as the high-level qualifier of the data set name.

If you use the default STACK naming, specify a data set name prefix containing 7 or fewer characters. MVS™ naming convention requires that a generated data set name contain 44 or fewer characters.

This prefix must conform to the normal data set naming standards; it can include periods but must not end with a period.

If this parameter is left blank, a data set name prefix is not assigned.

ICHLQ2(hlq2)

This parameter specifies the data set name prefix of the image copy data set.

You can use a data set name prefix when you allocate an output image copy data set dynamically.

hlq2: The data set name prefix of the secondary output image copy data set for the Image Copy function or sets a symbolic value for &ICHLQ2.

ICHLQ2= parameter cannot be specified with ICHLQ=(hlq1,hlq2).

When you use the default ICOUT naming (ICNMRULE=N), specify a data set name prefix containing 33 or fewer characters.

This prefix is used as the high-level qualifier of the data set name.

If you use the default STACK naming, specify a data set name prefix containing 7 or fewer characters. MVS naming convention requires that a generated data set name contain 44 or fewer characters.

This prefix must conform to the normal data set naming standards; it can include periods but must not end with a period.

If this parameter is left blank, a data set name prefix is not assigned.

ICNMRULE(Y | N)

This parameter is used to select a naming convention for the output image copy data set.

Y

Selects the naming convention of the output image copy data set as follows:

ichlq.ICn.dbdname.ddname.Dyyddd.Thhmmss

N

Selects the naming convention of the image copy data set as follows:

ichlq.ICn.dbdname.ddname

Within these naming conventions, the following meanings apply:

ichlq: Is specified with the ICHLQ= keyword.
n: Is 1 or 2, indicating the primary or secondary copy.
dbdname: Is the DBD name of the database to be copied.
ddname: Is the DD name of the target date set group or area to be copied.
yyddd: Is the date.
hhmmss: Is the time stamp.

N is the default value.

KEYLABEL(key-label-name)

This parameter specifies the name of the key label used to encrypt the image copy output data sets.

key-label-name: The name of the key label to be used for allocating the encrypted image copy output data set.
The name that you define, is 1- to 64-characters long.

This parameter does not have a default.

MGMTCLAS(mgmt-class-name)

This parameter specifies the name of the management class for the new SMS managed image copy output data sets that are dynamically allocated.

mgmt-class-name: The name of the management class to be used for allocating the data set.
The name that you define, is one-to eight-characters long.

This parameter does not have a default.

NOTIFY(Y | N)

This parameter specifies whether the Image Copy function registers the image copy with DBRC.

N: Does not register the image copy with DBRC.
Y: Registers the image copy with DBRC.
Y is the default value.

RETPD(nnnn)

This parameter specifies the retention period, in days, for the output image copy data set.

nnnn

The retention period for the output image copy.

You can specify a value from 0 - 9999.

This parameter does not have a default value.

SPACE({CYL | TRK | blk},primary[,secondary])[,RLSE][,CONTIG | ,MXIG | ,ALX][,DYN][,ROUND])

This parameter specifies the space parameter of the output image copy data set for dynamic allocation.

CYL | TRK | blk

Specifies how the Image Copy function is to allocate the output image copy data set.

CYL: The allocation in cylinders.
TRK: The allocation in tracks.
blk: The allocation in blocks. For example: SPACE(1024,10,10).

primary

The number of tracks, cylinders, or blocks to be allocated.

secondary

The additional number of tracks or cylinders to be allocated, if more are needed.

If this option is specified, it must be located in the third position.

RLSE

Requests that space allocated to an output data set but not used, is to be released when the data set is closed.

CONTIG: Requests that space allocated to the data set must be contiguous.
MXIG: Requests that space allocated to the data set must be the largest area of available contiguous space on the volume and equal to, or greater than, the primary quantity.
ALX: Requests that space allocated to the data set is the largest 5 areas of available contiguous space on the volume.

DYN

Using this option causes IMS Database Recovery Facility to determine the space attributes for the output image copy from the space attributes of the input image copy being used for the recovery.

The dynamic space calculation is determined from the number of records in the input image copy:

If the input image copy space attributes cannot be determined dynamically, the values specified on the SPACE parameter are used.
If only SPACE(DYN) is specified and the space attributes cannot be determined, it is treated as if the SPACE parameter were omitted.

This option is only valid when the input image copy is on DASD. Otherwise dynamic space calculation is bypassed.

When DYN is specified, allocation is in units of TRK or CYL, RLSE is always appended and ROUND is disregarded.

If the input image copy has attribute CONTIG, MXIG, or ALX and propagation of this attribute to the output image copy is not required, then code a null argument at the end of the SPACE parameter. For example:

SPACE(CYL,10,1,DYN,)

ROUND

When the first option specifies the average block length, this parameter requests that space allocated to the data set must be equal to an integral number of cylinders.

More detail information for each of these values is shown in the z/OS JCL reference manual.

This parameter does not have a default.

Output Device under SMS:
The SPACE parameter in the SMS definition is used as the default.

If you specify the SPACE keyword in the ICEIN control statement or the site default table, the SMS definition is overwritten by the specified SPACE parameters.
Non-SMS Output Device:
The SPACE keyword is a required parameter.

If you omit this keyword, dynamic allocation fails.

If you defined SPACE in the site default table, IMS High Performance Image Copy uses the SPACE parameter in the site default.

STORCLAS(stor-class-name)

This parameter specifies the name of the storage class for the new SMS managed image copy output data sets that are dynamically allocated.

stor-class-name: The name of a storage class to be used for allocating the data set.
The name that you define, is one-to eight-characters long.

An ACS routine can override the storage class that you specify in the STORCLAS keyword.

This keyword does not have a default.

UNIT(TAPE | unitname | unitname,unitcount)

This parameter specifies the UNIT of the output image copy data set for allocation.

Note: When an image copy is requested, the UNIT parameter must be present either on the IC keyword or on the UTILGBL control statement; otherwise, an error results and no IC is created.

TAPE | unitname | unitname,unitcount

The option for allocating the output image copy.

For example, UNIT(TAPE) or UNIT(TAPE,2).

The default value is TAPE.

UNIT2(unitname | unitname,unitcount)

This parameter specifies the UNIT of the secondary output image copy data set, which is used for allocation.

unitname or unitname,unitcount: The option for allocating the secondary output image copy.
For example, UNIT2(TAPE) or UNIT2(TAPE,2).

This parameter does not have a default.

If both UNIT2 and STORCLAS are specified, the value specified in the STORCLAS keyword is not applied to the secondary output image copy data set.

VIC(Y | N)

This parameter specifies whether the Image Copy function registers the dummy data set name that is specified on the VICDSN parameter with DBRC as a virtual image copy.

Y: Registers the image copy with DBRC.
N: Does not register the image copy with DBRC. N is the default.

VOLCNT(1 | nnn)

This parameter specifies the number of volumes used for the output image copy data set.

nnn

The maximum number of volumes that an output image copy data set requires.

The volume count is a decimal number from 1 through 255 for a tape data set and from 1 through 59 for a DASD data set.

If you omit VOLCNT, 1 is used as the default.

VOLSER(volsern | volsern, volsern...)

This parameter specifies the volume serial number of the volume used for the primary data set of the output image copy.

volser or (volser1, volser2,...): The volume serial number of the volume allocated to the primary data set of the output image copy.
This parameter does not have a default.

VOLSER2(volsern | volsern, volsern...)

This parameter specifies the volume serial number of the volume used for the secondary data set of the output image copy.

volser or (volser1,volser2,...): The volume serial number of the volume allocated to the secondary data set of the output image copy.
This parameter does not have a default.

Unsupported keywords

The following IMS High Performance Image Copy keywords are not supported by IMS Database Recovery Facility:

AREA | DBD=
CAGRP=
DBBUF=
DBDSGRP=
DSN3-7=
CRCTYPE=
DBD=
DBDALLOC=
DDN=
DEDBPC=
DEDBEFCTL
FUNC=
HDPC=
ICHLQ3-7=
ICOUT=
PART=

Important: ICOUT=* is implied if you are requesting one image copy. If you are requesting two image copies, then ICOUT=*.* is implied.

Example of using the ADD IC() command

XCFGROUP(TOIREORG)                                                   
SORTPARM(ASPREF(DR3S))                                               
UTILGBL(IBPREF(DR3I),PRPREF(DR3P),PCPROCNM(FRXPATH0),PCJOBNM(DR3C))  
REPORT(RPTTYPE=APP,DRFUNIT=SYSDA,DRFHLQ=hlq)                         
DRFIAX(FRXJCLIP)                                                     
LIU@GOPT(xxxx)                                                       
DBDSN101(%P(duphlq))                                                 
DBDSL101(DISP(NEW),STGC(storclas),VOL(volser))                       
ADD DB(HIDAM1) DBATRB(DBDSL(101),DBDSN(101)), -                    
  IC (ICHLQ(ichlq),SPACE(CYL,3,1),ICNMRULE(Y),ICCAT(Y), -           
      DSNTYPE(BASIC),COMP(N), -                                   
      STORCLAS(storcl),MGMTCLAS(mgmtcl),DATACLAS(datacl),UNIT(unit))
START ERROR(CONT) DBRCMD(GLOBAL) STACMD(GLOBAL) READNUM(5)