[Enhancement][2071][zos_mvs_raw]Programs_fails_when_need_access_to_the_first_and_second_columns (#2086)

* Fix line problem

* Add prepend spaces option

* Resolve read a file

* Add test cases to validate the work of columns reserved

* Add fragment

* Fix lint

* Add new space

* Fix typo

* Update plugins/modules/zos_mvs_raw.py

Co-authored-by: Fernando Flores <[email protected]>

* Update plugins/modules/zos_mvs_raw.py

Co-authored-by: Fernando Flores <[email protected]>

* Update plugins/modules/zos_mvs_raw.py

Co-authored-by: Fernando Flores <[email protected]>

* Update plugins/modules/zos_mvs_raw.py

Co-authored-by: Fernando Flores <[email protected]>

* Update plugins/modules/zos_mvs_raw.py

Co-authored-by: Fernando Flores <[email protected]>

* Fix space

* Add documentation

---------

Co-authored-by: Fernando Flores <[email protected]>

Author: AndreMarcel99

changelogs/fragments/2086_Programs_fails_when_need_access_to_the_first_and_second_columns.yml

@@ -0,0 +1,5 @@
+minor_changes:
+  - zos_mvs_raw  - Before this addition, you could not put anything in columns 1 or 2, were reserved for JCL processing.
+    Change now allows add reserved_cols option and validate that the module get access to modify dd_content option
+    base on the value, if not retain the previous behavior or work.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2086)

plugins/modules/zos_mvs_raw.py

@@ -583,6 +583,13 @@
                 string, list of strings and when using a YAML block indicator.
             required: true
             type: raw
+          reserved_cols:
+            description:
+              - Determines how many columns at the beginning of the content are reserved with
+                empty spaces.
+            type: int
+            required: false
+            default: 2
           return_content:
             description:
               - Determines how content should be returned to the user.
@@ -1195,6 +1202,13 @@
                         string, list of strings and when using a YAML block indicator.
                     required: true
                     type: raw
+                  reserved_cols:
+                    description:
+                      - Determines how many columns at the beginning of the content are reserved with
+                        empty spaces.
+                    type: int
+                    required: false
+                    default: 2
                   return_content:
                     description:
                       - Determines how content should be returned to the user.
@@ -1607,6 +1621,28 @@
                       VOLUMES(222222) -
                       UNIQUE)
 
+- name: Simple FTP connection using frist and second columns.
+  zos_mvs_raw:
+    program_name: AMAPDUPL
+    auth: true
+    dds:
+      - dd_output:
+          dd_name: sysprint
+          return_content:
+            type: text
+      - dd_data_set:
+          dd_name: SYSUT1
+          data_set_name: myhlq.ds1.output
+          disposition: shr
+      - dd_input:
+          dd_name: sysin
+          reserved_cols: 0
+          content: |
+            USERID=anonymous
+            PASSWORD=anonymous
+            TARGET_SYS=testcase.boulder.ibm.com
+            TARGET_DSN=wessamp.bigfile
+
 - name: List data sets matching pattern in catalog,
     save output to a new generation of gdgs.
   zos_mvs_raw:
