[Enhancement] [zos_stat] Add support to stat migrated data sets (#2075)

* [Enhancement] [zos_stat] Add support for aliases (#2048)

* Update fragment

* Add support for migrated data sets

* Move recall to an earlier step

* Fix trailing comma

* Fix handling of migrated data sets when not recalled

* Fix tsocmd validation

* Update RST file

* Add changelog fragment

* Fix escaping

* Fix pep8 issue

* Update module docs

Author: rexemin

changelogs/fragments/2075-migrated-data-sets-support-zos_stat.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - zos_stat - Added support to recall migrated data sets and return
+    its attributes.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2075)

docs/source/modules/zos_stat.rst

@@ -32,6 +32,8 @@ name
 
   Data sets can be sequential, partitioned (PDS), partitioned extended (PDSE), VSAMs or generation data sets (GDS).
 
+  This option doesn't accept the use of wilcards (? and *).
+
   | **required**: True
   | **type**: str
 
@@ -71,6 +73,24 @@ sms_managed
   | **default**: False
 
 
+recall
+  Whether to recall a migrated data set to fully query its attributes.
+
+  If set to ``false``, the module will return a limited amount of information for a migrated data set.
+
+  Recalling a data set will make the module take longer to execute.
+
+  Ignored when the data set is not found to be migrated.
+
+  The data set will not be migrated again afterwards.
+
+  The data set will not get recalled when running the module in check mode.
+
+  | **required**: False
+  | **type**: bool
+  | **default**: False
+
+
 tmp_hlq
   Override the default high level qualifier (HLQ) for temporary data sets.
 

plugins/module_utils/data_set.py

@@ -2102,6 +2102,59 @@ def _build_volume_string_iehprogm(volumes):
                 volume_string += single_volume_string + ")\n"
         return volume_string
 
+    @staticmethod
+    def check_if_data_set_migrated(name):
+        """Compares the output of datasets.list_dataset_names with and
+        without migrated data set names to check if name has been migrated.
+
+        Parameters
+        ----------
+        name : str
+            Name of a data set.
+
+        Returns
+        -------
+        bool
+            Whether the data set has been migrated.
+        """
+        has_been_migrated = False
+
+        non_migrated_list = datasets.list_dataset_names(name, migrated=False)
+        migrated_list = datasets.list_dataset_names(name, migrated=True)
+
+        if name in migrated_list and name not in non_migrated_list:
+            has_been_migrated = True
+
+        return has_been_migrated
+
+    @staticmethod
+    def recall_migrated_data_set(name, module, tmp_hlq=None):
+        """Recalls a data set using HRECALL.
+
+        Parameters
+        ----------
+        name : str
+            Name of a data set.
+        module : AnsibleModuleHelper
+            Ansible object capable of executing commands.
+
+        Keyword Parameters
+        ------------------
+        tmp_hlq : str
+            Temp HLQ to use with mvscmdauth.
+
+        Returns
+        -------
+        tuple(int, str, str)
+            Return code, standard output and standard error from
+            the HRECALL call.
+        """
+        name = name.replace('$', '\\$')
+        recall_cmd = f"""tsocmd "HRECALL '{name}'" """
+        rc, stdout, stderr = module.run_command(recall_cmd)
+
+        return rc, stdout, stderr
+
     @staticmethod
     def get_name_if_data_set_is_alias(name, tmp_hlq=None):
         """Checks the catalog to see if 'name' corresponds to a data set

plugins/modules/zos_stat.py

@@ -35,6 +35,7 @@
           or a UNIX System Services file path, to query.
         - Data sets can be sequential, partitioned (PDS), partitioned
           extended (PDSE), VSAMs or generation data sets (GDS).
+        - This option doesn't accept the use of wilcards (? and *).
     type: str
     required: true
     aliases:
@@ -77,6 +78,20 @@
     type: bool
     required: false
     default: false
+  recall:
+    description:
+      - Whether to recall a migrated data set to fully query its
+        attributes.
+      - If set to C(false), the module will return a limited amount of
+        information for a migrated data set.
+      - Recalling a data set will make the module take longer to execute.
+      - Ignored when the data set is not found to be migrated.
+      - The data set will not be migrated again afterwards.
+      - The data set will not get recalled when running the module in
+        check mode.
+    type: bool
+    required: false
+    default: false
   tmp_hlq:
     description:
       - Override the default high level qualifier (HLQ) for temporary data
@@ -1708,7 +1723,8 @@ def __init__(
         ds_type,
         tmp_hlq=None,
         missing_volumes=None,
-        alias=None
+        alias=None,
+        migrated=False
     ):
         """Create a new handler that will handle the query of a sequential or
         partitioned data set. This subclass should only be instantiated by
@@ -1725,6 +1741,7 @@ def __init__(
             missing_volumes (list, optional) -- List of volumes where a data set was searched
                 but not found.
             alias (str, optional) -- Alias of the data set that the user provided.
+            migrated (bool, optional) -- Whether it is a migrated data set.
         """
         super().__init__(
             name,
@@ -1737,6 +1754,7 @@ def __init__(
             alias=alias
         )
         self.missing_volumes = missing_volumes
+        self.migrated = migrated
 
     def query(self):
         """Uses LISTDSI to query facts about a data set, while also handling
@@ -1754,6 +1772,14 @@ def query(self):
         data = super().query()
         attributes = {}
 
+        if self.migrated:
+            data['attributes'] = fill_missing_attrs(
+                self._parse_attributes(attributes),
+                self.expected_attrs
+            )
+
+            return data
+
         try:
             # First creating a temp data set to hold the LISTDSI script.
             # All options are meant to allocate just enough space for it.
@@ -2293,7 +2319,8 @@ def get_data_set_handler(
     volumes,
     module,
     tmp_hlq=None,
-    sms_managed=False
+    sms_managed=False,
+    recall=False
 ):
     """Returns the correct handler needed depending on the type of data set
     we will query.
@@ -2305,6 +2332,7 @@ def get_data_set_handler(
         module (AnsibleModule) -- Ansible object with the task's context.
         tmp_hlq (str, optional) -- Temp HLQ for certain data set operations.
         sms_managed (bool, optional) -- Whether the data set is managed by SMS.
+        recall (bool, optional) -- Whether a migrated data set should be recalled.
 
     Returns
     -------
@@ -2321,6 +2349,27 @@ def get_data_set_handler(
 
     alias_name = None
 
+    has_been_migrated = DataSet.check_if_data_set_migrated(name)
+    if has_been_migrated:
+        if recall and not module.check_mode:
+            rc, stdout, stderr = DataSet.recall_migrated_data_set(
+                name,
+                module,
+                tmp_hlq=tmp_hlq
+            )
+
+            # Ignoring whatever comes out of stderr because tsocmd decides
+            # to pollute it even when the command runs fine.
+            if rc != 0:
+                raise QueryException(
+                    'An error ocurred while recalling a migrated data set.',
+                    rc,
+                    stdout,
+                    stderr
+                )
+        else:
+            return NonVSAMDataSetHandler(name, 'MIGRAT', module, sms_managed, None, migrated=True)
+
     try:
         is_an_alias, base_name = DataSet.get_name_if_data_set_is_alias(
             name,
@@ -2385,6 +2434,7 @@ def get_facts_handler(
     volumes=None,
     tmp_hlq=None,
     sms_managed=False,
+    recall=False,
     file_args=None
 ):
     """Returns the correct handler needed depending on the type of resource
@@ -2398,14 +2448,15 @@ def get_facts_handler(
         volumes (list, optional) -- Volumes where a data set is allocated.
         tmp_hlq (str, optional) -- Temp HLQ for certain data set operations.
         sms_managed (bool, optional) -- Whether a data set is managed by SMS.
+        recall (bool, optional) -- Whether migrated data sets should be recalled.
         file_args (dict, optional) -- Options affecting how a file is query.
 
     Returns
     -------
         FactsHandler -- Handler for data sets/GDGs/aggregates/files.
     """
     if resource_type == 'data_set':
-        return get_data_set_handler(name, volumes, module, tmp_hlq, sms_managed)
+        return get_data_set_handler(name, volumes, module, tmp_hlq, sms_managed, recall)
     elif resource_type == 'gdg':
         return GenerationDataGroupHandler(name, module, tmp_hlq)
     elif resource_type == 'file':
@@ -2441,6 +2492,11 @@ def run_module():
                 'required': False,
                 'default': False
             },
+            'recall': {
+                'type': 'bool',
+                'required': False,
+                'default': False
+            },
             'tmp_hlq': {
                 'type': 'str',
                 'required': False
@@ -2490,6 +2546,10 @@ def run_module():
             'arg_type': 'bool',
             'required': False
         },
+        'recall': {
+            'arg_type': 'bool',
+            'required': False
+        },
         'tmp_hlq': {
             'arg_type': 'str',
             'required': False
@@ -2527,6 +2587,7 @@ def run_module():
     resource_type = module.params.get('type')
     tmp_hlq = module.params.get('tmp_hlq')
     sms_managed = module.params.get('sms_managed')
+    recall = module.params.get('recall')
     file_args = {
         'follow': module.params.get('follow'),
         'get_mime': module.params.get('get_mime'),
@@ -2542,6 +2603,7 @@ def run_module():
             volumes,
             tmp_hlq,
             sms_managed,
+            recall,
             file_args
         )
     except QueryException as err: