[Enabler][2148]update_zos_job_query_module (#2204)

AndreMarcel99 · fernandofloresg · André Marcel Gutiérrez Benítez · web-flow · commit 0a6c24cab6da · 2025-07-12T10:58:01.000-06:00
* Change interface

* Remove lines

* Update documentation

* Move steps out of ret_code

* Adjust documentation for steps and module

* Replace steps on test suite

* Fix documentation

* Add fragment

* Update changelogs/fragments/2204-Update_zos_job_query_module.yml

Co-authored-by: Fernando Flores &lt;fernandofloresdev@gmail.com&gt;

* Fix null for none

---------

Co-authored-by: Fernando Flores &lt;fernandofloresdev@gmail.com&gt;
Co-authored-by: André Marcel Gutiérrez Benítez &lt;Andre.Marcel.Gutierrez@ibm.com&gt;
diff --git a/changelogs/fragments/2204-Update_zos_job_query_module.yml b/changelogs/fragments/2204-Update_zos_job_query_module.yml
@@ -0,0 +1,3 @@
+breaking_changes:
+  - zos_job_query - Return value ``message`` is deprecated in favor of ``msg``. Return value ``steps`` are no longer under `` but is now included under jobs.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2204).
diff --git a/plugins/module_utils/job.py b/plugins/module_utils/job.py
@@ -381,7 +381,7 @@ def _get_job_status(job_id="*", owner="*", job_name="*", dd_name=None, dd_scan=T
             job["queue_position"] = entry.queue_position
             job["program_name"] = entry.program_name
             job["class"] = ""
-            job["ret_code"]["steps"] = []
+            job["steps"] = []
             job["ddnames"] = []
             job["duration"] = duration
             if hasattr(entry, "execution_time"):
@@ -493,7 +493,7 @@ def _get_job_status(job_id="*", owner="*", job_name="*", dd_name=None, dd_scan=T
 
                     dd["content"] = tmpcont.split("\n")
 
-                    job["ret_code"]["steps"].extend(_parse_steps(tmpcont))
+                    job["steps"].extend(_parse_steps(tmpcont))
 
                     job["ddnames"].append(dd)
                     if len(job["class"]) < 1:
diff --git a/plugins/modules/zos_job_query.py b/plugins/modules/zos_job_query.py
@@ -108,6 +108,7 @@
     True if the state was changed, otherwise False.
   returned: always
   type: bool
+  sample: True
 jobs:
   description:
     The output information for a list of jobs matching specified criteria.
@@ -153,21 +154,21 @@
          The job entry subsystem that MVS uses to do work.
       type: str
       sample: STL1
-    cpu_time:
+    origin_node:
       description:
-        Sum of the CPU time used by each job step, in microseconds.
-      type: int
-      sample: 5
+        Origin node that submitted the job.
+      type: str
+      sample: "STL1"
     execution_node:
       description:
         Execution node that picked the job and executed it.
       type: str
       sample: "STL1"
-    origin_node:
+    cpu_time:
       description:
-        Origin node that submitted the job.
-      type: str
-      sample: "STL1"
+        Sum of the CPU time used by each job step, in microseconds.
+      type: int
+      sample: 5
     ret_code:
       description:
          Return code output collected from job log.
@@ -210,19 +211,35 @@
                 The CC returned for this step in the DD section.
               type: int
               sample: 0
-
       sample:
         ret_code: {
          "msg": "CC 0000",
          "msg_code": "0000",
          "msg_txt": "",
-         "code": 0,
-         "steps": [
-            { "step_name": "STEP0001",
-              "step_cc": 0
-            }
-          ]
+         "code": 0
         }
+    steps:
+      description:
+        Series of JCL steps that were executed and their return codes.
+      type: list
+      elements: dict
+      contains:
+        step_name:
+          description:
+            Name of the step shown as "was executed" in the DD section.
+          type: str
+          sample: "STEP0001"
+        step_cc:
+          description:
+            The CC returned for this step in the DD section.
+          type: int
+          sample: 0
+      sample:
+        "steps": [
+          { "step_name": "STEP0001",
+            "step_cc": 0
+          }
+        ]
     job_class:
       description:
         Job class for this job.
@@ -277,14 +294,20 @@
             "job_name": "LINKJOB",
             "owner": "ADMIN",
             "job_id": "JOB01427",
-            "ret_code": "null",
-            "job_class": "K",
             "content_type": "JOB",
-            "svc_class": "?",
+            "ret_code": { "msg" : "CC", "msg_code" : "0000", "code" : "0", msg_txt : "CC" },
+            "steps": [
+              { "step_name": "STEP0001",
+                "step_cc": 0
+              }
+            ],
+            "job_class": "STC",
+            "svc_class": "null",
             "priority": 1,
             "asid": 0,
             "creation_date": "2023-05-03",
             "creation_time": "12:13:00",
+            "program_name": "BPXBATCH",
             "queue_position": 3,
             "execution_time": "00:00:02",
             "system": "STL1",
@@ -298,7 +321,8 @@
             "owner": "ADMIN",
             "job_id": "JOB16577",
             "content_type": "JOB",
-            "ret_code": { "msg": "CANCELED", "code": "null" },
+            "ret_code": { "msg" : "CANCELED", "msg_code" : "null", "code" : "null", msg_txt : "CANCELED" },
+            "steps" : [],
             "job_class": "A",
             "svc_class": "E",
             "priority": 0,
@@ -307,14 +331,15 @@
             "creation_time": "12:14:00",
             "queue_position": 0,
             "execution_time": "00:00:03",
+            "program_name": "null",
             "system": "STL1",
             "subsystem": "STL1",
             "cpu_time": 1414,
             "execution_node": "STL1",
             "origin_node": "STL1"
         },
     ]
