[New module] zos_started_task

docs/source/modules/zos_started_task.rst

@@ -0,0 +1,164 @@
+
+:github_url: https://github.com/ansible-collections/ibm_zos_core/blob/dev/plugins/modules/zos_started_task.py
+
+.. _zos_started_task_module:
+
+
+zos_started_task -- Perform operations on started tasks.
+========================================================
+
+
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Synopsis
+--------
+- start, display, modify, cancel, force and stop a started task
+
+
+
+
+
+Parameters
+----------
+
+
+asid
+  *asid* is a unique address space identifier which gets assigned to each running started task.
+
+  | **required**: False
+  | **type**: str
+
+
+device_type
+  *device_type* is the type of the output device (if any) associated with the task.
+
+  | **required**: False
+  | **type**: str
+
+
+device_number
+  *device_number* is the number of the device to be started. A device number is 3 or 4 hexadecimal digits. A slash (/) must precede a 4-digit number but is not before a 3-digit number.
+
+  | **required**: False
+  | **type**: str
+
+
+identifier_name
+  *identifier_name* is the name that identifies the task to be started. This name can be up to 8 characters long. The first character must be alphabetical.
+
+  | **required**: False
+  | **type**: str
+
+
+job_account
+  *job_account* specifies accounting data in the JCL JOB statement for the started task. If the source JCL was a job and has already accounting data, the value that is specified on this parameter overrides the accounting data in the source JCL.
+
+  | **required**: False
+  | **type**: str
+
+
+job_name
+  *job_name* is a name which should be assigned to a started task while starting it. If job_name is not specified, then member_name is used as job_name.
+
+  | **required**: False
+  | **type**: str
+
+
+keyword_parameters
+  Any appropriate keyword parameter that you specify to override the corresponding parameter in the cataloged procedure. The maximum length of each keyword=option is 66 characters. No individual value within this field can be longer than 44 characters in length.
+
+  | **required**: False
+  | **type**: str
+
+
+member_name
+  *member_name* is a 1 - 8 character name of a member of a partitioned data set that contains the source JCL for the task to be started. The member can be either a job or a cataloged procedure.
+
+  | **required**: False
+  | **type**: str
+
+
+operation
+  The started task operation which needs to be performed.
+
+  If *operation=start* and the data set does not exist on the managed node, no action taken, module completes successfully with *changed=False*.
+
+
+  | **required**: True
+  | **type**: str
+  | **choices**: start, stop, modify, display, force, cancel
+
+
+parameters
+  Program parameters passed to the started program, which might be a list in parentheses or a string in single quotation marks
+
+  | **required**: False
+  | **type**: str
+
+
+reus_asid
+  When REUSASID=YES is specified on the START command and REUSASID(YES) is specified in the DIAGxx parmlib member, a reusable ASID is assigned to the address space created by the START command. If REUSASID=YES is not specified on the START command or REUSASID(NO) is specified in DIAGxx, an ordinary ASID is assigned.
+
+  | **required**: False
+  | **type**: str
+  | **choices**: YES, NO
+
+
+subsystem_name
+  The name of the subsystem that selects the task for processing. The name must be 1 - 4 characters, which are defined in the IEFSSNxx parmlib member, and the subsystem must be active.
+
+  | **required**: False
+  | **type**: str
+
+
+volume_serial
+  If devicetype is a tape or direct-access device, the volume serial number of the volume is mounted on the device.
+
+  | **required**: False
+  | **type**: str
+
+
+verbose
+  Return System logs that describe the task's execution.
+
+  | **required**: False
+  | **type**: bool
+  | **default**: False
+
+
+wait_time_s
+  Option *wait_time_s* is the total time that module `zos_started_tak <./zos_started_task.html>`_ will wait for a submitted task. The time begins when the module is executed on the managed node.
+
+  | **required**: False
+  | **type**: int
+  | **default**: 5
+
+
+
+
+
+
+Examples
+--------
+
+.. code-block:: yaml+jinja
+
+
+   - name: Start a started task using member name.
+     zos_started_task:
+       member: "PROCAPP"
+       operation: "start"
+
+
+
+
+
+
+
+
+
+

plugins/module_utils/better_arg_parser.py

@@ -152,6 +152,7 @@ def __init__(self, arg_name, contents, resolved_args, arg_defs):
         # TODO: determine if we should optionally allow top-level args to be passed
         self.type_handlers = {
             "dict": self._dict_type,
+            "basic_dict": self._basic_dict_type,
             "list": self._list_type,
             "str": self._str_type,
             "bool": self._bool_type,
@@ -160,6 +161,8 @@ def __init__(self, arg_name, contents, resolved_args, arg_defs):
             "data_set": self._data_set_type,
             "data_set_base": self._data_set_base_type,
             "data_set_member": self._data_set_member_type,
+            "member_name": self._member_name_type,
+            "identifier_name": self._identifier_name_type,
             "qualifier": self._qualifier_type,
             "qualifier_or_empty": self._qualifier_or_empty_type,
             "qualifier_pattern": self._qualifier_pattern_type,
@@ -252,6 +255,32 @@ def _dict_type(self, contents, resolved_dependencies):
         self._assert_mutually_exclusive(contents)
         return contents
 
+    def _basic_dict_type(self, contents, resolve_dependencies):
+        """Resolver for str type arguments.
+
+        Parameters
+        ----------
+        contents : dict
+            The contents of the argument.
+        resolved_dependencies : dict
+            Contains all of the dependencies and their contents,
+            which have already been handled,
+            for use during current arguments handling operations.
+
+        Returns
+        -------
+        dict
+            The arguments contents after any necessary operations.
+
+        Raises
+        ------
+        ValueError
+            When contents is invalid argument type.
+        """
+        if not isinstance(contents, dict):
+            raise ValueError('Invalid argument "{0}" for type "dict".'.format(contents))
+        return contents
+
     def _str_type(self, contents, resolve_dependencies):
         """Resolver for str type arguments.
 
@@ -329,6 +358,70 @@ def _bool_type(self, contents, resolve_dependencies):
             raise ValueError('Invalid argument "{0}" for type "bool".'.format(contents))
         return contents
 
+    def _member_name_type(self, contents, resolve_dependencies):
+        """Resolver for data_set type arguments.
+
+        Parameters
+        ----------
+        contents : bool
+            The contents of the argument.
+        resolved_dependencies : dict
+            Contains all of the dependencies and their contents,
+            which have already been handled,
+            for use during current arguments handling operations.
+
+        Returns
+        -------
+        str
+            The arguments contents after any necessary operations.
+
+        Raises
+        ------
+        ValueError
+            When contents is invalid argument type.
+        """
+        if not fullmatch(
+            r"^[A-Z$#@]{1}[A-Z0-9$#@]{0,7}$",
+            str(contents),
+            IGNORECASE,
+        ):
+            raise ValueError(
+                'Invalid argument "{0}" for type "member_name".'.format(contents)
+            )
+        return str(contents)
+
+    def _identifier_name_type(self, contents, resolve_dependencies):
+        """Resolver for data_set type arguments.
+
+        Parameters
+        ----------
+        contents : bool
+            The contents of the argument.
+        resolved_dependencies : dict
+            Contains all of the dependencies and their contents,
+            which have already been handled,
+            for use during current arguments handling operations.
+
+        Returns
+        -------
+        str
+            The arguments contents after any necessary operations.
+
+        Raises
+        ------
+        ValueError
+            When contents is invalid argument type.
+        """
+        if not fullmatch(
+            r"^[A-Z]{1}[A-Z0-9$#@]{0,7}$",
+            str(contents),
+            IGNORECASE,
+        ):
+            raise ValueError(
+                'Invalid argument "{0}" for type "identifier_name".'.format(contents)
+            )
+        return str(contents)
+
     def _path_type(self, contents, resolve_dependencies):
         """Resolver for path type arguments.