ABARS exits - syncsort_cobol_migration_manager - syncsort_clone_center - syncsort_space_recovery_system - syncsort_scc_monitor - syncsort_simulate_2000 - syncsort_allocation_control_center - Latest

Changing the EXTABARS

Rules in Effect

It is not necessary to stop and restart the ABARS exits via the DFSMShsm commands to change the EXTABARS rules. All that is necessary is to refresh the rules.

Member EXT0009 in the EXTABARS load library is link-edited with aliases for all of the ABARS exits. Member EXT0009 will be entered for each exit and will transfer control to the appropriate EXTABARS routine.

This chapter contains descriptions of the EASY/Exit environments that receive control during DFSMShsm ABARS processing.

Environments

• ABACKUP - Backup Error (BE) Environment

  The Backup Error (BE) environment is entered during ABACKUP when an error is encountered while attempting to back up a file. The variable &ERROR_TYPE is set to indicate the type of error (I/O error, DFSMShsm serialization error, and so on). The EXTABARS rules can decide whether to bypass the backup of the dataset in error or not. If the dataset is skipped (not included in the backup), the ABACKUP job continues. If the EXTABARS rules indicate not to skip the dataset (it must be included in the backup), then the ABACKUP fails.

  The Backup Error environment can be used to allow an ABACKUP to continue even though some datasets were not able to be backed up. The EXTABARS rules for the BE environment establish policies for what types of ABACKUP errors are acceptable for various datasets. If an in-error dataset is skipped, it may be desirable to write an SMF record or a message to the storage administrator indicating which dataset was not included and why.

  For more information, examine ABACKUP - Backup Error (BE) Environment.

• ARECOVER - Conflict Resolution (CR) Environment

  The Conflict Resolution (CR) environment is entered during ARECOVER processing when a dataset to be restored has the same name as a dataset which already exists on the system. The EXTABARS rules executed in this environment determine what action should be taken to resolve the conflict. Possible actions include failing the ARECOVER (default), renaming the dataset to be restored, or taking other actions specified by the variable &CR_ACTION.

  Because the EXTABARS rules allow per-dataset processing, the Conflict Resolution environment provides more flexibility than the DSCONFLICT REPLACE or RENAMESOURCE operands of the ARECOVER command. Note: the Conflict Resolution environment can be used to rename datasets being restored from the backup; it cannot be used to rename already-existing datasets.

  For more information, examine ARECOVER - Conflict Resolution (CR) Environment.

• ABACKUP - Expiration Date (ED) Environment

  The Expiration Date environment receives control when the ABACKUP control dataset (the 'C' file) is about to be created. It allows the expiration date of the ABACKUP output files (the 'C', 'D', 'I', and 'O' files) to be changed from the default to a desired value, or set to permanent retention.

  This environment can be used to set special expiration-date values for tape management (for example, catalog control or foreign tape), or to set differing expiration dates for files of different aggregates. Note: the Expiration Date environment is effective only during ABACKUP processing; to bypass tape management during ARECOVER, use the BTP option of Application Backup Center.

  For more information, examine ABACKUP - Expiration Date (ED) Environment.

• ABACKUP - Migration Level 2 (M2) Environment

  The Migration Level 2 environment receives control when a dataset that resides on an ML2 volume must be backed up. Because ML2 backups can be time consuming, this environment can be used to include only the most important datasets on ML2 and bypass others. This provides finer control than the ABACKUP PROCESSONLY option.

  For more information, examine ABACKUP - Migration Level 2 (M2) Environment.

• ARECOVER - Dataset Skip (SK) Environment

  The Dataset Skip environment receives control during ARECOVER for a dataset, before conflict resolution is performed. It can be used to bypass recovery for any dataset, allowing selective recovery of individual datasets from an ABACKUP, regardless of where they resided at backup time (primary DASD, ML1, or ML2) or which selection list they were in (INCLUDE, ACCOMPANY, or ALLOCATE).

  For more information, examine ARECOVER - Dataset Skip (SK) Environment.

Variables for All EXTABARS Environments

The following variables are available to all EXTABARS environments.

Table 10-1. Variables for all ABARS Environments

Environment Description

