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

Prevent deletion of datasets with second-level qualifier PROD or datasets that currently or previously resided on primary volumes beginning with SYS33. When such a dataset is a deletion candidate, issue a warning message to the storage administrator.

DEFRULE IMPORTANTDS IF &ENV = ARCADEXT
&QUAL2 = 'PROD' OR &VOLSER = SYS33*
THEN SET &BYPASS_DELETE = YES WRITEMSG(WARNMSG)

DEFMSG WARNMSG
'WARNING! DATASET &DSNAME FOUND ELIGIBLE FOR DELETION BY HSM &ENVS PROCESSING. ORIGINAL VOLUME=&VOLSER' USERID(STGADMIN)
          

Prevent DBA and DBU deletions for volumes beginning with PRODX on Saturday or Sunday.

DEFRULE NODEL
IF &ENV = ARCADEXT
&CURDAY = (SATURDAY,SUNDAY) &VOLSER = PRODX*
THEN SET &BYPASS_DELETE = YES
          

The ARCBDEXT environment is entered during DFSMShsm volume backup processing for each dataset that DFSMShsm determines should be backed up. It applies to both SMS-managed and non-SMS datasets on primary (L0) and ML1 volumes.

EXTHSM variables indicate candidate status for Backup-While-Open (BWO), dataset size, volume, and more. Use EXTHSM to bypass backups, prevent software compaction, manage serialization/enqueue behaviour, or adjust flags when bypassing backups.

To receive control:

• Activate the ARCBDEXT exit.
• Ensure EXTHSM load modules are in a linklist library or STEPLIB accessible to DFSMShsm.
• Activate exit: SETSYS EXITON(BD).

Entered for each dataset processed by volume backup; volume may be primary (L0) or migration (L1). It is entered after DFSMShsm determines the dataset is eligible for backup (i.e., this environment is later than ARCSAEXT).

Example: Prevent backup of datasets with second-level qualifier SYSX* on primary volumes beginning with WRK9* and larger than 500 MB. Turn off DS1IND02 so they are not included in future incremental backups.

DEFRULE NOBACKUP IF &ENV = ARCBDEXT
&QUAL2 = 'SYSX*' &VOLSER = WRK9* &VOL_TYPE = L0
&SIZE-K-ALL GT 500000
THEN SET &BYPASS_BACKUP = YES
     SET &RESET_UPDFLAG = YES
          

Example: Require serialization for datasets beginning with PRODX.USERDATA (retry preferred), and ignore enqueue attempts for datasets beginning with PRODY.READONLY.

DEFRULE SOMEENQ IF &ENV = ARCBDEXT
IF &DSNAME = 'PRODX.USERDATA.*'
THEN SET &INUSE = RETRY_PREFERRED

IF &ENV = ARCBDEXT
IF &DSNAME = 'PRODY.READONLY.*'
THEN SET &INUSE = IGNORE
          

Example: Datasets under PRODZ.SPECIAL.DATA.* — retry required; datasets under PROD1.ANYDATA.* — no retry (NORETRY).

DEFRULE MUSTENQ IF &ENV = ARCBDEXT
IF &DSNAME = 'PRODZ.SPECIAL.DATA.*'
THEN SET &INUSE = RETRY_REQUIRED

IF &ENV = ARCBDEXT
IF &DSNAME = 'PROD1.ANYDATA.*'
THEN SET &INUSE = NORETRY
          

The ARCCBEXT environment is entered after DFSMShsm control dataset (MCDS, BCDS, OCDS, and journal) backup completes, whether successful or not. Use this environment to alert administrators, write records, submit jobs (for tape copy), or take automatic actions based on backup success/failure.

To receive control: activate the ARCCBEXT exit and ensure EXTHSM load modules are accessible; use SETSYS EXITON(CB).

Table 9-4. Variables for the ARCCBEXT Environment

Notify storage administrator when any of the control dataset backups failed.

DEFRULE CDSERR
IF &MCDS_ERROR = YES OR &BCDS_ERROR = YES OR &OCDS_ERROR = YES OR &JRNL_ERROR = YES
THEN ISSUE WRITEMSG(WARNADM)

