[v1.10.0] [Enabler] Standardization of choices in modules (#1388)

* Update zos_archive choices

* Update zos_backup_restore choices

* Update zos_copy choices

* Update zos_data_set choices

* Update module docs

* Update zos_job_submit choices

* Update zos_mount choices

* Update zos_unarchive choices

* Fix zos_archive and update its tests

This also includes major work on zos_data_set since half of the test suite for zos_archive depends on creating data sets.

* Update zos_backup_restore tests

* Update zos_blockinfile tests

* Update more modules

* Updated more tests

* Update zos_unarchive and zos_mount

* Update zos_backup_restore unit tests

* Update zos_mvs_raw

* Update zos_copy tests

* Fix some sanity issues

* Fix zos_copy KSDS test

* Update zos_copy some more

* Fix ZFS call

* Update zos_unarchive tests

* Add massive changelog fragment

* Fix call to zos_data_set

* Fix more test issues in zos_fetch

* Fix zos_find tests

* Generate updated docs

Author: rexemin

changelogs/fragments/1388-lowercase-choices.yml

@@ -0,0 +1,87 @@
+breaking_changes:
+  - zos_archive - option ``terse_pack`` no longer accepts uppercase choices,
+    users should replace them with lowercase ones.
+    Suboption ``type`` of ``dest_data_set`` no longer accepts uppercase
+    choices, users should replace them with lowercase ones.
+    Suboption ``space_type`` of ``dest_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Suboption ``record_format`` of ``dest_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_backup_restore - option ``space_type`` no longer accepts uppercase
+    choices, users should replace them with lowercase ones.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_copy - suboption ``type`` of ``dest_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Suboption ``space_type`` of ``dest_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Suboption ``record_format`` of ``dest_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_data_set - option ``type`` no longer accepts uppercase choices,
+    users should replace them with lowercase ones.
+    Option ``space_type`` no longer accepts uppercase choices, users
+    should replace them with lowercase ones.
+    Option ``record_format`` no longer accepts uppercase choices, users
+    should replace them with lowercase ones.
+    Options inside ``batch`` no longer accept uppercase choices, users should
+    replace them with lowercase ones.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_job_submit - option ``location`` no longer accepts uppercase choices,
+    users should replace them with lowercase ones.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_mount - option ``fs_type`` no longer accepts uppercase choices,
+    users should replace them with lowercase ones.
+    Option ``unmount_opts`` no longer accepts uppercase choices, users
+    should replace them with lowercase ones.
+    Option ``mount_opts`` no longer accepts uppercase choices, users
+    should replace them with lowercase ones.
+    Option ``tag_untagged`` no longer accepts uppercase choices, users
+    should replace them with lowercase ones.
+    Option ``automove`` no longer accepts uppercase choices, users
+    should replace them with lowercase ones.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_mvs_raw - suboption ``type`` of ``dd_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Suboptions ``disposition_normal`` and ``disposition_abnormal`` of
+    ``dd_data_set`` no longer accept ``catlg`` and ``uncatlg`` as choices.
+    This also applies when defining a ``dd_data_set`` inside ``dd_concat``.
+    Suboption ``space_type`` of ``dd_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Suboption ``record_format`` of ``dd_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Suboption ``record_format`` of ``dd_unix`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Options inside ``dd_concat`` no longer accept uppercase choices,
+    users should replace them with lowercase ones.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_unarchive - suboption ``type`` of ``dest_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Suboption ``space_type`` of ``dest_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    Suboption ``record_format`` of ``dest_data_set`` no longer accepts
+    uppercase choices, users should replace them with lowercase ones.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+
+trivial:
+  - zos_blockinfile - updated tests to use lowercase options when calling
+    another module in the collection.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_find - updated tests to use lowercase options when calling
+    another module in the collection.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_lineinfile - updated tests to use lowercase options when calling
+    another module in the collection.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_encode - updated tests to use lowercase options when calling
+    another module in the collection.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_fetch - updated tests to use lowercase options when calling
+    another module in the collection.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_job_output - updated tests to use lowercase options when calling
+    another module in the collection.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).
+  - zos_job_query - updated tests to use lowercase options when calling
+    another module in the collection.
+    (https://github.com/ansible-collections/ibm_zos_core/pull/1388).

docs/source/modules/zos_apf.rst

@@ -37,7 +37,7 @@ library
 
 
 state
-  Ensure that the library is added ``state=present`` or removed ``state=absent``.
+  Ensure that the library is added \ :literal:`state=present`\  or removed \ :literal:`state=absent`\ .
 
   The APF list format has to be "DYNAMIC".
 
@@ -58,38 +58,38 @@ force_dynamic
 
 
 volume
-  The identifier for the volume containing the library specified in the ``library`` parameter. The values must be one the following.
+  The identifier for the volume containing the library specified in the \ :literal:`library`\  parameter. The values must be one the following.
 
   1. The volume serial number.
 
-  2. Six asterisks (******), indicating that the system must use the volume serial number of the current system residence (SYSRES) volume.
+  2. Six asterisks (\*\*\*\*\*\*), indicating that the system must use the volume serial number of the current system residence (SYSRES) volume.
 
-  3. *MCAT*, indicating that the system must use the volume serial number of the volume containing the master catalog.
+  3. \*MCAT\*, indicating that the system must use the volume serial number of the volume containing the master catalog.
 
-  If ``volume`` is not specified, ``library`` has to be cataloged.
+  If \ :literal:`volume`\  is not specified, \ :literal:`library`\  has to be cataloged.
 
   | **required**: False
   | **type**: str
 
 
 sms
-  Indicates that the library specified in the ``library`` parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library.
+  Indicates that the library specified in the \ :literal:`library`\  parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library.
 
-  If ``sms=True``, ``volume`` value will be ignored.
+  If \ :literal:`sms=True`\ , \ :literal:`volume`\  value will be ignored.
 
   | **required**: False
   | **type**: bool
   | **default**: False
 
 
 operation
-  Change APF list format to "DYNAMIC" ``operation=set_dynamic`` or "STATIC" ``operation=set_static``
+  Change APF list format to "DYNAMIC" \ :literal:`operation=set\_dynamic`\  or "STATIC" \ :literal:`operation=set\_static`\ 
 
-  Display APF list current format ``operation=check_format``
+  Display APF list current format \ :literal:`operation=check\_format`\ 
 
-  Display APF list entries when ``operation=list`` ``library``, ``volume`` and ``sms`` will be used as filters.
+  Display APF list entries when \ :literal:`operation=list`\  \ :literal:`library`\ , \ :literal:`volume`\  and \ :literal:`sms`\  will be used as filters.
 
-  If ``operation`` is not set, add or remove operation will be ignored.
+  If \ :literal:`operation`\  is not set, add or remove operation will be ignored.
 
   | **required**: False
   | **type**: str
@@ -99,23 +99,23 @@ operation
 tmp_hlq
   Override the default high level qualifier (HLQ) for temporary and backup datasets.
 
-  The default HLQ is the Ansible user used to execute the module and if that is not available, then the value ``TMPHLQ`` is used.
+  The default HLQ is the Ansible user used to execute the module and if that is not available, then the value \ :literal:`TMPHLQ`\  is used.
 
   | **required**: False
   | **type**: str
 
 
 persistent
-  Add/remove persistent entries to or from *data_set_name*
+  Add/remove persistent entries to or from \ :emphasis:`data\_set\_name`\ 
 
-  ``library`` will not be persisted or removed if ``persistent=None``
+  \ :literal:`library`\  will not be persisted or removed if \ :literal:`persistent=None`\ 
 
   | **required**: False
   | **type**: dict
 
 
   data_set_name
-    The data set name used for persisting or removing a ``library`` from the APF list.
+    The data set name used for persisting or removing a \ :literal:`library`\  from the APF list.
 
     | **required**: True
     | **type**: str
@@ -124,23 +124,23 @@ persistent
   marker
     The marker line template.
 
-    ``{mark}`` will be replaced with "BEGIN" and "END".
+    \ :literal:`{mark}`\  will be replaced with "BEGIN" and "END".
 
-    Using a custom marker without the ``{mark}`` variable may result in the block being repeatedly inserted on subsequent playbook runs.
+    Using a custom marker without the \ :literal:`{mark}`\  variable may result in the block being repeatedly inserted on subsequent playbook runs.
 
-    ``{mark}`` length may not exceed 72 characters.
+    \ :literal:`{mark}`\  length may not exceed 72 characters.
 
-    The timestamp (<timestamp>) used in the default marker follows the '+%Y%m%d-%H%M%S' date format
+    The timestamp (\<timestamp\>) used in the default marker follows the '+%Y%m%d-%H%M%S' date format
 
     | **required**: False
     | **type**: str
     | **default**: /* {mark} ANSIBLE MANAGED BLOCK <timestamp> \*/
 
 
   backup
-    Creates a backup file or backup data set for *data_set_name*, including the timestamp information to ensure that you retrieve the original APF list defined in *data_set_name*".
+    Creates a backup file or backup data set for \ :emphasis:`data\_set\_name`\ , including the timestamp information to ensure that you retrieve the original APF list defined in \ :emphasis:`data\_set\_name`\ ".
 
-    *backup_name* can be used to specify a backup file name if *backup=true*.
+    \ :emphasis:`backup\_name`\  can be used to specify a backup file name if \ :emphasis:`backup=true`\ .
 
     The backup file name will be return on either success or failure of module execution such that data can be retrieved.
 
@@ -152,11 +152,11 @@ persistent
   backup_name
     Specify the USS file name or data set name for the destination backup.
 
-    If the source *data_set_name* is a USS file or path, the backup_name name must be a file or path name, and the USS file or path must be an absolute path name.
+    If the source \ :emphasis:`data\_set\_name`\  is a USS file or path, the backup\_name name must be a file or path name, and the USS file or path must be an absolute path name.
 
-    If the source is an MVS data set, the backup_name must be an MVS data set name.
+    If the source is an MVS data set, the backup\_name must be an MVS data set name.
 
-    If the backup_name is not provided, the default backup_name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp. For example, ``/path/file_name.2020-04-23-08-32-29-bak.tar``.
+    If the backup\_name is not provided, the default backup\_name will be used. If the source is a USS file or path, the name of the backup file will be the source file or path name appended with a timestamp. For example, \ :literal:`/path/file\_name.2020-04-23-08-32-29-bak.tar`\ .
 
     If the source is an MVS data set, it will be a data set with a random name generated by calling the ZOAU API. The MVS backup data set recovery can be done by renaming it.
 
@@ -168,9 +168,9 @@ persistent
 batch
   A list of dictionaries for adding or removing libraries.
 
-  This is mutually exclusive with ``library``, ``volume``, ``sms``
+  This is mutually exclusive with \ :literal:`library`\ , \ :literal:`volume`\ , \ :literal:`sms`\ 
 
-  Can be used with ``persistent``
+  Can be used with \ :literal:`persistent`\ 
 
   | **required**: False
   | **type**: list
@@ -185,24 +185,24 @@ batch
 
 
   volume
-    The identifier for the volume containing the library specified on the ``library`` parameter. The values must be one of the following.
+    The identifier for the volume containing the library specified on the \ :literal:`library`\  parameter. The values must be one of the following.
 
     1. The volume serial number
 
-    2. Six asterisks (******), indicating that the system must use the volume serial number of the current system residence (SYSRES) volume.
+    2. Six asterisks (\*\*\*\*\*\*), indicating that the system must use the volume serial number of the current system residence (SYSRES) volume.
 
-    3. *MCAT*, indicating that the system must use the volume serial number of the volume containing the master catalog.
+    3. \*MCAT\*, indicating that the system must use the volume serial number of the volume containing the master catalog.
 
-    If ``volume`` is not specified, ``library`` has to be cataloged.
+    If \ :literal:`volume`\  is not specified, \ :literal:`library`\  has to be cataloged.
 
     | **required**: False
     | **type**: str
 
 
   sms
-    Indicates that the library specified in the ``library`` parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library.
+    Indicates that the library specified in the \ :literal:`library`\  parameter is managed by the storage management subsystem (SMS), and therefore no volume is associated with the library.
 
-    If true ``volume`` will be ignored.
+    If true \ :literal:`volume`\  will be ignored.
 
     | **required**: False
     | **type**: bool
@@ -283,9 +283,9 @@ Return Values
 stdout
   The stdout from ZOAU command apfadm. Output varies based on the type of operation.
 
-  state> stdout of the executed operator command (opercmd), "SETPROG" from ZOAU command apfadm
+  state\> stdout of the executed operator command (opercmd), "SETPROG" from ZOAU command apfadm
 
-  operation> stdout of operation options list> Returns a list of dictionaries of APF list entries [{'vol': 'PP0L6P', 'ds': 'DFH.V5R3M0.CICS.SDFHAUTH'}, {'vol': 'PP0L6P', 'ds': 'DFH.V5R3M0.CICS.SDFJAUTH'}, ...] set_dynamic>  Set to DYNAMIC set_static>   Set to STATIC check_format> DYNAMIC or STATIC
+  operation\> stdout of operation options list\> Returns a list of dictionaries of APF list entries [{'vol': 'PP0L6P', 'ds': 'DFH.V5R3M0.CICS.SDFHAUTH'}, {'vol': 'PP0L6P', 'ds': 'DFH.V5R3M0.CICS.SDFJAUTH'}, ...] set\_dynamic\>  Set to DYNAMIC set\_static\>   Set to STATIC check\_format\> DYNAMIC or STATIC
 
   | **returned**: always
   | **type**: str