CALL DWWCVRN

The file copy notification service can be started from a backup product or a separate user program that issues the CALL DWWCVRN statement, accompanied by a list of required and optional arguments and storage areas.

Format

Figure 1. Syntax of CALL_DWWCVRN
>>-+-------+-CALL-DWWCVRN-,-(-return_code-,-reason_code-,-prob_det-,-backup_product-,----->
   +-label-+

>--backup_type-,-dataset_name-,-backup_name-,-backup_date_local-,-backup_time_local-,----->

>--backup_date_GMT-,-backup_time_GMT-,-+-,-----------------+-+-,--------------+----------->
                                       +-,-operation_flags-+ +-,-status_flags-+ 

>--+-,---------------+-+-,--------------------------+-+-,------------------------+-------->
   +-,-BWO_timestamp-+ +-,-recovery_timestamp_local-+ +-,-recovery_timestamp_GMT-+

>--+-,-----------------------------+-+-,---------------------------+---------------------->
   +-,-optional_information_length-+ +-,-optional_information_area-+            

>--+-,-------------------+-+-,------------------+-+-,-------------+----------------------->
   +-,-number_of_volumes-+ +-,-volume_list_area-+ +-,-device_type-+

>--+-,-----------------+-+-,-------------------+-+-,-------------------+------------------>
   +-,-sequence_number-+ +-,-number_of_ddnames-+ +-,-ddname_and_APPLID-+

>--+-,-----------------+-+-,---------------+-+-,---------+-+-,-----------------------+---->
   +-,-log_stream_name-+ +-,-data_set_type-+ +-,-CI_size-+ +-,-maximum_record_length-+

>--+-,--------------+-+-,------------+-)-------------------------------------------------><
   +-,-key_position-+ +-,-key_length-+                                                
  

Parameters

Programming notes

Consider the following items considered when writing a call to the CICS® VR file copy notification service:
  • The number_of_ddnames, ddname_and_APPLID, log_stream_name, data_set_type, CI_size, maximum_record_length, key_position and key_length optional parameters 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 optional status_flags parameter is set.
  • When notifying CICS VR of a timestamp, be sure it includes "leap seconds" that can be inserted or deleted due to time-correction standards. This is important because the timestamps of log records written by CICS and CICS VR also include the leap seconds. For example, STCK returns the TOD clock, and this value might need to be adjusted to include leap seconds. Refer to z/Architecture® Principles of Operation for more details.
  • All registered backup data set names for a VSAM data set must be unique. If CICS VR is notified of a backup with a duplicate name for the same VSAM data set, the existing RCDS entry for the backup is replaced with information from the most recent notification.

    For example, consider the scenario where a backup named SAMPLE.BACKUP1 has been created and registered for VSAM sphere SAMPLE.BASE1 at 04.319 10:34:12. If CICS VR is then notified of a backup with the same name (SAMPLE.BACKUP1) for the same VSAM sphere (SAMPLE.BASE1) at 04.322 01:01:01, all information in the RCDS about the previous backup is replaced with information about the backup registered at 04.322 01:01:01.

Return and reason codes

When DWWCVRN returns control to the calling program, it provides both a return code and a reason code. DWWCVRN can return additional data useful for problem determination in the prob_det array. For assistance when coding the CICS VR file copy notification service in assembler language, CICS VR provides the caller a mapping macro DWW2NRRC located in the SDWWSORC data set for the non-server related return code and reason code equates. In addition, the CICS VR server address space might return a return and reason code when an error occurs during processing of the CICS VR file copy notification service.

The following table identifies return code and reason code combinations issued by CICS VR when a problem occurs while processing the file copy notification service. For each combination the following table lists the associated equate symbol, explains the meaning, explains what and when additional problem determination data is returned, and recommends what action to take.

Note: Any other return/reason code combination that is encountered and is not listed in the table below indicates that an internal CICS VR error has occurred. Capture any CICS VR error messages written to the console and contact the IBM® Support Center.
Table 1. DWWCVRN return and reason codes
Return code Hex Reason Code Hex Equate Symbol, Meaning, and Action
0 0 Operation is successful.
8 100 Equate Symbol: DWWCVRN_ReturnCodeRequired

