Environmental control statements

Reference: Environmental control statements

CACHE(Y | N)

Use this parameter specified as Y to indicate that the image copy data sets are managed on a VTS (virtual tape server) device and the data sets are to be preallocated to initiate staging to the cache before they are read.

CACHE parameter syntax

The default value is N, signifying that no image copy data sets are located on a VTS device.

CATDS(Y | D | R)

Use this parameter to control allocation of image copies, logs, and change accumulation data sets from either the MVS catalog or the RECON data sets.

CATDS parameter syntax

D

If a data set is cataloged, the catalog is used for allocation. If a data set is not cataloged, RECON data set information is used for allocation. This is the default value.

Y

Data sets must be cataloged, if not cataloged, abend U0384-00000029 is issued in the master address space, and allocation failed RSN: 1708 is issued in the subordinate address space.

R

The RECON data set information is used for allocation.

COMPRTNA(<subparameters>)

Use this parameter to specify the aliases that you created for IMS High Performance Image Copy compression routines. The options that you specify on this parameter become effective only when you use image copies that are compressed by IMS High Performance Image Copy.

COMPRTNA subparameters syntax

FABJCMP1(alias name)

Use this parameter to specify an alias name that overrides the IMS High Performance Image Copy compression 1 routine.

The default value is FABJCMP1.

FABJCMP2(alias name)

Use this parameter to specify an alias name that overrides the IMS High Performance Image Copy compression 2 routine.

The default value is FABJCMP2.

FABJCMP3(alias name)

Use this parameter to specify an alias name that overrides the IMS High Performance Image Copy compression 3 routine.

The default value is FABJCMP3.

FABJCMP4(alias name)

Use this parameter to specify an alias name that overrides the IMS High Performance Image Copy compression 4 routine.

The default value is FABJCMP4.

The following example shows how you might use the COMPRTNA parameter to specify aliases.

COMPRTNA(FABJCMP1(COMPRES1),FABJCMP3(COMPRES3))

DBDSLnnn

Use this parameter to supply the data set characteristics for any data sets which are created by recovery. The DBDSLnnn parameter is used to specify allocation characteristics which are used to create new data sets.

This parameter is used if you specify DUP or BOTH on the OUTPUT parameter.

The DBDSLnnn parameters can also be specified on the ADD command using the DBATRB parameter for creating duplicate database data sets. Refer to the ADD command syntax for further details.

You can specify multiple DBDSLnnn control statements where nnn is a unique 1-to 3-digit alphanumeric value.

If you want the different data sets that are created to have unique data set characteristics, you can use multiple data set name (DBDSNnnn) and data set characteristic (DBDSLnnn) definitions. The data set characteristics you specify on the DBDSLnnn environmental control statement override the data set characteristics obtained from the original data set.

The following section shows the syntax for specifying data set characteristics.

DBDSL data set allocation specification syntax

DISP(OLD | NEW | PDS)

If DISP(OLD) is supplied, an existing data set is used during recovery. If DISP(NEW) is supplied, a new data set is created during recovery. The DISP parameter is required if DBDSLnnn is supplied. If DBDSLnnn is not supplied, then the default disposition used is DISP(OLD).

Note: Database data sets that need to be automatically deleted and redefined must be included on the same ADD statement. The DBATRB() keyword must be specified on the ADD statement and must reference a DBDSLnnn that indicates DISP(NEW).

OLD

IMS Database Recovery Facility uses the characteristics of an existing data set. If you specify OLD, data set characteristics specified in DBDSLnnn are rejected and error message FRD6124A is issued. This value is the default.

If you specify OLD with the OUTPUT(PRO) option, IMS Database Recovery Facility uses existing characteristics from the production database data set in the recovery list.

If you specify OLD with the OUTPUT(DUP) option, IMS Database Recovery Facility uses existing characteristics from the predefined duplicate database data set.

Note: For OUTPUT(PRO), DBDSNnnn is ignored. For OUTPUT(DUP), DBDSNnnn(dsn) is required to identify the name of the predefined duplicate database data set.

Restriction: When specifying DISP(OLD), you must ensure that your data sets are predefined and cataloged. Specifying DISP(OLD) when you are using data sets that are not predefined or cataloged results in allocation errors during recovery. FRD4302I messages are issued during recovery for this failure.

NEW

IMS Database Recovery Facility creates a data set using data set characteristics identified in the DBDSLnnn environmental control statement, if you provided it.

If you specified NEW with the OUTPUT(PRO) option, any data set with a matching name is deleted and redefined. IMS Database Recovery Facility deletes and redefines the production database data set using additional characteristics identified in the DBDSLnnn control statement, if you provided it. DBDSNnnn is ignored for OUTPUT(PRO).

If you specified NEW with the OUTPUT(DUP) option, IMS Database Recovery Facility uses DBDSNnnn to generate the duplicate data set name. If a data set exists with that name, the process ends with condition code 8. You can optionally provide characteristics with DBDSLnnn to define the new duplicate database data set. If you do not specify DBDSLnnn, characteristics are obtained from the production data set.

If you specified NEW with the OUTPUT(BOTH) option, IMS Database Recovery Facility deletes and redefines the production database data set and generates the duplicate data set. DBDSNnnn is ignored for the production database data set, but used to generate the name for the duplicate. The production database data set is deleted at the same time the duplicate data set is being generated.

If a failure occurs during the generation of the duplicate data set, recovery processing is stopped. You must then manually submit a job to redefine the production database data set before resuming the IMS Database Recovery Facility process.

Storage and management class information from the existing data set is collected and used in allocating the new data set. For SMS-managed data sets, ACS routines based on STORCLAS and MGMTCLAS can be used for VOLUME definition; otherwise, a threshold for 20 VOLSERs is set. If ACS routines do not manage VOLUME information, the VOL() parameter can be used to override the threshold limit for VSAM data sets.

