[Enhancement][zos_data_set]Support for NOSCRATCH option when deleting datasets

changelogs/fragments/2202-zos_data_set-Support-noscratch-options.yml

@@ -0,0 +1,10 @@
+minor_changes:
+   - zos_data_set - Adds `noscratch` option to allow uncataloging
+     a data set without deleting it from the volume's VTOC.
+     (https://github.com/ansible-collections/ibm_zos_core/pull/2202)
+trivial:
+   - data_set - Internal updates to support the noscratch option.
+     https://github.com/ansible-collections/ibm_zos_core/pull/2202)
+   - test_zos_data_set_func - added test case to verify the `noscratch` option
+     functionality in zos_data_set module.
+     (https://github.com/ansible-collections/ibm_zos_core/pull/2202).

plugins/module_utils/data_set.py

@@ -241,7 +241,7 @@ def ensure_present(
         return True
 
     @staticmethod
-    def ensure_absent(name, volumes=None, tmphlq=None):
+    def ensure_absent(name, volumes=None, tmphlq=None, noscratch=False):
         """Deletes provided data set if it exists.
 
         Parameters
@@ -252,13 +252,15 @@ def ensure_absent(name, volumes=None, tmphlq=None):
             The volumes the data set may reside on.
         tmphlq : str
             High Level Qualifier for temporary datasets.
+        noscratch : bool
+            If True, the data set is uncataloged but not physically removed from the volume.
 
         Returns
         -------
         bool
             Indicates if changes were made.
         """
-        changed, present = DataSet.attempt_catalog_if_necessary_and_delete(name, volumes, tmphlq=tmphlq)
+        changed, present = DataSet.attempt_catalog_if_necessary_and_delete(name, volumes, tmphlq=tmphlq, noscratch=noscratch)
         return changed
 
     # ? should we do additional check to ensure member was actually created?
@@ -1003,7 +1005,7 @@ def attempt_catalog_if_necessary(name, volumes, tmphlq=None):
         return present, changed
 
     @staticmethod
-    def attempt_catalog_if_necessary_and_delete(name, volumes, tmphlq=None):
+    def attempt_catalog_if_necessary_and_delete(name, volumes, tmphlq=None, noscratch=False):
         """Attempts to catalog a data set if not already cataloged, then deletes
            the data set.
            This is helpful when a data set currently cataloged is not the data
@@ -1019,6 +1021,8 @@ def attempt_catalog_if_necessary_and_delete(name, volumes, tmphlq=None):
             The volumes the data set may reside on.
         tmphlq : str
             High Level Qualifier for temporary datasets.
+        noscratch : bool
+            If True, the data set is uncataloged but not physically removed from the volume.
 
         Returns
         -------
@@ -1039,7 +1043,7 @@ def attempt_catalog_if_necessary_and_delete(name, volumes, tmphlq=None):
                 present = DataSet.data_set_cataloged(name, volumes, tmphlq=tmphlq)
 
                 if present:
-                    DataSet.delete(name)
+                    DataSet.delete(name, noscratch=noscratch)
                     changed = True
                     present = False
                 else:
@@ -1074,7 +1078,7 @@ def attempt_catalog_if_necessary_and_delete(name, volumes, tmphlq=None):
 
                     if present:
                         try:
-                            DataSet.delete(name)
+                            DataSet.delete(name, noscratch=noscratch)
                         except DatasetDeleteError:
                             try:
                                 DataSet.uncatalog(name, tmphlq=tmphlq)
@@ -1101,14 +1105,14 @@ def attempt_catalog_if_necessary_and_delete(name, volumes, tmphlq=None):
                 present = DataSet.data_set_cataloged(name, volumes, tmphlq=tmphlq)
 
                 if present:
-                    DataSet.delete(name)
+                    DataSet.delete(name, noscratch=noscratch)
                     changed = True
                     present = False
         else:
             present = DataSet.data_set_cataloged(name, None, tmphlq=tmphlq)
             if present:
                 try:
-                    DataSet.delete(name)
+                    DataSet.delete(name, noscratch=noscratch)
                     changed = True
                     present = False
                 except DatasetDeleteError:
@@ -1414,7 +1418,7 @@ def create(
         return changed
 
     @staticmethod
-    def delete(name):
+    def delete(name, noscratch=False):
         """A wrapper around zoautil_py
         datasets.delete() to raise exceptions on failure.
 
@@ -1428,7 +1432,7 @@ def delete(name):
         DatasetDeleteError
             When data set deletion fails.
         """
-        rc = datasets.delete(name)
+        rc = datasets.delete(name, noscratch=noscratch)
         if rc > 0:
             raise DatasetDeleteError(name, rc)
 
@@ -2721,7 +2725,7 @@ def ensure_present(self, tmp_hlq=None, replace=False, force=False):
         self.set_state("present")
         return rc
 
-    def ensure_absent(self, tmp_hlq=None):
+    def ensure_absent(self, tmp_hlq=None, noscratch=False):
         """Removes the data set.
 
         Parameters
@@ -2734,7 +2738,7 @@ def ensure_absent(self, tmp_hlq=None):
         int
             Indicates if changes were made.
         """
-        rc = DataSet.ensure_absent(self.name, self.volumes, tmphlq=tmp_hlq)
+        rc = DataSet.ensure_absent(self.name, self.volumes, tmphlq=tmp_hlq, noscratch=noscratch)
         if rc == 0:
             self.set_state("absent")
         return rc

plugins/modules/zos_data_set.py

@@ -298,6 +298,15 @@
     type: bool
     required: false
     default: false
+  noscratch:
+    description:
+      - "When C(state=absent), specifies whether to keep the data set's entry in the VTOC."
+      - If C(noscratch=True), the data set is uncataloged but not physically removed from the volume.
+        The Data Set Control Block is not removed from the VTOC.
+      - This is the equivalent of using C(NOSCRATCH) in an C(IDCAMS DELETE) command.
+    type: bool
+    required: false
+    default: false
   volumes:
     description:
       - >
@@ -575,6 +584,15 @@
         type: bool
         required: false
         default: false
+      noscratch:
+        description:
+          - "When C(state=absent), specifies whether to keep the data set's entry in the VTOC."
+          - If C(noscratch=True), the data set is uncataloged but not physically removed from the volume.
+            The Data Set Control Block is not removed from the VTOC.
+          - This is the equivalent of using C(NOSCRATCH) in an C(IDCAMS DELETE) command.
+        type: bool
+        required: false
+        default: false
       extended:
         description:
           - Sets the I(extended) attribute for Generation Data Groups.
@@ -734,6 +752,12 @@
     name: someds.name.here
     state: absent
 
+- name: Uncatalog a data set but do not remove it from the volume.
+  zos_data_set:
+    name: someds.name.here
+    state: absent
+    noscratch: true
+
 - name: Delete a data set if it exists. If data set not cataloged, check on volume 222222 for the data set, and then catalog and delete if found.
   zos_data_set:
     name: someds.name.here
@@ -1404,7 +1428,7 @@ def get_data_set_handler(**params):
         )
 
 
-def perform_data_set_operations(data_set, state, replace, tmp_hlq, force):
+def perform_data_set_operations(data_set, state, replace, tmp_hlq, force, noscratch):
     """Calls functions to perform desired operations on
     one or more data sets. Returns boolean indicating if changes were made.
 
@@ -1439,7 +1463,7 @@ def perform_data_set_operations(data_set, state, replace, tmp_hlq, force):
     elif state == "absent" and data_set.data_set_type == "gdg":
         changed = data_set.ensure_absent(force=force)
     elif state == "absent":
-        changed = data_set.ensure_absent(tmp_hlq=tmp_hlq)
+        changed = data_set.ensure_absent(tmp_hlq=tmp_hlq, noscratch=noscratch)
     elif state == "cataloged":
         changed = data_set.ensure_cataloged(tmp_hlq=tmp_hlq)
     elif state == "uncataloged":
@@ -1586,6 +1610,11 @@ def parse_and_validate_args(params):
                     required=False,
                     default=False,
                 ),
+                noscratch=dict(
+                    type="bool",
+                    required=False,
+                    default=False,
+                ),
             ),
         ),
         # For individual data set args