DEFMSG WARNADM
'WARNING: HSM CDS BACKUP FAILED' USER(STGADM)
          

Write a record to a log file allocated to the DIF started task (DDNAME CDSFILE) for use with the EXTHSM CDS Backup Monitor ISPF application.

DEFRULE CDSDB
IF &ENV = ARCCBEXT
THEN ISSUE WRITEREC(CDSREC)
DEFREC CDSREC
INIT(BLANKS) DDNAME(CDSFILE) LENGTH(900)
FIELD &CURDATE FIELD &CURTIME FIELD &BKUP_TYPE FIELD &DATAMOVER FIELD &JRNL_ERROR FIELD &MCDS_ERROR FIELD &BCDS_ERROR FIELD &OCDS_ERROR FIELD &JRNL_BKDSN FIELD &MCDS_BKDSN FIELD &BCDS_BKDSN FIELD &OCDS_BKDSN FIELD &JRNL_BKVOLN FIELD &MCDS_BKVOLN FIELD &BCDS_BKVOLN FIELD &OCDS_BKVOLN FIELD &JRNL_BKVOLS FIELD &MCDS_BKVOLS FIELD &BCDS_BKVOLS FIELD &OCDS_BKVOLS
          

Submit a job (via REXX exec) that imports CDS backups and runs IDCAMS EXAMINE to validate structural integrity. If any backup failed, issue an operator message instead.

DEFRULE CDSCHK
IF &ENV = ARCCBEXT &DATAMOVER = HSM THEN DO
  IF &JRNL_ERROR = NO &MCDS_ERROR = NO &BCDS_ERROR = NO &OCDS_ERROR = NO
  THEN CALLREXX(EXTCBREX)
  ELSE ISSUE WRITEMSG(CBERRMSG)
END

DEFMSG CBERRMSG
'WARNING: DFSMSHSM CDS BACKUP FAILED!' WTORC(2) WTODC(2)
          

The REXX exec EXTCBREX constructs and submits JCL to an internal reader — see the sample library members referenced in the original documentation for full definitions.

Submit started tasks to copy CDS backup files from DASD to tape after successful backups. Use the sample catalogued procedure CDSCOPY to perform the copy via IEBGENER.

DEFRULE CDSCOPY
IF &MCDS_ERROR = NO &BCDS_ERROR = NO &OCDS_ERROR = NO &JRNL_ERROR = NO
THEN ISSUE OPERCMD(COPYJRNL,COPYMCDS,COPYBCDS,COPYOCDS)

DEFCMD COPYJRNL
'S CDSCOPY,S=&JRNL_BKDSN,T=&JRNL_BKDSN.COPY'
          

Catalogued procedure example (excerpt):

 //CDSCOPY PROC S=SOURCE,T=TARGET
 //COPY EXEC PGM=IEBGENER
 //SYSPRINT DD SYSOUT=*
 //SYSIN DD DUMMY
 //SYSUT1 DD DSN=&S,DISP=SHR
 //SYSUT2 DD DSN=&T,UNIT=(TAPE,,DEFER),
 //      DISP=(,CATLG,DELETE),
 //      LABEL=(1,SL,RETPD=30)
 // PEND
          

The ARCINEXT environment is entered during DFSMShsm startup just after the ARCCMDxx member has been processed. Use it to write messages or statistics, run REXX execs, or start tasks whenever a DFSMShsm address space starts.

To receive control: ensure ARCINEXT exit is active and EXTHSM is started prior to DFSMShsm (or reload exit after EXTHSM start). Activate exit with SETSYS EXITON(IN).

No ARCA-specific variables are required, but variables describing DFSMShsm address space (MQCT / MCVT control blocks) are available; HSM_EXIT_RC is ignored by DFSMShsm in this environment.

Table 9-5. Values for the ARCINEXT Environment

Write messages to DIF log and console recording job name, step name, system id, and start date/time.