Note: The following are the attributes and field names that are retrieved from an existing data set if not specified by DBDSLnnn:

• DEVTYP
• VOLSER
• STORCLAS
• DATACLAS
• MGMTCLAS
• NVSMATTR
• VSAMTYPE
• VSAMREUS
• ATTR2
• PRIMSPAC
• SCONSPAC
• SPACOPTN
• LRECL
• AMDKEY
• AMDCIREC
• PHYBLKSZ
• NOBLKTRK
• VSAMSTAT
• NOBYTTRK

PDS

Allows the use of a PDS library which contains the IDCAMS delete and define statements for the database data sets. The members within this PDS library must match the DD name of each individual database data set.

If DISP(PDS) is specified, IMS Database Recovery Facility searches through the DDEFPDS library by using the DD name, invokes IDCAMS to perform the redefinition of the database data set by using the definitions from the member, and returns control back to IMS Database Recovery Facility for recovery.

A new DD name DDEFPDS must be added as part of the IMS Database Recovery Facility MAS or RSS JCL. DDEFPDS identifies the PDS which contains the IDCAMS commands and definitions. If the DDEFPDS DD name is specified in both the MAS and the RSS JCL, the DDEFPDS DD specified in the MAS JCL prevails if they are different.

The PDS must be defined with LRECL=80 and fixed-block format.

The following example shows sample JCL that would accomplish this process:

//DDEFPDS DD DSN=IMSTESTL.IDCAMS,DISP=SHR

DBN(dbn)

The database name (DBN) of the entry to be added to the recovery list with the accompanying attributes until the next DBN is detected or the end of the DBDSLnnn statement is reached.

If you did not specify DBN for a list of attributes, the attributes you specified in the list apply to all the recovery list entries being added with this DBDSLnnn that do not have a DBN or DDN. dbn is the database name to which the DBDSLnnn applies.

DDN(ddn)

The DD name of the entry to be added to the recovery list with the accompanying attributes. If you did not supply ddn, the accompanying attributes apply to all data sets in the database.

ddn is the DD name of the database data set to which the DBDSL applies.

DATAC(data class)

The SMS data class for the output data set. data class must be a valid SMS data class.

data class is 1-to 8-character alphanumeric string.

STGC(storage class)

The SMS storage class for the output data set. storage class must be a valid SMS storage class.

storage class is 1- to 8-character alphanumeric string.

MGTC(management class)

The SMS management class for the output data set. management class must be a valid SMS management class.

management class is 1- to 8-character alphanumeric string.

PRIA(primary space)

The primary space allocation to be used for the new data set. The values specified for primary space can be one of the following values:

B(xxx)

number of bytes

R(xxx)

number of records (VSAM/OSAM LDS) or blocks (OSAM)

K(xxx)

number of kilobytes

M(xxx)

number of megabytes

SECA(secondary space)

The secondary space allocation to be used for the new data set. The values can be one of the following values:

B(xxx)

number of bytes

R(xxx)

number of records (VSAM/OSAM LDS) or blocks (OSAM)

K(xxx)

number of kilobytes

M(xxx)

number of megabytes

VOL(name1,....nameR)

The volume serial numbers (VOLSER) for location of the new data set.

The VOLSER is a 1 - 6 character valid VOSER name.

DBDSNnnn

Use this parameter to specify a template which can be used for naming new database data sets when duplicate databases are created. You can specify multiple DBDSNnnn control statements where nnn is a unique 1- 3 digit alphanumeric value.

The DBDSNnnn parameter is used to form a template from which the new data set name is created. This parameter is required if you specify OUTPUT(DUP) or OUTPUT(BOTH) parameter. The DBDSNnnn parameters can also be specified on the ADD command using the DBATRB parameter for creating duplicate database data sets. Refer to the ADD command syntax for further details.

For OUTPUT(PRO), DBDSNnnn is ignored. For OUTPUT(DUP) or OUTPUT(BOTH), DBDSNnnn is required in order to identify the name of the duplicate database data set.

The following example is the syntax of the DBDSN parameter:

DBDSNnnn(<qualifier1, qualifier2, ...qualifiern>) 
where  (n <= 22)

Syntax Elements:

qualifier =  element   OR   null

DBDSN name template symbolic qualifiers syntax

This is the syntax for specifying data set name qualifiers.

Notes:

• q = 1 through 22; no default
• literal = a string that you define of up to 8 characters

You can define up to 22 qualifiers to a data set name length limit of 44 characters according to the standard data set name syntax defined for z/OS®. Any of the 22 qualifiers can consist of one of the forms of an element defined in this topic or they can be null or omitted. The new name can be based on the data set name of the original source data set or it can be totally independent.

Each qualifier in the DBDSNnnn parameter equates to the corresponding qualifier in the new data set that is created. If you specified a null qualifier then the value used for that qualifier is the corresponding qualifier from the original source data set name. Only the qualifier levels that you want to change from the original source data set name need be included in the DBDSN parameter.

You can use periods or commas to separate the qualifier values. Qualifiers that you do not want to change can be omitted using a comma. For example, if you want to change only the first and third qualifiers, specify the following syntax: DBDSN001('HIGHQUAL',,%TIME). More examples of the use of this parameter follow the descriptions.

If the new data set name is greater than 44 characters or otherwise invalid, an error message is issued and generation of the copy is skipped or the process is stopped, depending on the error handling option, ERROR(STOP | CONT | ABORT) that you chose.

There are two types of values allowed in the data set name qualifiers; literals and predefined keywords. A literal is a static and unchangeable value that you specify and is used directly in the data set name. An example of a literal is %P(TEST) which would result in a prefix of TEST being added to the new data set name.

For a predefined keyword, the value is set by the system according to the current system attributes. An example of a predefined keyword is %TIME which would result in the current timestamp being inserted in the new data set name.

Keyword Definitions: The following list shows the qualifiers which allow a literal to be specified.

%P(literal)

