[Enhancement][zos_mvs_raw] Add support for volume definition in zos_mvs_raw module… (#2194)

* [Enhancement] Add support for volume definition in zos_mvs_raw module and corresponding tests

* changed from volser to volume

* Allow both volume or volume_name, but require at least one

* Rename 'volser' to 'volume' in test_full_volume_dump_with_custom_dd_volume function

* added fragments

* added documentation

* fixed doc

* fixed

* fixed

* required set to true

* fixed

* FIXED

* sanity fixed

* added choices for unit dd_volume

* FIXED

* removed return_content

* reviewed comment resolve

* fixed

* changed volume to volume_names

* reviewed comments resolved

* reviwed comments

* fixed

* changed fragments

* Update dd_statement.py

* Update plugins/modules/zos_mvs_raw.py

* added dd_output

* changed dd_dummy to dd_output in example section

* fixed

---------

Co-authored-by: Fernando Flores <[email protected]>

Author: mayankmani-sde

changelogs/fragments/2194-zos_mvs_raw-Supporting-for-volume-definition-in-zos_mvs_raw.yml

@@ -0,0 +1,7 @@
+minor_changes:
+   - zos_mvs_raw - Adds support for volume data definition.
+     (https://github.com/ansible-collections/ibm_zos_core/pull/2194)
+
+trivial:
+  - test_zos_mvs_raw_func - added test cases to verify volume definition functionality in zos_mvs_raw module.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2194).

plugins/module_utils/dd_statement.py

@@ -656,15 +656,21 @@ def _build_arg_string(self):
 
 
 class VolumeDefinition(DataDefinition):
-    def __init__(self, volume_name):
-        """Volume DD data type to be used in a DDStatement.
-
+    def __init__(self, volume_name, unit, disposition):
+        """
+        Volume DD data type to be used in a DDStatement.
         Parameters
         ----------
         volume_name : str
             The volume name to associate with the DD statement.
+        unit : str
+            The unit of measurement to use when defining the volume.
+        disposition : str
+            The disposition of the volume.
         """
         super().__init__(volume_name)
+        self.unit = unit
+        self.disposition = disposition
 
     def _build_arg_string(self):
         """Build a string representing the arguments of this particular data type
@@ -675,7 +681,11 @@ def _build_arg_string(self):
         str
             ',vol'
         """
-        return ",vol"
+        mvscmd_string = ",vol"
+        mvscmd_string = self._append_mvscmd_string(mvscmd_string, "unit", self.unit)
+        if self.disposition:
+            mvscmd_string += f",{self.disposition}"
+        return mvscmd_string
 
 
 class StdoutDefinition(DataDefinition):

plugins/modules/zos_mvs_raw.py

@@ -690,6 +690,37 @@
               - The DD name.
             required: true
             type: str
+      dd_volume:
+        description:
+          - Use I(dd_volume) to specify the volume to use in the DD statement.
+        required: false
+        type: dict
+        suboptions:
+          dd_name:
+            description: The DD name.
+            required: true
+            type: str
+          volume_name:
+            description:
+              - The volume serial number.
+            type: str
+            required: true
+          unit:
+            description:
+              - Device type for the volume.
+              - This option is case sensitive.
+            type: str
+            required: true
+          disposition:
+            description:
+              - I(disposition) indicates the status of a data set.
+            type: str
+            required: true
+            choices:
+              - new
+              - shr
+              - mod
+              - old
       dd_concat:
         description:
           - I(dd_concat) is used to specify a data set concatenation.
@@ -1351,6 +1382,37 @@
           dd_name: sysin
           content: " LISTCAT ENTRIES('SOME.DATASET.*')"
 
+- name: Full volume dump using ADDRDSU.
+  zos_mvs_raw:
+    program_name: adrdssu
+    auth: true
+    dds:
+      - dd_data_set:
+          dd_name: dumpdd
+          data_set_name: mypgm.output.ds
+          disposition: new
+          disposition_normal: catalog
+          disposition_abnormal: delete
+          space_type: cyl
+          space_primary: 10
+          space_secondary: 10
+          record_format: u
+          record_length: 0
+          block_size: 32760
+          type: seq
+      - dd_volume:
+          dd_name: voldd
+          volume_name: "000000"
+          unit: "3390"
+          disposition: old
+      - dd_input:
+          dd_name: sysin
+          content: " VOLDUMP VOL(voldd) DSNAME(dumpdd) FULL"
+      - dd_output:
+          dd_name: sysprint
+          return_content:
+            type: text
+
 - name: List data sets matching patterns in catalog,
     save output to a new sequential data set and return output as text.
   zos_mvs_raw:
@@ -1698,6 +1760,7 @@
     DDStatement,
     DummyDefinition,
     VIODefinition,
+    VolumeDefinition,
 )
 
 from ansible_collections.ibm.ibm_zos_core.plugins.module_utils.zos_mvs_raw import (
@@ -1907,14 +1970,19 @@ def run_module():
             ),
         )
     )
-
+    dd_volume_base = dict(
+        volume_name=dict(type="str", required=True),
+        unit=dict(type="str", required=True),
+        disposition=dict(type="str", choices=["new", "shr", "mod", "old"], required=True),
+    )
     dd_data_set = dict(type="dict", options=combine_dicts(dd_name_base, dd_data_set_base))
     dd_unix = dict(type="dict", options=combine_dicts(dd_name_base, dd_unix_base))
     dd_input = dict(type="dict", options=combine_dicts(dd_name_base, dd_input_base))
     dd_output = dict(type="dict", options=combine_dicts(dd_name_base, dd_output_base))
     dd_dummy = dict(type="dict", options=combine_dicts(dd_name_base, dd_dummy_base))
     dd_vio = dict(type="dict", options=combine_dicts(dd_name_base, dd_vio_base))
     dd_concat = dict(type="dict", options=combine_dicts(dd_name_base, dd_concat_base))
+    dd_volume = dict(type="dict", options=combine_dicts(dd_name_base, dd_volume_base))
 
     module_args = dict(
         program_name=dict(type="str", aliases=["program", "pgm"], required=True),
@@ -1934,6 +2002,7 @@ def run_module():
                 dd_vio=dd_vio,
                 dd_concat=dd_concat,
                 dd_dummy=dd_dummy,
+                dd_volume=dd_volume,
             ),
         ),
     )
@@ -2148,14 +2217,19 @@ def parse_and_validate_args(params):
             ),
         )
     )
-
+    dd_volume_base = dict(
+        volume_name=dict(type="str", required=True),
+        unit=dict(type="str", required=True),
+        disposition=dict(type="str", choices=["new", "shr", "mod", "old"], required=True),
+    )
     dd_data_set = dict(type="dict", options=combine_dicts(dd_name_base, dd_data_set_base))
     dd_unix = dict(type="dict", options=combine_dicts(dd_name_base, dd_unix_base))
     dd_input = dict(type="dict", options=combine_dicts(dd_name_base, dd_input_base))
     dd_output = dict(type="dict", options=combine_dicts(dd_name_base, dd_output_base))
     dd_dummy = dict(type="dict", options=combine_dicts(dd_name_base, dd_dummy_base))
     dd_vio = dict(type="dict", options=combine_dicts(dd_name_base, dd_vio_base))
     dd_concat = dict(type="dict", options=combine_dicts(dd_name_base, dd_concat_base))
+    dd_volume = dict(type="dict", options=combine_dicts(dd_name_base, dd_volume_base))
 
     module_args = dict(
         program_name=dict(type="str", aliases=["program", "pgm"], required=True),
@@ -2176,6 +2250,7 @@ def parse_and_validate_args(params):
                 dd_vio=dd_vio,
                 dd_concat=dd_concat,
                 dd_dummy=dd_dummy,
+                dd_volume=dd_volume,
             ),
         ),
         # verbose=dict(type="bool", required=False),
@@ -2690,6 +2765,9 @@ def get_dd_name_and_key(dd):
     elif dd.get("dd_concat"):
         dd_name = dd.get("dd_concat").get("dd_name")
         key = "dd_concat"
+    elif dd.get("dd_volume"):
+        dd_name = dd.get("dd_volume").get("dd_name")
+        key = "dd_volume"
     return dd_name, key
 
 
@@ -2797,6 +2875,14 @@ def build_data_definition(dd):
             dd.get("dd_vio").get("tmphlq"))
     elif dd.get("dd_dummy"):
         data_definition = DummyDefinition()
+    elif dd.get("dd_volume"):
+        volume_args = dd["dd_volume"]
+        data_definition = VolumeDefinition(
+            volume_name=volume_args.get("volume_name"),
+            unit=volume_args.get("unit"),
+            disposition=volume_args.get("disposition"),
+        )
+
     elif dd.get("dd_concat"):
         data_definition = []
         for single_dd in dd.get("dd_concat").get("dds", []):

tests/functional/modules/test_zos_mvs_raw_func.py

@@ -45,6 +45,62 @@ def get_temp_idcams_dataset(hosts):
 #                               Data set DD tests                              #
 # ---------------------------------------------------------------------------- #
 
+def test_full_volume_dump_with_custom_dd_volume(ansible_zos_module, volumes_on_systems):
+    hosts = ansible_zos_module
+    dump_dataset = get_tmp_ds_name()
+    volume_handler = Volume_Handler(volumes_on_systems)
+    test_volume = volume_handler.get_available_vol()
+    try:
+        results = hosts.all.zos_mvs_raw(
+            program_name="ADRDSSU",
+            auth=True,
+            verbose=True,
+            dds=[
+                {
+                    "dd_data_set": {
+                        "dd_name": "DUMPDD",
+                        "data_set_name": dump_dataset,
+                        "disposition": "new",
+                        "disposition_normal": "catalog",
+                        "disposition_abnormal": "delete",
+                        "space_type": "cyl",
+                        "space_primary": 10,
+                        "space_secondary": 2,
+                        "record_format": "u",
+                        "record_length": 0,
+                        "block_size": 32760,
+                        "type": "seq",
+                    }
+                },
+                {
+                    "dd_volume": {
+                        "dd_name": "VOLDD",
+                        "volume_name": test_volume,
+                        "unit": "3390",
+                        "disposition": "old",
+                    }
+                },
+                {
+                    "dd_input": {
+                        "dd_name": "SYSIN",
+                        "content": "  DUMP FULL INDDNAME(VOLDD) OUTDDNAME(DUMPDD)"
+                    }
+                },
+                {
+                    "dd_output":{
+                        "dd_name":"SYSPRINT",
+                        "return_content":{
+                            "type":"text"
+                        }
+                    }
+                },
+            ],
+        )
+        for result in results.contacted.values():
+            assert result.get("ret_code", {}).get("code", -1) == 0
+            assert result.get("changed", False) is True
+    finally:
+        hosts.all.zos_data_set(name=dump_dataset, state="absent")
 
 def test_failing_name_format(ansible_zos_module):
     hosts = ansible_zos_module