DEFRULE HSMSTART IF &ENV EQ ARCINEXT
THEN ISSUE WRITEMSG(ARCSTRT01)

DEFMSG ARCSTRT01
'DFSMSHSM INITIALIZATION JOB=&JOBNAME STEP=&STEPNAME COMPLETE ON SYSTEM &SYSID AT &JOBSDATE &JOBSTIME'
GENID WTODC(2) WTORC(2) LOG(DIFLOG)
          

Write a fixed-length record to a log file at startup (suitable for report processing).

DEFRULE HSMINSTAT IF &ENV EQ ARCINEXT
THEN ISSUE WRITEREC(INSTATS)

DEFREC INSTATS DDNAME(STATSLOG) LENGTH(200)
FIELD &JOBSDATE
FIELD &JOBSTIME
FIELD &HSM_PROCNAM
FIELD &HSM_STCNAM
FIELD &HSM_HOSTID
FIELD &HSM_HOSTTYPE
FIELD &HSM_AUTHID
FIELD &ARCCMDXX
          

The ARCMDEXT environment is entered when datasets migrate from primary volumes during primary space management, interval migration, or when a MIGRATE VOLUME command is issued. Applies to both SMS-managed and non-SMS datasets. EXTHSM variables describe dataset and volume characteristics.

Use cases include bypassing migration, preventing software compaction, forcing migration to DASD or tape, overriding management class defaults, or managing the Fast Subsequent Migration (reconnect) feature.

Activate exit: SETSYS EXI-TON(MD).

Entered for each dataset meeting migration criteria. Volume is always primary (L0). May overlap with ARCSAEXT processing; ARCMDEXT is entered only for datasets eligible for migration (i.e., after eligibility determination).

Default for &BYPASS_MIGRATE is NO (datasets are migrated if eligible). If neither MIGRATE_TO_TAPE nor MIGRATE_TO_DASD is set to YES, DFSMShsm chooses the device.

Table 9-6. Variables for the ARCMDEXT Environment

Rule: migrate datasets larger than 100 MB directly to ML2 tape (overrides SMS where applicable), except during extent-reduction processing.

DEFRULE DIRECTML2
IF &SIZE-K-ALL GT 100000 &ENVS NE (EXTRED)
THEN SET &MIGRATE_TO_TAPE = YES
          

Rule: migrate datasets smaller than 20 MB to ML1 DASD; exclude reconnectable datasets.

DEFRULE DIRECTML1
IF &SIZE-K-ALL LT 20000 &RECONNECTABLE = NO
THEN SET &MIGRATE_TO_DASD = YES
          

DEFRULE NOMIGRATE IF &QUAL1 = SYS3*
&VOLSER = PROD*
THEN SET &BYPASS_MIGRATE = YES
          

This example demonstrates using EXTHSM rules to apply consistent migration policies for non-SMS datasets without creating many management classes.

DEFRULE NONSMSPOL
IF &SMS = NO &VOLSER = WRK* THEN SET &BYPASS_MIGRATION = YES
IF &DSNAME = PROD.* &SMS = NO
THEN SET &MIGRATE_TO_DASD = YES
     SET &MIGRATE_NOCOMP = YES
IF &SIZE-K-ALL GT 50000 &SMS = NO
THEN SET &MIGRATE_TO_TAPE = YES
          

The ARCMMEXT environment is entered when datasets migrate from migration volumes during secondary space management or other DFSMShsm processing (e.g., L1 → L2). It is not entered for command migration of individual datasets.

Use cases include bypassing second-level migration, writing SMF/statistics, triggering jobs, or other actions.

To receive control: activate SETSYS EXI-TON(MM) and ensure EXTHSM load modules are accessible.

Entered whenever DFSMShsm determines a dataset on migration volumes must migrate again — as a result of MIGRATE VOLUME, FREEVOL, DELVOL, automatic secondary space management, or other processes.

Default for &BYPASS_MIGRATE is NO (datasets are migrated by default).

Table 9-8. Variables for the ARCMMEXT Environment

EXTHSM rules in the ARCMMEXT environment may read fields from MCD records; these variables are read-only. See Table 9-9 for the complete list (MCD_VSN, MCD_NMIG, MCD_DLU, etc.).

Prevent migration to L2 unless at least 90 days have elapsed since last L0 reference for selected datasets (QUAL2 = 'PROD' and L0_VOLSER = SYSM*).

DEFRULE KEEPONML1 IF &QUAL2 = 'PROD'
&L0_DAYS_UNREF LT 90 &L0_VOLSER = SYSM* THEN DO
  IF &MIGRATE_TGTLVL = L1 OR &MIGRATE_TGTUNIT = DASD OR &FREEVOL_AGE_ZERO = YES
  THEN SET &BYPASS_MIGRATE = NO
  ELSE SET &BYPASS_MIGRATE = YES
END
          

Use ARCMMEXT to select only datasets in SDSPs for migration prior to deleting SDSPs on certain DASD platforms.

DEFRULE SDSPSELECT
IF &L1_VOLSER = HSM002 &SDSP EQ NO THEN SET &BYPASS_MIGRATE = YES
          

DEFRULE MIGINFO
IF &DSNAME = SOME.GROUP.OF.DS* &MIGRATE_TGTLVL = L2 &MIGRATE_TGTUNIT = TAPE
THEN ISSUE WRITEREC(MIGREC)

DEFREC MIGREC DDNAME(STATSLOG) LENGTH(300)
FIELD &DSNAME FIELD &MCD_MCANM FIELD &MCD_OVSN FIELD &MCD_VSN FIELD &MCD_SIZE FIELD &MCD_DAYS FIELD &MCD_NMIG FIELD &MCD_DLC FIELD &MCD_DLR FIELD &MCD_DLU
          

The ARCMVEXT environment is entered after DFSMShsm completes processing of a primary volume as part of MIGRATE VOLUME, interval migration, or primary space management. Use it to trigger defragmentation, start jobs, write SMF records, or take other actions after volume processing.

Entered whenever DFSMShsm completes processing for a volume that underwent space management or migration. If starting other jobs, consider time-of-day to avoid resource contention.

Table 9-10. Variables for the ARCMVEXT Environment

Issue a WTO if free space in the PROD storage group falls below 20%; start a defrag started task for WRK volumes with fragmentation index > 500.

DEFRULE ALERTRULE CONTINUE(NEXTIF)
IF &ENV = ARCMVEXT &STORGRP = PROD* &FREE_SPACE LT 20
THEN ISSUE WRITEMSG(ALRTMSG1)

IF &ENV = ARCMVEXT &VOLSER = WRK* &FRAG_INDEX GT 500
THEN ISSUE OPERCMD(DODEFRAG)

DEFMSG ALRTMSG1
'EXTMSG01 WARNING! LOW FREE SPACE ON VOLUME &VOLSER' WTORC(2)

DEFCMD DODEFRAG 'S EXTDFRAG,V=&L0_VOLSER' CN(0)
          

The ARCRPEXT environment is entered when a request to recall a migrated dataset, recover a dataset or volume, or delete a dataset is placed on DFSMShsm work queues and must wait. Use it to prioritize requests, prevent requests, or issue confirmation messages.

Activate exit with: SETSYS EXITON(RP).

Entered for each recall, recover, or delete request that must wait (after MWE built, before MWE is queued).

Default for &BYPASS_REQUEST is NO (requests proceed if eligible). Use PRIORITY and other variables to control request handling.

Table 9-11. Variables for the ARCRPEXT Environment

Example rules to prioritize production recalls, give high priority to sysprog TSO recalls, lower priority for daytime tape recalls, and bypass recalls for obsolete data.

DEFRULE RCALPRTY
IF &ENV NE ARCRPEXT THEN CONTINUE AT NEXTRULE

/* PRODUCTION RECALLS HAVE ABSOLUTE PRIORITY */
IF &QUAL2 = PROD* &ENVS = RECALL
THEN SET &PRIORITY = 100