Generates a prefix to your data set name. The literal is a string of up to eight alphanumeric characters, where the first character must be an alphabetic character.

If used, %P(literal) must be the first qualifier specified.

%S(literal)

Generates a suffix to your data set name. The literal is a string of up to eight characters of your choice that is allowable in a data set name.

If used, %S(literal) must be the last qualifier keyword you specify, except for %END.

literal

Generates a static character string in your data set name. The literal is a string of up to eight alphanumeric characters that are allowable in a data set name.

The literal must be contained within single quotation marks. If not, error message FRD6124A INVALID DATA ENCOUNTERED is issued, and the subsequent command or control statement report is blank.

The SYSIN DD statements are not displayed.

< predefined keyword >

The following qualifiers allow predefined keywords to be defined.

%TIME =

Generates a qualifier consisting of a system timestamp in the format of Thhmmssm.

Where T is a literal character, hh is hour in 24 hour format, mm is minutes, ss is seconds, and m is milliseconds.

%DATE =

Generates a qualifier that consists of a system date stamp in the format of Dyyyyddd.

Where D is a literal character, yyyy is year and ddd is the number of days.

%JOBN =

Generates a qualifier that consists of the IMS Database Recovery Facility job name.

%STEP =

Generates a qualifier that consists of the IMS Database Recovery Facility step name.

%MDBD =

Generates a qualifier that consists of the HALDB master database name for a HALDB or the database name for a non-HALDB.

%DBD =

Generates a qualifier that consists of the HALDB partition name for a HALDB or the database name for a non-HALDB.

%DDN =

Generates a qualifier that consists of the DD name for the database data set.

%SDSN(q) =

Generates a qualifier from the source data set name. This element requires a value (q) that specifies the number of the qualifier referenced from the source data set name. The valid values of q are 1 - 22.

This qualifier is only needed if you want to use a qualifier from the source data set name but want it to appear in a different position in the new data set name.

If %SDSN(q) refers to a qualifier in the source data set name that is greater than the number of qualifiers in the data set, then the last encountered qualifier is used. For example if DBDSN101('TESTDB',%SDSN(4)) is used as the data set name template and the original data set name is PRODDB.PARTS.INV, then the generated data set name is TESTDB.INV.

%END =

No further qualifiers are to be included. Use this qualifier to truncate the new name.

Rules for specifying qualifiers:

Each DBDSNnnn parameter can specify any number of qualifiers to a maximum of 22. If the source data set name consists of fewer qualifiers than are specified in the parameter, then the extra qualifiers correspond to the later qualifiers in the source.

For example, if the source data set name is PRODDB.PARTS.IMSA.INV and DBDSN001(,,,,%DATE,%TIME) is specified, the resulting new data set name would be PRODDB.PARTS.Dyyyyddd.Thhmmss. As you can see, the source data set name consisted of only four qualifiers but the new data set name consisted of six possible qualifiers. The last two qualifiers of the source data set name were replaced by a date stamp and a time stamp.

If you specifying %P(literal), it must be the first qualifier in the list.

If you specifying %S(literal), it must be the last qualifier in the list, just before the %END.

If the source data set name consists of more qualifiers than are specified in the DBDSNnnn parameter, then the additional qualifiers from the source data set name are included in the new data set name in their corresponding positions.

Examples of specifying DBDSNnnn:

The following are examples of specifying DBDSNnnn with positional notation:

DBDSN001()

Use the source data set name for the new data set name.

DBDSN001(%P(BKU))

Prefix the first database data set name with BKU. For example, if the source data set name is:

IMS1.REGTST.SAMPLIB.V345 

Your new data set name would be:

BKU.IMS1.REGTST.SAMPLIB.V345 

DBDSN002(,,,,%TIME)

Use the system time as the fifth qualifier in the new data set name. The first four qualifiers are copied from the source data set name and the time stamp is used as the fifth qualifier.

If the source data set name has fewer than five qualifiers, the time stamp is substituted for the last qualifier. For example, if the source database data set name is:

IMS1.REGTST.SAMPLIB.V345

Your new data set name would be:

IMS1.REGTST.SAMPLIB.Thhmmss

Even though the DBDSNnnn indicated that %TIME is be used as the fifth qualifier, because the input data set has only four qualifiers, %TIME was substituted as the last qualifier in the new data set name.

DBDSN001(,,,%DATE,%TIME)

Use the system date as the fourth qualifier and the system time as the fifth qualifier in the new data set name.

The first three qualifiers are copied from the source data set name. For example, if the source database data set name is:

IMS1.REGTST.SAMPLIB.V345.TEST

Your new data set name would be:

IMS1.REGTST.SAMPLIB.Dyyyyddd.Thhmmss

If there are 5 or fewer qualifiers in the source data set name, date and time are substituted for the last two qualifiers.

DBDSN001('HIGHQUAL')

Use the literal 'HIGHQUAL' in place of the high-level qualifier and use the remaining qualifiers from the source data set name to create the new data set name.

The commas for null values are not necessary in this case.

DBDSN001('HIGHQUAL',,,,%TIME)

Use the literal 'HIGHQUAL' as the high-level qualifier and time as the fifth qualifier for the new data set name. If there were four or fewer qualifiers in the source data set name, time is substituted for the last qualifier.

The shortest possible generated name in this case would consist of two qualifiers.

DBDSN001('HIQUAL',%SDSN(1),,%TIME,%END)

Use the literal 'HIQUAL' as the high-level qualifier, use the existing high-level qualifier as the second-level qualifier, use the existing third qualifier, and use time as the fourth qualifier to create the new data set name.

End the name after the time qualifier.

DBDSN002(%S(UPDT))

Suffix the new data set name with UPDT. For example, if your source data set name is:

IMS2.REGTST.SAMPLIB.V346 

Your new data set name would be:

IMS2.REGTST.SAMPLIB.V346.UPDT

