[New module] zos_started_task #2275

surendrababuravella · 2025-09-10T16:52:37Z

SUMMARY

New module zos_started_task which support start, display, modify, cancel, stop and force operations.

ISSUE TYPE

New Module Pull Request

COMPONENT NAME

zos_started_task

ADDITIONAL INFORMATION

* add nonscratch parameter in main module * added support for nonscratch in module_utils * added test case * added fragments * FIXED * changed in fragments * Updated changelogs * reviewed comments * fixed * removed print statement * removed extra validation --------- Co-authored-by: Fernando Flores <[email protected]>

…ible-collections/ibm_zos_core into enhancement/zos_started_task

…d_task Merging latest dev changes

surendrababuravella · 2025-09-18T16:28:43Z

Display command response:

{
    "msg": [
        {
            "changed": true,
            "cmd": "D A,vlf.vlf",
            "failed": false,
            "rc": 0,
            "state": "displayed",
            "stderr": "",
            "stderr_lines": [
                ""
            ],
            "stdout": "EC01248B   2025272  03:33:45.00             ISF031I CONSOLE OMVS0000 ACTIVATED\nEC01248B   2025272  03:33:45.00            -D A,VLF.VLF \nEC01248B   2025272  03:33:45.00             CNZ4106I 03.33.45 DISPLAY ACTIVITY 791\n                                            JOBS     M/S    TS USERS    SYSAS    INITS   ACTIVE/MAX VTAM     OAS\n                                           00013    00014    00000      00033    00037    00000/00020       00022\n                                            VLF      VLF      VLF      NSW  S   A=0062   PER=NO   SMC=000\n                                                                                PGN=N/A  DMN=N/A  AFF=NONE\n                                                                                CT=000.014S  ET=01.24.25\n                                                                                WKL=SYSTEM   SCL=SYSSTC   P=1\n                                                                                RGP=N/A      SRVR=NO  QSC=NO\n                                                                                ADDR SPACE ASTE=1EE16880\n                                                                                DSPNAME=DCSVLLA  ASTE=01302180\n                                                                                DSPNAME=CCSVLLA  ASTE=01302200\n",
            "stdout_lines": [
                "EC01248B   2025272  03:33:45.00             ISF031I CONSOLE OMVS0000 ACTIVATED",
                "EC01248B   2025272  03:33:45.00            -D A,VLF.VLF ",
                "EC01248B   2025272  03:33:45.00             CNZ4106I 03.33.45 DISPLAY ACTIVITY 791",
                "                                            JOBS     M/S    TS USERS    SYSAS    INITS   ACTIVE/MAX VTAM     OAS",
                "                                           00013    00014    00000      00033    00037    00000/00020       00022",
                "                                            VLF      VLF      VLF      NSW  S   A=0062   PER=NO   SMC=000",
                "                                                                                PGN=N/A  DMN=N/A  AFF=NONE",
                "                                                                                CT=000.014S  ET=01.24.25",
                "                                                                                WKL=SYSTEM   SCL=SYSSTC   P=1",
                "                                                                                RGP=N/A      SRVR=NO  QSC=NO",
                "                                                                                ADDR SPACE ASTE=1EE16880",
                "                                                                                DSPNAME=DCSVLLA  ASTE=01302180",
                "                                                                                DSPNAME=CCSVLLA  ASTE=01302200",
                ""
            ],
            "tasks": [
                {
                    "address_space_second_table_entry": "1EE16880",
                    "affinity": "NONE",
                    "asid": "0062",
                    "cpu_time": "000.014S",
                    "dataspaces": [
                        {
                            "data_space_address_entry": "01302180",
                            "data_space_name": "DCSVLLA"
                        },
                        {
                            "data_space_address_entry": "01302200",
                            "data_space_name": "CCSVLLA"
                        }
                    ],
                    "domain_number": "N/A",
                    "elapsed_time": "01.24.25",
                    "priority": "1",
                    "proc_step_name": "VLF",
                    "program_event_recording": "NO",
                    "program_name": "N/A",
                    "queue_scan_count": "NO",
                    "resource_group": "N/A",
                    "server": "NO",
                    "started_class_list": "SYSSTC",
                    "started_time": "2025-09-29 09:09:20.765165+00:00",
                    "system_management_control": "000",
                    "task_identifier": "VLF",
                    "task_name": "VLF",
                    "task_status": "S",
                    "task_type": "NSW",
                    "workload_manager": "SYSTEM"
                }
            ],
            "verbose_output": "NC0000000 EC01248B 25272 03:33:45.56 OMVS0000 00000210  D A,VLF.VLF\nMR0000000 EC01248B 25272 03:33:45.56 OMVS0000 00000010  CNZ4106I 03.33.45 DISPLAY ACTIVITY 791\nLR                                        791 00000010   JOBS     M/S    TS USERS    SYSAS    INITS   ACTIVE/MAX VTAM     OAS\nLR                                        791 00000010  00013    00014    00000      00033    00037    00000/00020       00022\nDR                                        791 00000010   VLF      VLF      VLF      NSW  S   A=0062   PER=NO   SMC=000\nDR                                        791 00000010                                       PGN=N/A  DMN=N/A  AFF=NONE\nDR                                        791 00000010                                       CT=000.014S  ET=01.24.25\nDR                                        791 00000010                                       WKL=SYSTEM   SCL=SYSSTC   P=1\nDR                                        791 00000010                                       RGP=N/A      SRVR=NO  QSC=NO\nDR                                        791 00000010                                       ADDR SPACE ASTE=1EE16880\nDR                                        791 00000010                                       DSPNAME=DCSVLLA  ASTE=01302180\nER                                        791 00000010                                       DSPNAME=CCSVLLA  ASTE=01302200\nN 0000000 EC01248B 25272 03:33:45.57 STC00159 00000210  IEA631I  OPERATOR OMVS0000 NOW INACTIVE, SYSTEM=EC01248B, LU=OMVSADM\nNR0000000 EC01248B 25272 03:33:45.60 STC00159 00000010  CNZ4000I EMCS CONSOLE OMVS0000 HAS BEEN REMOVED"
        }
    ]
}

