Merge branch 'main' into ibm_concert

README.md

@@ -59,7 +59,9 @@ often repeated and in need of automation.
   - [Initialize DASD volume, Copy JCL to PDS, and Submit Job](zos_concepts/volume_management/volume_initialization/init_dasd_vol_and_run_sample_jcl)
 - Concepts
   - [Copy and Fetch Data sets](zos_concepts/data_transfer/copy_fetch_data_set)
+  - [Copy, Edit and Fetch Generation Data Groups](zos_concepts/gdg_datasets/copy_edit_fetch)
   - [Copy, Sort and Fetch Data Sets on z/OS using Ansible](zos_concepts/data_transfer/copy_sort_fetch)- \[[Playback](https://mediacenter.ibm.com/media/Copy%2C+sort%2C+and+fetch+data+on+z+OS+using+Ansible/1_ah4qhyvu)]
+  - [Create, Copy and Submit Generation Data Groups](zos_concepts/gdg_datasets/create_copy_submit)
   - [Terse Data Set and Fetch](zos_concepts/data_transfer/terse_fetch_data_set)
   - [Dump, Archive, Fetch, Copy and Unarchive Data Sets](zos_concepts/data_transfer/archive_copy_unarchive_restore)
   - [Transfer, Dump and Unpack Data Sets](zos_concepts/data_transfer/dump_pack_ftp_unpack_restore)

zos_concepts/gdg_datasets/copy_edit_fetch/README.md

@@ -0,0 +1,68 @@
+# Create, add, edit, copy and fetch with Generation data group
+This playbook demonstrates how to create, edit, copy and fetch
+Generation Data Groups (GDG) and Generation Datasets (GDS).
+
+This playbook uses:
+  - collection:
+    - ibm.ibm_zos_core
+  - modules:
+    - zos_copy
+    - zos_data_set
+    - zos_fetch
+    - zos_blockinfile
+    - zos_lineinfile
+
+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.
+
+## Playbook Requirements
+
+This playbook requires:
+- [IBM® z/OS® core collection 1.11.0 or later](https://galaxy.ansible.com/ibm/ibm_zos_core)
+- [Ansible® 2.15 or later](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html)
+
+## Configuration
+- Configure the included [inventory.yml](inventories/inventory.yml) with the
+  information from the managed z/OS host.
+  - Review [inventory documentation](../../../docs/share/zos_core/configure_inventory.md)
+- Configure the included **host_vars** [zos_host.yml](inventories/host_vars/zos_host.yml)
+  with the information from your z/OS system.
+  - Review [host_vars documentation](../../../docs/share/zos_core/configure_host_vars.md)
+    and any additional noted variables in the configuration.
+
+## Run the playbook
+
+This project has included a `site.yml` playbook that serves as the primary playbook
+that provides additional prerequisite checks then it invokes the `copy_edit_fetch.yml`
+playbook.
+
+If you want to run the primary playbook `site.yml` it will check that your environment
+has the correct version of Ansible as well as the collection needed to execute
+correctly. To run the primary playbook, use command:
+
+```bash
+ansible-playbook -i inventories site.yml
+```
+
+You can skip the prerequisite check and run the `copy_edit_fetch.yml` with
+command:
+
+```bash
+ansible-playbook -i inventories copy_edit_fetch.yml
+```
+
+# Changelog
+All changes are maintained chronologically by date found in the
+[changelog](changelog.yml).
+
+# Copyright
+© Copyright IBM Corporation 2024
+
+# License
+Licensed under [Apache License,
+Version 2.0](https://opensource.org/licenses/Apache-2.0).
+
+# Support
+Please refer to the [support section](../../../README.md#support) for more
+details.

zos_concepts/gdg_datasets/copy_edit_fetch/ansible.cfg

@@ -0,0 +1,17 @@
+################################################################################
+# Copyright (c) IBM Corporation 2024
+################################################################################
+
+################################################################################
+# Minimum required configuration for this playbook.
+# For additional `ansible.cfg` configuration options, review:
+#   https://docs.ansible.com/ansible/latest/reference_appendices/config.html
+#   https://github.com/ansible/ansible/blob/devel/examples/ansible.cfg
+################################################################################
+
+[defaults]
+forks = 25
+roles_path = ../../../roles:.
+
+[ssh_connection]
+pipelining = True

zos_concepts/gdg_datasets/copy_edit_fetch/changelog.yml

@@ -0,0 +1,33 @@
+################################################################################
+# Copyright (c) IBM Corporation 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
+# repository.
+#
+# releases:
+#     2024.08.26:
+#         date: 2024-08-26
+#         changes:
+#             added:
+#                 - new features are added
+#             deprecated:
+#                 - features being removed in the future
+#             fixed:
+#                 - bug fixes
+#             minor:
+#                 - changes in existing functionality
+#             removed:
+#                 - features removed no longer available
+#             security:
+#                 - vulnerabilities fixed
+#             summary:
+#                 - summary of changes or link to Git issue, pull request
+################################################################################
+
+releases:
+    2024.08.26:
+        date: 2024-08-26
+        changes:
+            added:
+                - Released initial version

zos_concepts/gdg_datasets/copy_edit_fetch/copy_edit_fetch.yml

@@ -0,0 +1,168 @@
+###############################################################################
+# © Copyright IBM Corporation 2024
+###############################################################################
+
+###############################################################################
+# This sample playbook demonstrates how to create a new Generation Data Group(GDG),
+# add text content to a Generation Data Set(GDS), copy to another
+# Generation Data Group(GDG), edit the copy and fetch the content.
+#
+# Usage:
+#  ansible-playbook -i <inventory> <playbook>
+#
+# Example:
+#  ansible-playbook -i inventories copy_edit_submit.yml
+#
+#  When running this playbook, review the comments on how ths sample will
+#  interact with your target, ensure you have the required authority and
+#  permissions such as writing the the target directories or creating data sets.
+#
+# Requirements:
+#     - IBM z/OS core collection 1.11.0 or later
+#
+###############################################################################
+
+---
+- hosts: zos_host
+  collections:
+    - ibm.ibm_zos_core
+  gather_facts: false
+  environment: "{{ environment_vars }}"
+
+  tasks:
+    # ##########################################################################
+    # Generate a temporary data set names, date time, system name and get last
+    # four minutes of the operator console log.
+    # ##########################################################################
+    - name: Create temp data set name
+      command: "mvstmp {{ ansible_user | upper }}"
+      register: tmp_ds1
+
+    - name: Create temp data set name
+      command: "mvstmp {{ ansible_user | upper }}"
+      register: tmp_ds2
+
+    - name: Get date time
+      shell: "date +%Y-%m-%d%H:%M:%S"
+      register: date_time
+
+    - name: Get system name
+      zos_gather_facts:
+      register: sys_info
+
+    - name: Ensure console log.
+      command: "pcon -l"
+      ignore_errors: yes
+
+    - name: Check content of last ten minutes of console log
+      command: "pcon -r"
+      register: log_output
+
+    - set_fact:
+        tmp_data_set1: "{{ tmp_ds1.stdout }}"
+        tmp_data_set2: "{{ tmp_ds2.stdout }}"
+        date: "{{ date_time.stdout[0:10] }}"
+        time: "{{ date_time.stdout[10:] }}"
+        sys_name: "{{ sys_info.ansible_facts.sys_name}}"
+        log_output: "{{ log_output.stdout }}"
+
+    # ##########################################################################
+    # Modules: zos_data_set, zos_blockinfile, zos_copy,
+    # zos_lineinfile, zos_fetch.
+    # ##########################################################################
+    # +-------------------------------------------------------------------------
+    # | - Using zos_data_set, create two generation data groups with names
+    # |   {{ tmp_data_set1 }} and {{ tmp_data_set2 }}
+    # | - Using zos_data_set, create a generation of the GDG from {{ tmp_data_set1 }}.
+    # | - Using zos_data_set, create a generation of the GDG from {{ tmp_data_set2 }}.
+    # | - Using zos_blockinfile, add the logs to the latest generation of GDG {{ tmp_data_set1 }}.
+    # | - Using zos_copy, copy the content from the latest generation of {{ tmp_data_set1 }}
+    # |   to latest generation of {{ tmp_data_set2 }}.
+    # | - Using zos_lineinfile, add a comment to a latest generation of {{ tmp_data_set2 }}
+    # |   using relative notation notation {{ tmp_data_set2 }}(0).
+    # | - Using zos_fetch, to fetch the latest generation of the GDG {{ tmp_data_set2 }}.
+    # +-------------------------------------------------------------------------
+    - name: "Create the Generation Data Group(GDG) {{tmp_data_set1}} with a limit of 2 generations"
+      zos_data_set:
+        name: "{{ tmp_data_set1 }}"
+        type: gdg
+        limit: 2
+      register: result_create_gdg
+
+    - name: "Create the Generation Data Group(GDG) {{tmp_data_set2}} with a limit of 2 generations to backup {{ tmp_data_set1 }}"
+      zos_data_set:
+        name: "{{ tmp_data_set2 }}"
+        type: gdg
+        limit: 2
+      register: result_create_gdg
+
+    - name: "Response of the GDG creation {{ tmp_data_set2 }} with a limit of 2 generations"
+      debug:
+        msg:
+          - "{{ result_create_gdg }}"
+
+    - name: "Create the GDS for {{ tmp_data_set1 }} of sequential type and record length of 200"
+      zos_data_set:
+        name: "{{ tmp_data_set1 }}(+1)"
+        type: seq
+        record_length: 200
+        state: "present"
+
+    - name: "Create the GDS for {{ tmp_data_set2 }} of sequential type and record length of 200"
+      zos_data_set:
+        name: "{{ tmp_data_set2 }}(+1)"
+        type: seq
+        record_length: 200
+        state: "present"
+      register: result_create_gds
+
+    - name: "Response of the GDS {{ tmp_data_set2 }}(+1) creation"
+      debug:
+        msg:
+          - "{{ result_create_gds }}"
+
+    - name: "Write the last 10 minutes of the operator console log into {{ tmp_data_set1 }}"
+      zos_blockinfile:
+        src: "{{ tmp_data_set1 }}(0)"
+        marker: "//* {mark} *//"
+        marker_begin: " Log of date {{ date }} "
+        marker_end: " End of log time {{ time }} "
+        insertbefore: BOF
+        state: present
+        block: "{{ log_output }}"
+
+    - name: "Copy from the current generation of {{ tmp_data_set1 }} to the last Generation of {{ tmp_data_set2 }}"
+      zos_copy:
+        src: "{{ tmp_data_set1 }}(0)"
+        dest: "{{ tmp_data_set2 }}(0)"
+        remote_src: true
+
+    - name: "Edit last generation {{ tmp_data_set2 }} to add a comment"
+      zos_lineinfile:
+        src: "{{ tmp_data_set2 }}(0)"
+        insertbefore: BOF
+        state: present
+        line: "#### Console log from system {{ sys_name }} ####"
+
+    - name: "Fetch {{ tmp_data_set2 }}(0) to the local controller"
+      zos_fetch:
+        src: "{{ tmp_data_set2 }}(0)"
+        dest: "{{ playbook_dir }}/"
+      register: fetch_result
+
+    - name: "Result of Fetch {{ tmp_data_set2 }}(0) to the local machine"
+      debug:
+        msg:
+          - "{{ fetch_result }}"
+
+    - name: Delete the data sets
+      zos_data_set:
+        batch:
+          - name: "{{ tmp_data_set1 }}(0)"
+            state: absent
+          - name: "{{ tmp_data_set2 }}(0)"
+            state: absent
+          - name: "{{ tmp_data_set1 }}"
+            state: absent
+          - name: "{{ tmp_data_set2 }}"
+            state: absent

zos_concepts/gdg_datasets/copy_edit_fetch/inventories/group_vars/all.yml

@@ -0,0 +1,52 @@
+################################################################################
+# Copyright (c) IBM Corporation 2024
+################################################################################
+
+################################################################################
+# Enviroment variables for all z/OS managed nodes (target) that do not need
+# further configuration.
+################################################################################
+environment_vars:
+  _BPXK_AUTOCVT: "ON"
+  ZOAU_HOME: "{{ ZOAU }}"
+  PYTHONPATH: "{{ ZOAU_PYTHON_LIBRARY_PATH }}"
+  LIBPATH: "{{ ZOAU }}/lib:{{ PYZ }}/lib:/lib:/usr/lib:."
+  PATH: "{{ ZOAU }}/bin:{{ PYZ }}/bin:/bin:/var/bin"
+  _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
+  _TAG_REDIR_ERR: "txt"
+  _TAG_REDIR_IN: "txt"
+  _TAG_REDIR_OUT: "txt"
+  LANG: "C"
+  PYTHONSTDINENCODING: "cp1047"
+
+################################################################################
+# Description of the properties used in this configuration:
+################################################################################
+# - Property BPXK_AUTOCVT must be configured to "ON"; e.g., _BPXK_AUTOCVT: "ON"
+# - Property ZOAU_HOME is the Z Open Automation Utilities (ZOAU) install root path;
+#   e.g., ZOAU_HOME: "/usr/lpp/IBM/zoautil"
+# - Property PYTHONPATH is the Z Open Automation Utilities (ZOAU) Python library path;
+#   e.g., PYTHONPATH: "/usr/lpp/IBM/zoautil/lib"
+# - Property LIBPATH is both the path to the Python libraries on the target
+#   and the Z Open Automation Utilities (ZOAU) Python library path separated by semi-colons; e.g.,
+#   LIBPATH: "/usr/lpp/IBM/zoautil/lib/:/usr/lpp/IBM/cyp/v3r8/pyz/lib:/usr/lib:/lib:."
+# - Property PATH is the ZOA utilities BIN path and Python interpreter path, e.g.,
+#   PATH: "/usr/lpp/IBM/zoautil/bin:/usr/lpp/IBM/cyp/v3r8/pyz/bin:/bin"
+# - Property _CEE_RUNOPTS is the invocation Language Environment® runtime
+#   options for programs and used by Python. e.g.,
+#   _CEE_RUNOPTS: "FILETAG(AUTOCVT,AUTOTAG) POSIX(ON)"
+# - Properties __TAG_REDIR_ERR, _TAG_REDIR_IN, _TAG_REDIR_OUT are txt and used
+#   by the shell; e.g.,
+#      _TAG_REDIR_ERR: "txt"
+#      _TAG_REDIR_IN: "txt"
+#      _TAG_REDIR_OUT: "txt"
+# - Property LANG is the name of the default locale; value
+#   C specifies the POSIX locale; for example: ``LANG: "C"``.
+# - Property `PYTHONSTDINENCODING` should be set to the encoding Unix System Services
+#   is configured as, supported encodings are ASCII or EBCDIC. This environment
+#   variable is used to instruct Ansible which encoding it will *pipe* content to
+#   Python's STDIN (standard in) when `pipelining=true` is set in `ansible.cfg` .
+#   This environment variable will only apply when using IBM Enterprise Python
+#   3.10 or later, otherwise, it is ignored.
+#   For example:`PYTHONSTDINENCODING: "cp1047"`.
+################################################################################