Specifying DBDSN002(%S(UPDT),%END) gives you the same result.

DRFIAX(procname)

Use this parameter to specify the name of the procedure that is used to initiate the IMS Database Recovery Facility Utility Address Space (UAS/IAX) for IMS Index Builder, the image copy function of IMS HP Image Copy, DFSPREC0, and the Build Index function of FPA.

The default for the DRFIAX parameter is FRXJCLIP.

The procedure must reside in a valid z/OS PROCLIB data set.

Samples of this procedure are located in SFRXSAMP(FRXIAX|FRXJCLIP).

Tip: Customize the FRXIAX procedure and rename to FRXIAXxx, where xx is the maintenance level used (for example, TEST or PROD).

DRFIAX parameter syntax

DRFPROC(procname)

Use this parameter to specify the name of the procedure that is used to initiate the IMS Database Recovery Facility recovery sort subordinate address space (RSS).

The procedure must reside in a valid z/OS PROCLIB data set. If you specify this parameter in the SYSIN control statements, the procedure name that is defined by the SET statements in your execution JCL is overridden.

Samples of this procedure are located in SFRXSAMP(FRXRSS|FRXJCLSB).

Tip: Customize the FRXRSS procedure and rename to FRXRSSxx, where xx is the maintenance level used (for example, TEST or PROD).

DRFPROC parameter syntax

HPIO

Use this parameter to specify whether HPIO writes to any OSAM or VSAM ESDS DBDS during recovery.

HPIO write is not supported for HISAM Overflow DBDS.

HPIO write is not supported for OUTPUT(BOTH) and is dynamically disabled when OUTPUT(BOTH) is specified.

HPIO parameter syntax

The WRITE option sets HPIO write either ON (Y) or OFF (N) for writing to the DBDS during recovery.

WRITE([Y|N],[nn])

WRITE(Y,[nn])

The optional nn subparameter specifies a 1-2 digit integer value ranging from 5-15 that sets the number of HPIO write threads.

The default value for nn is 5.

WRITE(N)

WRITE(N) is the default setting.

For WRITE(N), nn is ignored.

ICNOTIFY(HPIC | DRF)

ICNOTIFY determines if IMS HP Image Copy or IMS Database Recovery Facility causes the NOTIFY.IC commands to be issued to register the image copies generated by the IMS Database Recovery Facility job, if any, to DBRC.

If ICNOTIFY is not specified, IMS HP Image Copy causes the NOTIFY.IC commands to be issued.

Note: ICNOTIFY(DRF) and ICNDX(Y) are mutually exclusive.

ICNUM(nn,tn)

Use this parameter to specify the maximum number of tape drives used for reading image copy data sets (nn). For ICNUM, (tn) is ignored.

ICNUM parameter syntax

If you do not specify ICNUM, then the default values are those values that are used by READNUM.

If ICNUM or READNUM are not specified, the default values for ICNUM are the same default values used by READNUM.

Refer to the description of READNUM for more details.

LBI(Y | N)

Use this parameter to indicate whether the large block interface is in use at your location (Y), or not (N).

LBI parameter syntax

The default value of N is assumed if you do not make a specification.

LCLTIME(Y | N)

Specifies whether local time stamps (Y) are to be used in messages and reports, or if GMT time stamps (N) are to be used.

LCLTIME parameter syntax

The default is LCLTIME(Y).

LIU@GOPT(xxxx)

Use this parameter to identify the IMS Library Integrity Utilities global option module LIU@xxxx, which is loaded from the STEPLIB by IMS Library Integrity Utilities. This allows IMS Library Integrity Utilities to load global option member LIU@xxxx to accept user defined run time options that have been assembled therein.

LIU@GOPT(xxxx) parameter syntax

LOGNUM(nn,tn)

Use this parameter to specify the maximum number of tape drives used for reading change accumulation data sets (nn) and the maximum number of read instances which can be initiated in parallel (tn). LOGNUM operates in the same way that READNUM does, but is associated with reading change accumulation data sets. Refer to the description of READNUM for more details.

LOGNUM parameter syntax

If you do not specify LOGNUM then the default values are those that are used by READNUM.

If LOGNUM or READNUM are not specified, the default values for LOGNUM are the same default values used by READNUM. Refer to the description of READNUM for more details.

MAXPRI(nnnn)

This optional parameter limits the space, in cylinders, of the primary allocation for the output image copy when the DYN option of the auxiliary parameter SPACE is specified.

Primary allocation is calculated based on the number of records in the input image copy used for recovery.

Range: 1-32767

Default: 6000

MAXSEC(nnnn)

This optional parameter limits the space, in cylinders, of the secondary allocation for the output image copy when the DYN option of the auxiliary parameter SPACE is specified.

Secondary allocations are calculated as 10% of the primary allocation +1.

Range: 1-3276

Default: 600

OPTION(<subparameters>)

Use this parameter to specify optional parameters and overriding default values for your recovery environment.

OPTION subparameters syntax

You can specify DISPSHR, FCTOPPRCP, USERPROP, USPCPROP, or a combination of these sub parameters.

DISPSHR(Y | N)

Specifies whether the default dynamic allocation for image copy, log and change accumulation data sets will be allocated with a disposition of share (Y) or not (N). The default is N which means that these data sets will be allocated using DISP=OLD.

Allocating these data sets with a DISP=OLD helps ensure that no other jobs attempt to update the contents of your input data sets while a recovery is in process.

The DISP=SHR setting gives users the flexibility of running multiple jobs in parallel if all that is expected by these jobs is READ access.

FCTOPPRCP(Y | N)

Specifies whether the DFSMSdss FCTOPPRPCPrimary option is to be used (Y) or not (N) when restoring from a FlashCopy® image copy. The default is N.

For details, see the description about FCTOPPRCPrimary in the z/OS DFSMSdss Storage Administration Reference.

