Optional parameters

,operation_flags 
TYPE: BINARY 
LENGTH: HALF WORD
EXPLANATION: This parameter contains a set of optional flags used to indicate how the file copy notification service must be processed. For each flag, 1 is ON and 0 is OFF. This is an optional input parameter. A list of the possible bits along with their associated meanings:
0-7
reserved
8
PROCESSING MODE - Specifies desired processing mode.
ON - synchronous processing
Set this bit on to process the notification request in synchronous processing mode. CICS® VR accepts the request, validates parameters, and processes the request before returning control back to the caller.
OFF - asynchronous processing
Set this bit off to process the notification request in asynchronous processing mode. CICS VR accepts the request and validates parameters. Control is then returned to the caller while the request is being processed.

The default value is OFF (asynchronous processing).

Note: Asynchronous processing achieves better performance when compared to synchronous processing. However, synchronous processing must be used when it is mandatory to guarantee the notification completed successfully before the calling program continues.
9
PROCESS BWO - Specifies if the product that created the backup uses the DFSMS backup-while open (BWO) protocols.
ON - The backup was taken while the data set remained open to CICS for update, and the backup product set the BWO STATUS flags and either the BWO TIMESTAMP field or RECOVERY TIMESTAMP fields in the catalog entry of the VSAM data set. When the backup is selected for restore and recovery, CICS VR:
  • Checks for the proper setting of the BWO STATUS flags prior to forward recovery processing.
  • Sets the BWO STATUS flags to '001' prior to recovery.
  • Uses either the value of the BWO TIMESTAMP field or the RECOVERY TIMESTAMP fields in the catalog entry of the data set as the forward recovery start time.
  • Set sthe BWO STATUS flags to '000' after a successful recovery.
Note: The backup product sets the BWO status flags to '101' after the backup was restored, indicating an online backup was restored, and needs to be forward recovered before it can be made available to CICS.
The PROCESS BWO bit can only be set on if one of the following status flags is also set on:
  • SHARP ONLINE BACKUP WITH TIEUP LOG RECORD
  • FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD
  • SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD
  • FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD
Note: If the PROCESS BWO bit is set, and either the SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit or the FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is also set, the ONLINEBACKUPNAME keyword must be added to the RECOVER command for CICS VR to use the BWO protocols during recovery.
OFF - Specifies that either:
  • The backup was taken while the data set was offline from CICS.
  • The backup was taken while the data set remained available for update to CICS, but the backup product did not use DFSMS BWO protocols (did not set the BWO STATUS flags and the BWO TIMESTAMP field or RECOVERY TIMESTAMP fields in the catalog entry of the VSAM data set).

The default value is OFF.

10
PREALLOCATION REQUIRED - Specifies if the product that created the backup pre-allocates the target data set at the time of the restore.
ON
The product that created the backup does not preallocate the target data set at the time of the restore. CICS VR extracts information from the ICF catalog about the allocation attributes of the data set, and register this information in the RCDS. Subsequently, at the time of the restore, CICS VR uses the registered information to create a restore job which includes a step to preallocate the target data set.
OFF
The product that created the backup pre-allocates the target data set at the time of the restore. So, at the time of the restore, CICS VR creates a restore job which does not include a step to preallocate the target data set.
11-15
reserved
,status_flags 
TYPE:  BINARY 
LENGTH:  HALF WORD
EXPLANATION: This parameter contains a set of flags used to indicate various states of the backup. For each flag, 1 is ON and 0 is OFF. This is an optional input parameter. A list of the possible bits along with their associated meanings:
0
SHARP ONLINE BACKUP WITH TIEUP LOG RECORD
Set this bit if:
  • The backup was created for a VSAM data set while the data set remained open for update.
  • A tieup log record was written to the log stream with a timestamp equal to the time specified in the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters.
  • No updates were made to the VSAM data through the base cluster or any paths during the entire duration of backup processing.

If this flag is set on, the backup product must have the ability to successfully create a backup with data integrity while it remains open for update. Also, the timestamp of a tieup log record must be specified in either the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters.

When this bit is set on, CICS VR does not run in "fuzzy" processing mode, meaning that CICS VR treats any log records found for updates that are already reflected in the backup as an error condition.

The FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD, SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD, and FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bits cannot be set on if this bit is set on.

1
FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD
Set this bit if:
  • The backup was created for a VSAM data set while the data set remained open for update.
  • A tieup log record was written to the log stream with a timestamp equal to the time specified in the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters.
  • One or more updates might have been made to the VSAM data through the base cluster or any paths during the duration of backup processing.

If this flag is set on, the backup product must have the ability to successfully create a backup with data integrity while it remains open for update. Also, the timestamp of a tieup log record must be specified in either the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters.

When this bit is set on, CICS VR runs in "fuzzy" processing mode, meaning that CICS VR reports, but ignores any log records found for updates that are already reflected in the backup.

The SHARP ONLINE BACKUP WITH TIEUP LOG RECORD, SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD, and FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bits cannot be set on if this bit is set on.

2
SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD
Set this bit if:
  • The backup was created for a VSAM data set while the data set remained open for update.
  • No updates were made to the VSAM data through the base cluster or any paths during the entire duration of backup processing.
  • A new tieup log record for the VSAM data set was not written to the log prior to backup creation, other than when the data set was initially open (CICS writes a tieup log record when a data set is initially open). Standard CICS VR forward recovery always starts by reading a tieup log record. Therefore, if a tieup is not written prior to backup processing, CICS VR would need to start forward recovery from when the data set was initially open.
However, if you have access to the information normally read from a tieup log record, you can set this flag on, and also specify information in the following parameters of this service:
  • ddnames_list
    • number_of_ddnames
    • ddname_and_APPLID
  • log_stream_name
  • data_set_type
  • CI_size
  • maximum_record_length
  • key_position
  • key_length
Note: The parameters listed can only be specified when CICS VR is notified of an online backup that does not have a corresponding tieup log record.

A timestamp must also be specified in either the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters. The specified timestamp must accurately reflect when the information in the parameters listed was retrieved. For example, if the list of all opens (ddnames_list) against the data set was accurate at the timestamp 04.322 12:15:17, then this must be the timestamp specified in either the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters (in the appropriate time format).

Therefore, if this backup is selected for restore and forward recovery, CICS VR can start recovery at the timestamp specified in either the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters and does not have to start by reading a tieup log record on the log stream.

If this flag is set on, the backup product must have the ability to successfully create a backup with data integrity while it remains open for update. Also, when this bit is set on, CICS VR does not run in "fuzzy" processing mode, meaning that CICS VR treats any log records found for updates that are already reflected in the backup as an error condition.

The SHARP ONLINE BACKUP WITH TIEUP LOG RECORD, FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD, and FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bits cannot be set on if this bit is set on.

3
FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD
Set this bit if:
  • The backup was created for a VSAM data set while the data set remained open for update.
  • One or more updates might have been made to the VSAM data through the base cluster or any paths during the duration of backup processing.
  • A new tieup log record for the VSAM data set was not written to the log prior to backup creation, other than when the data set was initially open (CICS writes a tieup log record when a data set is initially open). Standard CICS VR forward recovery always starts by reading a tieup log record. Therefore, if a tieup is not written prior to backup processing, CICS VR would need to start forward recovery from when the data set was initially open.

However, if you have access to the information normally read from a tieup log record, you can set this flag on, and specify information in the parameters listed in the description of bit 2, SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD. Also as described for bit 2, a timestamp must be specified in either the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters.

If this flag is set on, the backup product must have the ability to successfully create a backup with data integrity while it remains open for update. Also, when this bit is set on, CICS VR runs in "fuzzy" processing mode, meaning that CICS VR treats any log records found for updates that are already reflected in the backup as an error condition.

The SHARP ONLINE BACKUP WITH TIEUP LOG RECORD, FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD, and SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD bits cannot be set on if this bit is set on.

4-7
reserved
8
BACKUPDELETED - This backup that was previously registered to CICS VR through the file copy notification interface has now been deleted and CICS VR deregisters the backup from the RCDS.