Meaning: The return_code parameter is not specified.

Action: Specify the return_code parameter in the CALL DWWCVRN statement and retry the request.

8 104 Equate Symbol: DWWCVRN_ReasonCodeRequired

Meaning: The reason_code parameter is not specified.

Action: Specify the reason_code parameter in the CALL DWWCVRN statement and retry the request.

8 108 Equate Symbol: DWWCVRN_ProbDetRequired

Meaning: The prob_det parameter is not specified.

Action: Specify the prob_det parameter in the CALL DWWCVRN statement and retry the request.

8 10C Equate Symbol: DWWCVRN_BackupProductRequired

Meaning: The backup_product parameter is not specified.

Action: Specify the backup_product parameter in the CALL DWWCVRN statement and retry the request

8 110 Equate Symbol: DWWCVRN_BackupTypeRequired

Meaning: The backup_type parameter is not specified.

Action: Specify the backup_type parameter in the CALL DWWCVRN statement and retry the request.

8 114 Equate Symbol: DWWCVRN_DataSetNameRequired

Meaning: The dataset_name parameter is not specified.

Action: Specify the dataset_name parameter in the CALL DWWCVRN statement and retry the request.

8 118 Equate Symbol: DWWCVRN_BackupNameRequired

Meaning: The backup_name parameter is not specified.

Action: Specify the backup_name parameter in the CALL DWWCVRN statement and retry the request.

8 11C Equate Symbol: DWWCVRN_BackupDateLocalRequired

Meaning: The backup_date_local parameter is not specified.

Action: Specify the backup_date_local parameter in the CALL DWWCVRN statement and retry the request.

8 120 Equate Symbol: DWWCVRN_BackupTimeLocalRequired

Meaning: The backup_time_local parameter is not specified.

Action: Specify the backup_time_local parameter in the CALL DWWCVRN statement and retry the request.

8 124 Equate Symbol: DWWCVRN_BackupDateGMTRequired

Meaning: The backup_date_GMT parameter is not specified.

Action: Specify the backup_date_GMT parameter in the CALL DWWCVRN statement and retry the request.

8 128 Equate Symbol: DWWCVRN_BackupTimeGMTRequired

Meaning: The backup_time_GMT parameter is not specified.

Action: Specify the backup_time_GMT parameter in the CALL DWWCVRN statement and retry the request.

8 134 Equate Symbol: DWWCVRN_OnlineBackupTimestampRequired

Meaning: The SHARP ONLINE BACKUP WITH TIEUP LOG RECORD, FUZZY ONLINE BACKUP WITH TIEUP LOG RECORD, SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD, or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the BWO_timestamp parameter and the recovery_timestamp_local and recovery_timestamp_GMT parameters are not specified.

Action: Either specify the BWO_timestamp parameter or the recovery_timestamp_local and recovery_timestamp_GMT parameters in the CALL DWWCVRN statement, and retry the request if the backup was created with integrity when the data set was open for update.

8 148 Equate Symbol: DWWCVRN_OptInfoLengthRequired

Meaning: The optional_information_length parameter is not specified. The optional_information_length parameter must be specified when the optional_information_area parameter is specified.

Action: Specify the optional_information_length parameter in the CALL DWWCVRN statement and retry the request.

8 14C Equate Symbol: DWWCVRN_OptInfoAreaRequired

Meaning: The optional_information_area parameter is not specified. The optional_information_area parameter must be specified when the optional_information_length parameter is specified.

Action: Specify the optional_information_area parameter in the CALL DWWCVRN statement and retry the request.

8 150 Equate Symbol: DWWCVRN_NumberOfVolumesRequired

Meaning: The number_of _volumes parameter is not specified. The number_of _volumes, volume_list_area and device_type parameters are all required when specifying volume information.

Action: Specify the number_of _volumes parameter in the CALL DWWCVRN statement and retry the request.

8 154 Equate Symbol: DWWCVRN_VolumeListAreaRequired

