add rc to executions, generate doc for executions

Signed-off-by: Andrew Twydell <[email protected]>

Author: AndrewTwydell

docs/source/modules/stop_region.rst

@@ -183,7 +183,7 @@ Return Values
         rc
           | The return code for the program execution.
       
-          | **returned**: on shutdown execution
+          | **returned**: always
           | **type**: int
       
 
@@ -204,10 +204,18 @@ Return Values
       
 
 
+         failed
+            | True if the module failed, otherwise False.
+      
+            | **returned**: always
+            | **type**: bool
+      
+      
+                              
          jobs
             | The output information for a list of jobs matching specified criteria.
       
-            | **returned**: success
+            | **returned**: on zos_job_query module execution
             | **type**: list
               
 
@@ -298,16 +306,82 @@ Return Values
          message
             | Message returned on failure.
       
-            | **returned**: failure
+            | **returned**: on zos_job_query module execution
             | **type**: str
       
 
 
          content
             | The resulting text from the command submitted.
       
-            | **returned**: on success of PERFORM SHUTDOWN command submission.
+            | **returned**: on zos_operator module execution
+            | **type**: list
+      
+      
+                              
+         cmd
+            | The operator command that has been executed
+      
+            | **returned**: on zos_operator module execution
+            | **type**: str
+      
+      
+                              
+         rc
+            | The return code from the operator command
+      
+            | **returned**: on zos_operator module execution
+            | **type**: int
+      
+      
+                              
+         max_rc
+            | The maximum return code from the tso status command
+      
+            | **returned**: on zos_tso_command module execution
+            | **type**: int
+      
+      
+                              
+         output
+            | The output from the tso command
+      
+            | **returned**: on zos_tso_command module execution
             | **type**: list
+              
+   
+                              
+          command
+              | The executed TSO command.
+      
+              | **returned**: always
+              | **type**: str
+      
+      
+                              
+          rc
+              | The return code from the executed TSO command.
+      
+              | **returned**: always
+              | **type**: int
+      
+      
+                              
+          content
+              | The response resulting from the execution of the TSO command.
+      
+              | **returned**: always
+              | **type**: list
+      
+      
+                              
+          lines
+              | The line number of the content.
+      
+              | **returned**: always
+              | **type**: int
+      
+        
 
 
 

plugins/action/stop_region.py

@@ -195,6 +195,7 @@ def _get_running_jobs(self):
     def _add_status_execution(self, job, result):
         self.executions.append({
             NAME: CHECK_CICS_STATUS.format(job),
+            RC: result.get("max_rc"),
             RETURN: result,
         })
 
@@ -241,6 +242,7 @@ def execute_zos_job_query(self, job_id):
         )
         self.executions.append({
             NAME: "ZOS Job Query - {0}".format(job_id),
+            RC: 0 if query_response.get("message", "-") == "" and isinstance(query_response.get("jobs", {}), list) else 1,
             RETURN: query_response
         })
         return query_response
@@ -253,6 +255,7 @@ def execute_zos_operator_cmd(self, command):
         )
         self.executions.append({
             NAME: "ZOS Operator Command - {0}".format(command),
+            RC: operator_response.get("rc"),
             RETURN: operator_response,
         })
         return operator_response
@@ -276,6 +279,7 @@ def execute_cancel_shell_cmd(self, job_name, job_id):
         cancel_response = command_action.run(task_vars=self.task_vars)
         self.executions.append({
             NAME: "Cancel command - {0}({1})".format(job_name, job_id),
+            RC: cancel_response.get("rc"),
             RETURN: cancel_response,
         })
         return cancel_response

plugins/modules/stop_region.py

@@ -123,7 +123,7 @@
     rc:
       description: The return code for the program execution.
       type: int
-      returned: on shutdown execution
+      returned: always
     return:
       description: The standard output returned by the program execution.
       type: dict
@@ -133,10 +133,14 @@
           description: True if the state was changed, otherwise False.
           returned: always
           type: bool
+        failed:
+          description: True if the module failed, otherwise False.
+          returned: always
+          type: bool
         jobs:
           description: The output information for a list of jobs matching specified criteria.
           type: list
-          returned: success
+          returned: on zos_job_query module execution
           elements: dict
           contains:
             job_id:
