From 4afe33f9c4237242febcf5c029cf384ed2f70461 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Marcel=20Guti=C3=A9rrez=20Ben=C3=ADtez?= <68956970+AndreMarcel99@users.noreply.github.com> Date: Wed, 13 Nov 2024 12:08:48 -0600 Subject: [PATCH] [Enable][1618]create_gdg_playbooks_into_respository (#277) * Add create_copy_submit * Fix inconsitency * Add second case * Fix title * Fix lint * Fix comments * Change read me and case * Fix comments * Fix comments * Update all and zos_hosts * Fix solution * Fix copy and comments * Update create_copy_submit.yml * Update create_copy_submit.yml * Update create_copy_submit.yml * Update README.md * Ensure works every time * Update copy_edit_fetch.yml * Use gather facts --- README.md | 2 + .../gdg_datasets/copy_edit_fetch/README.md | 68 +++++++ .../gdg_datasets/copy_edit_fetch/ansible.cfg | 17 ++ .../copy_edit_fetch/changelog.yml | 33 ++++ .../copy_edit_fetch/copy_edit_fetch.yml | 168 ++++++++++++++++++ .../inventories/group_vars/all.yml | 52 ++++++ .../inventories/host_vars/zos_host.yml | 65 +++++++ .../copy_edit_fetch/inventories/inventory.yml | 17 ++ .../copy_edit_fetch/runtime-requirements.yml | 31 ++++ .../gdg_datasets/copy_edit_fetch/site.yml | 34 ++++ .../gdg_datasets/create_copy_submit/README.md | 66 +++++++ .../gdg_datasets/create_copy_submit/UPTIME | 24 +++ .../create_copy_submit/ansible.cfg | 17 ++ .../create_copy_submit/changelog.yml | 33 ++++ .../create_copy_submit/create_copy_submit.yml | 118 ++++++++++++ .../inventories/group_vars/all.yml | 52 ++++++ .../inventories/host_vars/zos_host.yml | 65 +++++++ .../inventories/inventory.yml | 17 ++ .../runtime-requirements.yml | 31 ++++ .../gdg_datasets/create_copy_submit/site.yml | 34 ++++ 20 files changed, 944 insertions(+) create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/README.md create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/ansible.cfg create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/changelog.yml create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/copy_edit_fetch.yml create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/inventories/group_vars/all.yml create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/inventories/host_vars/zos_host.yml create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/inventories/inventory.yml create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/runtime-requirements.yml create mode 100644 zos_concepts/gdg_datasets/copy_edit_fetch/site.yml create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/README.md create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/UPTIME create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/ansible.cfg create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/changelog.yml create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/create_copy_submit.yml create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/inventories/group_vars/all.yml create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/inventories/host_vars/zos_host.yml create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/inventories/inventory.yml create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/runtime-requirements.yml create mode 100644 zos_concepts/gdg_datasets/create_copy_submit/site.yml diff --git a/README.md b/README.md index e75aa32fb..b796f106c 100644 --- a/README.md +++ b/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) diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/README.md b/zos_concepts/gdg_datasets/copy_edit_fetch/README.md new file mode 100644 index 000000000..4b19f4cfe --- /dev/null +++ b/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. diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/ansible.cfg b/zos_concepts/gdg_datasets/copy_edit_fetch/ansible.cfg new file mode 100644 index 000000000..fcdc90db4 --- /dev/null +++ b/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 diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/changelog.yml b/zos_concepts/gdg_datasets/copy_edit_fetch/changelog.yml new file mode 100644 index 000000000..7056e4a6b --- /dev/null +++ b/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 \ No newline at end of file diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/copy_edit_fetch.yml b/zos_concepts/gdg_datasets/copy_edit_fetch/copy_edit_fetch.yml new file mode 100644 index 000000000..40a122836 --- /dev/null +++ b/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 +# +# 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 diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/inventories/group_vars/all.yml b/zos_concepts/gdg_datasets/copy_edit_fetch/inventories/group_vars/all.yml new file mode 100644 index 000000000..486fe46a3 --- /dev/null +++ b/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"`. +################################################################################ diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/inventories/host_vars/zos_host.yml b/zos_concepts/gdg_datasets/copy_edit_fetch/inventories/host_vars/zos_host.yml new file mode 100644 index 000000000..0bd62568f --- /dev/null +++ b/zos_concepts/gdg_datasets/copy_edit_fetch/inventories/host_vars/zos_host.yml @@ -0,0 +1,65 @@ +--- +################################################################################ +# 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 +# (target) node e.g, PYZ: "/usr/lpp/IBM/cyp/v3r12/pyz" +# - Property `PYZ_VERSION` is the version of python on the z/OS managed +# (target) node e.g, PYZ_VERSION: "3.12". +# - Property `ZOAU` is the ZOAU installation home on the z/OS managed (target) +# node, e.g, ZOAU: "/usr/lpp/IBM/zoautil". +# - Property `ZOAU_PYTHON_LIBRARY_PATH` is the path to the Z Open Automation +# Utilities (ZOAU) python library. Specifically, the path points to the +# directory containing 'zoautil_py'. Packages installed using 'pip' generally +# default to the 'site-packages' directory within the python installation, +# eg "/usr/lpp/IBM/cyp/v3r12/pyz/lib/python3.12/site-packages/". +# If the installation uses options such as '--user' or '--target', the module +# is installed to a non-default location which must be configured in +# `ZOAU_PYTHON_LIBRARY_PATH`. +# If the wheel installation method is used with the '--target' or '--user' +# option, `ZOAU_PYTHON_LIBRARY_PATH` should point to the directory the wheel +# file was installed to. e.g ZOAU_PYTHON_LIBRARY_PATH: "/usr/zoau-wheel/". +# Else 'ZOAU_PYTHON_LIBRARY_PATH' should point to the directory containing +# the pre-compiled binary. +# For ZOAU v1.2.x, the pre-compiled binary is located in the 'lib' directory. +# e.g "/usr/lpp/IBM/zoautil/lib" or "{{ ZOAU }}/lib". +# For ZOAU v1.3.x, the pre-compiled binary is located in a sub-directory +# corresponding to the `PYZ_VERSION` inside the 'lib' directory, +# e.g "/usr/lpp/IBM/zoautil/lib/3.12" or "{{ ZOAU }}/lib/{{ PYZ_VERSION }}". +# - 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, PYZ_VERSION, and ZOAU environment variables must be configured. +################################################################################ + +PYZ: "path_to_python_installation_on_zos_target" +PYZ_VERSION: "3.xx" + +ZOAU: "path_to_zoau_installation_on_zos_target" + +# Configuring the `ZOAU_PYTHON_LIBRARY_PATH` property is required. + +# If the ZOAU python package, zoautil_py, has been installed as a wheel (*.whl) +# with the '--target' or '--user' option, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ path_to_wheel_installation_directory }}" + +# If the ZOAU python zoautil_py package has been installed in the default location +# that is part of Python's search path, the `ZOAU_PYTHON_LIBRARY_PATH` environment +# variable must be set as an empty string. Uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "" + +# If using pre-compiled binaries for ZOAU v1.3.x, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib/{{ PYZ_VERSION }}" + +# If using pre-compiled binaries for ZOAU v1.2.x, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib" + + +################################################################################ +# Do not configure, variable substituion will correctly set the +# variable `ansible_python_interpreter` +################################################################################ +ansible_python_interpreter: "{{ PYZ }}/bin/python3" diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/inventories/inventory.yml b/zos_concepts/gdg_datasets/copy_edit_fetch/inventories/inventory.yml new file mode 100644 index 000000000..27508a303 --- /dev/null +++ b/zos_concepts/gdg_datasets/copy_edit_fetch/inventories/inventory.yml @@ -0,0 +1,17 @@ +################################################################################ +# © Copyright IBM Corporation 2024 +################################################################################ + +################################################################################ +# Description of the properties used in this configuration: +# - Property `ansible_host` is the z/OS managed node (target), +# e.g, ansible_host: "zvm1.vmec.svl.ibm.com" +# - Property `ansible_user` is the z/OS managed user to connect and run as over SSH, +# e.g, ansible_user: "zosadm" +################################################################################ + +source_system: + hosts: + zos_host: + ansible_host: zos_target_address + ansible_user: zos_target_username diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/runtime-requirements.yml b/zos_concepts/gdg_datasets/copy_edit_fetch/runtime-requirements.yml new file mode 100644 index 000000000..d66077b23 --- /dev/null +++ b/zos_concepts/gdg_datasets/copy_edit_fetch/runtime-requirements.yml @@ -0,0 +1,31 @@ +################################################################################ +# Copyright (c) IBM Corporation 2024 +################################################################################ + +################################################################################ +# List `requires_ansible_version` contains Ansible version entries that this +# playbook requires. It can be one more then one Ansible version +# e.g, `- 2.9` would be interpreted as 2.9 - 2.9.n where n is >= 0. Where `- 2.9.0` +# would be require an exact match, just like 2.9.12 would be an exact match. +# +# Dictionary `requires_collection` can include more than one collection such as +# in the case a playbook depends on other IBM z collections. +# e.g, +# requires_collection: +# - ibm_zos_core: +# name: "ibm_zos_core" +# version: "1.4.0-beta.1" +# - ibm_zos_ims: +# name: "ibm_zos_ims" +# version: "1.4.0-beta.1" +################################################################################ + +requires_ansible_version: + - "2.15" + - "2.16" + - "2.17" + +requires_collection: + - ibm_zos_core: + name: "ibm_zos_core" + version: "1.11.0" diff --git a/zos_concepts/gdg_datasets/copy_edit_fetch/site.yml b/zos_concepts/gdg_datasets/copy_edit_fetch/site.yml new file mode 100644 index 000000000..4dd00aa58 --- /dev/null +++ b/zos_concepts/gdg_datasets/copy_edit_fetch/site.yml @@ -0,0 +1,34 @@ +############################################################################### +# © Copyright IBM Corporation 2024 +############################################################################### + +############################################################################### +# This playbook (`site.yml`) is the master playbook for this project. Based on +# the playbooks requirements, `site.yml` playbook will evalute the requirements +# and report when the minimum requirements are not configured and fail playbook +# execution. +# +# Upon successful dependency analysis, the z/OS playbook will be executed. +# +# Usage: +# ansible-playbook -i +# +# Example: +# ansible-playbook -i inventories site.yml +# ansible-playbook -i inventories site.yml -v +############################################################################### + + +--- +- hosts: localhost + + tasks: + - name: Parse the registry for collection entries + include_vars: runtime-requirements.yml + + - name: Display the registered collections and properites in `registry.yml`. + include_role: + name: requirements-check + +- name: Executing the z/OS Ansible playbook + import_playbook: copy_edit_fetch.yml diff --git a/zos_concepts/gdg_datasets/create_copy_submit/README.md b/zos_concepts/gdg_datasets/create_copy_submit/README.md new file mode 100644 index 000000000..756a80617 --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/README.md @@ -0,0 +1,66 @@ +# Using a GDG, copy Directory to GDS and Submit Job +This playbook demonstrates how to create a GDG create copy delete and submit +creations of GDS. + +This playbook uses: + - collection: + - ibm.ibm_zos_core + - modules: + - zos_copy + - zos_data_set + - zos_job_submit + +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 `create_copy_submit.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 `create_copy_submit.yml` with +command: + +```bash +ansible-playbook -i inventories create_copy_submit.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. diff --git a/zos_concepts/gdg_datasets/create_copy_submit/UPTIME b/zos_concepts/gdg_datasets/create_copy_submit/UPTIME new file mode 100644 index 000000000..c66f03432 --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/UPTIME @@ -0,0 +1,24 @@ +//****************************************************************************** +//* Copyright (c) IBM Corporation 2024 +//****************************************************************************** +//****************************************************************************** +//* Configure the job card as needed, most common keyword parameters often +//* needing editing are: +//* CLASS: Used to achieve a balance between different types of jobs and avoid +//* contention between jobs that use the same resources. +//* MSGLEVEL: controls hpw the allocation messages and termination messages are +//* printed in the job's output listing (SYSOUT). +//* MSGCLASS: assign an output class for your output listing (SYSOUT) +//****************************************************************************** +//UPTIME JOB (T043JM,JM00,1,0,0,0),'UPTIME - JRM', +// MSGCLASS=X,MSGLEVEL=1,NOTIFY=&SYSUID +//* +//* PRINT USS COMMAND ON JOB OUTPUT +//* +//UPTIME EXEC PGM=BPXBATCH +//STDPARM DD * +SH uptime +//STDIN DD DUMMY +//STDOUT DD SYSOUT=* +//STDERR DD SYSOUT=* +// \ No newline at end of file diff --git a/zos_concepts/gdg_datasets/create_copy_submit/ansible.cfg b/zos_concepts/gdg_datasets/create_copy_submit/ansible.cfg new file mode 100644 index 000000000..fcdc90db4 --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/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 diff --git a/zos_concepts/gdg_datasets/create_copy_submit/changelog.yml b/zos_concepts/gdg_datasets/create_copy_submit/changelog.yml new file mode 100644 index 000000000..f79b96d6d --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/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-09-26 + changes: + added: + - Released initial version \ No newline at end of file diff --git a/zos_concepts/gdg_datasets/create_copy_submit/create_copy_submit.yml b/zos_concepts/gdg_datasets/create_copy_submit/create_copy_submit.yml new file mode 100644 index 000000000..8360f01a7 --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/create_copy_submit.yml @@ -0,0 +1,118 @@ +############################################################################### +# © Copyright IBM Corporation 2024 +############################################################################### + +############################################################################### +# This sample playbook demonstrates how to create gds, copy a local JCL, copy +# to a new generation, delete a previous generation and execute the JCL. +# +# Usage: +# ansible-playbook -i +# +# Example: +# ansible-playbook -i inventories create_copy_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 to 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 name + # ########################################################################## + - name: Create temp data set name + command: "mvstmp {{ ansible_user | upper }}" + register: tmp_ds + + - set_fact: + tmp_data_set: "{{ tmp_ds.stdout }}" + # ########################################################################## + # Modules: zos_data_set, zos_copy, zos_job_submit + # ########################################################################## + # +------------------------------------------------------------------------- + # | - Using zos_data_set, create Generation Data Group with {{ tmp_data_set }} + # | name with a limit of 3 generations. + # | - Using zos_data_set, create a Generation Data Set with relative notation. + # | - Using zos_copy, copy {{ playbook_dir }}/UPTIME file to last creation of + # | GDS with relative notation {{ tmp_data_set }}(0). + # | - Using zos_copy, copy {{ tmp_data_set }}(0) to a new generation GDS with + # | relative notation {{ tmp_data_set }}(+1). + # | - Using zos_data_set, delete first creation of GDG {{ tmp_data_set }}(-1). + # | - Using zos_job_submit, submit the last creation of GDG with relative + # | notation {{ tmp_data_set }}(0). + # +------------------------------------------------------------------------- + - name: "Create the GDG {{tmp_data_set}} with limit of 3" + zos_data_set: + name: "{{ tmp_data_set }}" + type: gdg + limit: 3 + register: result_create_gdg + + - name: "Response from creating GDG {{ tmp_data_set }} with limit of 3" + debug: + msg: "{{ result_create_gdg }}" + + - name: "Create the GDS with relative notation {{ tmp_data_set }}(+1)" + zos_data_set: + name: "{{ tmp_data_set }}(+1)" + type: seq + state: "present" + register: result_create_gds_relative + + - name: "Response of the creation of the GDS {{ tmp_data_set }}(+1)" + debug: + msg: "{{ result_create_gds_relative }}" + + - name: "Copy local file {{ playbook_dir }}/UPTIME to latest creation of GDG {{ tmp_data_set }}" + zos_copy: + src: "{{ playbook_dir }}/UPTIME" + dest: "{{ tmp_data_set }}(0)" + encoding: + from: ISO8859-1 + to: IBM-1047 + register: result_copy_dir + + - name: "Response from copying local file {{ playbook_dir }}/UPTIME to latest creation of GDS {{ tmp_data_set }}." + debug: + var: result_copy_dir + + - name: "Copy SEQ gds {{ tmp_data_set }}(0) to a new GDS creation {{ tmp_data_set }}(+1)" + zos_copy: + src: "{{ tmp_data_set }}(0)" + dest: "{{ tmp_data_set }}(+1)" + remote_src: true + + - name: "Delete previous data set {{ tmp_data_set }}(-1)" + zos_data_set: + name: "{{ tmp_data_set }}(-1)" + state: absent + + - name: "Submit the JCL from the last generation {{ tmp_data_set }}(0)" + zos_job_submit: + src: "{{ tmp_data_set }}(0)" + location: data_set + register: result_submit + + - name: "Response from submitting JCL {{ tmp_data_set }}(0)" + debug: + var: result_submit + + - name: Delete the data sets + zos_data_set: + batch: + - name: "{{ tmp_data_set }}(0)" + state: absent + - name: "{{ tmp_data_set }}" + state: absent diff --git a/zos_concepts/gdg_datasets/create_copy_submit/inventories/group_vars/all.yml b/zos_concepts/gdg_datasets/create_copy_submit/inventories/group_vars/all.yml new file mode 100644 index 000000000..486fe46a3 --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/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"`. +################################################################################ diff --git a/zos_concepts/gdg_datasets/create_copy_submit/inventories/host_vars/zos_host.yml b/zos_concepts/gdg_datasets/create_copy_submit/inventories/host_vars/zos_host.yml new file mode 100644 index 000000000..0bd62568f --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/inventories/host_vars/zos_host.yml @@ -0,0 +1,65 @@ +--- +################################################################################ +# 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 +# (target) node e.g, PYZ: "/usr/lpp/IBM/cyp/v3r12/pyz" +# - Property `PYZ_VERSION` is the version of python on the z/OS managed +# (target) node e.g, PYZ_VERSION: "3.12". +# - Property `ZOAU` is the ZOAU installation home on the z/OS managed (target) +# node, e.g, ZOAU: "/usr/lpp/IBM/zoautil". +# - Property `ZOAU_PYTHON_LIBRARY_PATH` is the path to the Z Open Automation +# Utilities (ZOAU) python library. Specifically, the path points to the +# directory containing 'zoautil_py'. Packages installed using 'pip' generally +# default to the 'site-packages' directory within the python installation, +# eg "/usr/lpp/IBM/cyp/v3r12/pyz/lib/python3.12/site-packages/". +# If the installation uses options such as '--user' or '--target', the module +# is installed to a non-default location which must be configured in +# `ZOAU_PYTHON_LIBRARY_PATH`. +# If the wheel installation method is used with the '--target' or '--user' +# option, `ZOAU_PYTHON_LIBRARY_PATH` should point to the directory the wheel +# file was installed to. e.g ZOAU_PYTHON_LIBRARY_PATH: "/usr/zoau-wheel/". +# Else 'ZOAU_PYTHON_LIBRARY_PATH' should point to the directory containing +# the pre-compiled binary. +# For ZOAU v1.2.x, the pre-compiled binary is located in the 'lib' directory. +# e.g "/usr/lpp/IBM/zoautil/lib" or "{{ ZOAU }}/lib". +# For ZOAU v1.3.x, the pre-compiled binary is located in a sub-directory +# corresponding to the `PYZ_VERSION` inside the 'lib' directory, +# e.g "/usr/lpp/IBM/zoautil/lib/3.12" or "{{ ZOAU }}/lib/{{ PYZ_VERSION }}". +# - 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, PYZ_VERSION, and ZOAU environment variables must be configured. +################################################################################ + +PYZ: "path_to_python_installation_on_zos_target" +PYZ_VERSION: "3.xx" + +ZOAU: "path_to_zoau_installation_on_zos_target" + +# Configuring the `ZOAU_PYTHON_LIBRARY_PATH` property is required. + +# If the ZOAU python package, zoautil_py, has been installed as a wheel (*.whl) +# with the '--target' or '--user' option, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ path_to_wheel_installation_directory }}" + +# If the ZOAU python zoautil_py package has been installed in the default location +# that is part of Python's search path, the `ZOAU_PYTHON_LIBRARY_PATH` environment +# variable must be set as an empty string. Uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "" + +# If using pre-compiled binaries for ZOAU v1.3.x, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib/{{ PYZ_VERSION }}" + +# If using pre-compiled binaries for ZOAU v1.2.x, uncomment the following line: +# ZOAU_PYTHON_LIBRARY_PATH: "{{ ZOAU }}/lib" + + +################################################################################ +# Do not configure, variable substituion will correctly set the +# variable `ansible_python_interpreter` +################################################################################ +ansible_python_interpreter: "{{ PYZ }}/bin/python3" diff --git a/zos_concepts/gdg_datasets/create_copy_submit/inventories/inventory.yml b/zos_concepts/gdg_datasets/create_copy_submit/inventories/inventory.yml new file mode 100644 index 000000000..27508a303 --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/inventories/inventory.yml @@ -0,0 +1,17 @@ +################################################################################ +# © Copyright IBM Corporation 2024 +################################################################################ + +################################################################################ +# Description of the properties used in this configuration: +# - Property `ansible_host` is the z/OS managed node (target), +# e.g, ansible_host: "zvm1.vmec.svl.ibm.com" +# - Property `ansible_user` is the z/OS managed user to connect and run as over SSH, +# e.g, ansible_user: "zosadm" +################################################################################ + +source_system: + hosts: + zos_host: + ansible_host: zos_target_address + ansible_user: zos_target_username diff --git a/zos_concepts/gdg_datasets/create_copy_submit/runtime-requirements.yml b/zos_concepts/gdg_datasets/create_copy_submit/runtime-requirements.yml new file mode 100644 index 000000000..d66077b23 --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/runtime-requirements.yml @@ -0,0 +1,31 @@ +################################################################################ +# Copyright (c) IBM Corporation 2024 +################################################################################ + +################################################################################ +# List `requires_ansible_version` contains Ansible version entries that this +# playbook requires. It can be one more then one Ansible version +# e.g, `- 2.9` would be interpreted as 2.9 - 2.9.n where n is >= 0. Where `- 2.9.0` +# would be require an exact match, just like 2.9.12 would be an exact match. +# +# Dictionary `requires_collection` can include more than one collection such as +# in the case a playbook depends on other IBM z collections. +# e.g, +# requires_collection: +# - ibm_zos_core: +# name: "ibm_zos_core" +# version: "1.4.0-beta.1" +# - ibm_zos_ims: +# name: "ibm_zos_ims" +# version: "1.4.0-beta.1" +################################################################################ + +requires_ansible_version: + - "2.15" + - "2.16" + - "2.17" + +requires_collection: + - ibm_zos_core: + name: "ibm_zos_core" + version: "1.11.0" diff --git a/zos_concepts/gdg_datasets/create_copy_submit/site.yml b/zos_concepts/gdg_datasets/create_copy_submit/site.yml new file mode 100644 index 000000000..9b614759b --- /dev/null +++ b/zos_concepts/gdg_datasets/create_copy_submit/site.yml @@ -0,0 +1,34 @@ +############################################################################### +# © Copyright IBM Corporation 2024 +############################################################################### + +############################################################################### +# This playbook (`site.yml`) is the master playbook for this project. Based on +# the playbooks requirements, `site.yml` playbook will evaluate the requirements +# and report when the minimum requirements are not configured and fail playbook +# execution. +# +# Upon successful dependency analysis, the z/OS playbook will be executed. +# +# Usage: +# ansible-playbook -i +# +# Example: +# ansible-playbook -i inventories site.yml +# ansible-playbook -i inventories site.yml -v +############################################################################### + + +--- +- hosts: localhost + + tasks: + - name: Parse the registry for collection entries + include_vars: runtime-requirements.yml + + - name: Display the registered collections and properites in `registry.yml`. + include_role: + name: requirements-check + +- name: Executing the z/OS Ansible playbook + import_playbook: create_copy_submit.yml