Meaning: The volume_list_area_address parameter is not specified. The number_of _volumes, volume_list_area and device_type parameters are all required when specifying volume information.

Action: Specify the volume_list_area parameter in the CALL DWWCVRN statement and retry the request.

8 158 Equate Symbol: DWWCVRN_DeviceTypeRequired

Meaning: The device_type parameter is not specified. The number_of _volumes, volume_list_area and device_type parameters are all required when specifying volume information.

Action: Specify the device_type parameter in the CALL DWWCVRN statement and retry the request.

8 200 Equate Symbol: DWWCVRN_InvalidBackupProductName

Meaning: An invalid or reserved backup product name is specified in the backup_product parameter. The DSS and HSM backup product names are reserved and cannot be specified.

Action: Change the backup_product parameter and retry the request.
Note: DFSMSdss and DFSMShsm automatically notify CICS VR when a backup is made. There is no need to code the file copy notification service when using DFSMSdss or DFSMShsm.
8 210 Equate Symbol: DWWCVRN_InvalidBackupType

Meaning: An invalid backup type is specified in the backup_type parameter.

Action: Change the backup_type parameter, using the required syntax, and retry the request.

8 220 Equate Symbol: DWWCVRN_InvalidDataSetName

Meaning: An invalid data set name is specified in the dataset_name parameter.

Action: Change the dataset_name parameter, using the required syntax, and retry the request.

8 230 Equate Symbol: DWWCVRN_InvalidBackupName

Meaning: An invalid backup name is specified in the backup_name parameter.

Action: Change the backup_name parameter, using the required syntax, and retry the request

8 290 Equate Symbol: DWWCVRN_InvalidOptInfoLength

Meaning: Length specified in the optional_information_length parameter is greater than 256 or less than or equal to 0.

Action: Change the optional_information_length parameter to an acceptable number and retry the request.

8 2AO Equate Symbol: DWWCVRN_InvalidNumberOfVolumes

Meaning: The value specified in the number_of_volumes parameter is greater than 99 or less than or equal to 0.

Action: Change the number_of_volumes parameter to an acceptable value and retry the request

8 2B0 Equate Symbol: DWWCVRN_InvalidSequenceNumber

Meaning: The value specified in the sequence_number parameter is greater than 9999 or less than 0.

Action: Change the sequence_number parameter to an acceptable value and retry the request.

8 15C Equate Symbol: DWWCVRN_NumberOfDDnamesRequired

Meaning: The SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the number_of_ddnames parameter is not specified.

Action: Specify the number_of_ddnames parameter in the CALL DWWCVRN statement and retry the request if the backup was created with integrity when the data set was open for update but a tieup was not written.

8 160 Equate Symbol: DWWCVRN_ddnameAndAPPLIDRequired

Meaning: The SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the ddname_and_APPLID parameter is not specified.

Action: Specify the ddname_and_APPLID parameter in the CALL DWWCVRN statement and retry the request if the backup was created with integrity when the data set was open for update but a tieup was not written.

8 164 Equate Symbol: DWWCVRN_LogStreamNameRequired

Meaning: The SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the log_stream_name parameter is not specified.

Action: Specify the log_stream_name parameter in the CALL DWWCVRN statement and retry the request if the backup was created with integrity when the data set was open for update but a tieup was not written.

8 168 Equate Symbol: DWWCVRN_DataSetTypeRequired

Meaning: The SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the data_set_type parameter is not specified.

Action: Specify the data_set_type parameter in the CALL DWWCVRN statement and retry the request if the backup was created with integrity when the data set was open for update but a tieup was not written.

8 16C Equate Symbol: DWWCVRN_CISizeRequired

Meaning: The SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the CI_size parameter is not specified.

Action: Specify the CI_size parameter in the CALL DWWCVRN statement and retry the request if the backup was created with integrity when the data set was open for update but a tieup was not written.

8 170 Equate Symbol: DWWCVRN_MaxRecLengthRequired

Meaning: The SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the maximum_record_length parameter is not specified.

Action: Specify the maximum_record_length parameter in the CALL DWWCVRN statement and retry the request if the backup was created with integrity when the data set was open for update but a tieup was not written.

