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

Environment Description

EASY/Exit can receive control and enforce standards and policies whenever DFSMSdss performs any of its functions, such as dataset or volume backup or restore, defragmentation, copying, deletion, and so on. EASY/Exit receives control at each of the four exit points within DFSMSdss.

The four exit points are:

• ADRUENQ
• ADRUPSWD
• ADRREBLK
• ADRUIXIT

By examining and setting the appropriate EASY/Exit variables at each of these exit points, EASY/Exit can enforce standards for DFSMSdss processing, issue warnings, alter DFSMSdss parameters and options, write log or SMF records for later analysis, and control just about any aspect of DFSMSdss operation.

When EASY/Exit receives control at any of these exit points, the environment name (that is, the variable &ENV) is DFDSS. The subenvironment name (that is, &ENVS) is one of ADRUENQ, ADRUPSWD, ADRREBLK, or ADRUIXIT, depending on which exit is being entered. The DFDSS environment and its subenvironments may be entered multiple times during a DFSMSdss execution. For example, the ADRUENQ exit is entered for each volume processed during a backup or copy, to give the exit a chance to indicate how long the VTOC enqueue should be held. If multiple volumes are processed, the ADRUENQ exit (and thus the EASY/ExitADRUENQ subenvironment) is entered multiple times, once for each volume. The other subenvironments may also be entered multiple times — the ADRUIXIT subenvironment, for example, is always entered at least twice — once to allow processing of values in the DFSMSdss EXECute statement parame-ter list, and again for each dataset or volume processed.

Environment for EASY/Exit

EASY/Exit communicates with DFSMSdss via the EASY/Exit interface modules, which are DFSMSdss exit 'stubs' that are defined to DFSMSdss as ordinary exits. These interface stubs communicate with the DIF started task to run the EASY/Exit policy rules, allowing the main DIF and EASY/Exit modules to be independent of DFSMSdss, and allowing the EASY/Exit policy rules to be changed without requiring an IPL, relink, or other changes.

Before using the DFDSS environment, the EASY/Exit interface module (the 'stub') for DFSMSdss must be linked into the DFSMSdss load module ADRDSSU, replacing the default exit points. Once these modules have been linked into ADRDSSU, they will be called whenever DFSMSdss runs from that library. After the modules have been linked into ADRDSSU, then DIF can be started and the EASY/Exit rules will be called in the DFDSS environment.

Only the modules for the desired exits need be linked into ADRDSSU. The linkage editor (binder) will take an '*' in column one as a comment. The installer can include any or all of the 4 pairs of INCLUDE/REPLACE statements for the EXT stub modules, depending on which exits need to be installed. If the output load library containing the modified ADRDSSU member is in the system linklist, an LLA refresh may be required.

The JCL to perform the link-edit is shown below.

//LINK EXEC PGM=IEWBLINK,PARM='XREF,LIST,LET,RENT',REGION=4M
 //SYSPRINT DD SYSOUT=*
 //SYSLMOD DD DISP=SHR,DSN=TEST.LINKLIB  <= OUTPUT LIBRARY
 //PRODLIB DD DISP=SHR,DSN=SYS1.LINKLIB  <= INPUT LIBRARY
 //DTSLIB  DD DISP=SHR,DSN=DTS.R71.LOADLIB  <= DIF LOAD LIBRARY
 //SYSPRINT DD SYSOUT=*
 //SYSLIN DD *
 INCLUDE PRODLIB(ADRDSSU)
 *
 ***********************************************
 * ADRUIXIT - CONTROL DFSMSDSS OPTIONS *
 *********************************************** REPLACE -IMMED,ADRUIXIT
 INCLUDE DTSLIB(EXTUIXIT)
 *
 ***********************************************
 * ADRUPSWD - VOLUME / DATASET AUTHORIZATION *
 *********************************************** REPLACE -IMMED,ADRUPSWD
 INCLUDE DTSLIB(EXTUPSWD)
 *
 ***********************************************
 * ADRUENQ - CONTROL VTOC ENQUEUE DURATION *
 *********************************************** REPLACE -IMMED,ADRUENQ
 INCLUDE DTSLIB(EXTUENQ)
 *
 ***********************************************
 * ADRREBLK - CONTROL COPY/RESTORE BLOCKSIZES *
 *********************************************** REPLACE -IMMED,ADRREBLK
 INCLUDE DTSLIB(EXTREBLK)
 *
 SETCODE AC(1) NAME ADRDSSU(R) 
      

Figure 11-1. Enabling the DFDSS Environment

The DFDSS Sub-environments

Each subenvironment within the DFDSS environment represents a different exit point in DFSMSdss processing. During DFSMSdss execution, the environment name DFDSS is stored in the variable &ENV, and the subenvironment name is stored in the variable &ENVS. The subenvironment may be any of the following:

• ADRREBLK — The DFSMSdss Reblock exit. This exit can be used to allow or disallow system-determined blocksize processing, set or change block-sizes, and indicate whether or not a dataset should be reblocked.

• ADRUENQ — The DFSMSdss Enqueue exit. Return codes from this exit indicate whether a short- or long-duration enqueue should be held on the VTOC.

• ADRUIXIT — The DFSMSdss Options exit. This exit receives control for almost all DFSMSdss functions and can be used to change almost any aspect of DFSMSdss processing, including overriding installation options and verifying or altering control statement parameters.

• ADRUPSWD — The DFSMSdss Authorization exit. Return codes from this exit indicate whether security checking should be performed at the dataset level or at the volume level, how much checking should be performed, whether security checking should be bypassed, or whether the function should be terminated.

The ADRREBLK exit is entered whenever DFSMSdss performs a COPY or RESTORE of a sequential or partitioned dataset. This exit may be used to examine the dataset block-size, change it, force use of system-determined blocksize, or prevent or force reblocking. Preventing or forcing reblocking has the same effect as if the REBLOCK keyword was entered on the COPY or RESTORE control statement.

Variables in the ADRREBLK Sub-environment

The following variables are specifically available in the DFDSSADRREBLK subenvironment. Also, many of the usual DIF variables (&JOBNAME, &SYSID, &CURDATE, &CURTIME, &STORGRP, &VOLSER, &UNITNAME, etc.) are also available in this subenvironment as well as the other DFDSS subenvironments.

Table 11-1. Variables in the ADRREBLK Subenvironment

Additional variables (continued):

Examples for the ADRREBLK Sub-environment

Example — Never reblock datasets beginning with SYS or PROD:

DEFENV DFDSS MODE(ACTIVE)
DEFRULE NOREBSYS
/* IF REBLOCK SUBENV */
IF &ENVS = ADRREBLK
/* FOR SELECTED DSNS */
IF &DSNAME = (SYS*,PROD*)
THEN SET &DSS_EXITRC = 8  /* NEVER REBLOCK */
      

Example 2 – Force Use of System-Determined Blocksize for Certain Datasets

In this example, datasets with a naming convention of 'PROD' in the high-level qualifier, and 'WEST' in the low-level qualifier, which have an LRECL of 80 and a current block-size of less than 800, are reblocked using system-determined blocksize.

DEFENV DFDSS MODE(ACTIVE)
DEFRULE SETSDB
IF &ENVS = ADRREBLK /* IF REBLOCK SUBENV */
  &HLQ = PROD        /* FOR SELECTED DSNS */
  &QUALL = WEST     /* FOR SELECTED DSNS */
  &LRECL = 80       /* WITH SPECIFIED LRECL */
  &BLKSIZE LT 800
THEN SET &DSS_EXITRC = 12  /* USE SYSTEM-DETERMINED BLOCKSIZE (SDB) */
      

The ADRUENQ exit is entered whenever DFSMSdss performs a physical COPY or DUMP. The COPY or DUMP may be either a full dump or a dump of only selected tracks. The subenvironment is also entered for a PRINT tracks operation. This subenvironment is not entered for DFSMSdss logical operations such as COMPRESS, DEFRAG, or logical dump.

By default, DFSMSdss will enqueue the VTOC for the entire duration of the physical COPY, DUMP, or PRINT for the volume. However, this can interfere with other access to the volume or make a 'deadly-embrace' possible. Using the EASY/Exit rules to set a return code (&EXIT_RC) of 4 in this subenvironment limits duration of the enqueue to only as long as VTOC access is required. This is usually a much shorter time than required to process the entire volume.

Variables in the DFDSS ADRUENQ

The following variables are specifically available in the DFDSSADRUENQ subenvironment. Also, many of the usual DIF variables (&JOBNAME, &SYSID, &CURDATE, &CURTIME, &STORGRP, &VOLSER, &UNITNAME, etc.) are also available in this subenvironment as well as the other DFDSS subenvironments.

Table 11-2. Variables in the ADRUENQ Subenvironment

Examples for the DFDSS ADRUENQ sub-environment

Example — Enqueue VTOC only as long as necessary for production volumes:

DEFENV DFDSS MODE(ACTIVE) DEFRULE PRODRULE
IF &ENVS = ADRUENQ &DSS_FUNC = (DUMP,COPY) THEN DO
  IF &DSS_SRCVOL = PROD* OR &STORGRP = (STGP1, STGP2)
  THEN SET &DSS_ENQTYPE=SHORT
END
      

ADRUIXIT - Control DFSMSdss Options

The ADRUIXIT exit allows the EASY/Exit administrator to define rules which can control many aspects of DFSMSdss processing. The rules in this exit can change DFSMSdss installation default options and can examine, supply, or override the options specified on DFSMSdss control statements.

The ADRUIXIT exit is entered at least twice for each execution of DFSMSdss. The first entry, called the "parm change" entry, allows the rules to change values that can be specified on the PARM field of the EXECute statement for DFSMSdss. This includes items such as setting SERIAL or PARALLEL operation and specifying where the I/O buffers should reside or be backed (above or below 16M), and whether RACF checking should be performed. The "parm change" entry into the exit is indicated by a value of PARMCHG in the variable &DSS_FUNC.

After the "parm change" entry has been performed, subsequent entries into ADRUIXIT are made for each function (for example, DUMP, RESTORE) to be performed. These are referred to as "function" entries. During a function entry, the rules may examine or modify variables that represent DFSMSdss keywords or options, such as ALLEXCP, ALLDATA, PURGE, REPLACE, SELECTMULTI, RECATALOG, and so on.

It is not necessary to set the exit return code (&DSS_EXITRC) to 4 in the rules for the ADRUIXIT subenvironment. If the rules change any variables that are represented in the ADRUIXIT parmlist, EASY/Exit will automatically set &DSS_EXITRC to 4 to indicate something has been changed. If a function is to be terminated (with an error), the rules can set &DSS_EXITRC to 8. This will cause the function to fail with message ADR036W.

If the rules alter any values in the ADRUIXIT subenvironment, the changed values will be displayed in the DFSMSdss SYSPRINT output with message ADR035I, for example:

ADR035I (001)-PRIME(12), INSTALLATION EXIT ALTERED ALLEXCP OPTION
ADR035I (001)-PRIME(15), INSTALLATION EXIT ALTERED ALLDATA OPTION
ADR035I (001)-PRIME(36), INSTALLATION EXIT ALTERED OPTIMIZE VALUE TO 4
      

Variables in the ADRUIXIT sub-environment

The following variables are specifically available in the DFDSSADRUIXIT environment. Also, many of the usual DIF variables (&JOBNAME, &SYSID, &CURDATE, &CURTIME, &STORGRP, &VOLSER, &UNITNAME, etc.) are also available in this subenvironment as well as the other DFDSS subenvironments.

Table 11-3. Variables in the ADRUIXIT Subenvironment

The following variables are available only during a "parm change" entry (when &DSS_FUNC = 'PARMCHG').

Table 11-4. Variables in the ADRUIXIT Subenvironment for &DSS_FUNC = 'PARMCHG'

The following variables are available only during a "function" entry (that is, when &DSS_FUNC is not equal to 'PARMCHG').

Table 11-5. Variables in the ADRUIXIT Subenvironment for &DSS_FUNC NOT = 'PARMCHG'

Continued (Table 11-5):

Examples for the ADRUIXIT Environment

Example — Prevent specified users from executing a DUMP function:

DEFENV DFDSS MODE(ACTIVE) DEFRULE KILLDUMP
IF &ENVS = ADRUIXIT  /* IF OPTIONS EXIT */
  &RUSER = STEVE     /* FOR SELECTED USERS */
  &DSS_FUNC = DUMP   /* FOR DUMPS */
THEN SET &DSS_EXITRC = 8  /* DISALLOW THE FUNCTION */
      

Example 2 — Set OPTIMIZE, WAIT, ALLEXCP, ALLDATA and other values

Example — Force OPTIMIZE(4), WAIT retries, and set ALLDATA/ALLEXCP to dump idle tracks:

DEFENV DFDSS MODE(ACTIVE) DEFRULE DFLTRULE
IF &ENVS = ADRUIXIT &DSS_FUNC NE PARMCHG
THEN
  SET &DSS_OPT_UOPTM = 4    /* OPTIMIZE(4) */
  SET &DSS_OPT_WAITR = 10  /* WAIT 10 SECS BETWEEN ENQ RETRIES */
  SET &DSS_OPT_WAITS = 10  /* UP TO 10 ENQ RETRIES */
  SET &DSS_OPT_ALD = YES   /* SET ALLDATA */
  SET &DSS_OPT_ALDL = YES  /* SET ALLDATA(*) */
  SET &DSS_OPT_ALLE = YES  /* SET ALLEXCP */
      