-message:
+msg:
   description:
      Message returned on failure.
   type: str
@@ -349,7 +374,7 @@ def run_module():
         job_id=dict(type="str", required=False),
     )
 
-    result = dict(changed=False, message="")
+    result = dict(changed=False)
 
     module = AnsibleModule(argument_spec=module_args, supports_check_mode=True)
 
@@ -379,6 +404,7 @@ def run_module():
         jobs_raw = query_jobs(name, id, owner)
         if jobs_raw:
             jobs = parsing_jobs(jobs_raw)
+            result["changed"] = True
         else:
             jobs = None
 
@@ -436,8 +462,8 @@ def parsing_jobs(jobs_raw):
         Parsed jobs.
     """
     jobs = []
-    ret_code = {}
     for job in jobs_raw:
+        ret_code = job.get("ret_code")
         # Easier to see than checking for an empty string, JOB NOT FOUND was
         # replaced with None in the jobs.py and msg_txt field describes the job query instead
         if job.get("ret_code") is None:
@@ -449,30 +475,32 @@ def parsing_jobs(jobs_raw):
 
         if "AC" in status_raw:
             # the job is active
-            ret_code = None
+            ret_code["msg"] = None
+            ret_code["msg_code"] = None
+            ret_code["code"] = None
+            ret_code["msg_txt"] = None
+
         elif "CC" in status_raw:
             # status = 'Completed normally'
-            ret_code = {
-                "msg": status_raw,
-                "code": job.get("ret_code").get("code"),
-            }
+            ret_code["msg"] = status_raw
+
         elif "ABEND" in status_raw:
             # status = 'Ended abnormally'
-            ret_code = {
-                "msg": status_raw,
-                "code": job.get("ret_code").get("code"),
-            }
+            ret_code["msg"] = status_raw
+
         elif "ABENDU" in status_raw:
             # status = 'Ended abnormally'
-            ret_code = {"msg": status_raw, "code": job.get("ret_code").get("code")}
+            ret_code["msg"] = status_raw
 
         elif "CANCELED" in status_raw or "JCLERR" in status_raw or "JCL ERROR" in status_raw or "JOB NOT FOUND" in status_raw:
             # status = status_raw
-            ret_code = {"msg": status_raw, "code": None}
+            ret_code["msg"] = status_raw
+            ret_code["code"] = None
+            ret_code["msg_code"] = None
 
         else:
             # status = 'Unknown'
-            ret_code = {"msg": status_raw, "code": job.get("ret_code").get("code")}
+            ret_code["msg"] = status_raw
 
         job_dict = {
             "job_name": job.get("job_name"),
@@ -485,6 +513,7 @@ def parsing_jobs(jobs_raw):
             "execution_node": job.get("execution_node"),
             "origin_node": job.get("origin_node"),
             "ret_code": ret_code,
+            "steps": job.get("steps"),
             "job_class": job.get("job_class"),
             "svc_class": job.get("svc_class"),
             "priority": job.get("priority"),
diff --git a/tests/functional/modules/test_zos_job_query_func.py b/tests/functional/modules/test_zos_job_query_func.py

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+breaking_changes:`
	`2`	+ - zos_job_query - Return value ``message`` is deprecated in favor of ``msg``. Return value ``steps`` are no longer under `` but is now included under jobs.
	`3`	`+ (https://github.com/ansible-collections/ibm_zos_core/pull/2204).`