Set this bit on if you want to remove the backup from CICS VR's inventory. The backup must have been previously registered to CICS VR using the file copy notification service. Once CICS VR is notified that the backup must be deregistered, the backup can no longer be displayed and selected through the CICS VR panel interface.

Note: Setting this bit only removes the backup entry from the CICS VR RCDS. It does not perform an actual delete of the backup. You can also deregister backups through the CICS VR panel interface.
9-15
reserved
,BWO_timestamp 
TYPE:  PACKED-DECIMAL 
LENGTH:  TWO FULL WORDS
EXPLANATION: This parameter may be specified if the backup created for the VSAM data set was made while the data set remained open for update. The backup product must have the ability to successfully create a backup with data integrity while it remains open for update. If specified, CICS VR uses the value of the BWO_timestamp parameter as the forward recovery start time when the backup is selected for restore and recovery.
You can only specify a value for the BWO_timestamp parameter if one of the following status flags has been set on:
  • SHARP ONLINE BACKUP WITH TIEUP LOG RECORD
  • FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD
  • SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD
  • FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD

If the SHARP ONLINE BACKUP WITH TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD status flag is set on, the value specified for the BWO_timestamp parameter must correspond with the timestamp of a tieup log record written to the forward recovery log stream for the VSAM data set.

If the SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD status flag is set on, the value specified for the BWO_timestamp parameter must reflect when the information in the following parameters was retrieved:
  • ddnames_list
    • number_of_ddnames
    • ddname_and_APPLID
  • log_stream_name
  • data_set_type
  • CI_size
  • maximum_record_length
  • key_position
  • key_length

Values cannot be specified for the recovery_timestamp_local and recovery_timestamp_GMT parameters if a value is specified for the BWO_timestamp parameter.

The BWO_timestamp parameter must be specified in the following format (the specified format is identical to the format used by the BWO TIMESTAMP ICF catalog entry):
  • The first word contains the date in packed-decimal format, 0CYYDDDF, where:
  • The second word contains the time in packed-decimal format, HHMMSSTF, where:

Example: One approach to associate a forward recovery start time with a backup made while the data set remains open for update is to enable the VSAM data set for dynamic backup processing. This approach requires that you either set the BACKUPTYPE parameter in the CICS file definition for the VSAM data set to DYNAMIC or specify the BWO(TYPECICS) parameter in the ICF catalog entry for the VSAM data set. You must also set the CICS activity keypoint frequency (AKPFREQ) to a nonzero number.

After performing the settings, CICS writes a tieup log record to the forward recovery log stream about every 30 minutes. The timestamp of the tieup log record is also recorded in the BWO TIMESTAMP field in the ICF catalog entry for the VSAM data set. When a backup is created for the VSAM data set while it is open to CICS, the timestamp in the BWO TIMESTAMP ICF catalog entry for the VSAM data set is the value that must be specified as the BWO_timestamp parameter value.

,recovery_timestamp_local,recovery_timestamp_GMT
TYPE:  CHARACTER or INTEGER 
LENGTH:  EIGHT BYTES
EXPLANATION: The recovery_timestamp_local and recovery_timestamp_GMT parameters might be specified if the backup created for the VSAM data set was made while the data set remained open for update. The backup product must have the ability to successfully create a backup with data integrity while it remains open for update.

If specified, CICS VR uses the value of the recovery_timestamp_local and recovery_timestamp_GMT parameters as the forward recovery start time when the backup is selected for restore and recovery.

You can only specify a value for the recovery_timestamp_local and recovery_timestamp_GMT parameters if one of the following status flags has been set on:
  • SHARP ONLINE BACKUP WITH TIEUP LOG RECORD
  • FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD
  • SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD
  • FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD

If the SHARP ONLINE BACKUP WITH TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD status flag is set on, the value specified for the recovery_timestamp_local or recovery_timestamp_GMT parameter must correspond with the timestamp of a tieup log record written to the forward recovery log stream for the VSAM data set.

If the SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD status flag is set on, the value specified for the recovery_timestamp_local or recovery_timestamp_GMT parameter must reflect when the information in the following parameters was retrieved:
  • ddnames_list
    • number_of_ddnames
    • ddname_and_APPLID
  • log_stream_name
  • data_set_type
  • CI_size
  • maximum_record_length
  • key_position
  • key_length