surendrababuravella · 2025-09-18T16:35:08Z

Start command response with verbose:

{
    "msg": [
        {
            "changed": true,
            "cmd": "S sample",
            "failed": false,
            "rc": 0,
            "state": "started",
            "stderr": "",
            "stderr_lines": [
                ""
            ],
            "stdout": "EC01248B   2025272  03:44:00.00             ISF031I CONSOLE OMVS0000 ACTIVATED\nEC01248B   2025272  03:44:00.00            -S SAMPLE \nEC01248B   2025272  03:44:00.00             ",
            "stdout_lines": [
                "EC01248B   2025272  03:44:00.00             ISF031I CONSOLE OMVS0000 ACTIVATED",
                "EC01248B   2025272  03:44:00.00            -S SAMPLE ",
                "EC01248B   2025272  03:44:00.00             "
            ],
            "tasks": [
                {
                    "address_space_second_table_entry": "1EE16580",
                    "affinity": "NONE",
                    "asid": "0056",
                    "cpu_time": "000.003S",
                    "domain_number": "N/A",
                    "elapsed_time": "001.335S",
                    "priority": "1",
                    "proc_step_name": "STEP1",
                    "program_event_recording": "NO",
                    "program_name": "N/A",
                    "queue_scan_count": "NO",
                    "resource_group": "N/A",
                    "server": "NO",
                    "started_class_list": "SYSSTC",
                    "started_time": "2025-09-29 10:43:59.583172+00:00",
                    "system_management_control": "000",
                    "task_identifier": "SAMPLE",
                    "task_name": "SAMPLE",
                    "task_status": "SO",
                    "task_type": "IN",
                    "userid": "USRT001",
                    "work_unit_identifier": "STC00173",
                    "workload_manager": "SYSTEM"
                }
            ],
            "verbose_output": "NC0000000 EC01248B 25272 03:43:59.49 OMVS0000 00000210  S SAMPLE\nN 0200000 EC01248B 25272 03:43:59.50 STC00173 00000201  $HASP100 SAMPLE   ON STCINRDR\nN 0020000 EC01248B 25272 03:43:59.53 STC00173 00000201  IEF695I START SAMPLE   WITH JOBNAME SAMPLE   IS ASSIGNED TO USER USRT001\nS                                                        , GROUP SYS1\nN 4000000 EC01248B 25272 03:43:59.53 STC00173 00000010  $HASP373 SAMPLE   STARTED\nN 0000000 EC01248B 25272 03:44:00.51 STC00158 00000210  IEA631I  OPERATOR OMVS0000 NOW INACTIVE, SYSTEM=EC01248B, LU=OMVSADM\nNR0000000 EC01248B 25272 03:44:00.54 STC00158 00000010  CNZ4000I EMCS CONSOLE OMVS0000 HAS BEEN REMOVED"
        }
    ]
}

