Enhancement/943/add wait zos operator and query

changelogs/fragments/943-enhance-Add-wait-zos-operator-and-query.yml

@@ -0,0 +1,6 @@
+minor_changes:
+  - zos_operator: Changed system to call 'wait=true' parameter to zoau call.
+      (https://github.com/ansible-collections/ibm_zos_core/pull/976)
+  - zos_operator_action_query: Add wait_time_s parameter in the operator_action_query.
+      (https://github.com/ansible-collections/ibm_zos_core/pull/976)
+

plugins/modules/zos_operator.py

@@ -55,16 +55,6 @@
     type: int
     required: false
     default: 1
-  wait:
-    description:
-      - Configuring wait used by the L(zos_operator,./zos_operator.html) module
-        has been deprecated and will be removed in a future ibm.ibm_zos_core
-        collection.
-      - Setting this option will yield no change, it is deprecated.
-      - Review option I(wait_time_s) to instruct operator commands to wait.
-    type: bool
-    required: false
-    default: true
 """
 
 EXAMPLES = r"""
@@ -81,16 +71,11 @@
   zos_operator:
     cmd: "\\$PJ(*)"
 
-- name: Execute operator command to show jobs, waiting up to 5 seconds for response
+- name: Execute operator command to show jobs, always waiting 5 seconds for response
   zos_operator:
     cmd: 'd a,all'
     wait_time_s: 5
 
-- name: Execute operator command to show jobs, always waiting 7 seconds for response
-  zos_operator:
-    cmd: 'd a,all'
-    wait_time_s: 7
-
 - name: Display the system symbols and associated substitution texts.
   zos_operator:
     cmd: 'D SYMBOLS'
@@ -178,6 +163,11 @@
 except Exception:
     opercmd = MissingZOAUImport()
 
+try:
+    from zoautil_py import ZOAU_API_VERSION
+except Exception:
+    ZOAU_API_VERSION = "1.2.0"
+
 
 def execute_command(operator_cmd, timeout=1, *args, **kwargs):
     start = timer()
@@ -195,7 +185,6 @@ def run_module():
         cmd=dict(type="str", required=True),
         verbose=dict(type="bool", required=False, default=False),
         wait_time_s=dict(type="int", required=False, default=1),
-        wait=dict(type="bool", required=False, default=True),
     )
 
     result = dict(changed=False)
@@ -266,8 +255,6 @@ def parse_params(params):
         cmd=dict(arg_type="str", required=True),
         verbose=dict(arg_type="bool", required=False),
         wait_time_s=dict(arg_type="int", required=False),
-        wait=dict(arg_type="bool", required=False, removed_at_date='2022-11-30',
-                  removed_from_collection='ibm.ibm_zos_core'),
     )
     parser = BetterArgParser(arg_defs)
     new_params = parser.parse_args(params)
@@ -286,6 +273,18 @@ def run_operator_command(params):
     wait_s = params.get("wait_time_s")
     cmdtxt = params.get("cmd")
 
+    zv = ZOAU_API_VERSION.split(".")
+    getit = False
+    if zv[0] > "1":
+        getit = True
+    elif zv[0] == "1" and zv[1] > "2":
+        getit = True
+    elif zv[0] == "1" and zv[1] == "2" and zv[2] > "4":
+        getit = True
+
+    if getit:
+        kwargs.update({"wait_arg": True})
+
     args = []
     rc, stdout, stderr, elapsed = execute_command(cmdtxt, timeout=wait_s, *args, **kwargs)
 

plugins/modules/zos_operator_action_query.py

@@ -57,6 +57,16 @@
       - A trailing asterisk, (*) wildcard is supported.
     type: str
     required: false
+  wait_time_s:
+    description:
+      - Set maximum time in seconds to wait for the commands to execute.
+      - When set to 0, the system default is used.
+      - This option is helpful on a busy system requiring more time to execute
+        commands.
+      - Because 2 functions are called, potential time delay is doubled.
+    type: int
+    required: false
+    default: 1
   message_filter:
     description:
       - Return outstanding messages requiring operator action awaiting a
@@ -101,6 +111,18 @@
   zos_operator_action_query:
       job_name: im5*
 
+- name: Display all outstanding messages whose job name begin with im7,
+        waiting 10 seconds per call (20 seconds overall) for data
+  zos_operator_action_query:
+      job_name: im7*
+      wait_time_s: 10
+
+- name: Display all outstanding messages whose job name begin with im9,
+        wait a full 15 seconds per call (30 seconds overall) for data
+  zos_operator_action_query:
+      job_name: im9*
+      wait_time_s: 15
+
 - name: Display all outstanding messages whose message id begin with dsi*
   zos_operator_action_query:
       message_id: dsi*
