Enhancement/943/add wait zos operator and query

[richp405]

SUMMARY

Enhancement to zos_operator, adding the 'wait' function back in with a new definition
Enhancement to zos_operator_action_query, adding both wait and wait_time_s

Addresses #943

ISSUE TYPE

• Feature Pull Request

COMPONENT NAME

zos_operator
zos_operator_action_query

ADDITIONAL INFORMATION

The timing system in zoau has changed to add new options:

• wait_time_s is the maximum number of seconds to wait for a response

• If wait is True, zoau will always wait the maximum amount of time

• If wait is False, zoau will return after data is received

If wait is not included, it defaults to False.

• name: Execute operator command to show jobs, always waiting 5 seconds for response
  zos_operator:
  cmd: 'd a,all'
  wait_time_s: 5
  wait: true

• name: Execute operator command to show jobs, waiting up to 7 seconds for response
  zos_operator:
  cmd: 'd a,all'
  wait_time_s: 7

[richp405]

[richp405]

After discussion, I've updated the code to check for zoau 1.2.5 or later, and will re-request reviews when the ansible tests have passed.

[richp405]

[AndreMarcel99]

Clean and direct

[fernandofloresg]

Looks good to me, just a couple of comments

[ddimatos]

I have not reviewed the code yet but would like to understand the value of wait in addition to wait_time_s, in some of the recent updates we removed wait and this does not align to that model.

So the opercmd docs are here for reference , my question is how more more value do really get from having wait. If wait is true it will wait the full time of wait_time_s , does that mean if wait is false it will return sooner than wait_time_s , eg i set a really long wait_time_s, say 60 seconds and the command finishes in 30 seconds, it returns? Is there a problem with this, in the past I think consoles could write to a registry more than once , would those repeated writes not be captured since wait is true?

I feel like if someone says wait 60, you might just want to always honor that, i see the value in returning early but only if we can be sure that returning early does not truncate anything, in that case we could always set the value to true and avoid exposing it.

[richp405]

@ddimatos This has been a back-and-forth. Customers don't want a big delay all the time, and in some cases they don't want to miss data. In the zoau slack channel, p1696597067029359 is a new entry, through support, asking about this. Ironically, this one is complaining that 1.2.4's 1-second delay is too long.

The return, as I understand if from Anthony, is once something is received and stopped, so wait=false means a 60 second delay could return in 2-3 seconds if output was received.

Just a thought here... maybe we should have a get-together with zoau team so we're all on the same page with what's being asked for, since I've heard a few contradictory issues.

[ddimatos]

@richp405 thanks for that, while I agree no one wants to wait longer then needed especially in a user interactive situation, eg using the the ZOAU cmd line interface. With an Ansible experience where users are more interested in success over performance, they probably don't mind the extra wait time (wait=true - meaning we default to this and don't expose it) else what they face is failing tasks that might return to soon where responses are chunks.

Ansible and ZOAU have two very difference audiences, I want to be sure we are always addressing the Ansible audience when exposing ZOAU options.

[storfibm]

Based on the discussion above, I think the new wait option needs to be integrated silently. Don't expose a new option in the module. Updated #943 to drop the option requirement. Just driving -T in the future alone, however, may cause early returns and truncation issues.

[richp405]

Rebuilt, removing option for wait, and passing through wait_arg=true (-w).

[ddimatos]

Hi @richp405 thanks for the updates and speedy turn around, as I was reading the source I found what I think might be a bug in both modules, more so please don't rush to make changes just yet, I have some concerns about adding wait_time_s to zos_operation_action_query and trying to understand where the original request came from and more so why.

[richp405]

Okay, variables renamed, calls and inputs shuffled, and through the smoke test:

This was addressed in code, with other change (version) being addressed in #1018

[ddimatos]

@richp405 - this looks good and thank you for the the added changes per the review comments, your great to work with, thanks so much Rich.

[fernandofloresg]

My comments around the zoau version checker are being addressed and the rest of this looks good to me.

[richp405]

@ddimatos One last question: should we add version detection here, to decide if default delay is passed as 5 (old style) or 500 (for 1.3 and later?).

[ddimatos]

@richp405 I did think about this and while I did not look their python source, my guess is the timeout is using shell interface option -T which various if you look at the noteworthy changes here and search on timeout you will see the behavior changed from one release to another. Since -w is the new option in ZOAU 1.2.5 which forces the full time specified in -T , i don't think we are using -w (obviously through the python interface but correct me if i am wrong) such that we need to do version detection around this code. I may have misunderstood your question though.

In 1.2.5 in appears to wait up to the time but reads as if it will return early UNLESS -w is specified.

New -w argument added to toggle behavior when waiting for command response output. Specifying this argument causes opercmd to wait the entire timeout period before returning.
The default timeout value has been changed to 1 second. This is the maximum amount of time that opercmd will wait before returning, regardless if it received any command response.

In 1.2.4.1 Python accepts the shell interface default , no change on the shell

In 1.2.4 it appears to wait the full time.

It now waits the exact amount of time specified in the TIMEOUT argument while collecting messages. This allows it to collect more complete message responses from commands that produce multiple single line messages.

Short answer, i don't think so, but correct me if I don't understand your question.