[Enhancement] [zos_stat] Extra return values for automation (#2137)

* Add new boolean fields

* Update test cases with new boolean fields

* Update module RST file

* Add `exists` return field

* Update tests with new field

* Update zos_stat's RST file

* Add changelog fragment

Author: rexemin

changelogs/fragments/2137-zos_stat-new-fields.yml

@@ -0,0 +1,8 @@
+minor_changes:
+  - zos_stat - Adds new fields that describe the type of the resource
+    that was queried. These new fields are `isfile`, `isdataset`,
+    `isaggregate` and `isgdg`.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2137)
+  - zos_stat - Module now returns whether the resource queried exists
+    on the managed node with the `exists` field inside `stat`.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2137)

docs/source/modules/zos_stat.rst

@@ -264,6 +264,61 @@ stat
     | **type**: str
     | **sample**: data_set
 
+  exists
+    Whether name was found on the managed node.
+
+    | **returned**: success
+    | **type**: bool
+    | **sample**:
+
+      .. code-block:: json
+
+          true
+
+  isfile
+    Whether name is a Unix System Services file.
+
+    | **returned**: success
+    | **type**: bool
+    | **sample**:
+
+      .. code-block:: json
+
+          true
+
+  isdataset
+    Whether name is a data set.
+
+    | **returned**: success
+    | **type**: bool
+    | **sample**:
+
+      .. code-block:: json
+
+          true
+
+  isaggregate
+    Whether name is an aggregate.
+
+    | **returned**: success
+    | **type**: bool
+    | **sample**:
+
+      .. code-block:: json
+
+          true
+
+  isgdg
+    Whether name is a Generation Data Group.
+
+    | **returned**: success
+    | **type**: bool
+    | **sample**:
+
+      .. code-block:: json
+
+          true
+
   attributes
     Dictionary containing all the stat data.
 

plugins/modules/zos_stat.py

@@ -242,6 +242,31 @@
       returned: success
       type: str
       sample: data_set
+    exists:
+      description: Whether name was found on the managed node.
+      returned: success
+      type: bool
+      sample: true
+    isfile:
+      description: Whether name is a Unix System Services file.
+      returned: success
+      type: bool
+      sample: true
+    isdataset:
+      description: Whether name is a data set.
+      returned: success
+      type: bool
+      sample: true
+    isaggregate:
+      description: Whether name is an aggregate.
+      returned: success
+      type: bool
+      sample: true
+    isgdg:
+      description: Whether name is a Generation Data Group.
+      returned: success
+      type: bool
+      sample: true
     attributes:
       description: Dictionary containing all the stat data.
       returned: success