surendrababuravella · 2025-09-18T16:39:43Z

Cancel command response with verbose:

{
    "msg": [
        {
            "changed": true,
            "cmd": "C sample",
            "failed": false,
            "rc": 0,
            "state": "cancelled",
            "stderr": "",
            "stderr_lines": [
                ""
            ],
            "stdout": "EC01248B   2025272  03:46:16.00             ISF031I CONSOLE OMVS0000 ACTIVATED\nEC01248B   2025272  03:46:16.00            -C SAMPLE \nEC01248B   2025272  03:46:16.00             IEE301I SAMPLE            CANCEL COMMAND ACCEPTED\n",
            "stdout_lines": [
                "EC01248B   2025272  03:46:16.00             ISF031I CONSOLE OMVS0000 ACTIVATED",
                "EC01248B   2025272  03:46:16.00            -C SAMPLE ",
                "EC01248B   2025272  03:46:16.00             IEE301I SAMPLE            CANCEL COMMAND ACCEPTED",
                ""
            ],
            "tasks": [
                {
                    "address_space_second_table_entry": "1EE16580",
                    "affinity": "NONE",
                    "asid": "0056",
                    "cpu_time": "000.003S",
                    "domain_number": "N/A",
                    "elapsed_time": "136.476S",
                    "priority": "1",
                    "proc_step_name": "STEP1",
                    "program_event_recording": "NO",
                    "program_name": "N/A",
                    "queue_scan_count": "NO",
                    "resource_group": "N/A",
                    "server": "NO",
                    "started_class_list": "SYSSTC",
                    "started_time": "2025-09-29 10:43:59.584406+00:00",
                    "system_management_control": "000",
                    "task_identifier": "SAMPLE",
                    "task_name": "SAMPLE",
                    "task_status": "SO",
                    "task_type": "OWT",
                    "userid": "USRT001",
                    "work_unit_identifier": "STC00173",
                    "workload_manager": "SYSTEM"
                }
            ],
            "verbose_output": "NC0000000 EC01248B 25272 03:46:16.23 OMVS0000 00000210  C SAMPLE\nNR0000000 EC01248B 25272 03:46:16.23 STC00161 00000010  IEE301I SAMPLE            CANCEL COMMAND ACCEPTED\nN 0000000 EC01248B 25272 03:46:16.23          00000201  IEA989I SLIP TRAP ID=X222 MATCHED.  JOBNAME=SAMPLE  , ASID=0056.\nM 0020000 EC01248B 25272 03:46:16.23 STC00173 00000210  BPXP018I THREAD 0DE1C80000000000, IN PROCESS 16777622, ENDED 985\nD                                         985 00000210  WITHOUT BEING UNDUBBED WITH COMPLETION CODE 40222000\nE                                         985 00000210  , AND REASON CODE 00000000.\nN 4000000 EC01248B 25272 03:46:16.23 STC00173 00000010  IEF450I SAMPLE SAMPLE - ABEND=S222 U0000 REASON=00000000\nN 4000000 EC01248B 25272 03:46:16.24 STC00173 00000010  $HASP395 SAMPLE   ENDED - ABEND=S222\nN 0000000 EC01248B 25272 03:46:16.24          00000201  IEA989I SLIP TRAP ID=X33E MATCHED.  JOBNAME=*UNAVAIL, ASID=0056.\nN 0200000 EC01248B 25272 03:46:16.25 STC00173 00000010  $HASP150 SAMPLE   OUTGRP=1.1.1 ON PRT2     50 (50) RECORDS\nN 0000000 EC01248B 25272 03:46:16.25 STC00161 00000210  IEA631I  OPERATOR OMVS0000 NOW INACTIVE, SYSTEM=EC01248B, LU=OMVSADM\nN 0200000 EC01248B 25272 03:46:16.28          00000201  $HASP160 PRT2       INACTIVE - CLASS=01234AZFWXYTV\nN 0200000 EC01248B 25272 03:46:16.28 STC00173 00000010  $HASP250 SAMPLE PURGED -- (JOB KEY WAS E18FE98D)\nNR0000000 EC01248B 25272 03:46:16.30 STC00161 00000010  CNZ4000I EMCS CONSOLE OMVS0000 HAS BEEN REMOVED"
        }
    ]
}

