Installing and configuring ZOAU

Software requirements

ZOAU is supported on z/OS 2.4 or later.

ZOAU requires one of the following job entry systems on your installation:

• JES2 (job entry subsystem 2). Learn more at z/OS JES2.
• JES3 (job entry subsystem 3). Learn more at z/OS JES3.

Required disk space

ZOAU requires approximately 750 tracks (50 cylinders), or 35MB of 3390 disk space for product installation.

To operate correctly, ZOAU requires a writable temporary directory (typically /tmp) with at least 100 MB of free space.

Installed items and optional programs

To use the ZOAU Python language pack, you must install IBM Open Enterprise SDK for Python version 3.9 or later. Learn more at IBM Open Enterprise SDK for Python.

The results of the ZOAU installation are a z/OS UNIX directory found at /usr/lpp/IBM/zoau/v1r3. The following subdirectories are included in the distribution:

Installing with pax

To download and install ZOAU with pax:

1. Navigate to Mainframe Downloads.

2. Search for the 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.Z file to your local device.

5. Transfer the zoau-<VERSION>.pax.Z file to your z/OS host by using binary mode.

6. Log in to your z/OS system. Ensure that the current user ID has the ability to set the APF authorization bit on a file; this can be the superuser or a user who has READ access to the BPX.FILEATTR.APF resource in the FACILITY class. To learn more, see Controlling who can set the APF-authorized attribute.

7. Continuing on z/OS, create and mount a new zFS filesystem as read-write.

8. Use the cd command to change the working directory to the new zFS filesystem.

9. Issue the following command to install ZOAU into the new zFS filesystem:

   pax -ppx -rf zoau-<VERSION>.pax.Z
   

   
   

   If the command produces an error message, the current user ID does not have sufficient authority to install ZOAU. For example, you might see the following error:

   pax: FSUMF073 bin/opercmdhelper: user not authorized to restore extended attribute "a"
   

   
   

   To remedy this situation, review the previous steps or consult your system programmer.

10. Change to the prior directory (cd -). This is so the ZOAU filesystem can be remounted.

11. Remount the ZOAU filesystem as read-only. The typical installation location for ZOAU is /usr/lpp/IBM/zoau/v1r3.

Install with SMP/E

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

Temporary directory

To function properly, ZOAU requires a writable temporary directory with a minimum 100 MB of free space. Typically mounted at /tmp, the temporary directory on z/OS should be a standalone zFS or TFS filesystem.

Unexpected behavior can occur if the directory is full and ZOAU cannot write to it, so specify a size that will not completely fill during typical system workloads. To monitor the amount of free space available, use the following methods:

• Monitoring space in the TFS
• The AGGRFULL option in the zFS MOUNT command

Set environment variables

An environment variable pairs a case-sensitive variable name with an assigned value in the form VARNAME=VALUE. Use environment variables with ZOAU to define and provide specific characteristics of your environment to the UNIX System Services and utilities at runtime.

Several environment variables must be set correctly for ZOAU to function properly. Some are unique to ZOAU, others are general to UNIX System Services. To learn more about general settings, see Abstract for z/OS UNIX System Services Planning.

Perform the following steps to configure required and optional environment variables for ZOAU.

_BPXK_AUTOCVT enables automatic conversion of tagged files. When set, this variable overrides the AUTOCVT setting in BPXPRMxx. The default setting is OFF. To ensure that ASCII-tagged content is properly handled by z/OS, set the _BPXK_AUTOCVT variable to ON:

export _BPXK_AUTOCVT=ON

To learn more about _BPXK_AUTOCVT, see _BPXK environment variables.

Create a ZOAU_HOME environment variable that points to the location where ZOAU v1.3 is installed. The default location is /usr/lpp/IBM/zoau/v1r3.

export ZOAU_HOME=<PATH_TO_ZOAU>

PATH sets a default command search path to search the directories concatenated in this string. Add ZOAU to the PATH environment variable.

export PATH=$PATH:$ZOAU_HOME/bin

LIBPATH specifies the directory to search for a dynamic link library (DLL) file name. Add ZOAU to the LIBPATH environment variable.

export LIBPATH=$LIBPATH:$ZOAU_HOME/lib

To learn more about PATH, LIBPATH, and MANPATH, see Customizing /etc/profile.

(Optional) To use the supplied man pages and view them with the man command, update the MANPATH environment variable.

export MANPATH=$MANPATH:$ZOAU_HOME/docs/%L

(Optional) TMPHLQ is a ZOAU-specific environment variable that is used by the mvstmp utility. If the user ID that runs ZOAU commands does not have write access to the high-level qualifier (HLQ) matching its username, use the TMPHLQ environment variable to specify a different HLQ.

export TMPHLQ=<WRITEHLQ>

(Optional) By default, temporary files are written to the /tmp directory. Use the TMPDIR standard environment variable to write temporary files to an alternate directory.

export TMPDIR=/tmp

(Optional) CONSBUFPGUM is a ZOAU-specific environment variable and is used by opercmd. Use CONSBUFPGNUM to specify the number of buffer pages allocated to command output.

export CONSBUFPGNUM=128

(Optional) To validate the ZOAU installation, run the following command, which reports any problems with the installation or configuration. This creates a report that can be used when working with IBM Support.

zoaversion -c

Set APF authorization

IMPORTANT: Do not use the NOSETUID option when mounting the filesystem on which ZOAU is installed. ZOAU contains APF-authorized programs. If the NOSETUID option is enabled, the APF bit will not be honored and ZOAU will not function correctly.

If you install ZOAU with SMP/E, the APF authorization bits should be correctly set for you, and this step should not be necessary. Otherwise, you can check that the APF authorization bit is on for the required commands.

1. Issue the following command:

   zoaversion -c
   

   
   

2. A ZOAU diagnostic report will be printed to the terminal. If any files are listed as missing the APF bit, the following error message will be displayed.

   Error: <FILENAME> does not have the APF authorization bit set.
   

   
   

   You can set the APF bit on the file with the following command:

   extattr +a ${ZOAU_HOME}/bin/<FILENAME>
   

   
   

   If you receive an error message when issuing the extattr command, then your user ID may not have authority to set the APF bit. You must use either the superuser ID or a user who has READ access to the BPX.FILEATTR.APF resource in the FACILITY class. Contact your system programmer for more information.

Setting console command authority

The EMCS console created by opercmd has MASTER authority. This authority level enables opercmd users to issue z/OS console commands, and allows opercmd to reply to WTOR messages issued by a different console. Access to opercmd should thus be restricted to authorized users.

Specific authorization is required to use jcan and opercmd. An authorized user (such as a system programmer) must define a profile named MVS.MCSOPER.ZOAU and then assign users READ access to that profile.

The following example shows how to use RACF commands to define the MVS.MCSOPER.ZOAU profile and assign users READ access on a system that includes the RACF security product. If your system uses a different security product, consult that product's documentation to configure the required security classes.

RDEFINE OPERCMDS MVS.MCSOPER.ZOAU
PERMIT MVS.MCSOPER.ZOAU CLASS(OPERCMDS) ID(userid) ACCESS(READ)
SETROPTS RACLIST(OPERCMDS) REFRESH

You might need to modify the previous commands for your installation. To learn more, see Controlling the use of operator commands.

Minimum Python versions

ZOAU is compatible with the following minimum versions of IBM Open Enterprise SDK for Python.

To use the ZOAU Python APIs, use only one of the following installation methods:

• Python wheel installation method
• PYTHONPATH environment variable method
• Python setuptools installation method (not recommended)

Python wheel installation method

A wheel file is a ZIP-format archive with a specially formatted file name followed by the .whl extension. It contains a precompiled python module ready to install.

The ZOAU pax archive contains a .whl file for each of the currently supported versions of IBM Open Enterprise SDK for Python. In the following table, <zoauversion> represents the ZOAU version included in the pax archive.

For example, the .whl file for IBM Open Enterprise SDK for Python version 3.12 for ZOAU version 1.3.0.0 has the file name zoautil_py-1.3.0.0-cp312-none-any.whl.

Warning: The Python wheel installation method performs version matching against the .whl file name. Any modification to the file name can break and corrupt the module installation.

To install the ZOAU API with a wheel package, run the following command after replacing <zoauversion> with your version of ZOAU (including dots, such as 1.3.0.0), and <pythonversion> with your version of IBM Open Enterprise SDK for Python (excluding dots, such as 312):

pip3 install zoautil_py-<zoauversion>-cp<pythonversion>-none-any.whl

For example, the command to install the Python 3.12 version of the ZOAU 1.3.0.0 wheel would look like the following:

pip3 install zoautil_py-1.3.0.0-cp312-none-any.whl

PYTHONPATH environment variable method

The PYTHONPATH environment variable method sets this to point to the zoautil_py directory path containing the ZOAU Python APIs and a precompiled binary.

This environment variable must be set to the correct ZOAU directory that corresponds to the version of Python installed on your z/OS system.

1. If not already done, set the environment variables.

2. Determine the version of Python running on your system. This can be discovered by running the command python3 --version. The version number used in this case is the first two digits in the output. For example:

   ~> python3 --version
   Python 3.12.0
   # The python version is 3.12.
   

3. Set the PYTHONPATH environment variable. The final part of the path will correspond to the version number of the Python runtime. You must adjust this value to match what is installed on your system. Note that this step requires the ZOAU_HOME environment variable to be set.

   export PYTHONPATH=${PYTHONPATH}:${ZOAU_HOME}/lib/3.12
   

Python setuptools installation method (not recommended)

Note: The Python setuptools method is not recommended due to additional complextity and software requirements. Only use this method if neither of the others work for you.

This installation method requires one of the following C compilers to build the Cpython source code in the ZOAU langugage pack.

1. If not already done, set the environment variables.

2. Create a virtual environment by using the following commands:

   python3 -m venv env
   source env/bin/activate
   

3. Find the pip installable package, which is included in the ZOAU pax file. Follow the Installing with 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 ZOAU Python APIs with the following command:

   pip3 install zoautil_py-<version>.tar.gz
   

Python stub files

A zoautil_py-stubs directory that contains optional Python stub files is included as part of your ZOAU installation. To import the stub files into your preferred development environment, see your environment's documentation.