Example — Change PARM options to place buffers above 16M, use 64-bit real storage if available, and set WORKVOL/WORKUNIT:

DEFENV DFDSS MODE(ACTIVE) DEFRULE PARMSRULE
IF &ENVS = ADRUIXIT &DSS_FUNC EQ PARMCHG
THEN
  SET DSS_PARM_AI31B = YES
  SET DSS_PARM_REAL64 = YES
  SET DSS_PARM_XABUFF = YES
  SET DSS_PARM_WKVOL = DTS003
  SET DSS_PARM_WKUNIT = 3390
      

ADRUPSWD - Volume/Dataset Authorization

The ADRUPSWD exit is called once for each volume processed, and, depending on the return codes from this call or subsequent calls, may be called once for each dataset on the volume. At each call, ADRUPSWD can return a code that indicates whether:

• processing should be terminated (with an error) for the dataset or volume
• authorization should be checked for the dataset or volume
• whether the ADRUPSWD exit should be called again (note: ADRUPSWD is not called for the CONVERTV or COPYDUMP functions)

Volume-Level Calls vs. Dataset-Level Calls

The ADRUPSWD exit is not called if the volume being processed is a non-SMS volume already protected by a DASDVOL profile. For all other volumes, the exit is called first at the volume level (&DSS_PROCLEVEL = VOLUME). If the rules return a zero return code (&DSS_EXITRC = 0), then no further checking on the volume is performed — no dataset-level checks are performed. If the rules return a nonzero return code for the volume-level call, then dataset-level checking is performed (unless the rules set a return code greater than 12, which ends the function with an error).

Dataset-level calls are not made for the DEFRAG function.

Table 11-6. Return Codes when &DSS_PROCLEVEL = VOLUME

Any other value for &DSS_EXITRC will result in DFSMSdss terminating the function with message ADR402E-15.

If the return code from the volume-level call is greater than zero (and less than or equal to 12), then ADRUPSWD is called for each dataset on the volume. For these dataset-level calls, the value of &DSS_PROCLEVEL is DATASET. For each dataset-level call, the rules may set a return code which indicates whether any further calls should be made.

Table 11-7. Return Codes when &DSS_PROCLEVEL = DATASET

The following variables are specifically available in the DFDSSADRUPSWD subenvironment. Also, many of the usual DIF variables are also available in this subenvironment as well as the other DFDSS subenvironments.

Table 11-8. Variables in the ADRUPSWD Subenvironment

Examples for the ADRUPSWD Sub-environment

Example 1 — Bypass authorization checking for certain volumes:

DEFENV DFDSS MODE(ACTIVE) DEFRULE BYPRULE1
IF &ENVS = ADRUPSWD
  &DSS_FUNC = DUMP        /* BACKUPS */
  &DSS_PROCLEVEL = VOLUME /* VOLUME-LEVEL ENTRY */
  &VOLSER = PRD*         /* FOR SPECIFIED VOLUMES */
  &RUSER = P32*          /* FOR SPECIFIED USERIDS */
THEN SET &DSS_EXITRC = 0 /* NO AUTH CHECKING NEEDED */

IF &ENVS = ADRUPSWD &DSS_PROCLEVEL = VOLUME
THEN SET &DSS_EXITRC = 12 /* PERFORM VOLUME-LEVEL AUTH */
      

Example — If datasets on volumes beginning with PRD must start with PROD; otherwise fail dataset:

DEFENV DFDSS MODE(ACTIVE) DEFRULE CHKRULE1
IF &ENVS = ADRUPSWD &DSS_PROCLEVEL = VOLUME &VOLSER = PRD* THEN SET &DSS_EXITRC = 8 /* CHECK AT DATASET LEVEL */

IF &ENVS = ADRUPSWD &DSS_PROCLEVEL = DATASET &VOLSER = PRD* &DSNAME = PROD** THEN SET &DSS_EXITRC = 8 /* AUTH-CHECK AND REENTER */

IF &ENVS = ADRUPSWD &DSS_PROCLEVEL = DATASET &VOLSER = PRD* &DSNAME NE PROD** THEN SET &DSS_EXITRC = 20 /* FAIL THIS DATASET */