[v1.9.0] Collaboration 1246 to add typrun support for zos_job_submit

[ddimatos]

SUMMARY

Address issues:

• [Collaboration] [zos_job_submit] When submitting JCL with with TYPRUN=SCAN returns misleading response and fails the module #1246
• [Enhancement] [zos_job_submit] Adopt ZOAU 1.2.3 updated status #1278

When JCL is submitted with a job card indicating the job should only be validated with TYPRUN=SCAN the message that is returned is in this format:

"msg":"The JCL submitted with job id JOB00406 but there was an error, please review the error for further details: The job return code was not available in the job log, please review the job log and error ? ?."

This PR adds support to such that typrun=scan does not trigger a job submission failure with updated ret_code values:

"ret_code": {
                    "code": null,
                    "msg": "TYPRUN=SCAN",
                    "msg_code": null,
                    "msg_txt": "The job JOB00283 was run with special job processing TYPRUN=SCAN. This will result in no completion, return code or job steps and changed will be false.",
                    "steps": []
                },

ISSUE TYPE

Collaboration

COMPONENT NAME

IBM z/OS core zos_job_submit

ADDITIONAL INFORMATION

See git issue for more details

[ddimatos]

This issue addresses #1246 in that a job with TYPRUN=SCAN will no longer be considered a failure by the module, this is done inspecting the DD JESJCL among other things.

This response now succeeds where in the past TYRUN=SCAN was considered a job failure and error on completion. This now looks like (note there is no msg as there is no failure):

                "ret_code": {
                    "code": null,
                    "msg": "TYPRUN=SCAN",
                    "msg_code": null,
                    "msg_txt": "The job JOB00551 was run with special job processing TYPRUN=SCAN. This will result in no completion, return code or job steps and changed will be false.",
                    "steps": []
                },

This issue partially addresses issues

• [Collaboration] [zos_job_submit] When submitting JCL with with TYPRUN=HOLD returns misleading response and fails the module #1271
• [Enhancement] [zos_job_submit] Update module using jls latest NOEXEC status for jobs that run with TYPRUN=COPY #1272
• [Collaboration] [zos_job_submit] When submitting JCL with with TYPRUN=JCLHOLD returns misleading response and fails the module. #1273
  in that the msg no longer has a [zoauresponse] embedded in it (see below)

"msg": "The JCL submitted with job id JOB00478 but there was an error, please review the error for further details:
[ZOAUResponse]\n\trc: 3\n\tresponse_format: UTF-8\n\tstdout_response: \n\tstderr_response: BGYSC5403E Job is in
phase STAT_SELECT: Awaiting selection on main and is not ready for DD queries.\n\n\tcommand: ddls JOB00478 '//'"

The responses and ret_code were cleaned up such that they are now:

• TYPRUN=HOLD (still considered a job submission failure)

                "ret_code": {
                    "code": null,
                    "msg": "AC",
                    "msg_code": "?",
                    "msg_txt": "The JCL submitted with job id JOB00554 but appears to be a long running job that exceeded its maximum wait time of 10 second(s). Consider using module zos_job_query to poll for a long running job or increase option 'wait_times_s' to a value greater than 12.",
                    "steps": []
                },
                "subsystem": "",
                "svc_class": "ALLBATCH",
                "system": ""
            }
        ],
        "mode": "0600",
        "msg": "The JCL submitted with job id JOB00554 but appears to be a long running job that exceeded its maximum wait time of 10 second(s). Consider using module zos_job_query to poll for a long running job or increase option 'wait_times_s' to a value greater than 12.",

• TYPRUN=JCLHOLD (still considered a job submission failure)

                "ret_code": {
                    "code": null,
                    "msg": "AC",
                    "msg_code": "?",
                    "msg_txt": "The JCL submitted with job id JOB00555 but appears to be a long running job that exceeded its maximum wait time of 10 second(s). Consider using module zos_job_query to poll for a long running job or increase option 'wait_times_s' to a value greater than 11.",
                    "steps": []
                },
                "subsystem": "",
                "svc_class": "?",
                "system": ""
            }
        ],
        "mode": "0600",
        "msg": "The JCL submitted with job id JOB00555 but appears to be a long running job that exceeded its maximum wait time of 10 second(s). Consider using module zos_job_query to poll for a long running job or increase option 'wait_times_s' to a value greater than 11.",

• TYPRUN=COPY (still considered a job submission failure)

                "ret_code": {
                    "code": null,
                    "msg": "?",
                    "msg_code": "?",
                    "msg_txt": "The JCL submitted with job id JOB00553 but appears to be a long running job that exceeded its maximum wait time of 10 second(s). Consider using module zos_job_query to poll for a long running job or increase option 'wait_times_s' to a value greater than 11.",
                    "steps": []
                },
                "subsystem": "STL1",
                "svc_class": "?",
                "system": "STL1"
            }
        ],
        "mode": "0600",
        "msg": "The JCL submitted with job id JOB00553 but appears to be a long running job that exceeded its maximum wait time of 10 second(s). Consider using module zos_job_query to poll for a long running job or increase option 'wait_times_s' to a value greater than 11.",

Things to note:

• this will require a manual forward port to 1.10-beta.1
• this could all change when ZOAU supports additional status such as STAT_INPUT which will likely only be a 1.3 or later change of ZOAU given the architecture change that occurred in 1.3 to support these statuses.
• 2 other bugs were found:
  • jobs.py had written this job["ret_code"]["msg_txt"] as job["ret_code"]["msg_text"] causing and additional response property
  • jobs.py was setting job["ret_code"]["msg"] = entry.status + " " + entry.rc when it really should have been setting it as job["ret_code"]["msg"] = entry.status
• The only way to support TYPRUN = HOLD | JCLHOLD| COPY without the aid of ZOAU is to preprocess the JCL on the Ansible side, this was not achievable in the current time frame. I suggest that the issues noted above:
  • [Collaboration] [zos_job_submit] When submitting JCL with with TYPRUN=HOLD returns misleading response and fails the module #1271
  • [Enhancement] [zos_job_submit] Update module using jls latest NOEXEC status for jobs that run with TYPRUN=COPY #1272
  • [Collaboration] [zos_job_submit] When submitting JCL with with TYPRUN=JCLHOLD returns misleading response and fails the module. #1273
    be completed concurrently when support for multiple job cards in one JCL are supported.

The reason is , to support single JCL with multiple job statements it would need pre-processing from Ansible and at that time the HOLD, JCLHOLD and COPY could be addressed, this is a large change to the modules architecture , for multiple job statements see issue:

• [Collaboration] [Enhancement] [zos_job_submit] When submitting JCL with 2 job cards only the last one is returned #1274

[ddimatos]

I ran zos_job_submit here:

zos_job_query here:

zos_job_output here:

[fernandofloresg]

Looks good to me. Thanks for adding comments, for v1.10.0 I would suggest removing the code instead of commenting, we can always review previous versions in SCM