ALTER GDG

Syntax

GDG Filtering Selection Related

Related to disaster-recovery or environmental-cleanup:

Attributes

Limit ranges

Storage categories

Trim Parameters

Notes:

• ¹ Default values may be provided via the CKMINI member when the keyword is omitted.
• ² Time is specified in seconds, optionally to up to a 1/10th or 1/100th granularity.
• ³ Ranges, series of rangers, and single values can be specified. For GDG-Extended, ranges from 1 to 999 are allowed. Otherwise, the range includes 1 to 255.

Keywords

INCLUDE-GDG

(Required) Specifies one or more GDG Base names or masks which ALTER GDG is to select for processing. When using the RECLAIM option for a GDG structure that is missing the Type(B) base record, this keyword should be specified with the discrete GDG base name to be reclaimed, and the BCS keyword must specify the catalog in which the GDG resides. Specifying INCLUDE-GDG(**) without the BCS keyword is permitted, however the impact will be analogous to specifying “**” as an argument for ISPF Option 3.4.

DIAGNOSE

Specifies that ALTER GDG only performs GDG structural analysis and reporting. DIAGNOSE is identical to SIMULATE, except that no security checking is performed against the GDG base name, or the GDG data sets. However, the BCS in which they are cataloged will still require at least READ access. In addition, the serialization requirements for the GDG ENQ resources are minimized to reduce impact to concurrent activity.

DIAGNOSE is mutually exclusive with SIMULATE and with EXECUTE, and is the default when neither SIMULATE nor EXECUTE are specified.

SIMULATE

indicates that you want to test the command without actually performing it. When SIMULATE is specified, ALTER GDG performs GDG structural analysis and reporting without updating the catalog, VVDS, or VTOCs, and without writing SMF type-66 records. It is always recommended that you first run an ALTER GDG request in SIMULATE mode to ensure that the end results will be consistent with the intended expectations.

SIMULATE is mutually exclusive with EXECUTE and with DIAGNOSE.

EXECUTE

Indicates that you want to have ALTER GDG perform the updates to the catalog, write SMF Type-66 records, and (by default) update the VVDS and VTOC where necessary, following the successful completion of the GDG Structural analysis. ALTER GDG will bypass the updates for a GDG base structure when the analysis does not propose any significant changes, unless the REORGANIZE keyword is also specified.

EXECUTE is mutually exclusive with SIMULATE and with DIAGNOSE.

RECLAIM

Optionally specifies that ALTER GDG will attempt to re-incorporate any orphaned GDS entries back into the GDG structure, when possible. These entries will have been previously invisible from catalog searches, and would have become orphaned at the time the structural corruption event occurred.

REORGANIZE

Optionally specifies that the entire GDG structure will be rebuilt, even if the GDG had no changes nor problems. For a NOEXTENDED GDG, this may be used to eliminate excessive extension records. Without this keyword, ALTER GDG will not rebuild a GDG structure if there is no apparent reason to do so. If the EXECUTE keyword is not in effect, then the REORGANIZE keyword will be ignored.

BCS

Optionally specifies that all selected GDG structures will exclusively reside in this specified catalog. This includes generation data set catalog entries that may be invisible because the master catalog does not have an appropriate high-level qualifier alias assigned to the BCS connector entry (in the master catalog) which would otherwise direct searches for this dataset name into this catalog. Use of the BCS keyword is required when using the RECLAIM keyword to rebuild an individual GDG structure that had lost its Type(B) GDG-Base catalog record. The BCS keyword is intended for exceptional situations.

NEW-ATTR

Optionally specifies one or more GDG attributes that you wish to apply against the selected GDG bases. EXTENDED and NOEXTENDED are the most significant options, and SCRATCH/NOSCRATCH can influence Generation Dataset processing when the GDG LIMIT is also decreased via the NEW-LIMIT keyword. As an alternative, IDCAMS ALTER on the individual GDG names may also change attributes such as EMPTY/NOEMPTY, FIFO/LIFO, and PURGE/NOPURGE.

NEW-LIMIT