Note: FCTOPPRCP is ignored when IMS Database Recovery Facility is not restoring from a FlashCopy or if the release level of DFSMSdss is lower than 1.6. FCTOPPRCP is supported by DFSMSdss 1.6 or higher.

USERPROP(Y | N)

Specifies whether the user ID that is associated with the IMS Database Recovery Facility master job is propagated to the subordinate address spaces that are directly started by IMS Database Recovery Facility.

These address spaces include the recovery sort subordinate address space, the IMS Index Builder address space, the DFSPREC0 utility address space, and the address space for the Build Index function of FPA.

User ID propagation allows the subordinate address space to run with the same level of security as the IMS Database Recovery Facility master job, eliminating the need for special entries in the RACF® STARTED class.

The default is Y, indicating that the user ID propagation is performed.

This parameter is useful in cases where the TEMPDSN class is active and you need to manually code the SORTWORK DD statements in the DRFPROC() procedure.

For details on user ID propagation to the IMS High Performance Pointer Checker address space, see the description of the USPCPROP parameter.

USPCPROP(Y | N)

Specifies whether the user ID that is associated with the IMS Database Recovery Facility master job is propagated to the address space for IMS High Performance Pointer Checker (DMB Analyzer subordinate address space) that is started by IMS Database Recovery Facility.

The default is N, indicating that the user ID propagation is not performed.

OUTPUT(DUP | ICR | ICRCA | PRO | BOTH)

Use this parameter to specify the type of output processing to be performed by the IMS Database Recovery Facility. The default is OUTPUT(PRO) which recovers all the production database data sets associated with the recovery list.

OUTPUT parameter syntax

Note: The term production DBDS can be interpreted as the DBDS listed in the RECON data sets for the supplied DB name DD name pair. The term non-production DBDS can be interpreted as a copy of the DBDS listed in the RECON data sets for the supplied DB name DD name pair.

DUP

Specifies Database Copy Generation, where a non-production duplicate of every DBDS in the recovery list is created using the recovery process. This results in creating a duplicate of each production DBDS with a new data set name. This DBDS duplicate can be processed in a test environment on a separate IMS system using the same DBD name, or it can be processed in the production environment if you provided a different DBD.

The DBDSNnnn statement is used to create the data set name for the duplicate data sets and is required. The DBDSLnnn statement can be used to specify the allocation attributes for creating the duplicate data sets.

DBDSLnnn is optional and if it is not specified, the allocation attributes are taken from the original data sets. The DBATRB parameter must be specified on the ADD statement to specify the DBDSNnnn and the DBDSLnnn (if specified).

Sample JCL using OUTPUT(DUP):

DBDSN002('MYDATB')                            
DBDSL004(DISP(NEW),DBNMYDB1))
OUTPUT(DUP)                                   
ADD DB(DBOVLFPC) DBATRB(DBDSN(002) DBDSL(004))
START                                         

In this sample, duplicate database data sets are created for all database data sets associated with the DBOVLFPV database. The first level qualifier on the new data sets are 'MYDATB'. The allocation characteristics for the new data sets are taken from the original data sets.

Restrictions:

• User-ICs or SAMEDS ICs are not supported with this function. IB and IC statements are ignored.
• If you are recovering to an OLR-capable database, OUTPUT(DUP) is not recommended.

  Since OUTPUT(DUP) creates a copy of the "active" data sets for the current recons of the source system, it may not match the "active" data sets on the target system for the duplicated data sets.

  You would be required to make sure the OLR status (active data sets) is the same on both systems and you should not use OUTPUT(DUP) for a copy of the database data sets (active or inactive) if either the source or target system is in the middle of an OLR.

ICR

Specifies Image Copy, where a new image copy is created from an image copy and log, or change accumulation input data sets, for every DBDS in the recovery list by using the recovery process. The RCVTIME parameter can be specified to create the image copy to a specific point in time. Actual database recovery is not performed and the databases are not accessed.

If you specify OUTPUT(ICR) while the databases are offline, or specify RCVTIME to a time when the databases are offline, the image copy is registered to the RECON as BATCH.

If you specify OUTPUT(ICR) while the databases are online, or specify RCVTIME to a time when the databases are online, the image copy is registered to the RECON as CONCUR.

You cannot specify ICR with any other output option.

Sample OUTPUT(ICR) control statements:

REPORT(RPTTYPE=SEP,DRFUNIT=SYSDA,DRFHLQ=DRFIC1)
UTILGBL(COMP(N),DSN(&ICHLQ..&DBD..&DDN.),UNIT(3390),-
        VOLSER(222222))
OUTPUT(ICR)
ADD DB(DIVNTZ02,DHVNTZ02,DXVNTZ02) IC(ICHLQ=(DRFIC1),-
       SPACE=(CYL,10,10))
START ERROR(CONT)

Note: Use the DSN() and DSN2() parameters of the UTILGBL() control statement to specify the name of the output image copy data set. You cannot use the DSN() or DSN2() parameters on the IC() control statement.

Restriction: The use of user-image copies, IC2, SAMEDS ICs, or FlashCopies are not supported with the ICR option. Use of a PITCA created by the IMS High Performance Change Accumulation is not allowed as input to the ICR process

ICRCA

This option is like ICR, but it specifies that only a BATCH image copy is to be generated using only a prior image copy and a change accumulation as input. Log input is ignored.

IMS Database Recovery Facility locates and uses a timestamp where a clean recovery point or batch window exists. A clean recovery point or batch window, is defined as a period of time where the database was previously taken offline or where an OLDS switch occurred with logs archived.

IMS Database Recovery Facility uses this timestamp if a complete change accumulation also exists within this time frame. All databases that are included in the recovery list must belong to the same CAGRP. The resulting image copy is registered as a batch image copy and contains all updates up to this change accumulation.

If a complete change accumulation is not found within a usable batch window then a copy of the prior image copy is generated.