/* HIGH PRIORITY FOR SYSPROG RECALLS */
IF &ENVS = RECALL &REQUEST_SOURCE = TSO &USERID = STGADM*
THEN SET &PRIORITY = 75

/* LOW PRIORITY FOR DAYTIME TAPE RECALLS */
IF &ENVS = RECALL &DATA_SOURCE = TAPE
   &CURTIME GT 09:00:00 &CURTIME LT 17:00:00 &CURDAY NE (SATURDAY,SUNDAY)
THEN SET &PRIORITY = 40

/* WARN/PREVENT RECALLS OF OBSOLETE DATA */
IF &ENVS = RECALL &DSNAME = OLD.DATA.*
THEN SET &BYPASS_REQUEST = YES ISSUE WRITEMSG(EMSG1)

DEFMSG EMSG1
'RECALL BYPASSED FOR OLD DATASET &DSNAME. CONTACT SYSPROG' USERID(&USERID)
          

DEFRULE NODEL
IF &ENV EQ ARCRPEXT &ENVS = DELETE &QUAL2 = PROD*
THEN SET &BYPASS_REQUEST = YES
     SET &RP_MSG1 = 'EXT PREVENTED HDELETE OF &DSNAME'
          

Example adjusts priority based on host id and whether the request is WAIT or NOWAIT.

DEFRULE PRTY
IF &ENV EQ ARCRPEXT &ENVS = RECALL &HSM_HOSTID = 3 THEN DO
  IF &REQUEST_TYPE = WAIT THEN SET &PRIORITY = 70
  IF &REQUEST_TYPE = NOWAIT THEN SET &PRIORITY = 90
END
          

The ARCSAEXT environment receives control for every dataset during DFSMShsm volume backup, migration, or space management processing. It is entered prior to the AD (ARCADEXT), BD (ARCBDEXT), and MD (ARCMDEXT) environments and allows EXTHSM to 'see all' datasets and optionally bypass later processing.

Use ARCSAEXT to examine dataset characteristics and set variables such as BYPASS_MGMTBK or BYPASS_BACKUP to prevent later processing.

Activate exit with: SETSYS EXITON(SA).

Entered for each dataset processed by DFSMShsm during volume-level space management or backup — not for individual dataset command migration/backup.

Default for BYPASS_MGMTBK and BYPASS_BACKUP is NO (datasets are processed normally if eligible).

Table 9-12. Variables for the ARCSAEXT Environment

Example: prevent DBA/DBU/migration processing for datasets with QUAL2 = 'TEST' between dates December 20 and January 3 (example period).

DEFRULE MIGHOLIDAY IF &ENV = ARCSAEXT
&ENVS = (DBA,DBU,MIGRATE) &QUAL2 = 'TEST' &JULIAN:CURDATE GE 2003.354
&JULIAN:CURDATE LE 2004.003
THEN SET &BYPASS_MGMTBK = YES
          

When datasets processed for migration or deletion have VTOC/VVDS errors, write a record to an error log and prevent delete processing; allow migration and backup to continue.

DEFRULE NOTE_ERRORS IF &ENV = ARCSAEXT
IF &ENVS NE BACKUP &DS_ERROR NE '' THEN DO
  ISSUE WRITEREC(ERR_REC)
  IF &ENVS = (DBA,DBU) THEN SET &BYPASS_MGMTBK = YES
END

DEFREC ERR_REC INIT(BLANKS) DDNAME(ERRFILE) LEN(250)
FIELD &DSNAME FIELD &CURDATE FIELD &CURTIME FIELD &ENVS
          

DEFRULE BYPASS_BKUP IF &ENV = ARCSAEXT
IF &MGMTCLAS = MCTMP*
THEN SET &BYPASS_BACKUP = YES
          

The ARCSDEXT environment receives control during DFSMShsm termination, just before functional subtasks are stopped. Use it to write messages, write SMF records, run REXX execs, start tasks, free resources, or perform other termination actions.

Activate exit with: SETSYS EXITON(SD).

The SD environment is entered once, at the termination of DFSMShsm processing (not entered if the DFSMShsm address space is cancelled).