Optionally specifies the new GDG LIMIT that will be assigned to all selected GDG Base structures. When the new limit is being increased for a GDG that contains SMS-Managed GDS entries, the ROLLIN keyword is significant. When the new limit is being decreased for a GDG that contains DASD GDS entries, the SCRATCH/NOSCRATCH attribute applies for those generations that become rolled-off of the Active Generation set.

WAIT

Optionally specifies how many accumulated seconds ALTER GDG should wait for each selected GDG while acquiring control under contention for all ENQ, and RESERVE resources necessary to serialize a complete GDG Sphere structure. The time interval may be specified as a value from 0 to 86400.00 seconds, and up to 2 digits to the right of the decimal point are accepted. If ALTER GDG is unable to obtain control of the GDG within that time interval, then the processing of that GDG is bypassed. Deadlock embrace situations are detected and broken out of, which can also increase consumption of the allotted wait time. When a wait time of zero is in effect, and contention on a GDG-related enqueue resource is encountered, then processing of that GDG is immediately skipped. The default value may be provided via the CKMINI member when this keyword is not specified.

ROLLIN

Optionally specifies that when an SMS-Managed generation has been rolled-out, and the GDG LIMIT will allow it to become an Active generation, ALTER GDG should or should not automatically roll such a generation back in.

• NO -When NO is specified, ALTER GDG will not roll any SMS DASD Rolled-Out generations back in as Active Generations. When the LIMIT is being increased, this is identical to how IDCAMS ALTER on the GDG name behaves with the larger LIMIT value.

• YES: When YES is specified and an SMS-Managed generation had been rolled-out, and the GDG LIMIT will allow it to become an Active generation, ALTER GDG will automatically roll that generation back in.

The default value may be provided via the CKMINI member when this keyword is not specified.

VVDS-UPDATE

Optionally specifies if ALTER GDG (when in EXECUTE mode) is to be allowed to update the status in the NVR of DASD SMS-Managed Generation Data sets in the respective VVDS.

• YES - When YES is specified, ALTER GDG (in EXECUTE mode) will be allowed to update the VVDS NVR of an SMS-Managed DASD generation dataset so that the attribute in the NVR is consistent with its corresponding catalog entry in the BCS.
• NO - When NO is specified, ALTER GDG will not be allowed to update the NVR in the VVDS. Normally, when an SMS generation is rolled out of the active generation list, it is appropriate to update that data set’s NVR in the VVDS to reflect the new status. When the GDS status is changed by ALTER GDG and VVDS-UPDATE(NO) is specified, the synchronization of that changed status will not be maintained within the data set’s NVR. These may appear as anomalies to DIAGNOSE.

The default value may be provided via the CKMINI member when this keyword is not specified.

ALLOW-GDS-SCRATCH

Optionally specifies whether ALTER GDG will be allowed to Scratch expired generation datasets that would have otherwise been scratched due to normal GDG processes.

• YES: When YES is specified, ALTER GDG (in EXECUTE mode) will be allowed to Scratch generation data sets when the DFSMS rules dictate that the DASD dataset is to be scratched. An SMS-Managed data set on DASD will be either cataloged or scratched. The SCRATCH/NOSCRATCH attribute of the GDG base will be honored.
• NO - When NO is specified, ALTER GDG will not be allowed to scratch any data sets. For Non-SMS generation data sets exceeding the GDG LIMIT, those data sets will continue to exist on DASD in an uncataloged state, even when the GDG base has the SCRATCH attribute. When SMS-Managed generations exceed the GDG LIMIT, they will instead be rolled-out as if the GDG had the NOSCRATCH attribute. Uncataloged data sets resulting on DASD will be reported at the end of the ALTER GDG command execution to enable subsequent manual cleanup.

The default value may be provided via the CKMINI member when this keyword is not specified.

PRINT

Optionally specifies the level of detail that the SYSPRINT reporting is to produce.

• NONE- When NONE is specified, the batch SYSPRINT messages will focus more on the GDG structural and attribute issues, and only report on individual generation data sets when a problem is detected. Otherwise, the generation data sets are referenced only in count totals.
• KEY- When KEY is specified, reporting on individual generation data sets with a GDG as line items is enabled.
• DATA- When DATA is specified, reporting on individual generation data sets with detail (including the list of volsers that the dataset resides on, SMS attributes, Volume, DSCB, and NVR status) is enabled. The default value may be provided via the CKMINI member when this keyword is not specified.

