[Bugfix] [Forward port] [zos_copy] Use of force_lock with ASA data sets (#1941)

* [Bugfix] [Forward port] [v1.13.0] [zos_copy] Use of force_lock with ASA data sets (#1939)

* [Bugfix] [v1.12.1] [zos_copy] Add force_lock when copying into an ASA data set (#1932)

* Add force_lock when copying into an ASA data set

* Add changelog fragment

* Add tests

* Update changelog fragment

* Fix force_lock test

* Update changelog fragment

Author: rexemin

changelogs/fragments/1941-zos_copy-asa-dest-lock-support.yml

@@ -0,0 +1,6 @@
+bugfixes:
+  - zos_copy - When ``asa_text`` was set to true at the same time as ``force_lock``,
+    a copy would fail saying the destination was already in use.
+    Fix now opens destination data sets up with disposition SHR when ``force_lock`` and
+    ``asa_text`` are set to true.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1941).

plugins/module_utils/copy.py

@@ -209,7 +209,7 @@ def copy_vsam_ps(src, dest, tmphlq=None):
     return rc, out, err
 
 
-def copy_asa_uss2mvs(src, dest, tmphlq=None):
+def copy_asa_uss2mvs(src, dest, tmphlq=None, force_lock=False):
     """Copy a file from USS to an ASA sequential data set or PDS/E member.
 
     Parameters
@@ -220,6 +220,8 @@ def copy_asa_uss2mvs(src, dest, tmphlq=None):
         The MVS destination data set or member.
     tmphlq : str
         High Level Qualifier for temporary datasets.
+    force_lock : bool
+        Whether to open the destination in SHR mode.
 
     Returns
     -------
@@ -231,12 +233,17 @@ def copy_asa_uss2mvs(src, dest, tmphlq=None):
         The stderr after the copy command executed successfully.
     """
 
-    module = AnsibleModuleHelper(argument_spec={})
-    new_dest = dest.replace('\\', '')
-    new_source = src.replace('\\', '')
     # Removes escaping to execute this command
-    oget_cmd = f"tsocmd \" OGET '{new_source}' '{new_dest}' \""
-    rc, out, err = module.run_command(oget_cmd)
+    dest = dest.replace('\\', '')
+    src = src.replace('\\', '')
+    dest_dsp = "shr" if force_lock else "old"
+
+    ocopy_cmd = "OCOPY INDD(DSSRC) OUTDD(DSTAR) TEXT"
+    ocopy_dds = {
+        "dssrc": src,
+        "dstar": f"{dest},{dest_dsp}"
+    }
+    rc, out, err = ikjeft01(ocopy_cmd, dds=ocopy_dds, authorized=True, tmphlq=tmphlq)
 
     return TSOCmdResponse(rc, out, err)
 

plugins/modules/zos_copy.py

@@ -1083,7 +1083,7 @@ def copy_to_seq(
         copy_args["options"] = ""
 
         if src_type == 'USS' and self.asa_text:
-            response = copy.copy_asa_uss2mvs(new_src, dest, tmphlq=self.tmphlq)
+            response = copy.copy_asa_uss2mvs(new_src, dest, tmphlq=self.tmphlq, force_lock=self.force_lock)
 
             if response.rc != 0:
                 raise CopyOperationError(
@@ -2153,7 +2153,7 @@ def copy_to_member(
         opts["options"] = ""
 
         if src_type == 'USS' and self.asa_text:
-            response = copy.copy_asa_uss2mvs(src, dest, tmphlq=self.tmphlq)
+            response = copy.copy_asa_uss2mvs(src, dest, tmphlq=self.tmphlq, force_lock=self.force_lock)
             rc, out, err = response.rc, response.stdout_response, response.stderr_response
         else:
             # While ASA files are just text files, we do a binary copy

tests/functional/modules/test_zos_copy_func.py

@@ -2088,6 +2088,91 @@ def test_copy_dest_lock(ansible_zos_module, ds_type, f_lock ):
         hosts.all.zos_data_set(name=data_set_2, state="absent")
 
 
+@pytest.mark.seq
+@pytest.mark.pdse
+@pytest.mark.asa
+@pytest.mark.parametrize("ds_type, f_lock",[
+    ( "pds", True),   # Success path, pds locked, force_lock enabled and user authorized
+    ( "pdse", True),  # Success path, pdse locked, force_lock enabled and user authorized
+    ( "seq", True),   # Success path, seq locked, force_lock enabled and user authorized
+    ( "pds", False),  # Module exits with: Unable to write to dest '{0}' because a task is accessing the data set."
+    ( "pdse", False), # Module exits with: Unable to write to dest '{0}' because a task is accessing the data set."
+    ( "seq", False),  # Module exits with: Unable to write to dest '{0}' because a task is accessing the data set."
+])
+def test_copy_asa_dest_lock(ansible_zos_module, ds_type, f_lock ):
+    hosts = ansible_zos_module
+    data_set = get_tmp_ds_name(llq_size=4)
+    data_set = f"{data_set}$#@"
+    member_name = "MEM1"
+
+    if ds_type == "pds" or ds_type == "pdse":
+        dest_data_set = f"{data_set}({member_name})"
+    else:
+        dest_data_set = data_set
+
+    try:
+        hosts.all.zos_data_set(name=data_set, state="present", type=ds_type, replace=True, record_format="fba")
+        if ds_type == "pds" or ds_type == "pdse":
+            hosts.all.zos_data_set(name=dest_data_set, state="present", type="member", replace=True)
+
+        # copy/compile c program and copy jcl to hold data set lock for n seconds in background(&)
+        temp_dir = get_random_file_name(dir=TMP_DIRECTORY)
+        hosts.all.zos_copy(content=c_pgm, dest=f'{temp_dir}/pdse-lock.c', force=True)
+        hosts.all.zos_copy(
+            content=call_c_jcl.format(temp_dir, dest_data_set),
+            dest=f'{temp_dir}/call_c_pgm.jcl',
+            force=True
+        )
+        hosts.all.shell(cmd="xlc -o pdse-lock pdse-lock.c", chdir=f"{temp_dir}/")
+        # submit jcl
+        hosts.all.shell(cmd="submit call_c_pgm.jcl", chdir=f"{temp_dir}/")
+        # pause to ensure c code acquires lock
+        time.sleep(5)
+
+        results = hosts.all.zos_copy(
+            content=ASA_SAMPLE_CONTENT,
+            dest=dest_data_set,
+            remote_src=False,
+            asa_text=True,
+            force=True,
+            force_lock=f_lock
+        )
+
+        for result in results.contacted.values():
+            print(result)
+            if f_lock: #and apf_auth_user:
+                assert result.get("changed") is True
+                assert result.get("msg") is None
+
+                # We need to escape the data set name because we are using cat, using dcat will
+                # bring the trailing empty spaces according to the data set record length.
+                # We only need to escape $ character in this notation
+                dest_escaped = dest_data_set.replace('$', '\\$')
+                verify_copy = hosts.all.shell(
+                    cmd="cat \"//'{0}'\"".format(dest_escaped),
+                    executable=SHELL_EXECUTABLE,
+                )
+
+                for v_cp in verify_copy.contacted.values():
+                    assert v_cp.get("rc") == 0
+                    assert v_cp.get("stdout") == ASA_SAMPLE_RETURN
+            else:
+                assert result.get("failed") is True
+                assert result.get("changed") is False
+                assert "because a task is accessing the data set" in result.get("msg")
+                assert result.get("rc") is None
+    finally:
+        # extract pid
+        ps_list_res = hosts.all.shell(cmd="ps -e | grep -i 'pdse-lock'")
+        # kill process - release lock - this also seems to end the job
+        pid = list(ps_list_res.contacted.values())[0].get('stdout').strip().split(' ')[0]
+        hosts.all.shell(cmd="kill 9 {0}".format(pid.strip()))
+        # clean up c code/object/executable files, jcl
+        hosts.all.shell(cmd=f'rm -r {temp_dir}')
+        # remove destination data set.
+        hosts.all.zos_data_set(name=data_set, state="absent")
+
+
 @pytest.mark.uss
 @pytest.mark.seq
 def test_copy_file_record_length_to_sequential_data_set(ansible_zos_module):