@@ -229,12 +251,18 @@
 except Exception:
     opercmd = MissingZOAUImport()
 
+try:
+    from zoautil_py import ZOAU_API_VERSION
+except Exception:
+    ZOAU_API_VERSION = "1.2.0"
+
 
 def run_module():
     module_args = dict(
         system=dict(type="str", required=False),
         message_id=dict(type="str", required=False),
         job_name=dict(type="str", required=False),
+        wait_time_s=dict(type="int", required=False, default=1),
         message_filter=dict(
             type="dict",
             required=False,
@@ -251,7 +279,28 @@ def run_module():
     try:
         new_params = parse_params(module.params)
 
-        cmd_result_a = execute_command("d r,a,s")
+        kwargs = {}
+
+        wait_s = new_params.get("wait_time_s")
+
+        zv = ZOAU_API_VERSION.split(".")
+        getit = False
+        if zv[0] > "1":
+            getit = True
+        elif zv[0] == "1" and zv[1] > "2":
+            getit = True
+        elif zv[0] == "1" and zv[1] == "2" and zv[2] > "4":
+            getit = True
+
+        if getit:
+            kwargs.update({"wait_arg": True})
+
+        args = []
+
+        cmdtxt = "d r,a,s"
+
+        cmd_result_a = execute_command(cmdtxt, timeout=wait_s, *args, **kwargs)
+
         if cmd_result_a.rc > 0:
             module.fail_json(
                 msg="A non-zero return code was received while querying the operator.",
@@ -263,7 +312,10 @@ def run_module():
                 cmd="d r,a,s",
             )
 
-        cmd_result_b = execute_command("d r,a,jn")
+        cmdtxt = "d r,a,jn"
+
+        cmd_result_b = execute_command(cmdtxt, timeout=wait_s, *args, **kwargs)
+
         if cmd_result_b.rc > 0:
             module.fail_json(
                 msg="A non-zero return code was received while querying the operator.",
@@ -295,6 +347,7 @@ def parse_params(params):
         system=dict(arg_type=system_type, required=False),
         message_id=dict(arg_type=message_id_type, required=False),
         job_name=dict(arg_type=job_name_type, required=False),
+        wait_time_s=dict(arg_type="int", required=False),
         message_filter=dict(arg_type=message_filter_type, required=False)
     )
     parser = BetterArgParser(arg_defs)
@@ -395,9 +448,11 @@ def handle_conditions(list, condition_type, value):
     return newlist
 
 
-def execute_command(operator_cmd):
+def execute_command(operator_cmd, timeout=1, *args, **kwargs):
+
+    # response = opercmd.execute(operator_cmd)
+    response = opercmd.execute(operator_cmd, timeout, *args, **kwargs)
 
-    response = opercmd.execute(operator_cmd)
     rc = response.rc
     stdout = response.stdout_response
     stderr = response.stderr_response

tests/functional/modules/test_zos_operator_action_query_func.py

@@ -16,7 +16,7 @@
 __metaclass__ = type
 
 import pytest
-import unittest
+
 
 def test_zos_operator_action_query_no_options(ansible_zos_module):
     hosts = ansible_zos_module
@@ -29,6 +29,7 @@ def test_zos_operator_action_query_no_options(ansible_zos_module):
                     cmd="{0}cancel".format(action.get("number")))
     except Exception:
         pass
+
     for result in results.contacted.values():
         assert result.get("actions")
 
@@ -43,6 +44,7 @@ def test_zos_operator_action_query_option_message_id(ansible_zos_module):
                     cmd="{0}cancel".format(action.get("number")))
     except Exception:
         pass
+
     for result in results.contacted.values():
         assert result.get("actions")
 
@@ -267,7 +269,6 @@ def test_zos_operator_action_query_option_message_filter_multiple_matches(
     except Exception:
         pass
     for result in results.contacted.values():
-        print(result.get("actions"))
         assert result.get("actions")
         assert len(result.get("actions")) > 1
 

tests/functional/modules/test_zos_operator_func.py

@@ -112,7 +112,6 @@ def test_zos_operator_positive_verbose_with_quick_delay(ansible_zos_module):
     # assert timediff < 15
 
     for result in results.contacted.values():
-        pprint(result)
         assert result["rc"] == 0
         assert result.get("changed") is True
         assert result.get("content") is not None