@@ -1131,6 +1156,10 @@ def query(self):
             attributes = {
                 'name': self.name,
                 'resource_type': 'aggregate',
+                'isfile': False,
+                'isdataset': False,
+                'isaggregate': True,
+                'isgdg': False,
                 'attributes': {
                     'total_size': int(size_search.group(3)),
                     'free': int(size_search.group(1)),
@@ -1253,6 +1282,10 @@ def query(self):
             attributes = {
                 'name': self.name,
                 'resource_type': 'file',
+                'isfile': True,
+                'isdataset': False,
+                'isaggregate': False,
+                'isgdg': False,
                 'attributes': {
                     'mode': "%04o" % stat.S_IMODE(mode),
                     'atime': raw_attributes.st_atime,
@@ -1456,6 +1489,10 @@ def query(self):
         """
         data = {
             'resource_type': 'data_set',
+            'isfile': False,
+            'isdataset': True,
+            'isaggregate': False,
+            'isgdg': False,
             'name': self.alias if self.alias else self.name
         }
         return data
@@ -2181,7 +2218,11 @@ def query(self):
         a GDG's attributes and current active generations."""
         data = {
             'resource_type': 'gdg',
-            'name': self.name
+            'name': self.name,
+            'isfile': False,
+            'isdataset': False,
+            'isaggregate': False,
+            'isgdg': True
         }
 
         attributes = {
@@ -2612,8 +2653,13 @@ def run_module():
     result = {}
 
     if not facts_handler.exists():
-        result['msg'] = f'{name} could not be found on the system.'
-        module.fail_json(**result)
+        result['stat'] = {
+            'name': name,
+            'resource_type': resource_type,
+            'exists': False
+        }
+        result['changed'] = False
+        module.exit_json(**result)
 
     try:
         data = facts_handler.query()
@@ -2632,6 +2678,7 @@ def run_module():
 
     result['stat'] = fill_return_json(data)
     result['changed'] = True
+    result['stat']['exists'] = True
     if notes:
         result['notes'] = notes
 

tests/functional/modules/test_zos_stat_func.py

@@ -195,6 +195,11 @@ def test_query_data_set_seq_no_volume(ansible_zos_module, volumes_on_systems):
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'ps'
@@ -262,6 +267,11 @@ def test_query_data_set_pds_no_volume(ansible_zos_module, volumes_on_systems):
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'po'
@@ -330,6 +340,11 @@ def test_query_data_set_pdse_no_volume(ansible_zos_module, volumes_on_systems):
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'po'
@@ -394,6 +409,11 @@ def test_query_data_set_vsam_ksds(ansible_zos_module):
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'vsam'
@@ -477,6 +497,11 @@ def test_query_data_set_gds(ansible_zos_module, volumes_on_systems):
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert name in stat.get('name')
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'ps'
@@ -548,6 +573,11 @@ def test_query_data_set_seq_with_correct_volume(ansible_zos_module, volumes_on_s
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'ps'
@@ -609,8 +639,9 @@ def test_query_data_set_seq_with_wrong_volume(ansible_zos_module, volumes_on_sys
 
         for result in zos_stat_result.contacted.values():
             assert result.get('changed', False) is False
-            assert result.get('failed') is True
-            assert 'could not be found' in result.get('msg', '')
+            assert result.get('failed', False) is False
+            assert result.get('stat') is not None
+            assert result.get('stat').get('exists') is False
     finally:
         hosts.all.shell(
             cmd=f'drm {escaped_name}'
@@ -659,6 +690,11 @@ def test_query_data_set_seq_multi_volume(ansible_zos_module, volumes_on_systems)
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'ps'
@@ -733,6 +769,11 @@ def test_query_data_set_seq_multi_volume_missing_one(ansible_zos_module, volumes
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'ps'
@@ -789,6 +830,11 @@ def test_query_gdg(ansible_zos_module):
             stat = result['stat']
             assert stat.get('resource_type') == 'gdg'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is False
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is True
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('limit') == limit
@@ -833,6 +879,11 @@ def test_query_aggregate(ansible_zos_module):
         stat = result['stat']
         assert stat.get('resource_type') == 'aggregate'
         assert stat.get('name') == aggregate_name
+        assert stat.get('exists') is True
+        assert stat.get('isfile') is False
+        assert stat.get('isdataset') is False
+        assert stat.get('isaggregate') is True
+        assert stat.get('isgdg') is False
         assert stat.get('attributes') is not None
 
         assert stat['attributes'].get('total_size') is not None
@@ -871,6 +922,11 @@ def test_query_file_no_symlink(ansible_zos_module):
         stat = result['stat']
         assert stat.get('resource_type') == 'file'
         assert stat.get('name') == test_file
+        assert stat.get('exists') is True
+        assert stat.get('isfile') is True
+        assert stat.get('isdataset') is False
+        assert stat.get('isaggregate') is False
+        assert stat.get('isgdg') is False
         assert stat.get('attributes') is not None
 
         for attr in EXPECTED_ATTRS['file']['flat']:
@@ -902,6 +958,11 @@ def test_query_file_no_checksum_no_mime(ansible_zos_module):
         stat = result['stat']
         assert stat.get('resource_type') == 'file'
         assert stat.get('name') == test_file
+        assert stat.get('exists') is True
+        assert stat.get('isfile') is True
+        assert stat.get('isdataset') is False
+        assert stat.get('isaggregate') is False
+        assert stat.get('isgdg') is False
         assert stat.get('attributes') is not None
 
         for attr in EXPECTED_ATTRS['file']['flat']:
@@ -949,6 +1010,11 @@ def test_query_file_symlink_follow_on(ansible_zos_module):
             stat = result['stat']
             assert stat.get('resource_type') == 'file'
             assert stat.get('name') == test_file
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is True
+            assert stat.get('isdataset') is False
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             # When following links, these two attributes should be None.
@@ -998,6 +1064,11 @@ def test_query_file_symlink_follow_off(ansible_zos_module):
             stat = result['stat']
             assert stat.get('resource_type') == 'file'
             assert stat.get('name') == test_file
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is True
+            assert stat.get('isdataset') is False
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             for attr in EXPECTED_ATTRS['file']['flat']:
@@ -1026,8 +1097,9 @@ def test_query_data_set_non_existent(ansible_zos_module, resource_type):
 
     for result in zos_stat_result.contacted.values():
         assert result.get('changed', False) is False
-        assert result.get('failed') is True
-        assert 'could not be found' in result.get('msg', '')
+        assert result.get('failed', False) is False
+        assert result.get('stat') is not None
+        assert result.get('stat').get('exists') is False
 
 
 def test_query_data_set_tmp_hlq(ansible_zos_module, volumes_on_systems):
@@ -1062,6 +1134,11 @@ def test_query_data_set_tmp_hlq(ansible_zos_module, volumes_on_systems):
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == name
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
     finally:
         hosts.all.shell(cmd=f'drm {name}')
@@ -1119,6 +1196,11 @@ def test_query_data_set_seq_with_alias(ansible_zos_module, volumes_on_systems):
             stat = result['stat']
             assert stat.get('resource_type') == 'data_set'
             assert stat.get('name') == alias
+            assert stat.get('exists') is True
+            assert stat.get('isfile') is False
+            assert stat.get('isdataset') is True
+            assert stat.get('isaggregate') is False
+            assert stat.get('isgdg') is False
             assert stat.get('attributes') is not None
 
             assert stat['attributes'].get('dsorg') == 'ps'