Skip to content

Commit

Permalink
[v1.10.0] [Enabler] Standardization of choices in modules (#1388)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
rexemin authored Apr 16, 2024
1 parent d8b87a4 commit 5b239b1
Show file tree
Hide file tree
Showing 54 changed files with 2,302 additions and 1,880 deletions.
87 changes: 87 additions & 0 deletions changelogs/fragments/1388-lowercase-choices.yml
Original file line number Diff line number Diff line change
@@ -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).
68 changes: 34 additions & 34 deletions docs/source/modules/zos_apf.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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".

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 5b239b1

Please sign in to comment.