8 174 Equate Symbol: DWWCVRN_KeyPositionRequired

Meaning: The SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the key_position parameter is not specified.

Action: Specify the key_position parameter in the CALL DWWCVRN statement and retry the request if the backup was created with integrity when the data set was open for update but a tieup was not written.

8 178 Equate Symbol: DWWCVRN_KeyLengthRequired

Meaning: The SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD or FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD bit is set ON in the status_flags parameter, but the key_length parameter is not specified.

Action: Specify the key_length parameter in the CALL DWWCVRN statement and retry the request if the backup was created with integrity when the data set was open for update but a tieup was not written.

8 2C0 Equate Symbol: DWWCVRN_InvalidStatusFlags
Meaning: More than one of the following flags of the status_flags parameter were 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
These bits are mutually exclusive.

Action: Only specify the appropriate flag in the status_flags parameter, then retry the request.

8 2C1 Equate Symbol: DWWCVRN_InvalidStatusFlags03
Meaning: None of the following flags of the status_flags parameter were 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
However, one or more of the following parameters were specified:
  • BWO_timestamp
  • recovery_timestamp_local
  • recovery_timestamp_GMT
The BWO or recovery timestamps can only be specified when CICS VR is being notified of an online backup.

Action: Specify the appropriate flag in the status_flags parameter, then retry the request if the backup was created with integrity when the data set was open for update.

8 2C2 Equate Symbol: DWWCVRN_InvalidStatusFlags23
Meaning: None of the following flags of the status_flags parameter were set ON:
  • SHARP ONLINE BACKUP WITHOUT TIEUP LOG RECORD
  • FUZZY ONLINE BACKUP WITHOUT TIEUP LOG RECORD
However, one or more of the following parameters were specified:
  • number_of_ddnames
  • ddname_and_APPLID
  • log_stream_name
  • data_set_type
  • CI_size
  • maximum_record_length
  • key_position
  • key_length

Action: Specify the appropriate flag in the status_flags parameter, then retry the request if the backup was created with integrity when the data set was open for update but a corresponding tieup log record was not written.

8 2C4 Equate Symbol: DWWCVRN_InvalidBWOorRecoveryTimestamp

Meaning: Zeroes were specified for either the BWO_timestamp parameter or both the recovery_timestamp_local and recovery_timestamp_GMT parameters. A zero value for the BWO_timestamp parameter is not allowed. A zero value can be specified for either the recovery_timestamp_local or recovery_timestamp_GMT parameter, but not both. CICS VR translates the given recovery timestamp into the format of the recovery timestamp that had a value of zeroes.

Action: Either specify an appropriate timestamp for the BWO_timestamp parameter, or one of the recovery timestamp parameters, then retry the request.

8 2C8 Equate Symbol: DWWCVRN_InvalidLogStreamName

Meaning: An invalid log stream name is specified in the log_stream_name parameter.

Action: Change the log_stream_name parameter, using the required syntax, and retry the request.

8 2CC Equate Symbol: DWWCVRN_InvalidDataSetType

Meaning: The specified value for the data_set_type parameter is incorrect. It must either be K, E, R, or V.

Action: Specify an acceptable value for the data_set_type parameter and retry the request.

8 2D0 Equate Symbol: DWWCVRN_ProcessBWOError
Meaning: The PROCESS BWO bit of the operation_flags parameter was set on. However, none of the following flags of the status_flags parameter were 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
The PROCESS BWO bit only applies to online backups.

Action: If this is an online backup, specify the appropriate flag in the status_flags parameter, then retry the request.

8 2D4 Equate Symbol: DWWCVRN_BWOAndRecoveryTimestampError

Meaning: A value is specified for both the BWO_timestamp parameter and the recovery_timestamp_local and recovery_timestamp_GMT parameters. The BWO_timestamp field is mutually exclusive with the recovery_timestamp_local and recovery_timestamp_GMT parameters.

Action: Only specify a value for either the BWO_timestamp field or the recovery_timestamp_local and recovery_timestamp_GMT parameters, then retry the request.