@@ -186,12 +190,47 @@
                       type: int
         message:
           description: Message returned on failure.
-          returned: failure
+          returned: on zos_job_query module execution
           type: str
         content:
           description: The resulting text from the command submitted.
-          returned: on success of PERFORM SHUTDOWN command submission.
+          returned: on zos_operator module execution
+          type: list
+        cmd:
+          description: The operator command that has been executed
+          returned: on zos_operator module execution
+          type: str
+        rc:
+          description: The return code from the operator command
+          returned: on zos_operator module execution
+          type: int
+        max_rc:
+          description: The maximum return code from the tso status command
+          returned: on zos_tso_command module execution
+          type: int
+        output:
+          description: The output from the tso command
+          returned: on zos_tso_command module execution
           type: list
+          elements: dict
+          contains:
+            command:
+              description: The executed TSO command.
+              returned: always
+              type: str
+            rc:
+              description: The return code from the executed TSO command.
+              returned: always
+              type: int
+            content:
+              description: The response resulting from the execution of the TSO command.
+              returned: always
+              type: list
+            lines:
+              description: The line number of the content.
+              returned: always
+              type: int
+
 msg:
   description: A string containing an error message if applicable
   returned: always

tests/integration/targets/cics_start_stop/playbooks/stop_args.yml

@@ -86,6 +86,12 @@
               - stop_result.executions[-1].return.output[0].content | length == 2
               - "'ON OUTPUT QUEUE' in '{{ stop_result.executions[-1].return.output[0].content | join(' ') }}'"
             fail_msg: "CICS Region did not stop successfully"
+        - name: Assert execution RCs are 0
+          ansible.builtin.assert:
+            that:
+              - item.rc == 0
+            msg: Job failed with RC != 0
+          loop: "{{ stop_result.executions }}"
 
       always:
         - name: Delete job
@@ -120,6 +126,12 @@
               - stop_result.executions[-1].return.output[0].content | length == 2
               - "'ON OUTPUT QUEUE' in '{{ stop_result.executions[-1].return.output[0].content | join(' ') }}'"
             fail_msg: "CICS Region did not stop successfully"
+        - name: Assert execution RCs are 0
+          ansible.builtin.assert:
+            that:
+              - item.rc == 0
+            msg: Job failed with RC != 0
+          loop: "{{ stop_result.executions }}"
 
     - name: Stop job mismatched name and ID
       block:

tests/integration/targets/cics_start_stop/repeatable_tasks/stop_region.yml

@@ -78,6 +78,14 @@
       - "'ON OUTPUT QUEUE' in '{{ stop_output.executions[-1].return.output[0].content | join(' ') }}'"
     fail_msg: "CICS Region did not stop successfully"
 
+- name: Assert execution RCs are 0
+  when: expect_failure is not defined or expect_failure is false
+  ansible.builtin.assert:
+    that:
+      - item.rc == 0
+    msg: Job failed with RC != 0
+  loop: "{{ stop_output.executions }}"
+
 - name: Execute a command to delete job
   when: expect_failure is not defined or expect_failure is false
   ansible.builtin.command:

tests/unit/modules/test_stop_cics.py renamed to tests/unit/modules/test_stop_region.py

@@ -33,26 +33,20 @@ def test__validate_sdtran():
     stop_module._module.params[SDTRAN] = "CESD"
     stop_module.main()
     assert stop_module.failed is False
-    assert stop_module.changed is False
-    assert stop_module.executions == []
 
 
 def test__validate_sdtran_3_chars():
     stop_module = initialise_module()
     stop_module._module.params[SDTRAN] = "C$D"
     stop_module.main()
     assert stop_module.failed is False
-    assert stop_module.changed is False
-    assert stop_module.executions == []
 
 
 def test__validate_sdtran_numerical():
     stop_module = initialise_module()
     stop_module._module.params[SDTRAN] = "1234"
     stop_module.main()
     assert stop_module.failed is False
-    assert stop_module.changed is False
-    assert stop_module.executions == []
 
 
 def test__validate_sdtran_too_long():
@@ -64,4 +58,3 @@ def test__validate_sdtran_too_long():
         stop_module.msg
         == "Value: CESDS, is invalid. SDTRAN value must be  1-4 characters."
     )
-    assert stop_module.executions == []