The Backup Error (BE) environment is entered during ABACKUP when an error is encountered while attempting to back up a file. The variable &ERROR_TYPE is set to indicate the type of error (I/O error, DFSMShsm serialization error, and so on). The EXTABARS rules can decide whether to bypass the backup of the dataset in error or not. If the dataset is skipped (not included in the backup), then the ABACKUP job continues. If the EXTABARS rules indicate not to skip the dataset (it must be included in the backup), then the ABACKUP fails.

The Backup Error environment can be used to allow an ABACKUP to continue even though some datasets were not able to be backed up. The EXTABARS rules for the BE environment establish policies for what types of ABACKUP errors are acceptable for various datasets. If the EXTABARS rules allow a dataset in error to be skipped, it may be desirable to write an SMF record or a message to the storage administrator at the same time, indicating which dataset was not included in the backup and why.

The following variables are available for use by the EXTABARS rules in the Backup Error environment. The default for the variable &BYPASS_DATASET is NO; i.e., the ABACKUP fails if a dataset cannot be backed up.

Table 10-2. Variables for the ARCBEEXT Environment

Examples for the Backup Error Environment

Example 1 - Ignore Uncataloged Datasets in the Selection Lists

Normally, ABACKUP will fail if a fully-qualified dataset name is specified in an ABARS selection dataset and the dataset cannot be found at backup time.

Datasets specified in the selection lists might not be found if, for example, they were deleted at the end of an application cycle, or if the ABACKUP was run before the datasets were created. The example below allows the ABACKUP to continue if such a selection-list dataset is not found; a message indicating the dataset was skipped is sent to the storage administrator using a message number reserved for ABARS exit processing.

DEFRULE BERULE
CONTINUE(NEXTRULE) IF &ENV = ARCBEEXT
&ERROR_TYPE = UNCAT
THEN SET &BYPASS_DATASET = YES WRITEMSG(UNCATMSG)

DEFMSG UNCATMSG
'ARC9201E UNCATALOGUED DATASET &DSNAME FOUND DURING
ABACKUP OF &AGGREGATE ON &CURDATE &CURTIME' USERID(STGADMIN)
      

Another common cause of ABACKUP errors is datasets that are already in use by DFSMShsm for primary space management, migration, or other processing.

DFSMShsm enqueues on the dataset using a QNAME of ARCDSN and an RNAME of the dataset name. ABARS also attempts to enqueue datasets using the same QNAME and RNAME. If the enqueue cannot be obtained, the backup fails.

The example below allows ABACKUP to continue if a selection-list dataset is in use by DFSMShsm and cannot be backed up. A message indicating the dataset was skipped is sent to the storage administrator.

IF &ENV = ARCBEEXT &ERROR_TYPE = ENQHSM
THEN SET &BYPASS_DATASET = YES WRITEMSG(HSMENQD)

DEFMSG HSMENQD
'ARC9202E DATASET &DSNAME NOT BACKED UP IN &AGGREGATE - IN USE BY HSM' USERID(STGADMIN)
      

ARECOVER - Conflict Resolution (CR) Environment

The Conflict Resolution (CR) environment is entered during ARECOVER processing when a dataset to be restored has the same name as a dataset which already exists on the system. The EXTABARS rules that execute in the Conflict Resolution environment determine what action should be taken to resolve the conflict. The ARECOVER may be failed (the default), the dataset to be restored may be renamed, or other actions specified by the variable &CR_ACTION may be taken.

Because the EXTABARS rules allow the ABARS administrator to specify different processing for each dataset, the Conflict Resolution environment allows more flexibility than the DSCONFLICT REPLACE operand of the ARECOVER command. The EXTABARS rules are also more flexible than the RENAMESOURCE operand of DSCONFLICT, which allows replacing only the high-level qualifier of conflicting datasets. The Conflict Resolution environment can be used to rename datasets being restored from the backup; it cannot be used to rename already-existing datasets.

When the CR Environment is Entered

The Conflict Resolution environment is entered for datasets in any of the ABARS selection lists (INCLUDE, ACCOMPANY, or ALLOCATE). Datasets in the ALLOCATE list may not overlay existing datasets; i.e., CR_ACTION cannot be set to REPLACE. However, datasets in the ALLOCATE list may be renamed or bypassed for restore (CR_ACTION set to RENAME or BYPASS).