Table 2. CICS VR server address space return and reason codes
Return Code Hex Reason Code Hex Equate Symbol, Meaning, and Action
8 71845448 Equate Symbol: DWWCVRN_InvalidBackupDateTimeLocal

Meaning: An invalid value is specified for the backup_date_local or backup_time_local parameter.

Action: Specify a valid value for the backup_date_local and backup_time_local parameters and retry the request.

8 7184544A Equate Symbol: DWWCVRN_InvalidBackupDateTimeGMT

Meaning: An invalid value is specified for the backup_date_GMT or backup_time_GMT parameter.

Action: Specify a valid value for the backup_date_GMT and backup_time_GMT parameters and retry the request.

8 7184544C Equate Symbol: DWWCVRN_InvalidBackupDateTime

Meaning: Inconsistent values are specified for the backup_date_local, backup_time_local, backup_date_GMT or backup_time_GMT parameters. For example, the difference between the specified GMT and local dates might be impossible.

Action: Specify valid values for the backup_date_local, backup_time_local, backup_date_GMT and backup_time_GMT parameters and retry the request.

8 7184544E Equate Symbol: DWWCVRN_InvalidOperationFlags

Meaning: An invalid value is specified for the operation_flags parameter.

Action: Specify a valid value for the operation_flags parameter and retry the request.

8 7184544F Equate Symbol: DWWCVRN_InvalidStatusFlags33

Meaning: An invalid value is specified for the status_flags parameter.

Action: Specify a valid value for the status_flags parameter and retry the request.

8 71845450 Equate Symbol: DWWCVRN_InvalidBWOTimestamp

Meaning: An invalid or unsupported value is specified for the BWO_timestamp parameter.

Action: Specify a valid value for the BWO_timestamp parameter and retry the request.

8 71845454 Equate Symbol: DWWCVRN_InvalidRecoveryTimestampLocal

Meaning: An invalid value is specified for the recovery_timestamp_local parameter.

Action: Specify a valid value for the recovery_timestamp_local parameter and retry the request.

8 71845455 Equate Symbol: DWWCVRN_InvalidRecoveryTimestampGMT

Meaning: An invalid value is specified for the recovery_timestamp_GMT parameter.

Action: Specify a valid value for the recovery_timestamp_GMT parameter and retry the request.

8 71845456 Equate Symbol: DWWCVRN_InvalidRecoveryTimestamps

Meaning: Inconsistent values are specified for the recovery_timestamp_local and recovery_timestamp_GMT parameters. For example, the difference between the specified GMT and local recovery timestamps might be impossible.

Action: Specify valid values for the recovery_timestamp_local and recovery_timestamp_GMT parameters and retry the request.

8 7184545C Equate Symbol: DWWCVRN_InvalidDeviceType

Meaning: An invalid value is specified for the device_type parameter.

Action: Specify a valid value for the device_type parameter and retry the request.

8 71845460 Equate Symbol: DWWCVRN_InvalidNumDDnames

Meaning: An invalid value is specified for the number_of_ddnames parameter.

Action: Specify a valid value for the number_of_ddnames parameter and retry the request.

8 71845461 Equate Symbol: DWWCVRN_InvalidDDname

Meaning: An invalid ddname is specified for the ddname_and_APPLID subparameter of the ddnames_list parameter.

Action: Specify valid ddnames for the ddname_and_APPLID subparameter and retry the request.

8 71845462 Equate Symbol: DWWCVRN_InvalidAPPLID

Meaning: An invalid APPLID is specified for the ddname_and_APPLID subparameter of the ddnames_list parameter.

Action: Specify valid APPLIDs for the ddname_and_APPLID subparameter and retry the request.

8 71845469 Equate Symbol: DWWCVRN_InvalidCISize

Meaning: An invalid value is specified for the CI_size parameter.

Action: Specify a valid value for the CI_size parameter and retry the request.

8 7184546A Equate Symbol: DWWCVRN_InvalidMaxRecLength

Meaning: An invalid value is specified for the maximum_record_length parameter.

Action: Specify a valid value for the maximum_record_length parameter and retry the request.

