[Enhancement] zos_mvs_raw dd_input content can vary for programs

[ddimatos]

Bug description

UPDATE: 9/13/23
[Start]
I decided against splitting this item because I did some of the work/research. I think the goal of this work item is now to update and add additional examples using various techniques such an array of strings, single string using quote and content block using YAML block scalars. Include additional doc updates and explain the various techniques to the user (educate them) so that the documentation aids them well enough to choose the best approach. We will update our doc to demonstrate and suggest In-stream control statements and in-stream data set inputs begin at column 2, of course there will exist a program that will want column 1 to be the starting point but that is likely to be a niche requirement, column 2 will be a better choice for our documentation. Please read through the original issue to understand more of the issue. With the latest update this aligns more to a doc issue but because some testing and development time will be needed we can move this from bug to enhancement.
[End]

Original issue:
I would not necessarily consider this a bug as is between a bug , doc enhancement and enabler.

The approach taken for zos_mvs_raw's dd_input was a standard approach of an array of strings, while that mostly works for programs like IDCAMS , have seen at times none of our documented inputs will suffice and I resort to more technically less common known ways such as using a block indicator and block indicator indentation ( conent: | 1). I don't know if we can find common denominator for all utilities or should document and maybe explain how one might go about trouble shooting.

If you use this issue to create your load module #633 then you can follow along with the RELINK scenario I will share and how you experience what I am describing.

In the working example notice the content block:

              content: |1
                INCLUDE INLIB
                NAME {{ MEM_TEST }}(R)

Then notice the content verbose output of how that is interpreted:

"dd_input": {
                        "content": " INCLUDE INLIB\n NAME HELLODDD(R)\n",
                        "dd_name": "syslin",
                        "return_content": null
                    },

Then try other combinations all of which will not work:
(1)

              content: |
                INCLUDE INLIB
                NAME {{ MEM_TEST }}(R)

results in:

"content": "INCLUDE INLIB\nNAME HELLODDD(R)\n",

(2)

              content: |
                "INCLUDE INLIB
                NAME {{ MEM_TEST }}(R)"

results in

 "content": "\"INCLUDE INLIB\nNAME HELLODDD(R)\"\n",

(3)

              content:
                "INCLUDE INLIB
                NAME {{ MEM_TEST }}(R)"

results in

"content": "INCLUDE INLIB NAME HELLODDD(R)",

(4)

              content:
               " INCLUDE INLIB -
                NAME {{ MEM_TEST }}(R)"

results in

"content": "INCLUDE INLIB - NAME HELLODDD(R)",

(5)

              content:
                - INCLUDE INLIB
                - NAME {{ MEM_TEST }}(R)

results in:

                        "content": [
                            "INCLUDE INLIB",
                            "NAME HELLODDD(R)"
                        ],

(6)

              content:
                - "INCLUDE INLIB"
                - "NAME {{ MEM_TEST }}(R)"

results in

                        "content": [
                            "INCLUDE INLIB",
                            "NAME HELLODDD(R)"
                        ],

I will leave the various additional variations of content up to the development team but this is a good start , ensure you look at the content output and you will see how each dd_input varies just enough to not work for IEWBLINK

Point of this issue is to see if there is common denominator (best practice) for input that we can default to or is there just no really reasonable way to do this and it must fall on documentation and education. In other words, the ask here is:

Is there a best practice across the board that column 1 of any input be empty for In-stream control statements and in-stream data set as a convention?

Because of the flexibility in the content block, it could mean success or failure. I would be hesitant to suggest that conten |1 always be used without proper research. I also would be hesitant to take control of users input and try to make it conform to a best practice as it would change the experience.

We might just need to add a number of new examples let users see other ways to pass content and let them try a few of them. That might be the short term plan and longer term we explore this space.

Thus for this item, i would expect we provide a variety of examples for the same command, maybe idcams could be the basis for that and also review item #374 which relates to this.

Playbook verbosity output

This is a working example:

---
- hosts: zvm
  collections:
    - ibm.ibm_zos_core
  gather_facts: false
  vars:
    LIB: "ANSIBLE.COBOL.LOADLIB"
    MEM_PGM: "HELLOPGM"
    MEM_TEST: "HELLODDD"
    USS_EXE: "/tmp/HIPGMUSS"
    VOLUME: "SCR03"

  environment: "{{ environment_vars }}"

  tasks:
    - name: Copy program object from "{{ LIB }}" to  "{{ USS_EXE }}"
      zos_copy:
        src: "{{ LIB }}({{ MEM_PGM }})"
        dest: "{{ USS_EXE }}"
        remote_src: yes
        force: true
      register: result

    - name: Result
      debug:
         msg: "{{result}}"

    - name: Relink "{{ USS_EXE }} to {{ LIB }}({{ MEM_TEST }})"
      zos_mvs_raw:
        program_name: IEWBLINK
        auth: no
        parm: "LIST,REUS,RENT,NCAL,LET,MAP"
        dds:
          - dd_unix:
              dd_name: INLIB
              path: "{{ USS_EXE }}"
              access_group: ordonly
          - dd_data_set:
              dd_name: SYSLMOD
              data_set_name: "{{ LIB }}"
              disposition: shr
              volumes:
                - "{{ VOLUME }}"
          - dd_input:
              dd_name: syslin
              content: |1
                INCLUDE INLIB
                NAME {{ MEM_TEST }}(R)
          - dd_output:
              dd_name: sysprint
              return_content:
                type: text
      register: result

    - name: Result
      debug:
         msg: "{{result}}"

Contents of ansible.cfg

No response

Contents of the inventory

No response

Contents of group_vars or host_vars

No response

Ansible version

2.11.12

IBM z/OS Ansible core Version

v1.5.0-beta.1

IBM ZOAU version

v1.2.2

z/OS version

No response

Ansible module

zos_mvs_raw