No variables apply explicitly to SD, but variables describing the DFSMShsm address space are available. HSM_EXIT_RC can be set but is ignored by DFSMShsm.

Table 9-13. Variables for the ARCSDEXT Environment

Send a message on termination; on weekdays send a highlighted warning to the operator. Write an SMF record and DIF log entry.

DEFRULE HSMTERM CONTINUE(NEXTIF) IF &ENV EQ ARCSDEXT
THEN DO
  ISSUE WRITEMSG(TERMMSG)
  IF &CURDAY NE (SATURDAY,SUNDAY) THEN ISSUE WRITEMSG(WARNMSG)
END

DEFMSG TERMMSG
'HSM JOB &JOBNAME &STEPNAME TERMINATED ON SYSTEM &SYSID AT &CURDATE &CURTIME'
SMF(201) LOG(DIFLOG)

DEFMSG WARNMSG
'WARNING! HSM BEING TERMINATED ON A WEEKDAY!' WTODC(2) WTORC(2)
          

The ARCTDEXT environment receives control when DFSMShsm writes a backup or migration tape. It allows the expiration date for the backup to be changed from the default (1999.365) and to perform other processing when tapes are mounted.

Note: ARCTDEXT is invoked only when DFSMShsm tape security options for expiration protection are in effect. It is not used for ABARS backups (use ARCEDEXT for ABARS).

Activate exit with: SETSYS EXITON(TD).

The primary variable for TD is EXPDT. DSNAME may indicate backup or migration. Avoid modifying JFCB variables where not recommended; HSM_EXIT_RC is ignored by DFSMShsm.

Table 9-14. Variables for the ARCTDEXT Environment

DEFRULE MIGEXP
IF &ENV EQ ARCTDEXT &DSNAME = HSM.HMIGTAPE*
THEN SET &EXPDT = 2005.007
          

The ARCTEEXT environment is entered during recall, recover, restore, or recycle processing when DFSMShsm detects that required tapes reside outside an automated library. It allows installations to prompt operators to insert non-library tapes into the library or to allocate non-library drives.

Activate exit with: SETSYS EXITON(TE).

Entered for dataset recalls from ML2 tapes, recovery/restore from backup or dump tapes, and recycle processing. EXTHSM variables provide tape list and location information; set &TAPE_LOC to LIBRARY when tapes are inserted.

The default for &TAPE_LOC is NOLIB (tapes not in library).

Table 9-15. Variables for the ARCTEEXT Environment

Table 9-16. ARCTEEXT Return Codes, Variable Settings, and DFSMShsm Actions

Example: present a message asking operator to load required tapes. Responses: 'L' = tapes in library, 'N' = leave tapes outside library (allocate non-library drives), 'X' = fail request.

DEFRULE LIBPROMPT IF &ENV = ARCTEEXT
&ENVS = (RESTORE,RECALL) &TAPETYPE = ML2 &COMMAND_TYPE = DATASET
THEN DO
  IF &LIBREPLY = 'L' THEN SET &TAPE_LOC = LIBRARY
  IF &LIBREPLY = 'N' THEN SET &TAPE_LOC = NOLIB
  IF &LIBREPLY = 'X' THEN SET &TAPE_LOC = ALLOCERR
END

DEFVAR LIBREPLY 'USRFLDC1(1,1)' OPER(WRITEMSG(M1,M2,M3,M4,M5)) WILD

DEFMSG M1 'DIF0001I &TAPEVOLN NONLIBRARY VOLUMES REQUIRED' WTORC(2)
DEFMSG M2 'DIF0001I FOR DFSMSHSM FOR RESTORE/RECALL' WTORC(2)
DEFMSG M3 'DIF0001I &TAPEVOLS ' WTORC(2)
DEFMSG M4 'DIF0001I INSERT IN LIBRARY AND REPLY ''L''' WTORC(2)
DEFMSG M5 'DIF0001I OR ''N'' IF VOLUMES CANNOT BE INSERTED' WTORC(2)