Merge pull request IBM#253 from IBM/params-update-for-ibm_zos_core-1.10

Params update for ibm zos core 1.10
frankmit11 · Jun 26, 2024 · 4155f20 · 4155f20
2 parents 1dba0f0 + 6924383
commit 4155f20
Show file tree

Hide file tree

Showing 40 changed files with 403 additions and 140 deletions.
diff --git a/zos_basics/constructs/README.md b/zos_basics/constructs/README.md
@@ -22,6 +22,27 @@ configuration, flexibility is written into the samples because it can't always
 be determined if a sample has access to the host’s resources. Review the
 playbook for additional details and configuration.
 
+> [!IMPORTANT]
+> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive
+> changes to modules, specifically that module choices must be lower case. See the porting
+> guide in the release notes
+> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide))
+> to understand the full scope of these changes.
+>
+> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, 
+> and since the earlier versions do not reach their end of life until April 2025, 
+> the sample playbook compatible with the older versions will remain available.
+>
+> To support both the latest and prior versions of the collection: 
+> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later.
+>   * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_basics/constructs).
+> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier.
+>   * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_basics/constructs).
+> 
+> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates.
+>
+>
+
 ## Playbook Requirements
 - [IBM® z/OS® core collection 1.0.0 or later](https://galaxy.ansible.com/ibm/ibm_zos_core)
 - [Ansible® 2.11 or later](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)

diff --git a/zos_basics/constructs/changelog.yml b/zos_basics/constructs/changelog.yml
@@ -1,5 +1,5 @@
 ################################################################################
-# Copyright (c) IBM Corporation 2021
+# Copyright (c) IBM Corporation 2021, 2024
 #
 # All notable changes to this project will be documented in this file. Following
 # releases is a decimal based date since playbooks have no version in this
@@ -40,3 +40,10 @@ releases:
                 - Added runtime-requirements.txt that lists the requirements needed for this playbook to execute
             minor:
                 - Changed dependency from Ansible 2.10 to 2.11 to align with the collections supported Ansible
+    2024.04.11:
+        date: 2024-04-11
+        changes:
+            fixed:
+                - Lower case zos_job_submit module option 'location' per ibm.ibm_zos_core:1.10.0 requirements.
+            removed:
+                - Remove deprecated zos_job_submit module option 'wait'.
diff --git a/zos_basics/constructs/zos_job_submit_ansible_constructs.yml b/zos_basics/constructs/zos_job_submit_ansible_constructs.yml
@@ -1,5 +1,5 @@
 ###############################################################################
-# Copyright (c) IBM Corporation 2021
+# Copyright (c) IBM Corporation 2021, 2024
 ###############################################################################
 
 ###############################################################################
@@ -382,8 +382,7 @@
     - name: Convert a local JCL file to IBM-037 and submit the job
       zos_job_submit:
         src: "{{playbook_dir}}/files/HELLO.jcl"
-        location: LOCAL
-        wait: false
+        location: local
         encoding:
           from: ISO8859-1
           to: IBM-037

diff --git a/zos_concepts/data_sets/copy_edit_submit/README.md b/zos_concepts/data_sets/copy_edit_submit/README.md
@@ -14,6 +14,27 @@ It is a good practice to review the playbook contents before executing
 them. It will help you understand the requirements in terms of space, location,
 names, authority, and the artifacts that will be created and cleaned up.
 
+> [!IMPORTANT]
+> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive
+> changes to modules, specifically that module choices must be lower case. See the porting
+> guide in the release notes
+> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide))
+> to understand the full scope of these changes.
+>
+> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, 
+> and since the earlier versions do not reach their end of life until April 2025, 
+> the sample playbook compatible with the older versions will remain available.
+>
+> To support both the latest and prior versions of the collection: 
+> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later.
+>   * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_concepts/data_sets/copy_edit_submit).
+> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier.
+>   * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_concepts/data_sets/copy_edit_submit).
+> 
+> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates.
+>
+>
+
 ## Playbook Requirements
 
 This playbook requires:

diff --git a/zos_concepts/data_sets/copy_edit_submit/changelog.yml b/zos_concepts/data_sets/copy_edit_submit/changelog.yml
@@ -1,5 +1,5 @@
 ################################################################################
-# Copyright (c) IBM Corporation 2021
+# Copyright (c) IBM Corporation 2021, 2024
 #
 # All notable changes to this project will be documented in this file. Following
 # releases is a decimal based date since playbooks have no version in this
@@ -43,3 +43,10 @@ releases:
                 - Renamed `copy_edit_submit.yaml` to `copy_edit_submit.yml` to standardize all playbooks with the same extension
             removed:
                 - Removed the zos_ssh connection plugin, it is no longer included in the ibm_zos_core collection.
+    2024.04.09:
+        date: 2024-04-09
+        changes:
+            fixed:
+                - Lower case zos_job_submit module option 'location' per ibm.ibm_zos_core:1.10.0 requirements.
+            removed:
+                - Remove deprecated zos_job_submit module option 'wait'.
diff --git a/zos_concepts/data_sets/copy_edit_submit/copy_edit_submit.yml b/zos_concepts/data_sets/copy_edit_submit/copy_edit_submit.yml
@@ -1,5 +1,5 @@
 ###############################################################################
-# © Copyright IBM Corporation 2020, 2021
+# © Copyright IBM Corporation 2020, 2024
 ###############################################################################
 
 ###############################################################################
@@ -93,8 +93,7 @@
     - name: "Submit the JCL {{ tmp_data_set }}(PSA)"
       zos_job_submit:
         src: "{{ tmp_data_set }}(PSA)"
-        location: DATA_SET
-        wait: true
+        location: data_set
       register: result_submit_psa
 
     - name: "Response for submitting JCL {{ tmp_data_set }}(PSA)"
@@ -104,8 +103,7 @@
     - name: "Submit the JCL {{ tmp_data_set }}(UPTIME)"
       zos_job_submit:
         src: "{{ tmp_data_set }}(UPTIME)"
-        location: DATA_SET
-        wait: true
+        location: data_set
       register: result_submit_uptime
 
     - name: "Response for submitting JCL {{ tmp_data_set }}(UPTIME)"

diff --git a/zos_concepts/data_sets/data_set_basics/changelog.yml b/zos_concepts/data_sets/data_set_basics/changelog.yml
@@ -1,5 +1,5 @@
 ################################################################################
-# Copyright (c) IBM Corporation 2021
+# Copyright (c) IBM Corporation 2021, 2024
 #
 # All notable changes to this project will be documented in this file. Following
 # releases is a decimal based date since playbooks have no version in this
@@ -44,3 +44,9 @@ releases:
                 - Renamed `data_set_basics.yaml` to `data_set_basics.yml` with a `yml` extenstion to follow standardize on the extension
             removed:
                 - Removed the zos_ssh connection plugin, it is no longer included in the ibm_zos_core collection.
+    2024.04.09:
+        date: 2024-04-09
+        changes:
+            fixed:
+                - Replace deprecated zos_data_set module option 'size' with new module options 'space_primary' and 'space_type'.
+                - Lower case zos_data_set module option 'type' per ibm.ibm_zos_core:1.10.0 requirements.
diff --git a/zos_concepts/data_sets/data_set_basics/data_set_basics.yml b/zos_concepts/data_sets/data_set_basics/data_set_basics.yml
@@ -1,5 +1,5 @@
 ###############################################################################
-# © Copyright IBM Corporation 2020, 2021
+# © Copyright IBM Corporation 2020, 2024
 ###############################################################################
 # This sample playbook demonstrates basic data set operations using modules
 # included in the Red Hat Ansible Certified  Content for IBM Z core collection.
@@ -85,7 +85,8 @@
         replace: true
         format: fb
         record_length: 100
-        size: 5M
+        space_primary: 5
+        space_type: m
       register: result
 
     - name: Response for data set creation
@@ -106,7 +107,6 @@
       zos_copy:
         src: "{{ playbook_dir }}/files/HELLO.jcl"
         dest: "{{ tgt_tmp_dir }}/HELLO"
-       # remote_src: yes
       register: result
 
     - name: Response for populating USS file {{ tgt_tmp_dir }}/HELLO
@@ -129,7 +129,8 @@
       zos_data_set:
         name: "{{ pds_name }}"
         type: pds
-        size: 5M
+        space_primary: 5
+        space_type: m
         format: fba
         record_length: 100
       register: result
