[enhancement][mvs_raw]Implement_max_rc_mvs_raw (#1813)

* Add test case and max_rc option

* Add fragment

* Update 1813-implement_max_rc_mvs_raw.yml

* Update plugins/modules/zos_mvs_raw.py

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

* Update changelogs/fragments/1813-implement_max_rc_mvs_raw.yml

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

* Fix comments generate defaults and more

* Fix documentation

* Change documentation

* Update 1813-implement_max_rc_mvs_raw.yml

* Update changelogs/fragments/1813-implement_max_rc_mvs_raw.yml

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

---------

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

Author: AndreMarcel99

changelogs/fragments/1813-implement_max_rc_mvs_raw.yml

@@ -0,0 +1,6 @@
+minor_changes:
+  - zos_mvs_raw - Added ``max_rc`` option. Now when the user sets ``max_rc``, the module tolerates the failure
+     if the return code is smaller than the ``max_rc`` specified, however, return value ``changed`` will be False if
+     the program return code is not 0.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1813).
+    

plugins/modules/zos_mvs_raw.py

@@ -58,6 +58,13 @@
     required: false
     type: bool
     default: false
+  max_rc:
+    description:
+      - Specifies the maximum return code allowed for the program output. If the
+        program generates a return code higher than the specified maximum, the module will fail.
+    required: false
+    type: int
+    default: 0
   dds:
     description:
       - The input data source.
@@ -1852,6 +1859,7 @@ def run_module():
         verbose=dict(type="bool", default=False),
         parm=dict(type="str", required=False),
         tmp_hlq=dict(type="str", required=False, default=None),
+        max_rc=dict(type="int", required=False, default=0),
         dds=dict(
             type="list",
             elements="dict",
@@ -1890,6 +1898,7 @@ def run_module():
             program_parm = parms.get("parm")
             authorized = parms.get("auth")
             verbose = parms.get("verbose")
+            max_rc = parms.get("max_rc")
             program_response = run_zos_program(
                 program=program,
                 parm=program_parm,
@@ -1900,13 +1909,18 @@ def run_module():
             )
             response = build_response(program_response.rc, dd_statements, program_response.stdout, program_response.stderr)
             result = combine_dicts(result, response)
-            if program_response.rc != 0 :
+
+            if program_response.rc > max_rc:
                 raise ZOSRawError(
                     program,
                     "{0} {1}".format(program_response.stdout, program_response.stderr),
                 )
 
-            result["changed"] = True
+            if program_response.rc != 0:
+                result["changed"] = False
+            else:
+                result["changed"] = True
+
         except Exception as e:
             result["backups"] = backups
             module.fail_json(msg=repr(e), **result)
@@ -2085,6 +2099,7 @@ def parse_and_validate_args(params):
         verbose=dict(type="bool", default=False),
         parm=dict(type="str", required=False),
         tmp_hlq=dict(type="qualifier_or_empty", required=False, default=None),
+        max_rc=dict(type="int", required=False, default=0),
         dds=dict(
             type="list",
             elements="dict",

tests/functional/modules/test_zos_mvs_raw_func.py

@@ -978,6 +978,37 @@ def test_data_set_name_special_characters(ansible_zos_module):
         if idcams_dataset:
             hosts.all.zos_data_set(name=idcams_dataset, state="absent")
 
+@pytest.mark.parametrize("max_rc", [4, 8])
+def test_new_disposition_for_data_set_members_max_rc(ansible_zos_module, max_rc):
+    hosts = ansible_zos_module
+    results = hosts.all.zos_mvs_raw(
+        program_name="idcams",
+        auth=True,
+        max_rc=max_rc,
+        dds=[
+            {
+                "dd_output":{
+                    "dd_name":"sysprint",
+                    "return_content":{
+                        "type":"text"
+                    }
+                }
+            },
+            {
+                "dd_input":{
+                    "dd_name":"sysin",
+                    "content":" DELETE THIS.DATASET.DOES.NOT.EXIST"
+                }
+            },
+        ],
+    )
+    for result in results.contacted.values():
+        assert result.get("changed") is False
+        assert result.get("ret_code", {}).get("code", -1) == 8
+        if max_rc != 8:
+            assert result.get("msg") is not None
+            assert result.get("failed") is True
+
 # ---------------------------------------------------------------------------- #
 #                                 Input DD Tests                                #
 # ---------------------------------------------------------------------------- #