[zos_job_submit] Fix TYPRUN=COPY, TYPRUN=HOLD and TYPRUN=JCLHOLD handling (#2229)

* Fix TYPRUN handling

* Add changelog fragment

* Remove commented code

* Update module documentation

Author: rexemin

changelogs/fragments/2229-job-typrun-support.yml

@@ -0,0 +1,7 @@
+minor_changes:
+  - zos_job_submit - Adds support for jobs with TYPRUN=JCLHOLD and TYPRUN=HOLD.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2229).
+trivial:
+  - zos_job_submit - Fixes a regression on ZOAU v1.3.6.0 where a job submitted
+    with TYPRUN=COPY would return an error.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2229).

docs/source/modules/zos_job_submit.rst

@@ -383,6 +383,7 @@ jobs
                 "asid": 0,
                 "class": "K",
                 "content_type": "JOB",
+                "cpu_time": 1,
                 "creation_date": "2023-05-03",
                 "creation_time": "12:13:00",
                 "ddnames": [
@@ -579,10 +580,12 @@ jobs
                         "stepname": "DLORD6"
                     }
                 ],
+                "execution_node": "STL1",
                 "execution_time": "00:00:10",
                 "job_class": "K",
                 "job_id": "JOB00361",
                 "job_name": "DBDGEN00",
+                "origin_node": "STL1",
                 "owner": "OMVSADM",
                 "priority": 1,
                 "program_name": "IEBGENER",
@@ -763,7 +766,9 @@ jobs
 
       Job status `TYPRUN=SCAN` indicates that the job had the TYPRUN parameter with SCAN option.
 
-      Job status `NOEXEC` indicates that the job had the TYPRUN parameter with COPY option.
+      Job status `TYPRUN=COPY` indicates that the job had the TYPRUN parameter with COPY option.
+
+      Job status `HOLD` indicates that the job had the TYPRUN parameter with either the HOLD or JCLHOLD options.
 
       Jobs where status can not be determined will result in None (NULL).
 
@@ -858,4 +863,34 @@ jobs
     | **type**: str
     | **sample**: IEBGENER
 
+  system
+    The job entry system that MVS uses to do work.
+
+    | **type**: str
+    | **sample**: STL1
+
+  subsystem
+    The job entry subsystem that MVS uses to do work.
+
+    | **type**: str
+    | **sample**: STL1
+
+  cpu_time
+    Sum of the CPU time used by each job step, in microseconds.
+
+    | **type**: int
+    | **sample**: 5
+
+  execution_node
+    Execution node that picked the job and executed it.
+
+    | **type**: str
+    | **sample**: STL1
+
+  origin_node
+    Origin node that submitted the job.
+
+    | **type**: str
+    | **sample**: STL1
+
 

plugins/modules/zos_job_submit.py

@@ -272,7 +272,8 @@
             - Job status `SYS` indicates a system failure.
             - Job status `?` indicates status can not be determined.
             - Job status `TYPRUN=SCAN` indicates that the job had the TYPRUN parameter with SCAN option.
-            - Job status `NOEXEC` indicates that the job had the TYPRUN parameter with COPY option.
+            - Job status `TYPRUN=COPY` indicates that the job had the TYPRUN parameter with COPY option.
+            - Job status `HOLD` indicates that the job had the TYPRUN parameter with either the HOLD or JCLHOLD options.
             - Jobs where status can not be determined will result in None (NULL).
           type: str
           sample: AC
@@ -1116,8 +1117,9 @@ def run_module():
                 result["execution_time"] = job_output_txt[0].get("execution_time")
 
             result["duration"] = duration
+            job_msg = job_output_txt[0].get("ret_code", {}).get("msg")
 