The default value may be provided via the CKMINI member when this keyword is not specified.

EXCLUDE-GDG

Optionally specifies one or more GDG Base names or masks which ALTER GDG is to not select for processing. Matching dataset names will be considered exceptions to the INCLUDE-GDG keyword specification.

INCLUDE-ATTR

Optionally specifies an additional filter that selects GDG names based upon GDG attributes. These are the same attributes that would typically be specified when defining a GDG base name using IDCAMS, except for the LIMIT attribute. For example, specifying INCLUDE-ATTR(NOEXTENDED) would only select GDG base names that do not have the EXTENDED attribute.

EXCLUDE-ATTR

Optionally specifies an additional filter to selecting GDG Base Names by GDG attribute, but instead indicates which GDG names are not to be selected. For example, specifying EXCLUDE-ATTR(EXTENDED) would cause GDG base names that have the EXTENDED attribute to be ignored. Note that illogical combinations of attributes specified between EXCLUDE-ATTR and INCLUDE-ATTR may result in a failure to select any GDG base names.

INCLUDE-LIMIT

Optionally specifies an additional filter to selecting GDG Base Names using the LIMIT attribute as a criterion. Ranges of LIMIT values, and/or individual limit values, may be specified. A GDG will be selected when its LIMIT value matches this specification. Specifying INCLUDE-LIMIT(1-999) is equivalent to not specifying this keyword at all.

EXCLUDE-LIMIT

Optionally specifies an additional filter to selecting GDG Base Names using the LIMIT attribute as a criterion. Ranges of LIMIT values, and/or individual limit values, may be specified. A GDG will be excluded (not selected) when its LIMIT value matches this specification.

INCLUDE-USAGE

Optionally specifies an additional filter to selecting GDG Base Names categorized by the storage nature of its existing population of generations. These categories include DASD, TAPE, and EMPTY. For example, INCLUDE-USAGE(TAPE EMPTY) will only consider GDG structures that either have at least one generation that is cataloged to a Tape volume, or GDG structures that have no active generations at all. The DASD category also has three sub-categories, which are SMS, NONSMS and MIGRAT. A migrated GDS is always considered as DASD, even if it has been technically migrated to tape, and will also be either SMS-Managed or Non-SMS. The existence of at least one migrated GDS within the GDG structure will cause the whole GDG to be categorized into the MIGRAT sub-category of DASD. Note that when a GDG is empty, ALTER GDG cannot determine if its intended usage is for DASD or TAPE. When the GDG contains a mixture of TAPE and DASD GDS generations, that GDG will belong in both categories, and the additional presence of the EXCLUDE-USAGE keyword may be appropriate.

EXCLUDE-USAGE

Optionally specifies an additional filter to selecting GDG Base Names categorized by the storage nature of its existing population of generations, but instead indicates what types are to be not selected. Note that illogical combinations of parameters between EXCLUDE-USAGE and INCLUDE-USAGE may result in a failure to select any GDG base names.

TRIM-GDS

Optionally specifies which generation datasets are to be removed from the selected GDG structures. Valid sub-parameter keywords are:

MAX-ACTIVE

Optionally specifies the maximum number of Active GDS generations that are to be kept for each of the selected GDG bases. This keyword may be used during alternate site Disaster Recovery exercises, where the number of active generations may be reduced to a number that is less than the defined GDG LIMIT. The default action for a trimmed-out generation would be the same as if its relative generation exceeded the GDG Limit. Specifying a value of Zero will cause all generations to be removed, thus producing an Empty GDG for all selected GDG Bases.

ROLLED

Optionally specifies that all Rolled-Out SMS-Managed DASD Generations are to be deleted from the selected GDG bases, unless ALLOW-GDS-SCRATCH(NO) is in effect.

DEFERRED

