Installing and configuring ZOA Utilities

Prerequisites

IBM® Z Open Automation Utilities has few prerequisites on z/OS.

Optional programs

Toolkit disk space

ZOA Utilities requires approximately 3000 tracks (200 cylinders) 3390 disk space for product installation.

Installing ZOA Utilities on z/OS

You can install ZOA Utilities via PAX or SMP/E.

Installing via PAX

To download and install ZOA Utilities via PAX:

  1. Navigate to Mainframe DEV.
  2. Search for product name "IBM Z Open Automation Utilities" listed under IBM Enterprise DevOps.
  3. Press Download and agree to the Software License Agreement.
  4. Save the zoau-<version>.pax file.
  5. Transfer zoau-<version>.pax to your z/OS host by using binary mode.

  6. Install ZOA Utilities on z/OS by issuing the command:

    pax -p e -rf zoau-<version>.pax

Installing via SMP/E

To install ZOA Utilities on z/OS via SMP/E, see the Program Directory for IBM Z Open Automation Utilities.

The results of the SMP/E installation are a USS directory found at /usr/lpp/IBM/zoautil and a data set containing sample members used for the installation. The USS directory contains these subdirectories:

Subdirectory Usage
bin Executable programs
docs Man pages and other supporting documentation
include Header files
lib API DLL files

Configuring ZOA Utilities

Complete the following procedure to configure ZOA Utilities. You do not need to follow the sequence.

  1. Set this environment variable:

    export _BPXK_AUTOCVT=ON

  2. Add ZOA Utilities to the PATH environment variable.

    For example, if you install ZOA Utilities in ${ZOAU_HOME}, add ${ZOAU_HOME}/bin to your PATH.

  3. Add ZOA Utilities to the LIBPATH environment variable.

    For example, if you install ZOA Utilities in ${ZOAU_HOME}, add ${ZOAU_HOME}/lib to your LIBPATH.

  4. Check that the APF authorization bit is on for the mvscmdauth and mvscmdauthhelper commands, which should be the case if you install ZOA Utilities by SMP/E. Issue ls -E /usr/lpp/IBM/zoautil/bin/mvscmdauth* and examine the second column of the command output. If it does not show a--- , set it by issuing extattr +a /usr/lpp/IBM/zoautil/bin/mvscmdauth*. If you cannot set the APF authorization bit, you might not have permission to do so and should consult your system programmer.

  5. (Optional) To use the supplied man pages, update environment variable MANPATH.

    For example, if you install ZOA Utilities in ${ZOAU_HOME}, add ${ZOAU_HOME}/docs/%L to your MANPATH.

    You can then invoke man pages with the command man.

  6. (Optional) To use ZOA Utilities Python APIs, complete either the preferred pip installation method or the PYTHONPATH environment method, but not both:

    pip installation method: Use the Python pip package manager to install ZOAU Python APIs. This method provides the benefits of pip package manager features and attempts to build Cpython source code for guaranteed PYZ version compatibility. In case of compilation failure, this method will use the precompiled binary file embedded in the tar.gz file for installation.

    1. Set these environment variables:

      export ZOAU_HOME=/usr/lpp/IBM/zoautil
export PATH=${ZOAU_HOME}/bin:$PATH
export LIBPATH=${ZOAU_HOME}/lib:${LIBPATH}

    2. (Recommended) Create a virtual environment by using this command:

      python3 -m venv env
source env/bin/activate

    3. Download the pip installable package, which is included in the ZOA Utilities PAX file. Follow the Installing via PAX procedure to download and extract the PAX file, from which you can get zoautil_py-<version>.tar.gz.

    4. Install the pip installable package for ZOA Utilities Python APIs with this command:

      pip3 install zoautil_py-<version>.tar.gz

PYTHONPATH environment method: This method sets the PYTHONPATH environment variable to point to the zoautil_py directory path containing ZOAU Python APIs and a precompiled binary. The script configure.py checks for and makes the precompiled binary compatible with the present IBM Open Enterprise Python for z/OS (PYZ) version on the system.

Set these environment variables:

   export ZOAU_HOME=/usr/lpp/IBM/zoautil
   export PATH=${ZOAU_HOME}/bin:$PATH
   export LIBPATH=${ZOAU_HOME}/lib:${LIBPATH}
   export PYTHONPATH=${PYTHONPATH}:${ZOAU_HOME}/lib

If using PYZ 3.9, check for and make the PYZ version compatible:

   cd ${ZOAU_HOME}/lib/zoautil_py/config
   ./configure.py

Enabling all ZOA Utilities capabilities

To enable all the capabilities of ZOA Utilities, set these environment variables and run the commands described in the previous configuration step:

# ZOAU REQUIREMENTS
export _BPXK_AUTOCVT=ON
export ZOAU_HOME=/usr/lpp/IBM/zoautil
export PATH=${ZOAU_HOME}/bin:$PATH
# ZOAU MAN PAGE REQS (OPTIONAL)
export MANPATH=${ZOAU_HOME}/docs/%L:$MANPATH
export CLASSPATH=${ZOAU_HOME}/lib/*:${CLASSPATH}
export LIBPATH=${ZOAU_HOME}/lib:${LIBPATH}
# ZOAU PYTHON REQS (OPTIONAL)
export ZOAU_HOME=/usr/lpp/IBM/zoautil
export PATH=${ZOAU_HOME}/bin:$PATH
export LIBPATH=${ZOAU_HOME}/lib:${LIBPATH}

Protecting ZOA Utilities for its APF authorized components

ZOA Utilities includes two programs installed in the zoautil bin directory that have extended attributes enabled that allow them to behave as if they are loaded from an APF authorized library. These are mvscmdauth and mvscmdauthhelper. The mvscmdauth utility can be used to invoke APF authorized programs as part of a ZOAU script. Other utilities also use these programs:

ZOAU utilities should be protected with adequate file based permissions to ensure that these utilities are only used by authorized users.

Enabling logging to gather debug information

Complete the following procedure to enable logging to gather debug information.

Enabling logging for Python

  1. Create a logging_config.py file for your program:

    import logging
from logging.config import dictConfig
from zoautil_py import datasets 

logging_config = dict(
   version = 1,
   formatters = {
      'f': {'format':
            '%(asctime)s %(name)-12s %(levelname)-8s %(message)s'}
      },
   handlers = {
      'h': {'class': 'logging.StreamHandler',
            'formatter': 'f',
            'level': logging.DEBUG}
      },
   root = {
      'handlers': ['h'],
      'level': logging.DEBUG,
      },
)

dictConfig(logging_config)

  2. Import Logging Config to Module:

    import logging_config
from zoautil_py import datasets 

# Create dataset so that we can force error
datasets.create("ZOAU.DATASET", verbose=True, debug=True)
# Force error
datasets.create("ZOAU.DATASET", verbose=True, debug=True)

The expected logging response is:

2021-04-09 10:46:55,292 zoautil_py.datasets INFO     Calling ZOAU shared library: dtouch -d -v "ZOAU.DATASET"
2021-04-09 10:46:56,126 zoautil_py.datasets ERROR    STDERR from ZOAU library call: 
BGYSC1409E Dataset ZOAU.DATASET already exists. New dataset not allocated.