Processing

If a dataset naming conflict is not resolved by the EXTABARS rules, an entry for the dataset is created in the Conflict Resolution dataset that is produced as part of the ARECOVER. That dataset must be edited after the ARECOVER completes to specify the action for each dataset when ARECOVER is rerun.

ABARS processing limits the number of datasets that may be renamed in the Conflict Resolution environment to 256. If more than 256 datasets encounter naming conflicts and must be renamed, the ARECOVER must be executed again to rename the remaining datasets. There is no limit on the number of conflicting datasets that may be skipped or replaced during an ARECOVER.

If the dataset being restored is a migrated non-VSAM dataset and the conflict resolution action is RENAME, only the high-level qualifier of the migrated dataset is changed; other qualifiers in the new name are ignored. Migrated non-VSAM datasets may only have their high-level qualifiers changed. Migrated VSAM datasets may not be renamed. If RENAME is specified for CR_ACTION for migrated VSAM, the action is ignored and NONE is used instead.

Variables for the Conflict Resolution Environment

The following variables are available for use by the EXTABARS rules in the Conflict Resolution environment. The value for &NEWDSN is ignored unless &CR_ACTION is set to RENAME.

Table 10-3. Variables for the ARCCREXT Environment

Examples for the Conflict Resolution Environment

Often, datasets may belong to more than one application and may be backed up in several aggregates. During ARECOVER of an important application, conflicts may arise because datasets already exist from earlier aggregate recoveries.

In this example, datasets whose names begin with the characters PAY1 are not restored if they already exist, unless they also contain a second qualifier of ACCT23, in which case they overlay the existing dataset.

DEFRULE CRRULE
CONTINUE(NEXTRULE) IF &ENV = ARCCREXT
&HLQ = PAY1
THEN DO
  IF &QUAL2 = 'ACCT23' THEN SET &CR_ACTION = REPLACE
  ELSE SET &CR_ACTION = BYPASS
END
      

Example 2 - Rename Datasets During ARECOVER

During disaster recovery testing, it may be necessary to rename datasets being recovered so as not to disturb existing production datasets. While the RENAMESOURCE and RENAMETARGET operands of the ARECOVER DSCONFLICT parameter can provide new high-level qualifiers, the EXTABARS rules offer more detailed control. In this example, several fully qualified datasets are renamed, a new high-level qualifier is provided for migrated datasets, and migrated VSAM datasets are bypassed (they cannot be renamed).

DEFRULE RENAMRULE

IF &ENV NE ARCCREXT THEN CONTINUE SCANNING AT NEXTRULE

IF &DSNAME = AB17.MAY98.ACCT5.MONTH.X34922
THEN SET &NEWDSN = AB17.TEST.MAY98.ACCT5.MONTH.X34922
     SET &CR_ACTION = RENAME

IF &DSNAME = PROD.DATA.BASE1
THEN SET &NEWNAME = PROD.DATA.BASETEST
     SET &CR_ACTION = RENAME

IF &DSNAME = PROD.* &MIGRATED = YES &VSAM = NO
THEN SET &NEWNAME = TEST
     SET &CR_ACTION = RENAME

IF &MIGRATED = YES &VSAM = YES
THEN SET &CR_ACTION = BYPASS
      

Environment Description

The Expiration Date environment receives control when the ABACKUP control dataset (the 'C' file) is about to be created. It allows the expiration date of all the ABACKUP output files (the 'C', 'D', 'I', and 'O' files) to be changed from the default to another value or to permanent retention. This can be useful to set special expiration values for tape management systems (for example, 99000 for catalog control or 98000 for foreign tape).

The Expiration Date environment can be used to set different expiration dates for different aggregates. Note that it is effective only during ABACKUP processing. To bypass the tape management system during ARECOVER, use the BTP option of Application Backup Center.

