Staging v1.7.0 beta.2 (#939)

* Enhancement/866 archive (#930)

* Added action plugin zos_unarchive

* Added zos_archive changes

* Added zos_unarchive changes

* Added zos_archive tests changes

* Added test zos_unarchive changes

* Added zos_archive changes

* fixed pep8 issues

* Changed source to src in docs

* Added correct copyright year

* Updated docs

* Added changelog fragments

* Updated docs

* Updated galaxy.yml

* Updated meta

* Updated docs

* Added zos_gather_facts rst

* Added changelog

* Added release notes

* Changed variable name to avoid shadowing import

* Delete 930-archive-post-beta.yml

* Delete v1.7.0-beta.2_summary.yml

Author: fernandofloresg

CHANGELOG.rst

@@ -5,6 +5,31 @@ ibm.ibm_zos_core Release Notes
 .. contents:: Topics
 
 
+v1.7.0-beta.2
+=============
+
+Release Summary
+---------------
+
+Release Date: '2023-08-21'
+This changelog describes all changes made to the modules and plugins included
+in this collection. The release date is the date the changelog is created.
+For additional details such as required dependencies and availability review
+the collections `release notes <https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html>`__
+
+Minor Changes
+-------------
+
+- zos_archive - If destination data set space is not provided then the module computes it based on the src list and/or expanded src list based on pattern provided. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+- zos_archive - When xmit faces a space error in xmit operation because of dest or log data set are filled raises an appropriate error hint. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+- zos_unarchive - When copying to remote fails now a proper error message is displayed. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+- zos_unarchive - When copying to remote if space_primary is not defined, then is defaulted to 5M. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+
+Bugfixes
+--------
+
+- zos_archive - Module did not return the proper src state after archiving. Fix now displays the status of the src after the operation. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+
 v1.7.0-beta.1
 =============
 

changelogs/.plugin-cache.yaml

@@ -126,4 +126,4 @@ plugins:
   strategy: {}
   test: {}
   vars: {}
-version: 1.7.0-beta.1
+version: 1.7.0-beta.2

changelogs/changelog.yaml

@@ -981,3 +981,31 @@ releases:
       name: zos_unarchive
       namespace: ''
     release_date: '2023-07-26'
+  1.7.0-beta.2:
+    changes:
+      bugfixes:
+      - zos_archive - Module did not return the proper src state after archiving.
+        Fix now displays the status of the src after the operation. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+      minor_changes:
+      - zos_archive - If destination data set space is not provided then the module
+        computes it based on the src list and/or expanded src list based on pattern
+        provided. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+      - zos_archive - When xmit faces a space error in xmit operation because of dest
+        or log data set are filled raises an appropriate error hint. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+      - zos_unarchive - When copying to remote fails now a proper error message is
+        displayed. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+      - zos_unarchive - When copying to remote if space_primary is not defined, then
+        is defaulted to 5M. (https://github.com/ansible-collections/ibm_zos_core/pull/930).
+      release_summary: 'Release Date: ''2023-08-21''
+
+        This changelog describes all changes made to the modules and plugins included
+
+        in this collection. The release date is the date the changelog is created.
+
+        For additional details such as required dependencies and availability review
+
+        the collections `release notes <https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html>`__'
+    fragments:
+    - 930-archive-post-beta.yml
+    - v1.7.0-beta.2_summary.yml
+    release_date: '2023-08-21'

docs/source/modules/zos_archive.rst

@@ -112,14 +112,20 @@ dest
 
   If *dest* is a nonexistent USS file, it will be created.
 
+  If *dest* is an existing file or data set and *force=true*, the existing *dest* will be deleted and recreated with attributes defined in the *dest_data_set* option or computed by the module.
+
+  If *dest* is an existing file or data set and *force=false* or not specified, the module exits with a note to the user.
+
   Destination data set attributes can be set using *dest_data_set*.
 
+  Destination data set space will be calculated based on space of source data sets provided and/or found by expanding the pattern name. Calculating space can impact module performance. Specifying space attributes in the *dest_data_set* option will improve performance.
+
   | **required**: True
   | **type**: str
 
 
 exclude
-  Remote absolute path, glob, or list of paths, globs or data set name patterns for the file, files or data sets to exclude from path list and glob expansion.
+  Remote absolute path, glob, or list of paths, globs or data set name patterns for the file, files or data sets to exclude from src list and glob expansion.
 
   Patterns (wildcards) can contain one of the following, `?`, `*`.
 
@@ -152,7 +158,7 @@ mode
 
   The mode may also be specified as a symbolic mode (for example, 'u+rwx' or 'u=rw,g=r,o=r') or a special string 'preserve'.
 
-  *mode=preserve* means that the file will be given the same permissions as the source file.
+  *mode=preserve* means that the file will be given the same permissions as the src file.
 
   | **required**: False
   | **type**: str
@@ -170,7 +176,7 @@ owner
 
 
 remove
-  Remove any added source files , trees or data sets after module `zos_archive <./zos_archive.html>`_ adds them to the archive. Source files, trees and data sets are identified with option *path*.
+  Remove any added source files , trees or data sets after module `zos_archive <./zos_archive.html>`_ adds them to the archive. Source files, trees and data sets are identified with option *src*.
 
   | **required**: False
   | **type**: bool
@@ -387,6 +393,8 @@ Notes
 
    When packing and using ``use_adrdssu`` flag the module will take up to two times the space indicated in ``dest_data_set``.
 
+   tar, zip, bz2 and pax are archived using python ``tarfile`` library which uses the latest version available for each format, for compatibility when opening from system make sure to use the latest available version for the intended format.
+
 
 
 See Also
@@ -425,7 +433,7 @@ dest_state
 
   ``compress`` when the file is compressed, but not an archive.
 
-  ``incomplete`` when the file is an archive, but some files under *path* were not found.
+  ``incomplete`` when the file is an archive, but some files under *src* were not found.
 
   | **returned**: success
   | **type**: str

docs/source/modules/zos_gather_facts.rst

@@ -22,6 +22,11 @@ Synopsis
 - Note, the module will fail fast if any unsupported options are provided. This is done to raise awareness of a failure in an automation setting.
 
 
+Requirements
+------------
+
+- ZOAU 1.2.1 or later.
+
 
 
 

docs/source/release_notes.rst

@@ -6,6 +6,39 @@
 Releases
 ========
 
+Version 1.7.0-beta.2
+====================
+
+Minor Changes
+-------------
+- ``zos_archive``
+
+      - When xmit faces a space error in xmit operation because of dest or log data set being filled raises an appropriate error hint.
+      - If destination data set space is not provided then the module computes it based on the src list and/or expanded src list based on pattern provided.
+
+- ``zos_unarchive``
+
+      - When copying to remote fails now a proper error message is displayed.
+      - When copying to remote if space_primary is not defined, then is defaulted to 5M.
+
+Bugfixes
+--------
+- ``zos_archive`` - Module did not return the proper src state after archiving. Fix now displays the status of the src after the operation.
+
+Availability
+------------
+
+* `Galaxy`_
+* `GitHub`_
+
+Reference
+---------
+
+* Supported by `z/OS V2R3`_ or later
+* Supported by the `z/OS® shell`_
+* Supported by `IBM Open Enterprise SDK for Python`_ `3.9`_ - `3.11`_
+* Supported by IBM `Z Open Automation Utilities 1.2.3`_ (or later) but prior to version 1.3.
+
 Version 1.7.0-beta.1
 ====================
 

galaxy.yml

@@ -6,7 +6,7 @@ namespace: ibm
 name: ibm_zos_core
 
 # The collection version
-version: 1.7.0-beta.1
+version: 1.7.0-beta.2
 
 # Collection README file
 readme: README.md
@@ -19,7 +19,7 @@ authors:
   - Ivan Moreno <[email protected]>
   - Oscar Fernando Flores Garcia <[email protected]>
   - Jenny Huang <[email protected]>
-  - Marcel Guitierrez <[email protected]>
+  - Marcel Gutierrez <[email protected]>
 
 # Description
 description: The IBM z/OS core collection includes connection plugins, action plugins, modules, filters and ansible-doc to automate tasks on z/OS.

meta/ibm_zos_core_meta.yml

@@ -1,5 +1,5 @@
 name: ibm_zos_core
-version: "1.7.0-beta.1"
+version: "1.7.0-beta.2"
 managed_requirements:
     -
         name: "IBM Open Enterprise SDK for Python"

plugins/action/zos_unarchive.py

@@ -61,6 +61,8 @@ def run(self, tmp=None, task_vars=None):
             format_name = format.get("name")
             copy_module_args = dict()
             dest_data_set = format.get("dest_data_set")
+            if dest_data_set is None:
+                dest_data_set = dict()
             dest = ""
             if source.startswith('~'):
                 source = os.path.expanduser(source)
@@ -80,14 +82,12 @@ def run(self, tmp=None, task_vars=None):
                     task_vars=task_vars,
                 )
                 dest = cmd_res.get("stdout")
-                if dest_data_set is None:
-                    if format_name == 'terse':
-                        dest_data_set = dict(type='SEQ', record_format='FB', record_length=1024)
-                    if format_name == 'xmit':
-                        dest_data_set = dict(type='SEQ', record_format='FB', record_length=80)
-            else:
-                # Raise unsupported format name
-                None
+                if dest_data_set.get("space_primary") is None:
+                    dest_data_set.update(space_primary=5, space_type="M")
+                if format_name == 'terse':
+                    dest_data_set.update(type='SEQ', record_format='FB', record_length=1024)
+                if format_name == 'xmit':
+                    dest_data_set.update(type='SEQ', record_format='FB', record_length=80)
 
             copy_module_args.update(
                 dict(
@@ -107,15 +107,17 @@ def run(self, tmp=None, task_vars=None):
                                                          templar=self._templar,
                                                          shared_loader_obj=self._shared_loader_obj)
             result.update(zos_copy_action_module.run(task_vars=task_vars))
-
-            module_args["src"] = dest
-            display.vvv(u"Copy args {0}".format(result), host=self._play_context.remote_addr)
-
-            result.update(
-                self._execute_module(
-                    module_name="ibm.ibm_zos_core.zos_unarchive",
-                    module_args=module_args,
-                    task_vars=task_vars,
+            display.vvv(u"Copy result {0}".format(result), host=self._play_context.remote_addr)
+            if result.get("msg") is None:
+                module_args["src"] = dest
+
+                result.update(
+                    self._execute_module(
+                        module_name="ibm.ibm_zos_core.zos_unarchive",
+                        module_args=module_args,
+                        task_vars=task_vars,
+                    )
                 )
-            )
+            else:
+                result.update(dict(failed=True))
         return result