Restriction: The use of user-image copies, IC2, SAMEDS ICs, or FlashCopies are not supported with the ICRCA option. Use of a PIT CA created by the IMS High Performance Change Accumulation product is not allowed as input to the ICRCA process.

PRO

Specifies recovery of one or more production databases, where every DBDS in the recovery list is recovered. This results in creating a recovered DBDS in place of the previous instance.

This is the default option for the OUTPUT keyword.

Note: If you specified OUTPUT(PRO), the DBATRB parameter is optional on the ADD statement.

BOTH

Specifies that recovery performs the functions of PRO and DUP at the same time. Recovery creates a recovered DBDS in place of the previous instance and generate a non-production duplicate with a new data set name.

Restrictions:

• If you specified OUTPUT(BOTH), you must also include the DBATRB parameter on the ADD statement.

  The DBATRB parameter identifies which DBDSNnnn to reference for naming convention rules.

  It can also specify a DBDSLnnn statement to identify allocation attributes for the new database data sets.

• If you are recovering to an OLR-capable database, OUTPUT(BOTH) is not recommended.

  Because OUTPUT(BOTH) creates a copy of the active data sets for the current RECONs of the source system, it might not match the active data sets on the target system for the duplicated data sets. You would be required to make sure the OLR status (active data sets) is the same on both systems.

  Do not use OUTPUT(BOTH) for a copy of the database data sets (active or inactive) if either the source or target system is in the middle of an OLR.

RCVPRGS(<subparameters>)

If PRT=Y is specified for RCVPRGS, IMS Database Recovery Facility displays the recovery progress rate.

The following four recovery progress rates are displayed.

OVERALL RECOVERY PROGRESS PERCENTAGE

The percentage of database data sets that have been recovered. When ADD IC is specified, the recovery is considered to be completed at the completion of image copy creation. Index database data sets that are recovered by specifying ADD IB are not included in this recovery progress rate.

DATA SET RESTORE COMPLETE PERCENTAGE

The percentage of database data sets that have restored image copies and applied log updates.

IC CREATION PERCENTAGE

The percentage of image copies that have been created when ADD IC is specified. Image copies of index database data sets that are created by specifying ADD IB ICNDX are not included in this recovery progress rate.

IB COMPLETE PERCENTAGE

The percentage of database data sets with indexes that have built indexes (including the secondary indexes) when ADD IB is specified.

RCVPRGS subparameters syntax

Set Y or N to the PRT option to specify whether to issue a message indicating the recovery progress rate.

PRT=( [ N | Y ] , [ SYS | WTO ] )

PRT=( Y, [ SYS | WTO ] )

Specifies whether recovery progress messages are issued to SYSPRINT or WTO. The default is SYS. If WTO is specified, recovery progress messages are issued to both SYSPRINT and WTO.

TIME=mmm

Defaults to 010, which specifies the number of minutes between the recovery progress messages.

The maximum value is 999 and the minimum is 001.

PRT=N

N is the default. If N is specified, the SYS, WTO, and TIME parameters are ignored.

Restriction: If the recovery termination process starts before the time specified by TIME= in RCVRPGS, the recovery progress rate will not be displayed depending on the timing.

READNUM(nn,tn)

Specify the maximum number of log read tasks that are started in parallel for tape only (nn) and the total number of concurrent read tasks (tn).

Tip: If possible, use the same system for recovery that was used to create the logs. If you are using a system with less capacity than the original system, consider reducing the READNUM (nn) value. If the IMS Database Recovery Facility log read task (RVRD) ends abnormally with S878, consider reducing the READNUM (tn) value.

READNUM parameter syntax

For tape input, specify this number as the maximum number of tape read devices (nn) to allocate to the recovery process.

The allowable range is 1 - 99. The default value for nn is 3.

The total number of concurrent read threads allowed is specified by tn. The actual number might be larger than tn if some input data sets exist that can be read from devices other than tape drives. The default maximum number of total concurrent read threads is tn or 3, whichever is greater.

If you omit or set the values of either tn or nn to 0, the default values are imposed.

The values specified in the FRXDRFxx member can be overridden using the READNUM parameter on the START control statement.

If you do not specify READNUM, the system default of (3,3) is used.

Note: If ICNUM or LOGNUM are not specified, the values used for READNUM are used.

REPORT(<subparameters>)

IMS Database Recovery Facility and the integrated auxiliary utilities write messages to various report DD statements. The IMS Database Recovery Facility master address space collects all messages and reports from all IMS Database Recovery Facility subordinate address spaces and organizes them in either the master address space REPORT DD or in separate utility report DD statements, such as the STATIPRT for IMS High Performance Pointer Checker. The REPORT parameter is used to control how and where these reports are created.

REPORT parameter syntax

RPTTYPE=

Specifies where the messages generated by the integrated auxiliary utilities are written.

SEP

Indicates that the utilities reports and messages are to be written to the standard utility report DD statements, separate from the IMS Database Recovery Facility REPORT DD.

RPTTYPE=SEP is the default setting.

APP

Indicates that the utilities reports and messages are appended to the IMS Database Recovery Facility REPORT DD.

SAS

Indicates that the utilities reports and messages are not sent to the master address space. Instead, they are written to the standard integrated auxiliary utilities report DD statements in the subordinate address spaces in which they were generated.

RPTTYPE=SAS reduces overall processing time and I/O for IMS Database Recovery Facility.

DRFUNIT=

Specifies a 1- to 7-character generic unit name passed to the subordinate address spaces in order to provide a unit type on which to dynamically allocate and catalog any report data sets. The default is SYSDA.

If genericunit is coded with a value that is not a valid generic unit in your system, messages FRD9003A and FRD4100I are issued and followed by abend U384-02C.

DRFHLQ=

Specifies a 1- to 8-character high-level qualifier that is passed to the subordinate address spaces in order to provide a high-level qualifier used to allocate and catalog any report data sets.

DRFVOLSR=

Specifies a 1- to 6-character volume serial number that is passed to the subspaces in order to provide a specific volume on which to allocate any report data sets. Use DRFVOLSR to specify a particular volume serial number on which to dynamically allocate and catalog any required data sets.

Specifying DRFVOLSR is optional. If you do not specify DRFVOLSR, the temporary data sets are written to local volumes. DRFVOLSR is required when you have insufficient local volumes or if the volumes are not SMS-managed.

RPTRET=

Specifies the disposition of report data sets when the recovery job ends abnormally.

N

Indicates that the REPORT work data sets are to be deleted in the event of an abend.

It also indicates that IMS Database Recovery Facility deletes any REPORT work data sets left from prior executions that would otherwise cause allocation errors due to duplicate names.

Y

Indicates that the REPORT work data sets are to be retained in the event of an abend.

Retaining these data sets might be helpful for diagnostic purposes, however, if they are retained then it is up to you to manually delete them.

The default setting for RPTRET is N.

RPTITKB=

Specifies whether or not IMS Tools Knowledge Base integration is active for the IMS Database Recovery Facility report.

Important: To use IMS Tools Knowledge Base integration, the ITKBSRVR keyword must be specified in the UTILGBL() environmental statement.

N

Indicates that IMS Tools Knowledge Base integration is not active.

Y

Indicates that IMS Tools Knowledge Base integration is active.

There are three reports types:

• IMS Database Recovery Facility report
• WTO
• SYSPRINT

The default setting for RPTITKB is N.

After a batch recovery completes, examine, first, the REPORT DD output file in the master address space to determine the results of the auxiliary utilities.

The return codes and reason codes from each utility for each DBD and DD/AreaName are written under a new heading in the REPORT DD at the end of file. If you invoked integrated auxiliary utilities and RPTTYPE=APP is specified, then reports and messages from the utilities appear in the REPORT DD after the IMS Database Recovery Facility report.

If RPTTYPE=SEP is specified, then reports and messages from the utilities are written separately to the standard utility report DD statements.

If RPTTYPE=APP is specified indicating the messages are appended to the REPORT DD, IMS Database Recovery Facility lists image copy messages followed by Pointer Checker messages under a separate heading by DBD and DD/AreaName, followed by messages for Index Builder, DFSPREC0, and the Build Index function of FPA.

The JOBNAME of the subordinate address space which created the utilities' reports and messages is also included in the heading.

For a list of the utility report DD statements, refer to Configuring JCL statements and procedures.

If RPTTYPE=SAS is specified, the reports are written to the integrated auxiliary utilities standard report DDs in the SAS in which they were generated.

SORTPARM(<subparameters>)

The subparameters listed here are values that you define that are passed to SORT as each task is started. Separate the subparameters with commas.

SORTPARM subparameters syntax

ASGNAME(Y|N)

Use this parameter to set a generic Started Task Control (STC) name for the sort subordinate address spaces created by the IMS Database Recovery Facility. This is an optional parameter.

Y

Specifies that IMS Database Recovery Facility overrides the job name for all sort subordinate address spaces in order to use DRFSORT as the started task name.

N

Specifies that the name used for all sort subordinate address spaces is generated using the information specified by the ASPREF parameter. This is the default.

See ASPREF for the method of naming subordinate address spaces.

ASPREF(cc | cccc | IDRF)

Use this parameter to set the prefix of the started task name for the recovery sort subordinate address spaces (RSS) created by the IMS Database Recovery Facility. This is an optional parameter.

If ASGNAME(N) is specified and ASPREF() is not specified, the default prefix of IDRF is used.

cc

When a 2-character prefix is specified, the job name is influenced by the NUM parameter.

If the value of NUM is less than (<) 100, the job name is constructed by using the format ccjjjj##, where:

cc

The specified prefix.

jjjj

The last 4 digits of the JES job number associated with the master address space.

##

A number from 01-99, incremented with each new RSS.

If the value of NUM is greater than (>) 99, the job name is constructed by using the format ccjjj###, where:

cc

The specified prefix.

jjj

The last 3 digits of the JES job number associated with the master address space.

###

A number from 1-250, incremented with each new RSS.

cccc

A 4-character prefix used to construct the STC name of the RSS.

When a 4-character prefix is specified, the job name is constructed by using the format cccc####, where:

cccc

The specified prefix.

####

A number from 0001-0250, incremented with each new RSS.

AVGRLEN(nnnnn)

Use this parameter to specify the average record length of the records to be sorted.

nnnnn

A 1-to 5-digit integer value of 4- through 32766 bytes that you use to specify the average record length of the records to be sorted.

The default value of AVGRLEN(nnnnn) is half of the maximum record length.

The range includes the 4 -byte record descriptor word (RDW).

DYNALLOC(device_name | SYSDA , nr_wrk_sets)

Use this parameter to specify the attributes for allocating the sort work data sets dynamically. The parameters that you specify is used in place of the SORT defaults.

device_name | SYSDA

A valid device name on which the work data sets are dynamically allocated.

The default value of device_name is SYSDA.

nr_wrk_sets

A 1-to 3-digit integer value from 1 to 255 that you use to specify the number of dynamically allocated work data sets that are used during the SORT.

The default for nr_wrk_sets is none, that defaults to either the IBM®-supplied default (4 for block set technique), or as you specified in the installation ICEMAC DYNALOC option.

FILSZ(nnnnnnnnn | 20000 | > 20000)

Use this parameter to specify the estimated number of records to be sorted.

nnnnnnnnn

A 1- to 9-digit integer value you use to specify the estimated number of records to be sorted.

This parameter is optional, and if you do not include it, the IMS Database Recovery Facility makes an estimate based on the RLDS record sequence number range provided by DBRC.

The minimum estimate that IMS Database Recovery Facility applies is 20000.

HIPRMAX(OPTIMAL | nnnnn)

Use this parameter to specify the maximum size of hiperspace to be used in the sort process.

OPTIMAL

If you specify the OPTIMAL option, SORT is allowed to calculate and use as much hiperspace as possible.

The HIPRMAX default is OPTIMAL.

nnnnn

A 1- to 5-digit integer value from 0 MB to 32766 MB that you use to specify the maximum amount of hiperspace to be used.

Note: Specifying a value of 0 tells SORT to inhibit the use of hiperspace sorting.

MAINSIZE(nnnn | 32)

The main storage size you set for the RSS SORT region.

nnnn

A 1- to 4-digit integer value (4 through 2000; in megabytes) that you set for the RSS SORT region. The default is 32 MB.

Note: If the value you specify is less than the SORT product's MINLIM installation value, then the MINLIM value overrides MAINSIZE.

NUM(nnn | 250)

A 1- to 3-digit integer value that you use to specify the maximum number of RSS spaces that are started in parallel.

The actual number of RSS spaces depends on the work required, so the number of subordinate address spaces might be less than the value you specified.

The number that is used is the smaller of the following values:

• The value nnn you specified in the NUM parameter.
• The number of unique collections of image copy data sets. These collections can be one or more of the following options:
  • An individual image copy data set on a DASD volume
  • Stacked image copy data sets on the same tape volume that do not span tape volumes
  • An image copy data set that spans volumes plus the image copy data sets stacked on the last volume of the spanning image copy
• The number 250 (the maximum value allowed).

If multiple image copy data sets that are required for recovery are stacked in the same volume or are part of the same data set (when they are created using the SAMEDS option for DFSMSdss - Concurrent Copy), they are processed by the same address space.

SOURCE(PRI | SEC | SECIC | SECLOG)

Use this parameter to specify the source of image copies and log data sets for the recovery process.

SOURCE parameter syntax

PRI

The primary image copy and log data sets are used as the sources for the recovery process.

If any of the primary sources are marked as invalid or are unreadable, the secondary sources are used, if available.

PRI is the default option for SOURCE.

SEC

The secondary image copy and log data sets, either SECLOG or SECSLD, are used as the sources for the recovery process.

If a required data set is marked as invalid or it is unavailable, recovery fails for that database data set.

SECIC

The secondary image copy data sets are used for the recovery process.

Primary log data sets are used as the default data sets.

SECLOG

The secondary log data sets, either SECLOG or SECSLD, are used for the recovery process.

Primary image copy data sets are used as the default data sets.

SPSIZE(yyyy | 1024)

Use this parameter to specify the integer value in megabytes, for the size of each data space used by the IMS Database Recovery Facility.

SPSIZE parameter syntax

When data space usage reaches your specified value, another data space is obtained. The range of valid values is: 1 to 2047.

The default value for SPSIZE is 1024 MB.

yyyy

The integer value in megabytes, for the size of each data space used by the spill manager.

TAPECHK(Y | N)

Use this parameter (Y) to allow IMS Database Recovery Facility to check the availability status of tape devices before DBDS allocation.

TAPECHK parameter syntax

If the number of image copies restore tasks on tape exceeds the number of available tape devices, then IMS Database Recovery Facility might stop scheduling parallel image copy restores when the number of tape devices that are required exceeds the number tape device that are available.

TAPECHK(Y) works in tandem with READNUM (or ICNUM, LOGNUM) to specify to IMS Database Recovery Facility the number of tape devices that are available.

TAPECHK(N) is the default.

USESLBIC(Y | N)

Specifies whether an IMS Recovery Expert System Level Backup will be used for recovery if it was created later than the image copy, whether for a full recovery or within the RCVTIME specification.

If IMS Recovery Expert is available and USESLBIC(YES) is specified, the Verify and Recovery functions cause IMS Recovery Expert to write an image copy record to the RECON which represents the System Level Backup. The image copy record receives a data set name in the form of SLB.Ixxxx.Dxxxx.dbdname.ddname, and this image copy record is used during the Verify and Recovery functions.

If there is already an image copy record for the System Level Backup or if no system level backup is available relative to the type of recovery specified then no image copy record will be written to the RECON.

Note: It is strongly suggested that USESLBIC is specified to match the same parameter in IMS Database Recovery Facility Extended Functions, especially when its Verify function is being used to determine the recovery time.

USESLBIC parameter syntax

The default value of N is assumed if you do not make a specification.

Reference: SLB offloaded data sets

SLBs exist either on a fast-replication capable device(s), or have been offloaded from the fast-replication devices onto sequential data sets on tape or DASD.

When on the fast-replication device, the data is an exact replica of the backed up data except that the data sets are not cataloged. During the offload process, IMS Recovery Expert creates one sequential data set per device and catalogs them on the offload volumes. An SLB can be used for recovery whether it resides on the fast-replication capable device(s) or the offload data sets.

For more detailed information, refer to the IMS Recovery Solution Pack: IMS Recovery Expert User's Guide.

UTILGBL(<subparameters>)

Use this parameter to specify the control statements that are used to control the execution of the integrated auxiliary utilities.

This parameter, and all the associated subparameters are described in Configuring the integrated auxiliary utilities environment.

XCFGROUP(name)

Use this parameter to specify the XCF group name used by the IMS Tools Online System Interface to communicate with the IMS systems associated with this recovery environment.

XCFGROUP parameter syntax

name

name is the 1-to 8-character alphanumeric name specified in the IMS Tools Online System Interface installation.

To find the IMS Tools Online System Interface XCF group name, look in the IMS PROCLIB member FOIxxxxP (where xxxx is the IMSID). In that member, the XCFGROUP= parameter specifies the last five characters of the XCF group name.

To construct the complete name, prefix this value with TOI. Or you can look in your IMS online job log for the FOI100I message; the value that is specified after XCF GROUP= indicates the complete IMS Tools Online System Interface XCF group name.

If this parameter is not specified, then automatic /DBR and /STA of databases will not be possible. There is no default for this parameter.