RECOVER: Forward recover a VSAM sphere

Keywords

SPHERE(sphere name)

Specifies the VSAM sphere to be forward recovered. It is the name as recorded on the log. Only one SPHERE keyword is allowed for each RECOVER control statement. The SPHERE keyword is required.

sphere name

Specifies the MVS data set name of the VSAM sphere to be forward recovered. This name is 1–44 characters.

ONLY | FIRST | INTERMEDIATE | LAST

Specifies the relative order of the steps in a job. These keywords are mutually exclusive. One of these keywords must be specified on a forward recovery command when the NEWSPHERE keyword has not be specified. A forward recovery job is composed of one or more steps. CICS VR must know the relative forward recovery step that is executing. If there is only one forward recovery step then specify ONLY. If there are two forward recovery steps, then specify FIRST on the first step and specify LAST on the last step. When there are more than two steps, specify INTERMEDIATE on all the intermediate forward recovery steps (the steps that are not the first or the last). This is handled automatically for you through the CICS VR panels.

STARTTIME(start date and time,LOCAL | GMT)

Specifies the earliest timestamp of the after-images that you want to recover the VSAM sphere from. CICS VR ignores all after-images on the logs until it finds an after-image for this VSAM sphere, whose timestamp is the same as, or later than, the time specified in the STARTTIME keyword. CICS VR applies all after-images for this VSAM sphere, from this place in the log, if a tie-up record (TUR) has been encountered on the log. Only one STARTTIME keyword is allowed for each RECOVER control statement. If you do not specify STARTTIME or STARTTOD, recovery starts at the first after-image encountered on the logs, after the first TUR.

For VSAM data sets that were restored from a product that used backup-while-open facilities, STARTTIME is the recovery point time. When you use the CICS VR dialog interface CICS VR automatically retrieves the recovery point time from the integrated catalog facility (ICF) catalog, so you do not need to specify STARTTIME in this situation.

start date and time

Must be in the format yy/ddd/hh/mm/ss, where:

yy

Is the last two digits of the year (00–99)

ddd

Is the day of the year (001–366)

hh

Is the hour of the day (00–23)

mm

Is the number of minutes (00–59)

ss

Is the number of seconds (00–59)

You can separate these values with a slash (/), period (.), or colon (:). You can also omit the separator character. For example:

STARTTIME(01.159/22:23:00)

You cannot substitute commas, blanks, and so on, for the time values, but you can omit values from the right. For example, if you specify STARTTIME(01.159), CICS VR assumes that the time segment is 00:00:00.

CICS VR interprets year values (yy) in the range 00–85 to be years 2000–2085, and year values in the range 86–99 to be years 1986–1999.

LOCAL

Specifies that the date and time are in local format. You can specify LOCAL if you are using MVS log streams. LOCAL is the default value.

GMT

Specifies that the date and time are in Greenwich mean time (GMT) format. You can specify GMT only if you are using MVS log streams.

STOPTIME(stop date and time,LOCAL | GMT)

Specifies the latest timestamp of the after-images that you want to recover the VSAM sphere from. CICS VR ignores all after-images on the logs after it finds an after-image for this VSAM sphere, whose timestamp is later than the time specified in the STOPTIME keyword. CICS VR applies all after-images for this VSAM sphere up to this place in the log. Only one STOPTIME keyword is allowed for each RECOVER control statement. If STOPTIME or STOPTOD is not specified, recovery stops after the last supplied log.

stop date and time

Must be in the format yy/ddd/hh/mm/ss, where:

yy

Is the last two digits of the year (00–99)

ddd

Is the day of the year (001–366)

hh

Is the hour of the day (00–23)

mm

Is the number of minutes (00–59)

ss

Is the number of seconds (00–59)

You can separate these values with a slash (/), period (.), or colon (:). You can also omit the separator character. For example:

STOPTIME(01.159/00:30:00)

You cannot substitute commas, blanks, and so on, for the time values, but you can omit values from the right. For example, you can specify day 01159, time 23:59:59, as follows:

STOPTIME(01.159)

If you specify this, CICS VR assumes that the day is 01365 and the time is 23:59:59:

STOPTIME(01)

CICS VR assumes that these values are for day 01159, and time 16:59:59:

STOPTIME(0115916)

CICS VR interprets year values (yy) in the range 00–85 to be years 2000–2085, and year values in the range 86–99 to be years 1986–1999.

LOCAL

Specifies that the date and time are in local format. You can specify LOCAL if you are using MVS log streams. LOCAL is the default value.

GMT

Specifies that the date and time are in GMT format. You can specify GMT only if you are using MVS log streams.

STARTTOD(start time of day,LOCAL | GMT)

Identifies the earliest time, in hexadecimal time-of-day (TOD) format, of the after-images that you want to recover the VSAM sphere from. CICS VR ignores all after-images on the logs until it finds an after-image for this VSAM sphere, whose TOD value is the same as, or later than, the time specified in the STARTTOD keyword. CICS VR applies all after-images for this VSAM sphere, from this place in the log, if a tie-up record (TUR) has been encountered on the log. Only one STARTTOD keyword is allowed for each RECOVER control statement. If you do not specify STARTTOD or STARTTIME, recovery starts at the first after-image encountered on the logs, after the first TUR.

Use the STARTTOD keyword only if the STARTTIME keyword value is not precise enough for your recovery stop time. The STARTTOD keyword has no synonyms.

start time of day

Must be 16 hex characters. Here is an example of a STARTTOD keyword:

STARTTOD(AC47C0403792C101)

LOCAL

Specifies that TOD value is in local format. You can specify LOCAL if you are using MVS log streams. LOCAL is the default value.

GMT

Specifies that the TOD value is in GMT format.

STOPTOD(start time of day,LOCAL | GMT)

Identifies the latest time, in hexadecimal time-of-day (TOD) format, of the after-images that you want to recover the VSAM sphere from. CICS VR ignores all after-images on the logs after it finds an after-image for this VSAM sphere, whose TOD value is later than the time specified in the STOPTOD keyword. CICS VR applies all after-images for this VSAM sphere up to this place in the log. Only one STOPTOD keyword is allowed for each RECOVER control statement. If STOPTOD or STOPTIME is not specified, recovery stops after the last supplied log.

Use the STOPTOD keyword only if the STOPTIME keyword value is not precise enough for your recovery stop time. The STOPTOD keyword has no synonyms.

stop time of day

Must be 16 hex characters. Here is an example of a STOPTOD keyword:

STOPTOD(AC47C0403792C101)

LOCAL

Specifies that TOD value is in local format. You can specify LOCAL if you are using MVS log streams. LOCAL is the default value.

GMT

Specifies that the TOD value is in GMT format.

NEWSPHERE(updated sphere name)

Specifies the name of the target VSAM sphere to be recovered. The specified name can be 1-44 characters.

This keyword is optional, except when the SHADOW keyword is also specified, because SHADOW processing must always be performed against a copy of the VSAM sphere.

If NEWSPHERE is specified, CICS VR forward recovery processing applies all log records written for the VSAM data set specified on the SPHERE keyword to the data set specified on the NEWSPHERE keyword.

If NEWSPHERE is omitted, CICS VR forward recovery processing applies all log records written for the VSAM data set specified on the SPHERE keyword, to that same data set.

If the VERSION or HSMDATE keyword has also been specified, CICS VR calls DFSMShsm utilities to restore the sphere to the name specified in the NEWSPHERE keyword.

updated sphere name

Specifies the MVS data set name of the VSAM sphere to be recovered. This name can be 1–44 characters.

SHADOW

The SHADOW keyword is optional and has no synonyms.

The concept is that the first time (run 1) that you run a shadow forward recovery, the backup is restored and some amount of the forward recovery log is applied. Subsequent shadow forward recovery runs (2 - n) apply more of the forward recovery log with the intent to keep the shadow copy as current as possible.

CICS VR saves the status of the shadow forward recovery in the RCDS, so the subsequent shadow forward recovery runs (2 - n) must not specify a start and stop time and must be run frequently, so as to minimize the log records to be applied.

When a problem occurs and a real forward recovery is required, the CICS VR shadow can be copied to replace the user data set.

If you are using the CICS VR VSAM batch logger to log the updates that are made to VSAM spheres by batch jobs, you must also add the REMOTE keyword to the RECOVER command. The REMOTE keyword specifies that the log records written by the CICS VR VSAM batch logger must be included during shadow recovery processing.

APPLYCA

The APPLYCA keyword is optional and has no synonyms.

APPLYCA indicates to CICS VR that there is change accumulation data that is relative to this data set that needs to be applied during forward recovery processing. If there is no change accumulation data set or CICS VR detects an error with the CA data set, the APPLYCA keyword is ignored.

STARTAT(REDO | DSNAME)

Specifies where on the log the recovery begins.

REDO

Specifies all after-images found after the time specified in the STARTTIME keyword is used in this recovery, provided a TUR has been found on the log for this VSAM sphere.

DSNAME

Specifies the first TUR found on the log after the time specified in the STARTTIME keyword is used. All after-images after this TUR and before the time specified in the STOPTIME keyword is used in the recovery. So any after-images found after the time specified in the STARTTIME keyword, and before the TUR for this VSAM sphere is ignored.

The STARTAT keyword is optional; if it is not specified, the default of REDO is used.

If you use the STARTAT keyword without the STARTTIME keyword, STARTAT is ignored.

The STARTAT keyword has no synonyms.

Note: When a file is opened, the association between the file name and the data set name is recorded on the log by a TUR.

HSMDATE(date)

Identifies the date of the DFSMShsm full volume dump which is to be used to restore the VSAM sphere. For more information about the DFSMShsm restore process, refer to z/OS® DFSMShsm Storage Administration Guide.

date

Specifies the DFSMShsm full volume dump date. The date must be in the format yyddd.

VERSION(DFSMShsm version number)

DFSMShsm version number identifies the version number of the DFSMShsm backup that is to be restored. The version number can be 0-999. For more information about the DFSMShsm restore process, refer to z/OS DFSMShsm Storage Administration Guide.

DFSMShsm version number

Identifies the version number of the DFSMShsm backup that is to be restored. The version number can be 0–999.

VOLUME(volume)

Specifies the volume serial number where the DFSMShsm backup of the VSAM sphere is restored to. This keyword can only be used if you have specified VERSION. If you specify VOLUME you must also specify the UNIT keyword. For more information about the DFSMShsm restore process, refer to z/OS DFSMShsm Storage Administration Guide.

volume

Identifies the volume which is to be used for the DFSMShsm restore of the VSAM sphere. The volume is 1–6 characters.

UNIT(unit)

Specifies the unit name where the DFSMShsm backup of the VSAM sphere is restored to. This keyword can only be used if you have specified VERSION. If you specify UNIT you must also specify the VOLUME keyword. For more information about the DFSMShsm restore process, refer to z/OS DFSMShsm Storage Administration Guide.

unit

Identifies the unit name which is to be used for the DFSMShsm restore of the VSAM sphere

AUTOJOURNALS

Specifies that CICS VR must apply only log records produced by CICS TS autojournaling to the VSAM spheres during forward recovery processing.

The AUTOJOURNALS keyword is optional, and if it is not specified, CICS VR only applies log records produced by CICS TS forward recovery logging, Transactional VSAM, and CICS VR batch logging during forward recovery processing.

The AUTOJOURNALS keyword is only valid for VSAM spheres that were updated by CICS TS, and it is ignored when recovering VSAM spheres that were not updated by CICS TS.

REMOTE

Specifies that shadow recovery processing must include log records that were written by the CICS VR VSAM batch logger. You must add the REMOTE keyword to the RECOVER command when both of the following conditions are true:

• The SHADOW keyword has also been added to the RECOVER command.
• You want to ensure that shadow recovery processing includes all log records that were written by the CICS VR VSAM batch logger when the VSAM spheres were updated by batch jobs.

The REMOTE keyword must not be added to the RECOVER command if the SHADOW keyword has not been added.

ONLINEBACKUPNAME(backup name)

Specifies the name of the online backup from which the VSAM data set being recovered was restored.

The ONLINEBACKUPNAME keyword is optional and must only be specified if:

• The data set being recovered was previously restored from a backup that was registered to CICS VR through the file copy notification service.
• The backup was taken while the data set remained online and open to CICS for update.
• The backup product did not use backup-while-open (BWO) facilities.
• The RCDS is available and allocated to the RECOVER job.

If these conditions are true, specify the ONLINEBACKUPNAME keyword to ensure that CICS VR uses the proper forward recovery start time. CICS VR uses the forward recovery start time that is stored in the RCDS for the specified backup. The STARTTIME keyword is therefore optional when the ONLINEBACKUPNAME keyword is specified.

The CICS VR panel interface automatically adds the ONLINEBACKUPNAME keyword to the produced RECOVER command if the backup selected for restore meets the criteria specified.

backup name

The fully qualified data set name of the online backup from which the VSAM data set was restored. The backup data set name can be 1-44 characters.

FILEID(file ddname)

An optional keyword specifying the ddname that CICS used to allocate the data set being recovered at the forward recovery start time specified in the RECOVER command.

A CICS file definition associates a unique 1-8 character ddname with every VSAM data set defined to the region. When a VSAM data set is opened, CICS writes the full data set name and corresponding ddname (along with other information) into a tieup (TUR) log record. In all subsequent after-image log records, only the ddname is used to reference the data set.

CICS VR forward recovery therefore always begins by reading a tieup log record. This allows CICS VR to relate all after-image log records to the appropriate VSAM sphere.

In rare cases when a tieup log record does not exist for a VSAM data set, traditional CICS VR recovery is not able to associate after-image log records with a VSAM sphere. The optional FILEID and CICSID keywords can be specified to inform CICS VR of this file ddname and data set name relation for each CICS region that is normally obtained from a tieup log record.

Note: Specifying the FILEID and CICSID keywords causes CICS VR to bypass some additional error checking that is normally performed during recovery processing when tieup log records are available. You must specify only the FILEID and CICSID keywords in rare cases when the tieup log records are not available and the keywords are absolutely necessary for recovery processing.

file ddname

The 1-8 character ddname used by CICS to allocate the data set being recovered at the start time specified in the RECOVER command.

More than one file ddname can be specified, separated by a comma. For each file ddname specified, a corresponding CICS applid must be specified in the CICSID keyword. CICS VR does not limit the number of file ddname and CICS applid pairs that can be specified.

For example, if at the specified forward recovery start time, components of the VSAM sphere were opened in two separate CICS regions, the following FILED and CICSID keywords might be specified:

FILEID(ACCTBASE, ACCTAIX1)
CICSID(CICSPRD1, CICSPRD2)

CICS VR forward recovery processing interprets this example as follows:

• CICS region CICSPRD1 had the VSAM sphere opened at the forward recovery start time with a ddname of ACCTBASE.
• CICS region CICSPRD2 had the VSAM sphere opened at the forward recovery start time with a ddname of ACCTAIX1.

To ensure proper forward recovery when a tieup log record is not available, all active opens, against all of the VSAM sphere components, base cluster and alternate indexes, from all CICS regions, at the specified forward recovery start time, must be specified in the FILEID and CICSID fields.

CICSID(CICS applid)

An optional keyword that specifies the CICS region APPLID associated with each of the file ddnames specified in the optional FILEID keyword.

Refer to the FILEID keyword description for information about how and when to use the FILEID and CICSID optional keywords.

Note: Specifying the FILEID and CICSID keywords causes CICS VR to bypass some additional error checking that is normally performed during recovery processing when tieup log records are available. You must specify the FILEID and CICSID keywords only in rare cases when the tieup log records are not available and the keywords are absolutely necessary for recovery processing.

CICS applid

The 1-8 character CICS region APPLID associated with the specified file ddname(s) in the FILEID keyword.

More than one CICS applid can be specified, separated by a comma. For each file ddname specified, a corresponding CICS applid must be specified in the CICSID keyword. CICS VR does not limit the number of file ddname and CICS applid pairs that can be specified. The FILEID keyword description has an example of how CICS VR interprets multiple file ddname and CICS applid pairs.

To ensure proper forward recovery when a tieup log record is not available, all active opens, against all of the VSAM sphere components, base cluster and alternate indexes, from all CICS regions, at the specified forward recovery start time, must be specified in the FILEID and CICSID fields.

NOTIEUPS

A backup is taken to forward recover the VSAM sphere specified in this RECOVER command. If no tieups were written when the backup was taken, this keyword must be specified.

If NOTIEUPS is specified, CICS VR uses information gathered during a log-of-log scan to determine which logged records to use during forward recovery. If you use this keyword, make sure that a log-of-log scan has been performed after the STARTTIME specified for this vsam sphere.

Usage notes

Synonyms

The following table provides the RECOVER commands or keywords along with acceptable synonyms that can be used in place of the commands or keywords.