-            if duration >= wait_time_s:
+            if duration >= wait_time_s and job_msg != "HOLD":
                 result["failed"] = True
                 result["changed"] = False
                 _msg = ("The JCL submitted with job id {0} but appears to be a long "
@@ -1161,19 +1163,13 @@ def run_module():
                                 job_ret_code.update({"msg_txt": _msg})
                                 raise Exception(_msg)
 
-                    if job_ret_code_code is not None and job_ret_code_msg == 'NOEXEC':
-                        job_dd_names = job_output_txt[0].get("ddnames")
-                        jes_jcl_dd = search_dictionaries("ddname", "JESJCL", job_dd_names)
-                        # These are the conditions for a job run with TYPRUN=COPY.
-                        if not jes_jcl_dd:
-                            job_ret_code.update({"msg": "TYPRUN=COPY"})
-                            _msg = ("The job was run with TYPRUN=COPY. "
-                                    "This way, the steps are not executed, but the JCL is validated and stored "
-                                    "in the JES spool. "
-                                    "Please review the job log for further details.")
-                            job_ret_code.update({"msg_txt": _msg})
-
-                    if job_ret_code_code is None or job_ret_code.get("msg") == 'NOEXEC':
+                    if job_ret_code_msg == 'HOLD':
+                        _msg = ("The job was run with TYPRUN=HOLD or TYPRUN=JCLHOLD "
+                                "to request special job processing. This will result in no completion, "
+                                "no return code, no job steps and changed will be set to false.")
+                        job_ret_code.update({"msg_txt": _msg})
+                        is_changed = False
+                    elif job_ret_code_code is None and job_ret_code.get("msg") == 'NOEXEC':
                         # If there is no job_ret_code_code (Job return code) it may NOT be an error,
                         # some jobs will never return have an RC, eg Started tasks(which are not supported),
                         # so further analyze the
@@ -1183,21 +1179,21 @@ def run_module():
                         jes_jcl_dd = search_dictionaries("ddname", "JESJCL", job_dd_names)
 
                         # Its possible jobs don't have a JESJCL which are active and this would
-                        # cause an index out of range error.
+                        # mean the job had TYPRUN=COPY.
                         if not jes_jcl_dd:
-                            _msg_detail = " for status {0}.".format(job_ret_code_msg) if job_ret_code_msg else "."
-                            _msg = ("The job return code was not available in the job log, "
-                                    "please review the job log{0}".format(_msg_detail))
+                            job_ret_code.update({"msg": "TYPRUN=COPY"})
+                            _msg = ("The job was run with TYPRUN=COPY. "
+                                    "This way, the steps are not executed, but the JCL is validated and stored "
+                                    "in the JES spool. "
+                                    "Please review the job log for further details.")
                             job_ret_code.update({"msg_txt": _msg})
-                            raise Exception(_msg)
-
-                        jes_jcl_dd_content = jes_jcl_dd[0].get("content")
-                        jes_jcl_dd_content_str = " ".join(jes_jcl_dd_content)
-                        # The regex can be r"({0})\s*=\s*(COPY|HOLD|JCLHOLD|SCAN)" once zoau support is in.
-                        special_processing_keyword = re.search(r"({0})\s*=\s*(SCAN)"
-                                                               .format("|".join(JOB_SPECIAL_PROCESSING)), jes_jcl_dd_content_str)
+                        else:
+                            jes_jcl_dd_content = jes_jcl_dd[0].get("content")
+                            jes_jcl_dd_content_str = " ".join(jes_jcl_dd_content)
+                            # The regex can be r"({0})\s*=\s*(COPY|HOLD|JCLHOLD|SCAN)" once zoau support is in.
+                            special_processing_keyword = re.search(r"({0})\s*=\s*(SCAN)"
+                                                                   .format("|".join(JOB_SPECIAL_PROCESSING)), jes_jcl_dd_content_str)
 
-                        if job_ret_code_msg == 'NOEXEC':
                             job_ret_code.update({"msg": special_processing_keyword[0]})
                             job_ret_code.update({"code": None})
                             job_ret_code.update({"msg_code": None})
@@ -1206,19 +1202,17 @@ def run_module():
                                                  "return code or job steps and changed will be false."
                                                  .format(job_submitted_id, special_processing_keyword[0])})
                             is_changed = False
-                        else:
-                            # The job_ret_code_code is None at this point, but the job_ret_code_msg_code could be populated
-                            # so check both and provide a proper response.
+                    elif job_ret_code_code is None:
+                        # The job_ret_code_code is None at this point, but the job_ret_code_msg_code could be populated
+                        # so check both and provide a proper response.
 