Optionally specifies that all Deferred Roll-in SMS-Managed DASD Generations are to be deleted from the selected GDG bases, unless ALLOW-GDS-SCRATCH(NO) is in effect.

NODSCB

Optionally specifies that all DASD generations (that are not migrated) which are not present in the VTOC of the online primary volume indicated by the catalog entries are to be automatically removed (uncataloged) from the GDG structure.

OFFLINE

Optionally specifies that all generations (that are not migrated) which are cataloged to DASD volumes that are not online to the current system are to be automatically uncataloged from the GDG structure.

Usage notes

1. Default values may be established via the INI for the following keywords:
   • ROLLIN
   • VVDSUPDATE
   • ALLOW-GDS-SCRATCH
   • WAIT
   • PRINT
2. The ARCHIVE_VOLSERS token in the CKMINI member determine which volsers will represent a migrated data set.
3. When DIAGNOSE is specified or defaulted to, the following keywords are ignored:
   • REORGANIZE
   • NEW-ATTR
   • NEW-LIMIT
   • ROLLIN
   • VVDSUPDATE
   • ALLOW-GDS-SCRATCH
   • TRIM-GDS
4. ALTER GDG administrator authority can be provided by UPDATE access to profile IBMTIVOLI.ACM.ALTER.GDG in the FACILITY class. Administrator privileges are equivalent to having ALTER access to any BCS in context to the catalog records that are involved with GDG structures. Otherwise, ALTER access to the DATASET profiles protecting the BCS in which the GDG resides, the GDG base name, and all generation data sets is required, unless the current user ID has the OPERATIONS attribute.
5. When ALLOW-GDS-SCRATCH(NO) is specified or otherwise in effect, a report is generated to help you in the process of manually deleting the uncataloged data sets on DASD. When ALLOW-GDS-SCRATCH(YES) is in effect, it is recommended for the current user ID to also have READ access to profile STGADMIN.IGG.DLVVRNVR.NOCAT in the FACILITY class. This enables ALTER GDG to scratch uncataloged Non-VSAM SMS-Managed data sets without the risk of encountering security errors.
6. In EXECUTE mode, ALTER GDG creates SMF record Type(66) for catalog updates, Type(60) for VVDS updates, and (on systems at the z/OS 2.3 levels and higher), Type(42(27)) for scratch actions.

Examples

• Simulate the conversion all GDG Bases of application “HLQ1” to GDG-EXTENDED.

  ALTER GDG -
     SIMULATE -
     INCLUDE-GDG(HLQ1.**) -
     INCLUDE-ATTR(NOEXTENDED) -
     NEW-ATTR(EXTENDED)
  
  

• Select all GDG-Extended bases with LIMIT(255), increase the limit to 366, and roll-in older SMS-Managed generations that had rolled out because they were beyond the (-255) relative generation.

  ALTER GDG -
    EXECUTE -  
    INCLUDE-GDG(HLQ1.**) -
    INCLUDE-ATTR(EXTENDED) -
    INCLUDE-LIMIT(255) -
    NEW-LIMIT(366) -
    ROLLIN(YES)
  
  

• At a Disaster Recovery exercise, reduce all Tape GDG’s for application “HLQ1” to only have the (+0) and (-1) generations, because the older generations will not be on site.

  ALTER GDG - 
    EXECUTE -
    INCLUDE-GDG(HLQ1.**) -
    INCLUDE-USAGE(TAPE) -
    TRIM-GDS(MAX-ACTIVE(2))
  
  

• Investigate a broken GDG structure that had been severely damaged.

  ALTER GDG -  
    SIMULATE -
    RECLAIM -
    INCLUDE-GDG(HLQ1.BROKEN.GDGBASE) -
    BCS(CATALOG.APPL1) -
    ALLOW-GDS-SCRATCH(NO) -
    PRINT(DATA)
  
  

• At a Disaster Recovery exercise, uncatalog all DASD generations of GDG’s for application “HLQ1” that do not physically exist on the volume.

  ALTER GDG –
    EXECUTE -
    INCLUDE-GDG(HLQ1.**) -
    INCLUDE-USAGE(DASD) -
    TRIM-GDS(NODSCB OFFLINE)