@@ -1785,6 +1821,7 @@ def run_module():
 
     dd_input_base = dict(
         content=dict(type="raw", required=True),
+        reserved_cols=dict(type="int", required=False, default=2),
         return_content=dict(
             type="dict",
             options=dict(
@@ -2045,7 +2082,8 @@ def parse_and_validate_args(params):
     )
 
     dd_input_base = dict(
-        content=dict(type=dd_content, required=True),
+        content=dict(type=dd_content, required=True, dependencies=["reserved_cols"]),
+        reserved_cols=dict(type="int", required=False, default=2),
         return_content=dict(
             type="dict",
             options=dict(
@@ -2301,15 +2339,16 @@ def dd_content(contents, dependencies):
         return None
     if contents is not None:
         # Empty string can be passed for content but not modify to ensure proper entry
+        spaces = dependencies.get("reserved_cols")
         if len(contents) > 0:
-            contents = modify_contents(contents)
+            contents = modify_contents(contents, spaces)
         return contents
     if isinstance(contents, list):
         return "\n".join(contents)
     return contents
 
 
-def modify_contents(contents):
+def modify_contents(contents, spaces):
     """Return the content of dd_input to a valid form for a JCL program.
 
     Parameters
@@ -2324,18 +2363,20 @@ def modify_contents(contents):
     """
     if not isinstance(contents, list):
         contents = list(contents.split("\n"))
-    contents = prepend_spaces(contents)
+    contents = prepend_spaces(contents, spaces)
     contents = "\n".join(contents)
     return contents
 
 
-def prepend_spaces(lines):
+def prepend_spaces(lines, spaces=2):
     """Return the array with two spaces at the beggining.
 
     Parameters
     ----------
         lines : list
               The list with a line of a program.
+        spaces : int
+              The number of columns to add as left padding to the content.
 
     Raises
     -------
@@ -2351,17 +2392,15 @@ def prepend_spaces(lines):
     for index, line in enumerate(lines):
         if len(line) > 0:
             if len(line) > 80:
-                msg = """Length of line {0} is over 80 characters. The maximum length allowed is 80 characters, including 2 spaces at the beginning.
-                                 If the two spaces are not present, the module will add them to ensure columns 1 and 2 are blank. """
+                msg = """Length of line {0} is over 80 characters. The maximum length allowed is 80 characters. """
                 module.fail_json(msg=msg.format(line))
             else:
-                if len(line) > 1 and line[0] != " " and line[1] != " ":
-                    if len(line) > 78:
-                        msg = """Length of line {0} is over 80 characters. The maximum length allowed is 80 characters, including 2 spaces at the beginning.
-                                         If the two spaces are not present, the module will add them to ensure columns 1 and 2 are blank. """
-                        module.fail_json(msg=msg.format(line))
-                    else:
-                        lines[index] = "  {0}".format(line)
+                len_line = len(line)
+                lines[index] = line.rjust(len_line + spaces, " ")
+                if len(lines[index]) > 80:
+                    msg = """Length of line {0} is over 80 characters. The maximum length allowed is 80 characters. Including the spaces at the beginning.
+                    Be aware that the module has reserved {1} columns to the left for JCL processing this value can be modified if the program allows for it."""
+                    module.fail_json(msg=msg.format(line, spaces))
     return lines
 
 

tests/functional/modules/test_zos_mvs_raw_func.py

@@ -109,6 +109,59 @@ def test_disposition_new(ansible_zos_module, verbose):
         if idcams_dataset:
             hosts.all.zos_data_set(name=idcams_dataset, state="absent")
 
+@pytest.mark.parametrize(
+        # Added this verbose to test issue https://github.com/ansible-collections/ibm_zos_core/issues/1359
+        # Where a program will fail if rc != 0 only if verbose was True.
+        "columns",
+        [0, 2],
+)
+def test_dd_content_reserved_columns(ansible_zos_module, columns):
+    idcams_dataset = None
+    try:
+        hosts = ansible_zos_module
+        default_data_set = get_tmp_ds_name()
+        idcams_dataset, idcams_listcat_dataset_cmd = get_temp_idcams_dataset(hosts)
+        idcams_listcat_dataset_cmd = idcams_listcat_dataset_cmd.lstrip()
+
+        hosts.all.zos_data_set(name=default_data_set, state="absent")
+        results = hosts.all.zos_mvs_raw(
+            program_name="idcams",
+            auth=True,
+            dds=[
+                {
+                    "dd_data_set":{
+                        "dd_name":SYSPRINT_DD,
+                        "data_set_name":default_data_set,
+                        "disposition":"new",
+                        "type":"seq",
+                        "return_content":{
+                            "type":"text"
+                        },
+                    },
+                },
+                {
+                    "dd_input":{
+                        "dd_name":SYSIN_DD,
+                        "reserved_cols": columns,
+                        "content":idcams_listcat_dataset_cmd
+                    }
+                },
+            ],
+        )
+        for result in results.contacted.values():
+            if columns > 0:
+                assert result.get("ret_code", {}).get("code", -1) == 0
+                assert len(result.get("dd_names", [])) > 0
+                assert result.get("failed", False) is False
+            else:
+                assert result.get("ret_code", {}).get("code", -1) == 12
+                assert len(result.get("dd_names", [])) > 0
+                assert result.get("failed", False) is True
+    finally:
+        hosts.all.zos_data_set(name=default_data_set, state="absent")
+        if idcams_dataset:
+            hosts.all.zos_data_set(name=idcams_dataset, state="absent")
+
 @pytest.mark.parametrize(
     "disposition",
     ["shr", "mod", "old"],
@@ -1198,7 +1251,7 @@ def test_input_provided_as_list(ansible_zos_module):
         ("text", "LISTCAT ENTRIES"),
         (
             "base64",
-            "QNPJ4uPDweNAxdXj2cnF4k1",
+            "QEBA08ni48PB40DF1ePZycX",
             # the above corresponds to the following bytes:
             # 40 d3 c9 e2 e3 c3 c1 e3 40 c5 d5 e3 d9 c9 c5 e2
             # which translate in ebdic to: " LISTCAT ENTRIES"