8 7184546B Equate Symbol: DWWCVRN_InvalidKeyPosition

Meaning: An invalid value is specified for the key_position parameter.

Action: Specify a valid value for the key_position parameter and retry the request.

8 7184546C Equate Symbol: DWWCVRN_InvalidKeyLength

Meaning: An invalid value is specified for the key_length parameter.

Action: Specify a valid value for the key_length parameter and retry the request.

8 71845471 Equate Symbol: DWWCVRN_IncorrectOperationFlags

Meaning: An invalid combination of flags are specified in the operation_flags parameter.

Action: Specify a valid combination of flags in the operation_flags parameter and retry the request.

8 71845472 Equate Symbol: DWWCVRN_IncorrectStatusFlags

Meaning: An unsupported flag is specified in the status_flags parameter.

Action: Specify a valid value for the status_flags parameter and retry the request.

8 71845477 Equate Symbol: DWWCVRN_IncorrectKeyValues
Meaning: One of the following error conditions was detected:
  • The data set is a KSDS and a valid value was not specified for either the key_position or key_length parameter.
  • The data set is an ESDS, RRDS, or VRRDS and a non-zero value has been specified for either the key_position or key_length parameter.

Action: Specify appropriate values for the key_position and key_length parameters, then retry the request.

8 7184547A Equate Symbol: DWWCVRN_RCDSError
Meaning: CICS VR received a request to either:
  • Register a backup for a data set that had a backup with an identical name already registered in the CICS VR RCDS.
  • Deregister a backup from the RCDS.
However, CICS VR detected an error in the RCDS entry of the registered backup.

Action: Capture any CICS VR messages that were written to the console and contact the IBM Support Center.

8 7184547C Equate Symbol: DWWCVRN_DuplicateBackupFailure

Meaning: CICS VR received a request to register a backup for a data set that had a backup with an identical name already registered in the CICS VR RCDS. However, the backup date and time of the registered backup is more recent than the backup date and time specified in the request. CICS VR could not replace the existing backup entry with the backup information specified in the latest request.

CICS VR can only register a backup with an identical name if the backup creation date and time in the request is more recent than the creation date and time of the registered backup, the existing entry is replaced.

This problem might be the result of submitting multiple registration requests in asynchronous mode.

Action: CICS VR cannot maintain multiple entries in the RCDS for backups created for the same data set with identical backup names.

If you want to register an earlier backup in the RCDS with the same name of an existing registered backup for the same data set, delete the existing backup entry, then retry the request.

4 7184547D

Equate Symbol: DWWCVRN_AllocRegisterFailure

Meaning: The PREALLOCATION REQUIRED bit of the operation_flags parameter was set ON. However, CICS VR has detected an error, the data set has not been found in the ICF catalog, the data set is not a VSAM data set, the data set is not a cluster, SHOWCAT system service failure, or CATALOG system service failure, while attempting to extract information from the ICF catalog concerning allocation attributes of the data set. The request processing has been completed successfully, but allocation attributes of the data set has not been registered in the RCDS. Preallocate the target data set manually before restoring the data set.

Action: Set the PREALLOCATION REQUIRED bit of the operation_flags parameter OFF, if it is suitable, or ensure that the data set has been catalogued in the ICF catalog and retry the request, if required.

4 718454E0 Equate Symbol: DWWCVRN_SelBkRegSphereNotRegistered

Meaning: CICS VR has received a request to register a backup for a data set that is not registered in the RCDS although selective backup registration is in effect. When selective backup registration is in effect, CICS VR registers only backups, for which data sets are already registered.

Action: If you want to register the backup in the RCDS, register the appropriate data set or deactivate the selective backup registration function, then retry the request.

8 71313E03

Meaning: CICS VR received a request from a user who is not authorized to perform file copy notification. The request is rejected.

Action: Contact the security administrator to request the correct access to perform file copy notification.

14 71425400 Equate Symbol: DWWCVRN_NotifyServiceNotAvailable

Meaning: The CICS VR file copy notification service is not available.

Action: The current version of CICS VR does not support the CICS VR file copy notification service. Contact IBM support for assistance