-                            if job_ret_code_msg_code is None:
-                                _msg_detail = " for status {0}.".format(job_ret_code_msg) if job_ret_code_msg else "."
-                                _msg = ("The job return code was not available in the job log, "
-                                        "please review the job log{0}".format(_msg_detail))
-                                job_ret_code.update({"msg_txt": _msg})
-                                raise Exception(_msg)
+                        if job_ret_code_msg_code is None:
+                            _msg_detail = " for status {0}.".format(job_ret_code_msg) if job_ret_code_msg else "."
+                            _msg = ("The job return code was not available in the job log, "
+                                    "please review the job log{0}".format(_msg_detail))
+                            job_ret_code.update({"msg_txt": _msg})
+                            raise Exception(_msg)
 
-                            # raise Exception("The job return code was not available in the job log, "
-                            #                 "please review the job log and error {0}.".format(job_ret_code_msg))
                     elif job_ret_code_code != 0 and max_rc is None:
                         _msg = ("The job return code {0} was non-zero in the "
                                 "job output, this job has failed.".format(str(job_ret_code_code)))

tests/functional/modules/test_zos_job_submit_func.py

@@ -1014,8 +1014,8 @@ def test_job_submit_local_jcl_typrun_copy(ansible_zos_module):
                                             "to": "IBM-1047"
                                         },)
     for result in results.contacted.values():
-        # With ZOAU 1.3.3 changes now code and return msg_code are 0 and 0000 respectively.
-        # assert result.get("changed") is False
+        # With ZOAU 1.3.6 changes now code and return msg_code are both None, now
+        # being consistent with the rest of the possible TYPRUN cases.
         # When running a job with TYPRUN=COPY, a copy of the JCL will be kept in the JES spool, so
         # effectively, the system is changed even though the job didn't run.
         assert result.get("changed") is True
@@ -1024,12 +1024,9 @@ def test_job_submit_local_jcl_typrun_copy(ansible_zos_module):
             r'The job was run with TYPRUN=COPY.',
             repr(result.get("jobs")[0].get("ret_code").get("msg_txt"))
         )
-        assert result.get("jobs")[0].get("ret_code").get("code") == 0
+        assert result.get("jobs")[0].get("ret_code").get("code") is None
         assert result.get("jobs")[0].get("ret_code").get("msg") == 'TYPRUN=COPY'
-        assert result.get("jobs")[0].get("ret_code").get("msg_code") == '0000'
-        # assert result.get("jobs")[0].get("ret_code").get("code") is None
-        # assert result.get("jobs")[0].get("ret_code").get("msg") is None
-        # assert result.get("jobs")[0].get("ret_code").get("msg_code") is None
+        assert result.get("jobs")[0].get("ret_code").get("msg_code") is None
 
 
 def test_job_submit_local_jcl_typrun_hold(ansible_zos_module):
@@ -1048,11 +1045,11 @@ def test_job_submit_local_jcl_typrun_hold(ansible_zos_module):
         assert result.get("changed") is False
         assert result.get("jobs")[0].get("job_id") is not None
         assert re.search(
-            r'long running job',
+            r'The job was run with TYPRUN=HOLD or TYPRUN=JCLHOLD',
             repr(result.get("jobs")[0].get("ret_code").get("msg_txt"))
         )
         assert result.get("jobs")[0].get("ret_code").get("code") is None
-        assert result.get("jobs")[0].get("ret_code").get("msg") == "AC"
+        assert result.get("jobs")[0].get("ret_code").get("msg") == "HOLD"
         assert result.get("jobs")[0].get("ret_code").get("msg_code") is None
 
 
@@ -1072,11 +1069,11 @@ def test_job_submit_local_jcl_typrun_jclhold(ansible_zos_module):
         assert result.get("changed") is False
         assert result.get("jobs")[0].get("job_id") is not None
         assert re.search(
-            r'long running job',
+            r'The job was run with TYPRUN=HOLD or TYPRUN=JCLHOLD',
             repr(result.get("jobs")[0].get("ret_code").get("msg_txt"))
         )
         assert result.get("jobs")[0].get("ret_code").get("code") is None
-        assert result.get("jobs")[0].get("ret_code").get("msg") == "AC"
+        assert result.get("jobs")[0].get("ret_code").get("msg") == "HOLD"
         assert result.get("jobs")[0].get("ret_code").get("msg_code") is None