The following variables are available for use by the EXTABARS rules in the Expiration Date environment. Normally, the variable &ABACKUP_EXPDT will contain 1999.365 (permanent retention) on entry. Prior to DFSMS version 1.1, ABACKUP_EXPDT could be zero and a retention period placed in ABACKUP_RETPD on entry. The EXTABARS rules may set either an expiration date or a retention period; if a retention period is specified, it overrides the expiration date.

Table 10-4. Variables for the ARCEDEXT Environment

Examples for the Expiration Date Environment

Example 1 - Set Expiration Date of ABACKUP Tapes

In this example, backups for production aggregates (whose names begin with PROD) are given an expiration date that allows them to remain known to the tape management system as long as they remain catalogued. Test aggregates (beginning with TEST) are retained for ten days.

DEFRULE EDRULE
CONTINUE(NEXTRULE) IF &AGGREGATE = PROD*
THEN SET &ABACKUP_EXPDT = 1999.000
IF &AGGREGATE = TEST*
THEN SET &ABACKUP_RETPD = 10
      

Environment Description

The Migration Level 2 environment receives control when a dataset which resides on an ML2 volume must be backed up. Since backups of datasets on ML2 tapes can be time consuming, this environment can be used to include only the most important ML2 datasets and bypass others that may not be needed at recovery time. This provides more flexibility than the ABACKUP PROCESSONLY option, which only allows inclusion or exclusion of all datasets on a particular migration level.

Examples for the Migration Level 2 Environment

The following variables are available to the EXTABARS rules in the Migration Level 2 environment. The default for &BYPASS_DATASET is NO; i.e., the dataset is included in the ABACKUP.

Table 10-5. Variables for the ARCM2EXT Environment

Example 1 - Bypass Backup of Specified ML2 Datasets

In this example, backups for most datasets migrated to ML2 are bypassed for some aggregates. Certain critical datasets are included in the ABACKUP even though they reside on ML2 volumes.

DEFRULE ML2RULE
CONTINUE(NEXTRULE)
IF &ENV = ARCM2EXT &AGGREGATE = PAY*
&DSNAME NE PAY.IMPORTANT.*
THEN SET &BYPASS_DATASET = YES
      

Environment Description

The Dataset Skip environment receives control during ARECOVER processing for a dataset before conflict resolution is performed. It can be used to bypass recovery for any dataset, allowing selective recovery of individual datasets from an ABACKUP regardless of where they resided at backup time (primary DASD, ML1, or ML2) and regardless of which selection list they were in (INCLUDE, ACCOMPANY, or ALLOCATE).

The following variables are available for use by the EXTABARS rules in the Dataset Skip environment. The default for &BYPASS_DATASET is NO; i.e., the dataset is included in the ARECOVER.

Table 10-6. Variables for the ARCSKEXT Environment

Examples for the Dataset Skip Environment

Example 1 - Recover Overlapping Datasets from Selected Aggregates

In this example, many datasets with the same name may have been included in the ABACKUPs of multiple aggregates. Datasets beginning with PAY are to be recovered only from the PAYROLL aggregate, while datasets with a second-level qualifier of ACCT98 are to be recovered only from the accounts-receivable aggregate.

DEFRULE DUPRULE
CONTINUE
IF &ENV NE ARCSKEXT THEN CONTINUE SCANNING AT NEXTRULE

IF &AGGREGATE NE PAYROLL &DSNAME = PAY*
THEN SET &BYPASS_DATASET = YES

IF &AGGREGATE NE ACCTR* &QUAL2 = ACCT98
THEN SET &BYPASS_DATASET = YES
      

Normally, ABARS will attempt to restore all datasets contained in an aggregate. Using Application Backup Center or by setting up a DFSMSdss restore job, individual datasets or groups of datasets may be restored if they resided on primary DASD at ABACKUP time. Using the EXTABARS rules in the Dataset Skip exit, selected datasets can be restored during ARECOVER regardless of where they resided at backup time.

In this example, datasets with a high-level qualifier of PROD are restored from the OFF-SITE aggregate; no other datasets backed up in the aggregate are restored. Only the OFF-SITE aggregate is affected.

DEFRULE SINGLE
IF &ENV EQ ARCSKEXT &AGGREGATE = OFFSITE &HLQ NE PROD
THEN SET &BYPASS_DATASET = YES