Values cannot be specified for the recovery_timestamp_local and recovery_timestamp_GMT parameters if a value is specified for the BWO_timestamp parameter.

The values of the recovery_timestamp_local and recovery_timestamp_GMT parameters must be specified in STCK format. If either parameter is specified, a value must also be specified in the other parameter. However, zeroes can be specified for one of the parameters. In this situation, CICS VR translates the value of the parameter where a nonzero value has been specified, into the format, local or GMT, used by the parameter where a zero value has been specified, and uses it as the value for that parameter.

Note: Local date and time formats are affected by a change in daylight saving time on a system. Therefore, when you later refer to a backup, IBM® recommends that you use the GMT date and time format for backups created near a change in daylight saving time.
,optional_information
Optional_information contains a set of subparameters that allow for additional information related to the backup or VSAM data set to be registered to CICS VR. This is an optional input parameter.

For example, you might want to enter a small description of the backup, such as "remote site backup", in this optional parameter that is viewable when selecting a backup to restore at a later time.

In another example, you might want to enter some value that is unique to the backup product that is stored with information about the backup; for example, a specific volume name. Then, during restore, this information could be use as input to the restore commands.

The optional_information parameter contains the following subparameters.
,optional_information_length
TYPE: INTEGER 
LENGTH: FULL WORD
EXPLANATION: Specifies the length, number of bytes, of the area in storage that contains the optional information. This value must be an integer greater than zero, and cannot be larger than 256 bytes. IBM recommends that the specified optional information length is a multiple of 64 bytes.
,optional_information_area 
TYPE: CHARACTER 
LENGTH: MAXIMUM 256 BYTES
EXPLANATION: Contains optional information and must have a length equal to the value that was specified in the optional_information_length subparameter. This is an optional character input field. The characters can be alphabetic, numeric, or national (@, #, $).

CICS VR divides and stores the entered optional information in 64 byte groups. For example, if 128 bytes of optional information is specified, CICS VR stores and displays this as two groups of 64 bytes. You can also view each 64 byte group through the CICS VR panel interface, and reference each 64 byte group individually using an appropriate variable in a restore JCL skeleton. You can therefore treat this optional parameter as 4 separate parameters that contain 64 bytes of optional information each, if appropriate.

For example, if you want to record two separate pieces of information, perhaps a data class and a management class, during notification, specify the first piece of information, data class, in the first 64 bytes, and the second piece of information, management class, in the second 64 bytes.

,volume_list
Volume_list is an optional input parameter that contains a set of subparameters that list the volumes on which the backup resides. This parameter must be specified if the backup is not cataloged. The volume_list parameter contains the following subparameters:
,number_of_volumes 
TYPE: INTEGER 
LENGTH: FULL WORD
EXPLANATION: This subparameter lists the number of volumes on which the backup resides.

For example, if the backup resides on three volumes, the number_of_volumes parameter must contain the integer 3.

,volume_list_area
TYPE: CHARACTER 
LENGTH: NUMBER OF VOLUMES MULTIPLIED BY 6
EXPLANATION: The list of volumes on which the backup resides. The volume area must be EBCDIC character type, and its length must be the number of volumes specified in the number_of_volumes subparameter multiplied by six. Each volume must occupy six characters and be padded on the right with EBCDIC blanks if necessary.
For example, if the backup resides on three volumes:
  • The number_of_volumes subparameter must contain the integer 3
  • The volume_list_area subparameter must contain the names of the three volumes on which the backup resides.
For example: 
 'VOL1  VOL2  VOL3  '
,device_type
TYPE:  CHARACTER 
LENGTH:  EIGHT BYTES
EXPLANATION: The name or group name of the device type of the previously listed volumes. This is an optional eight character input field and must be defined as EBCDIC character data. If the device type name is less than eight characters, left-justify the name in the field and pad it on the right with EBCDIC blanks.
,sequence_number
TYPE:  INTEGER 
LENGTH:  HALF WORD
EXPLANATION: The sequence number of the backup if the backup resides on tape and is not cataloged. This is an optional half word input field and must be defined as an integer. The minimum value that can be specified is 0 and the maximum value that can be specified is 9999.
,ddnames_list
ddnames_list is an optional input parameter. It contains a set of subparameters, which list all ddnames and corresponding CICS APPLIDs that CICS has used for all active opens against the base cluster and any AIXs of the base cluster.
Note: The ddnames_list parameter and its subparameters must only be specified if either the SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD flag or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD flag of the status_flags parameter is set.

The ddnames_list parameter contains the following subparameters:

,number_of_ddnames
TYPE:  INTEGER 
LENGTH:  FULL WORD
EXPLANATION: This subparameter lists the number of different ddnames that CICS has currently used to open the VSAM base cluster and any AIXs of the base cluster.

For example, if CICS currently has opened the VSAM base cluster with a ddname of PAY1BASE, and CICS has also opened an alternate index of the base cluster, using a path, with a ddname of PAY1AIX, the number_of_ddnames subparameter must contain the integer 2.

,ddname_and_APPLID
TYPE:  CHARACTER 
LENGTH:  NUMBER OF DDNAMES MULTIPLIED BY 16
EXPLANATION: This subparameter lists the ddnames and corresponding CICS APPLIDs that are currently used by CICS to open the VSAM base cluster and any alternate indexes of the base cluster. The field must be EBCDIC character type, and its length must be the number of ddnames specified in the number_of_ddnames subparameter multiplied by 16. Each ddname and CICS APPLID pair must occupy 16 characters and use the following format: 
'ddname  (8 characters) CICS APPLID (8 characters)'
The ddname must occupy the first 8 characters, padded on the right with EBCDIC blanks if necessary. Then, the CICS APPLID associated with the specified ddname must occupy the next 8 characters, again padded on the right with EBCDIC blanks if necessary.
For example, if a CICS region with an APPLID of CICSPROD currently has the base cluster of the VSAM data set opened with a ddname of PAY1BASE, and a CICS region with an APPLID of CICSPRD2 has an AIX® of the VSAM data set opened with a ddname of PAY1AIX:
  • The number_of_ddnames subparameter must contain the integer 2.
  • The ddname_and_APPLID subparameter must contain two ddname and CICS APPLID pairs. For example: 
    'PAY1BASECICSPRODPAY1AIX CICSPRD2 '
,log_stream_name
TYPE:  CHARACTER 
LENGTH:  26 BYTES
EXPLANATION: This optional parameter contains the name of the forward recovery log stream to which CICS logging is writing after-images for updates made to the VSAM data set.

This 26 character input field must be defined as EBCDIC character data and padded on the right with EBCDIC blanks if necessary.

,data_set_type
TYPE:  CHARACTER 
LENGTH:  ONE BYTE
EXPLANATION: This optional parameter contains an indication of the type of VSAM data set for which the backup has been created.
This one character input field must be defined as EBCDIC character data and can contain only one of the following values: 
K    KSDS VSAM sphere
E    ESDS VSAM sphere
R    RRDS VSAM sphere
V    VRRDS VSAM sphere
,CI_size
TYPE:  INTEGER 
LENGTH:  FULL WORD
EXPLANATION: This optional parameter contains the control interval size in bytes, of the VSAM data set for which the backup has been created.

This full word input field must be defined as an integer.

,maximum_record_length
TYPE:  INTEGER 
LENGTH:  FULL WORD
EXPLANATION: This optional parameter contains the maximum record length in bytes, of the VSAM data set for which the backup has been created.

This full word input field must be defined as an integer.

,key_position
TYPE:  INTEGER 
LENGTH:  FULL WORD
EXPLANATION: This optional parameter contains the key position of the VSAM data set if the backup was created for a KSDS VSAM data set. If the backup was created for a non-KSDS VSAM data set, then set this field to 0.

This full word input field must be defined as an integer.

,key_length
TYPE:  INTEGER 
LENGTH:  FULL WORD
EXPLANATION: This optional parameter contains the key length in bytes, of the VSAM data set if the backup was created for a KSDS VSAM data set. If the backup was created for a non-KSDS VSAM data set, then set this field to 0.

This full word input field must be defined as an integer.