14 EE01 Equate Symbol: DWWCVRN_ServerNotAvailable

Meaning: The CICS VR server is not available.

Action: Activate the CICS VR address space server on the system and retry the request.

Examples

The following diagram illustrates an example portion of a program that calls the CICS VR file copy notification service to notify CICS VR about a backup created for a VSAM data set.
Figure 2. Example program that calls the file copy notification service
         SAVE  (14,12)             SAVE REGISTERS
         BASR  RBASE,0             SET BASE REGISTER
         USING *,RBASE             ESTABLISH ADDRESSABILITY
         LR    R10,R13             CHAIN SAVE AREAS
         LA    R13,SAVEAREA
         ST    R10,4(,R13)
         ST    R13,8(,R10)
*
         LOAD EP=DWWCVRN           LOAD FILE COPY NOTIFICATION SERVICE
         LR R15,R0
         CALL (15),(RETCODE,                                           X
               RSNCODE,                                                X
               PROBDET,                                                X
               PRODUCT,                                                X
               TYPE,                                                   X
               DATASET,                                                X
               BACKUP,                                                 X
               DATELOC,                                                X
               TIMELOC,                                                X
               DATEGMT,                                                X
               TIMEGMT,                                                X
               OPER,                                                   X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               OPTLEN,                                                 X
               OPTDATA,                                                X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,                                                       X
               ,)
         LTR  R15,R15               TEST RETURN CODE
         BE   EXIT                  IF SUCCESSFUL CALL EXIT
         L    R15,RSNCODE           LOAD REASON CODE IF NOT SUCCESS
*
EXIT     EQU   *
         L     R13,SAVEAREA+4      GET SAVE AREA ADDRESS
         RETURN (14,12),RC=(15)    RESTORE REGISTERS AND RETURN