fernandofloresg

Requested few changes, only got to some of the docs will continue later

fernandofloresg · 2025-09-18T20:15:52Z

plugins/module_utils/better_arg_parser.py

        return contents

+    def _basic_dict_type(self, contents, resolve_dependencies):
+        """Resolver for str type arguments.


Suggested change

"""Resolver for str type arguments.

"""Resolver for basic dict type arguments.

fernandofloresg · 2025-09-18T20:16:40Z

plugins/module_utils/better_arg_parser.py

+        return str(contents)
+
+    def _identifier_name_type(self, contents, resolve_dependencies):
+        """Resolver for data_set type arguments.


Since this is used only in zos_started task could you comment a bit of where this is used ?

fernandofloresg · 2025-09-18T20:17:28Z

plugins/module_utils/better_arg_parser.py

        return contents

+    def _member_name_type(self, contents, resolve_dependencies):
+        """Resolver for data_set type arguments.


Since this is used only in zos_started task could you comment a bit of where and how this is used ? I mean, add as a comment in the function, so that is not used for other reasons. Is this member a data set member?

Updated. Member is the PDS/E member.

fernandofloresg · 2025-09-18T20:26:45Z

plugins/modules/zos_started_task.py

+  state:
+    description:
+        - The desired state the started task should be after the module is executed.
+        - If state=started and the started task is not found on the managed node, no action is taken,


I think this behavior should be changed, just checked the ansible.services module and when a service is not found in the managed node it fails

fatal: [zvm]: FAILED! => {"ansible_facts": {"discovered_interpreter_python": "/usr/bin/python3.12"}, "changed": false, "msg": "Could not find the requested service hpptt: host"}

This seems more aligned to the idea of idempotency, returning a succesful response with changed: false would give a false sense that the task is running already, even though we can start more than one.

Modified description. Here status of the started task or member are validated by ZOAU.

fernandofloresg · 2025-09-18T20:27:36Z

plugins/modules/zos_started_task.py

+          managed node, no action is taken, module completes successfully with changed=False.
+        - If state is modified and the started task is not running, not found or modification was not
+          done, the module will fail.
+        - If state is displayed the module will return the started task details.


In the case of state being displayed what is the changed return value? could you add that?

fernandofloresg · 2025-09-18T20:28:58Z

plugins/modules/zos_started_task.py

+    default: false
+  wait_time:
+    description:
+        - Option wait_time is the total time that module zos_started_tak will wait for a submitted


Suggested change

- Option wait_time is the total time that module zos_started_tak will wait for a submitted

- Option wait_time is the total time that module zos_started_task will wait for a submitted

richp405

I'll wait for you to address fernando's comments on return process from zos_started_task.

…ible-collections/ibm_zos_core into enhancement/zos_started_task

rexemin

Good work you have done in this module. There's a lot of comments, but they're mostly documentation or reminders of how to do things more in Python's style. Another question I have about cpu_time and elapsed_time: the time returned changes depending on how long the started task has been running for, would it be too cumbersome to convert all those formats into a single one like this: hhhhh.mm.ss.ttt? I'm thinking having the same format all the time would make automation easier. Of course, special values ******** and NOTAVAIL would remain the same.

All comments I've made are probably a lot of work and you've been waiting on more reviews, so if I don't review this PR again quickly please ping me

plugins/module_utils/better_arg_parser.py

plugins/modules/zos_started_task.py

surendrababuravella · 2025-09-24T15:18:17Z

Good work you have done in this module. There's a lot of comments, but they're mostly documentation or reminders of how to do things more in Python's style. Another question I have about cpu_time and elapsed_time: the time returned changes depending on how long the started task has been running for, would it be too cumbersome to convert all those formats into a single one like this: hhhhh.mm.ss.ttt? I'm thinking having the same format all the time would make automation easier. Of course, special values ******** and NOTAVAIL would remain the same.

All comments I've made are probably a lot of work and you've been waiting on more reviews, so if I don't review this PR again quickly please ping me

@rexemin Thank you for the review..
'elapsed_time' has handled already. 'started_time' has created from 'elapsed_time' only.
Regarding 'cpu_time', tried to analyse multiple scenarios. The logic which is used for 'elapsed_time' is applicable for this as well. But this can be handled if needed.

Other comments are addressed.

…ible-collections/ibm_zos_core into enhancement/zos_started_task

richp405

Surendra... I think you need to re-push your changes... the 'view changed' did not show changes that you marked as resolved. We need to see the actual changes in github before we can approve it.

plugins/modules/zos_started_task.py

surendrababuravella · 2025-09-29T18:27:50Z

Surendra... I think you need to re-push your changes... the 'view changed' did not show changes that you marked as resolved. We need to see the actual changes in github before we can approve it.

@richp405 this comment applicable at 2 places.. i missed updating here. Now updated..

richp405

There are a few document issues remaining in zos_started_task, but not deal busters in my opinion. A nice chunk of code.

rexemin

Looks pretty great, thanks for working on so many comments so quickly, I just have a couple of other corrections and some questions from last week pending

rexemin · 2025-09-29T19:14:26Z

plugins/modules/zos_started_task.py

+    else:
+        module.fail_json(
+            rc=5,
+            msg="job_name is missing which is mandatory to display started task details.",


You are stopping a started task here

rexemin · 2025-09-29T19:14:48Z

plugins/modules/zos_started_task.py

+    else:
+        module.fail_json(
+            rc=5,
+            msg="job_name is missing which is mandatory to display started task details.",


you are modifying a started task here

mayankmani-sde and others added 15 commits July 9, 2025 10:03

Adding new module

5134997

Update zos_started_task.py

19de431

Updating testcases

256d4c9

Updating test cases

8cd6c69

Updating testcases

241fabf

Adding features in display command and updating testcases

b6592c5

update parameters

fd063b7

Added RST for started task

2d2877b

Features update

08cdd4c

Merge branch 'enhancement/zos_started_task' of https://github.com/ans…

c7a20f2

…ible-collections/ibm_zos_core into enhancement/zos_started_task

Adding generic parameters support

9c244a1

Update better_arg_parser.py

38cf15b

Merge remote-tracking branch 'origin/dev' into enhancement/zos_starte…

1542041

…d_task Merging latest dev changes

Delete 2202-zos_data_set-Support-noscratch-options.yml

20f9223

surendrababuravella marked this pull request as draft September 10, 2025 16:54

surendrababuravella added 11 commits September 10, 2025 23:47

Update zos_started_task.py

45fd79d

Update testcases

ac961fb

Update test_zos_started_task_func.py

416cc5b

Update zos_started_task.py

b5a225c

adding time zone changes

8f0dda3

Update zos_started_task.py

712828b

Update zos_started_task.py

da3e810

Update zos_started_task.py

0c19b4f

Updating testcases

203cde7

Update zos_started_task.py

dd58e0d

Update test_zos_started_task_func.py

a5f1325

fernandofloresg requested changes Sep 18, 2025

View reviewed changes

richp405 reviewed Sep 18, 2025

View reviewed changes

surendrababuravella added 2 commits September 19, 2025 19:21

Resolving PR review comments

1a47874

Update zos_started_task.py

e097e77

surendrababuravella requested a review from ddimatos September 19, 2025 14:25

surendrababuravella added 6 commits September 22, 2025 12:39

Added msg in all error responses

e39507b

Replacing error strings with error codes

9b459ef

Updating documentation

d40565e

Merge branch 'dev' into enhancement/zos_started_task

cae13dc

Update zos_started_task.rst

61fa37b

Merge branch 'enhancement/zos_started_task' of https://github.com/ans…

f95db5f

…ible-collections/ibm_zos_core into enhancement/zos_started_task

fernandofloresg mentioned this pull request Sep 23, 2025

[Documentation] Review the zos_started_task documentation #2329

Open

1 task

rexemin requested changes Sep 23, 2025

View reviewed changes

Addressing PR comments

b47b3de

surendrababuravella and others added 6 commits September 25, 2025 20:42

resolving PR comments

d87d314

Merge branch 'dev' into enhancement/zos_started_task

8eb0c12

resolving review comments

cc68275

Update zos_started_task.rst

8852bfa

Merge branch 'enhancement/zos_started_task' of https://github.com/ans…

0380841

…ible-collections/ibm_zos_core into enhancement/zos_started_task

Updating doc changes

d44bcf7

surendrababuravella requested review from rexemin, fernandofloresg and richp405 September 29, 2025 10:54

richp405 reviewed Sep 29, 2025

View reviewed changes

plugins/modules/zos_started_task.py Outdated Show resolved Hide resolved

Adding document updates

b726c6e

surendrababuravella requested a review from richp405 September 29, 2025 18:30

richp405 approved these changes Sep 29, 2025

View reviewed changes

rexemin requested changes Sep 29, 2025

View reviewed changes

	"""Resolver for str type arguments.
	"""Resolver for basic dict type arguments.

	- Option wait_time is the total time that module zos_started_tak will wait for a submitted
	- Option wait_time is the total time that module zos_started_task will wait for a submitted

[New module] zos_started_task #2275

Are you sure you want to change the base?

[New module] zos_started_task #2275

Uh oh!

Conversation

surendrababuravella commented Sep 10, 2025

SUMMARY

ISSUE TYPE

COMPONENT NAME

ADDITIONAL INFORMATION

Uh oh!

surendrababuravella commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

surendrababuravella commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

surendrababuravella commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

fernandofloresg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

richp405 left a comment

Choose a reason for hiding this comment

Uh oh!

rexemin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

surendrababuravella commented Sep 24, 2025

Uh oh!

richp405 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

surendrababuravella commented Sep 29, 2025

Uh oh!

richp405 left a comment

Choose a reason for hiding this comment

Uh oh!

rexemin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

surendrababuravella commented Sep 18, 2025 •

edited

Loading

surendrababuravella commented Sep 18, 2025 •

edited

Loading

surendrababuravella commented Sep 18, 2025 •

edited

Loading