@@ -141,7 +142,7 @@
     - name: Remove the target PDS member if it exists, for idempotency.
       zos_data_set:
         name: "{{ pds_name }}(HELLO)"
-        type: MEMBER
+        type: member
         state: absent
       register: result
 

diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/README.md b/zos_concepts/data_transfer/archive_copy_unarchive_restore/README.md
@@ -21,6 +21,27 @@ names, authority, and the artifacts that will be created and cleaned up.
 - [**archive_fetch_data_sets.yml**](archive_fetch_data_sets.yml) - Dumps and archive of data sets.
 - [**unarchive_data_sets.yml**](unarchive_data_sets.yml) - Transfers, unarchives, and restores the target data set archive.
 
+> [!IMPORTANT]
+> The release of `ibm_zos_core` collection version 1.10.0 introduced case-sensitive
+> changes to modules, specifically that module choices must be lower case. See the porting
+> guide in the release notes
+> ([here](https://ibm.github.io/z_ansible_collections_doc/ibm_zos_core/docs/source/release_notes.html#porting-guide))
+> to understand the full scope of these changes.
+>
+> These changes are not compatible with earlier versions of the `ibm_zos_core` collection, 
+> and since the earlier versions do not reach their end of life until April 2025, 
+> the sample playbook compatible with the older versions will remain available.
+>
+> To support both the latest and prior versions of the collection: 
+> * The `main` branch will reflect playbooks compatible with `ibm_zos_core` version 1.10.0 or later.
+>   * Find this playbook on the `main` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/main/zos_concepts/data_transfer/archive_copy_unarchive_restore).
+> * The `ibm_zos_core-v1.9.x-samples` branch will reflect playbooks compatible with `ibm_zos_core` version 1.9.x or earlier.
+>   * Find this playbook on the `ibm_zos_core-v1.9.x-samples` branch: [here](https://github.com/IBM/z_ansible_collections_samples/tree/ibm_zos_core-v1.9.x-samples/zos_concepts/data_transfer/archive_copy_unarchive_restore).
+> 
+> The `ibm_zos_core-v1.9.x-samples` branch will remain available until April 2025 but will not receive updates.
+>
+>
+
 ## Playbook Requirements
 This playbook requires:
 

diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/archive_fetch_data_sets.yml b/zos_concepts/data_transfer/archive_copy_unarchive_restore/archive_fetch_data_sets.yml
@@ -1,5 +1,5 @@
 ###############################################################################
-# © Copyright IBM Corporation 2023
+# © Copyright IBM Corporation 2023, 2024
 ###############################################################################
 
 ###############################################################################
@@ -18,32 +18,37 @@
 #   IBM z/OS core collection 1.7.0 or later.
 #   Ansible Community General Collection
 #
-# Configure:
+# Configure (optional):
 #   data_sets_to_archive - A list of data sets contained in an archive you wish to include in dump.
-#   archive_data_set - The name to use for the data set archive,
-#                       if not provided, module-generated name will be used.
-#   delete - Indicates if terse and archive data sets should be deleted upon successful transfer.
+#   archive_data_set - The name to use for the data set archive.
+#   remove_data_sets - Indicates if terse and archive data sets should be deleted upon successful transfer.
 #
 ###############################################################################
 
 - hosts: source
   collections :
     - "ibm.ibm_zos_core"
   gather_facts: false
+
   vars:
-    data_sets_to_archive: ["USER.PRIVATE.TEST"]
-    archive_data_set: ""
-    delete: true
+    data_sets_to_archive:
+      - "{{ ansible_user | upper }}.ANSIBLE.SAMPLE.ONE"
+      - "{{ ansible_user | upper }}.ANSIBLE.SAMPLE.TWO"
+    archive_data_set: "{{ ansible_user | upper }}.ANSIBLE.SAMPLE.ARCHIVE"
+    remove_data_sets: true
+
   environment: '{{ environment_vars }}'
 
   tasks:
-    - name: Create a temporary data set
-      zos_data_set:
-        type: seq
-        space_primary: 5
-        space_secondary: 1
-        space_type: cyl
-        name: "{{ item }}"
+    - name: Create and copy content into data sets to archive.
+      zos_copy:
+        content: "HELLO WORLD - {{ item }}"
+        dest: "{{ item }}"
+        dest_data_set:
+          type: seq
+          space_primary: 5
+          space_secondary: 1
+          space_type: cyl
       loop: "{{ data_sets_to_archive }}"
 
     #########################################################################
@@ -76,18 +81,18 @@
     - name: Create a dump with adrdssu of the data sets and archive using terse.
       ibm.ibm_zos_core.zos_archive:
         src: "{{ data_sets_to_archive }}"
-        dest: "{{ dest_archive }}"
+        dest: "{{ archive_data_set }}"
         force: True
         format:
           name: terse
           format_options:
-            terse_pack: SPACK
+            terse_pack: spack
             use_adrdssu: True
-        remove: "{{ delete }}"
+        remove: "{{ remove_data_sets }}"
         dest_data_set:
           space_primary: "{{ size_in_cyls.primary }}"
           space_secondary: "{{ size_in_cyls.secondary }}"
-          space_type: CYL
+          space_type: cyl
       register: archive_result
 
     - debug:
@@ -103,12 +108,20 @@
     #########################################################################
     - name: Fetch the data set into the controller
       ibm.ibm_zos_core.zos_fetch:
-        src: "{{ dest_archive }}"
+        src: "{{ archive_data_set }}"
         dest: "{{ playbook_dir }}/"
         is_binary: True
         flat: True
       register: result
 
-    - name: "Result of fetching {{ dest_archive }} to controller node"
+    - name: "Result of fetching {{ archive_data_set }} to controller node"
       debug:
         msg: "{{ result }}"
+
+    #########################################################################
+    # Remove archive data set from remote system.
+    #########################################################################
+    - name: Delete archive data set from remote system.
+      zos_data_set:
+        name: "{{ archive_data_set }}"
+        state: absent
diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/changelog.yml b/zos_concepts/data_transfer/archive_copy_unarchive_restore/changelog.yml
@@ -1,5 +1,5 @@
 ################################################################################
-# Copyright (c) IBM Corporation 2023
+# Copyright (c) IBM Corporation 2023, 2024
 #
 # All notable changes to this project will be documented in this file. Following
 # releases is a decimal based date since playbooks have no version in this
@@ -31,3 +31,13 @@ releases:
         changes:
             added:
                 - Released initial version
+    2024.04.11:
+        date: 2024-04-11
+        changes:
+            added:
+                - Update description of optional configurations.
+                - Update vars section to use more generic data set names.
+                - Add new host_vars files for 'source' and 'destination' target nodes.
+            fixed:
+                - Lower case zos_archive module option 'terse_pack' per ibm.ibm_zos_core:1.10.0 requirements.
+                - Lower case zos_archive module option 'space_type' per ibm.ibm_zos_core:1.10.0 requirements.
diff --git a/...estore/inventories/host_vars/zos_host.yml → ...ore/inventories/host_vars/destination.yml b/...estore/inventories/host_vars/zos_host.yml → ...ore/inventories/host_vars/destination.yml
diff --git a/zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/source.yml b/zos_concepts/data_transfer/archive_copy_unarchive_restore/inventories/host_vars/source.yml
@@ -0,0 +1,24 @@
+################################################################################
+# Copyright (c) IBM Corporation 2024
+################################################################################
+
+################################################################################
+# Description of the properties used in this configuration:
+# - Property `PYZ` is the python installation home path on the z/OS managed node (target),
+#    e.g, pyz: "/usr/lpp/IBM/cyp/v3r11/pyz"
+# - Property `ZOAU` is the ZOAU installation home on the z/OS managed node (target),
+#    e.g, zoau: "/usr/lpp/IBM/zoautil"
+# - property `ansible_python_interpreter` is the z/OS managed node (target) Python
+#    binary installation path, e.g, ansible_python_interpreter: "{{PYZ}}/bin/python3"
+#
+# Note, PYZ and ZOAU environment variables must be configured.
+################################################################################
+
+PYZ: "path_to_python_installation_on_zos_target"
+ZOAU: "path_to_zoau_installation_on_zos_target"
+
+################################################################################
+# Do not configure, variable substituion will correctly set the
+# variable`ansible_python_interpreter`
+################################################################################
+ansible_python_interpreter: "{{ PYZ }}/bin/python3"