[zos_archive] Revert src encoding post successful archive (#2192)

* code changes to revert encoding

* revert encoding test case

* changelog addition

* resolving pipeline conflicts

* review comments incorporation

* adding link for zos_encode

Author: Rohitcodes28

changelogs/fragments/2192-zos_archive-revert_src_encoding.yml

@@ -0,0 +1,4 @@
+minor_changes:
+  - zos_archive - Adds support for reverting the encoding of a source's
+    files after archiving them. 
+    (https://github.com/ansible-collections/ibm_zos_core/pull/2192)

plugins/modules/zos_archive.py

@@ -318,6 +318,10 @@
         be restored to their original encoding.
       - If encoding fails for any file in a set of multiple files, an
         exception will be raised and archiving will be skipped.
+      - The original files in C(src) will be converted. The module will
+        revert the encoding conversion after a successful archive, but
+        no backup will be created. If you need to encode using a backup
+        and then archive take a look at L(zos_encode,./zos_encode.html) module.
     type: dict
     required: false
     suboptions:
@@ -780,6 +784,10 @@ def compute_dest_size(self):
     def encode_source(self):
         pass
 
+    @abc.abstractmethod
+    def revert_encoding(self):
+        pass
+
     @property
     def result(self):
         """Returns a dict with the results.
@@ -1045,6 +1053,23 @@ def encode_source(self):
             "skipped_encoding_targets": self.skipped_encoding_targets
         }
 
+    def revert_encoding(self):
+        """Revert src encoding to original
+        """
+        enc_utils = encode.EncodeUtils()
+
+        for target in self.encoded:
+            try:
+                convert_rc = enc_utils.uss_convert_encoding_prev(
+                    target, target, self.to_encoding, self.from_encoding
+                )
+                if convert_rc:
+                    enc_utils.uss_tag_encoding(target, self.from_encoding)
+
+            except Exception as e:
+                warning_message = f"Failed to revert source file {os.path.abspath(target)} to its original encoding."
+                raise EncodeError(warning_message) from e
+
 
 class TarArchive(USSArchive):
     def __init__(self, module):
@@ -1180,6 +1205,7 @@ def __init__(self, module):
         self.tmp_data_sets = list()
         self.dest_data_set = module.params.get("dest_data_set")
         self.dest_data_set = dict() if self.dest_data_set is None else self.dest_data_set
+        self.ds_types = {}
 
     def open(self):
         pass
@@ -1536,7 +1562,8 @@ def encode_source(self):
             try:
                 ds_type = data_set.DataSetUtils(target, tmphlq=self.tmphlq).ds_type()
                 if not ds_type:
-                    raise EncodeError("Unable to determine data set type of {0}".format(target))
+                    ds_type = "PS"
+                self.ds_types[target] = ds_type
                 enc_utils.mvs_convert_encoding(
                     target,
                     target,
@@ -1546,7 +1573,7 @@ def encode_source(self):
                     dest_type=ds_type,
                     tmphlq=self.tmphlq
                 )
-                self.encoded.append(os.path.abspath(target))
+                self.encoded.append(target)
             except Exception:
                 self.failed_on_encoding.append(os.path.abspath(target))
         return {
@@ -1555,6 +1582,27 @@ def encode_source(self):
             "skipped_encoding_targets": self.skipped_encoding_targets
         }
 
+    def revert_encoding(self):
+        """Revert src encoding to original
+        """
+        enc_utils = encode.EncodeUtils()
+
+        for target in self.encoded:
+            try:
+                ds_type = self.ds_types.get(target, "PS")
+                enc_utils.mvs_convert_encoding(
+                    target,
+                    target,
+                    self.to_encoding,
+                    self.from_encoding,
+                    src_type=ds_type,
+                    dest_type=ds_type,
+                    tmphlq=self.tmphlq
+                )
+            except Exception as e:
+                warning_message = f"Failed to revert source file {os.path.abspath(target)} to its original encoding."
+                raise EncodeError(warning_message) from e
+
 
 class AMATerseArchive(MVSArchive):
     def __init__(self, module):
@@ -2013,8 +2061,10 @@ def run_module():
     if archive.dest_exists() and not archive.force:
         module.fail_json(msg="%s file exists. Use force flag to replace dest" % archive.dest)
 
+    encoding_result = None
     archive.find_targets()
     if archive.targets_exist():
+        # encoding the source if encoding is provided.
         if encoding:
             archive.encoding_targets()
             encoding_result = archive.encode_source()
@@ -2031,6 +2081,9 @@ def run_module():
         if archive.dest_type() == "USS":
             archive.update_permissions()
         archive.changed = archive.is_different_from_original()
+        # after successful archive revert the source encoding for all the files encoded.
+        if encoding_result:
+            archive.revert_encoding()
     archive.get_state()
 
     module.exit_json(**archive.result)

tests/functional/modules/test_zos_archive_func.py

@@ -442,6 +442,7 @@ def test_uss_archive_encode_skip_encoding(ansible_zos_module, ds_format):
 # - test_mvs_archive_single_dataset_encoding
 # - test_mvs_archive_multiple_dataset_pattern_encoding
 # - test_mvs_archive_multiple_dataset_pattern_encoding_skip_encoding
+# - test_mvs_archive_multiple_dataset_pattern_encoding_revert_src_encoding
 
 
 @pytest.mark.ds
@@ -1464,6 +1465,126 @@ def test_mvs_archive_multiple_dataset_pattern_encoding_skip_encoding(ansible_zos
 
             archived_datasets.append(archive_data_set)
 
+    finally:
+        for ds_name in matched_datasets:
+            hosts.all.zos_data_set(name=ds_name, state="absent")
+        for archive_ds in archived_datasets:
+            hosts.all.zos_data_set(name=archive_ds, state="absent")
+
+@pytest.mark.ds
+@pytest.mark.parametrize(
+    "ds_format", [
+        "terse"
+    ])
+@pytest.mark.parametrize(
+    "data_set", [
+        {
+            "dstype": "seq",
+            "members": [""]
+        }
+    ])
+@pytest.mark.parametrize(
+    "encoding", [
+        {"from": "IBM-1047", "to": "ISO8859-1"},
+    ])
+def test_mvs_archive_multiple_dataset_pattern_encoding_revert_src_encoding(ansible_zos_module, ds_format, data_set, encoding):
+    try:
+        hosts = ansible_zos_module
+        hlq_prefix = "OMVSADM.ABC"
+        matched_datasets = [f"{hlq_prefix}.A", f"{hlq_prefix}.B"]
+        archived_datasets = []
+        copy_src_datasets = [f"{hlq_prefix}.C", f"{hlq_prefix}.D"]
+        all_datasets_to_process = matched_datasets + copy_src_datasets
+
+        for ds_name in all_datasets_to_process:
+            hosts.all.zos_data_set(name=ds_name, state="absent")
+            hosts.all.zos_data_set(
+                name=ds_name,
+                type=data_set.get("dstype"),
+                state="present",
+                replace=True,
+            )
+            if data_set.get("dstype") in ["pds", "pdse"]:
+                for member in data_set.get("members"):
+                    hosts.all.zos_data_set(
+                        name=f"{ds_name}({member})",
+                        type="member",
+                        state="present"
+                    )
+        
+        test_line = "pattern match"
+        for ds_name in all_datasets_to_process:
+            for member in data_set.get("members"):
+                ds_target = f"{ds_name}({member})" if member else ds_name
+                hosts.all.shell(cmd=f"decho '{test_line}' \"{ds_target}\"")
+
+        format_dict = {"name": ds_format}
+        if ds_format == "terse":
+            format_dict["format_options"] = {"terse_pack": "spack"}
+        for ds_name in matched_datasets:
+
+            original_hex_result = hosts.all.shell(cmd=f"dcat '{ds_name}' | od -x")
+            host_original_result = None
+            if original_hex_result.contacted:
+                host_original_result = next(iter(original_hex_result.contacted.values()))
+
+            original_hex_output_lines = [line.strip() for line in host_original_result.get("stdout", "").splitlines() if line.strip()]
+            archive_data_set = get_tmp_ds_name()
+            archive_result = hosts.all.zos_archive(
+                src=ds_name,
+                dest=archive_data_set,
+                format=format_dict,
+                encoding=encoding,
+            )
+            reverted_hex_result = hosts.all.shell(cmd=f"dcat '{ds_name}' | od -x")  
+            host_reverted_result = None
+            if reverted_hex_result.contacted:
+                host_reverted_result = next(iter(reverted_hex_result.contacted.values()))
+            reverted_hex_output_lines = [line.strip() for line in host_reverted_result.get("stdout", "").splitlines() if line.strip()]
+
+            original_hex = []
+            for line in original_hex_output_lines:
+                if line == '*':
+                    original_hex.append('*')
+                else:
+                    parts = line.split()
+                    if len(parts) > 1: 
+                        original_hex.extend(parts[1:])
+
+            reverted_hex = []
+            for line in reverted_hex_output_lines:
+                if line == '*':
+                    reverted_hex.append('*')
+                else:
+                    parts = line.split()
+                    if len(parts) > 1:
+                        reverted_hex.extend(parts[1:])
+
+            for result in archive_result.contacted.values():
+                try:
+                    original_first_star_idx = original_hex.index('*')
+                except ValueError:
+                    original_first_star_idx = len(original_hex) 
+
+                try:
+                    reverted_first_star_idx = reverted_hex.index('*')
+                except ValueError:
+                    reverted_first_star_idx = len(reverted_hex)
+                
+                original_hex_to_compare = original_hex[:original_first_star_idx]
+                reverted_hex_to_compare = reverted_hex[:reverted_first_star_idx]
+
+                is_identical = (original_hex_to_compare == reverted_hex_to_compare)
+                assert is_identical is True
+                assert result.get("changed") is True
+                assert result.get("dest") == archive_data_set
+                assert ds_name in result.get("archived")
+            cmd_result = hosts.all.shell(cmd=f"dls {archive_data_set}")
+            for c_result in cmd_result.contacted.values():
+                assert archive_data_set in c_result.get("stdout")
+
+            archived_datasets.append(archive_data_set)
+
     finally:
         for ds_name in matched_datasets:
             hosts.all.zos_data_set(name=ds_name, state="absent")