SAVEAREA DC    18F'0'              SAVE AREA
*
*
RETCODE  DS    F'0'                RETURN CODE
RSNCODE  DS    F'0'                REASON CODE
PROBDET  DS    2F'0'               PROBLEM DETERMINATION AREA
PRODUCT  DC    C'TST'              BACKUP PRODUCT 
TYPE     DC    C'LC'               BACKUP TYPE
DATASET  DC    CL44'TEST.VSAM.BASE.CLUSTER            '  DATA SET NAME
BACKUP   DC    CL44'COPY.TEST.VSAM.BASE.CLUSTER       '  BACKUP NAME
DATELOC  DC    X'00000000'         BACKUP DATE LOCAL
TIMELOC  DC    X'00000000'         BACKUP TIME LOCAL
DATEGMT  DC    X'00000000'         BACKUP DATE GMT
TIMEGMT  DC    X'00000000'         BACKUP TIME GMT
*
OPER     DC    X'0080'             OPERATION FLAGS
STATUS   DC    X'0000'             STATUS FLAGS
BWO      DC    X'0000000000000000' BWO TIMESTAMP
RECLOCAL DC    X'0000000000000000' RECOVERY TIMESTAMP LOCAL
RECGMT   DC    X'0000000000000000' RECOVERY TIMESTAMP GMT
OPTLEN   DC    F'64'               OPTIONAL INFORMATION LENGTH
OPTDATA  DC    CL64'TEST'          OPTIONAL INFORMATION VALUE
NUMVOL   DC    F'0'                NUMBER OF VOLUMES
VOLAREA  DC    C'      '           VOLUME LIST
DEVICE   DC    CL8'00000000'       DEVICE TYPE
SEQNUM   DC    H'0'                SEQUENCE NUMBER
NUMDDN   DC    F'0'                NUMBER OF DDNAMES
DDNAPPL  DC    C'      '           DDNAME AND CICS APPLID PAIR
LOGSTRM  DC    CL26'                          '      LOG STREAM NAME
DSTYPE   DC    C' '                DATA SET TYPE
CISIZE   DC    F'0'                CONTROL INTERVAL SIZE
MAXREC   DC    F'0'                MAXIMUM RECORD LENGTH
KEYPOS   DC    F'0'                KEY POSITION
KEYLEN   DC    F'0'                KEY LENGTH
The values passed to the file copy notification service in the example shown in Figure 2 are explained in Table 3.
Table 3. Values passed to the file copy notification service
Program variable name Corresponding file copy notification service variable name Meaning
RETCODE return_code Output area for return code issued by DWWCVRN.
RSNCODE reason_code Output area for reason code issued by DWWCVRN.
PROBDET prob_det Output area for problem determination information issued by DWWCVRN.
PRODUCT backup_product 3 character identifier of the product used to create the backup. In this example, 'TST' is used to represent a backup product named TEST.
TYPE backup_type 2 character identifier of the type of backup created. In this example, 'LC' is used to represent a Logical Copy.
DATASET dataset_name Name of the data set for which the backup was created.
BACKUP backup_name Name of the backup data set created.
DATELOC backup_date_local Date the backup was created in local format. In this scenario, CICS VR is notified immediately after creation of the backup. Therefore, all zeros are specified. CICS VR records the system date in local format at the time of this call to DWWCVRN as the local backup date.
TIMELOC backup_time_local Time the backup was created in local format. In this scenario, CICS VR is notified immediately after creation of the backup. Therefore, all zeros are specified. CICS VR records the system time in local format at the time of this call to DWWCVRN as the local backup time.
DATEGMT backup_date_GMT Date the backup was created in GMT format. In this scenario, CICS VR is notified immediately after creation of the backup. Therefore, all zeros are specified. CICS VR records the system date in GMT format at the time of this call to DWWCVRN as the GMT backup date.
DATELOC backup_time_GMT Time the backup was created in GMT format. In this scenario, CICS VR is notified immediately after creation of the backup. Therefore, all zeros are specified. CICS VR records the system time in GMT format at the time of this call to DWWCVRN as the GMT backup time.
OPER operation_flags Indicates that the file copy notification service is running in synchronous processing mode.
omitted status_flags In this scenario, the backup was created while the data set was offline. Therefore, no status flags are set.
omitted BWO_timestamp In this scenario, the backup was created while the data set was offline. Therefore, the BWO_timestamp parameter is omitted.
omitted recovery_timestamp_local In this scenario, the backup was created while the data set was offline. Therefore, CICS VR uses information from the RCDS to determine the forward recovery start time. The recovery_timestamp_local parameter is omitted.
omitted recovery_timestamp_GMT In this scenario, the backup was created while the data set was offline. Therefore, CICS VR uses information from the RCDS to determine the forward recovery start time. The recovery_timestamp_GMT parameter is omitted.
OPTLEN optional_information_length In this scenario, descriptive information is added for the backup. This field specifies the length of the optional information using the IBM recommended value of 64 byte multiples.
OPTDATA optional_information_area In this scenario, descriptive information 'TEST' is added for the backup. This field contains the optional information.
omitted number_of_volumes In this scenario, the backup is cataloged, therefore this field is omitted.
omitted volume_list_area In this scenario, the backup is cataloged, therefore this field is omitted.
omitted device_type In this scenario, the backup is cataloged, therefore this field is omitted.
omitted sequence_number In this scenario, the backup is cataloged, therefore this field is omitted.
omitted number_of_ddnames In this scenario, the backup was created while the data set was offline, therefore the number_of_ddnames parameter is omitted.
omitted ddname_and_APPLID In this scenario, the backup was created while the data set was offline, therefore the ddname_and_APPLID parameter is omitted.
omitted log_stream_name In this scenario, the backup was created while the data set was offline, therefore the log_stream_name parameter is omitted.
omitted data_set_type In this scenario, the backup was created while the data set was offline, therefore the data_set_type parameter is omitted.
omitted CI_size In this scenario, the backup was created while the data set was offline, therefore the CI_size parameter is omitted.
omitted maximum_record_length In this scenario, the backup was created while the data set was offline, therefore the maximum_record_length parameter is omitted.
omitted key_position In this scenario, the backup was created while the data set was offline, therefore the key_position parameter is omitted.
omitted key_length In this scenario, the backup was created while the data set was offline, therefore the key_length parameter is omitted.