@@ -1676,6 +1705,11 @@ def parse_and_validate_args(params):
             required=False,
             default=False,
         ),
+        noscratch=dict(
+            type="bool",
+            required=False,
+            default=False,
+        ),
         mutually_exclusive=[
             ["batch", "name"],
             # ["batch", "state"],
@@ -1788,6 +1822,11 @@ def run_module():
                     required=False,
                     default=False,
                 ),
+                noscratch=dict(
+                    type="bool",
+                    required=False,
+                    default=False,
+                ),
             ),
         ),
         # For individual data set args
@@ -1868,6 +1907,11 @@ def run_module():
             required=False,
             default=False
         ),
+        noscratch=dict(
+            type="bool",
+            required=False,
+            default=False
+        ),
     )
     result = dict(changed=False, message="", names=[])
 
@@ -1895,6 +1939,8 @@ def run_module():
             module.params["replace"] = None
         if module.params.get("record_format") is not None:
             module.params["record_format"] = None
+        if module.params.get("noscratch") is not None:
+            module.params["noscratch"] = None
     elif module.params.get("type") is not None:
         if module.params.get("type") in DATA_SET_TYPES_VSAM:
             # For VSAM types set the value to nothing and let the code manage it
@@ -1921,6 +1967,7 @@ def run_module():
                     replace=data_set_params.get("replace"),
                     tmp_hlq=data_set_params.get("tmp_hlq"),
                     force=data_set_params.get("force"),
+                    noscratch=data_set_params.get("noscratch"),
                 )
                 result["changed"] = result["changed"] or current_changed
         except Exception as e: