ZOAU Release Notes for IBM Z and Cloud Modernization Stack

These release notes provide information about Z Open Automation Utilities in IBM Z and Cloud Modernization Stack. For release notes about other products in IBM Z and Cloud Modernization Stack, see Release notes.

Important information

If this product is modified between releases of IBM Z and Cloud Modernization Stack, additional versions might be available. For the latest information about product versions, always check the IBM Z and Cloud Modernization Github community.

To view and contribute ZOAU samples, snippets, ideas, and conversations, visit the ZOAU community on GitHub.

Known issues and limitations

No known issues are present in Z Open Automation Utilities version 1.2.5.

New and noteworthy updates


Version 1.2.5.8

ZOAU 1.2.5.8 fixes the following problem:

Improvements

  • dcp
    • The efficiency of dcp has been improved.

Bug fixes

  • dcp
    • Trying to copy a load module with aliases into an existing PDSE two times fails when the second copy attempt is the same load module. This has been fixed.

Version 1.2.5.7

Bug fixes

ZOAU 1.2.5.7 fixes the following problem:

Python Library

  • datasets.list_vsam_datasets
    • An empty list is now returned if no data sets matching the provided pattern are found. This function previously threw an exception.

Version 1.2.5.6

Bug fixes

ZOAU 1.2.5.6 fixes the following problem:

  • core.so

    • Unprintable characters in the response buffer from a ZOAU utility are now converted to a space character. This prevents a UnicodeDecodeError exception from being thrown when the response buffer is converted to a Python string.

Version 1.2.5.5

Bug fixes

ZOAU 1.2.5.5 fixes the following problem:

  • pcon

    • The algorithm that calculates recent and specific log start times is fixed. A time provided with the -s argument now produces results similar to those produced by the -dlmrwy arguments.

    • More diagnostic messages are now available when you use the -v option.


Version 1.2.5.4

Bug fixes

ZOAU 1.2.5.4 fixes the following problem:

  • opercmd
    • On some systems, issuing an operator command could result in abend SD22 R=00000020. This has been fixed.

Version 1.2.5.3

Bug fixes

ZOAU 1.2.5.3 fixes the following problems:

  • pcon
    • An off-by-one error occurred if the -s argument was applied to January or February of a leap year. This has been fixed.

Version 1.2.5.2

Bug fixes

ZOAU v1.2.5.2 fixes the following problem:

Python Library

  • zoau_io.zopen
    • Passing an unsupported encoding page to the zopen() factory function caused an abend. This has been fixed to throw an exception.

Version 1.2.5.1

Improvements

  • Added support for IBM Open Enterprise Python version 3.12.
    • A new wheel file has been added to easily install support for the latest Python runtime.

Version 1.2.5.0

New commands

ZOAU v1.2.5.0 adds the following new utilities:

  • a2e and e2a
    • Convert files in-place between EBCDIC and ASCII. Reads and sets file tags during the conversion.
  • pdc
    • Print a list of the active data classes.
  • smsraw
    • Drive an SMS service through batch TSO.

ZOAU v1.2.5.0 adds these capabilities and enhancements:

Improvements

  • opercmd
    • New -w argument added to toggle behavior when waiting for command response output. Specifying this argument causes opercmd to wait the entire timeout period before returning.
    • The default timeout value has been changed to 1 second. This is the maximum amount of time that opercmd will wait before returning, regardless if it received any command response.
  • zoautil.so
    • Improved temporary file creation and cleanup.
  • zoaversion
    • A new -c argument has been added to print a diagnostic report about the ZOAU installation. This is intended for use by IBM service personnel.
    • The release "codename" is printed as part of the command output.

Python library

  • core.so
    • The Python language pack correctly performs a version check before loading the ZOAU shared library. If there is a version mismatch, an exception will be raised.
  • datasets.copy
    • Add new alias and executable arguments to allow for copying of data set aliases.
    • Fixed an issue that caused a dataset name containing a dollar sign to be unintentionally expanded as a shell variable.
  • datasets.create
    • Creation of VSAM datasets is now properly validated.
  • datasets.list_members
    • Add new alias argument to toggle display of data set member aliases.
  • types.DatasetDefinition
    • Fixed an argument error that caused message BGYSC0224E.
  • zsystem.read_console
    • Fixed an issue that caused incorrect output when using debug=True.

Bug fixes

ZOAU v1.2.5.0 fixes the following problems:

  • Many utilities did not properly support the -d option to enable debug output. This has been fixed.
  • ddls
    • The debug output is now correctly printed to standard error. This will allow using debug=True in jobs.list_dds().
  • decho
    • Fixed an issue that caused several "libdio error" messages to display.
  • dinfo
    • Fixed issues that produced unprintable characters in the output values and memory faults in certain cases.
  • dls
    • dls -s now shows the proper size of datasets larger than 4GB.
    • A memory overlay issue that caused corrupted output has been fixed.
  • dmod
    • Fixed a memory corruption issue.
    • Added validation checks when writing out the modified dataset.
    • New error message BGYSC4819E is produced when dmod is unable to find a z/OS UNIX file.
  • dzip
    • Fixed return codes produced when the compression step fails. dzip previously returned RC=8 in all failure cases. It will now pass through return codes from called programs.
  • jcan
    • Two new error messages BGYSC3804E and BGYSC3805E were added to jcan. The first is triggered if jcan detects a security manager error, and the second if jcan detects a memory error.
  • jsub
    • It is now possible to submit a job from a dataset that has a hyphen in the name.
  • mvscmd
    • Fixed a bug that triggered a shell syntax error when verbose output was enabled and a PDS member was used as a DD.
  • pjdd
    • Fixed an issue that displayed error message BGYSC3703E even on success.

Version 1.2.4.5

Bug fixes

ZOAU 1.2.4.5 fixes the following problem:

Python Library

  • zoau_io.zopen
    • Fixed an issue that was causing an abend when calling the zopen factory function multiple times.

Version 1.2.4.4

Bug fixes

ZOAU v1.2.4.4 fixes the following problem:

  • drm
    • Fixed an intermittent problem where message BGYSC1505E was produced and the specified datasets were not deleted.

Version 1.2.4.3

Bug fixes

ZOAU v1.2.4.3 fixes the following problems:

  • jls

    • Adjusted the -o and -l options to make -o have priority. Only the fields specified by the -o options will be honored, even if the -l option is also specified.

  • ddls

    • Fixed an issue that printed a single line with no details for jobs that were invalid or inaccessible to JES.

Version 1.2.4.2

Bug fixes

  • mvscmd
    • Fixed a bug that triggered a shell syntax error when verbose output was enabled and a PDS member was used as a DD.
    • Fixed a bug that didn't allow certain programs to receive input from stdin while using the documented syntax.

Version 1.2.4.1

Changes

ZOAU v1.2.4.1 changes the following behavior:

  • opercmd
    • The default wait time for a command response has been reduced. This can improve the performance of scripts that make repeated calls to opercmd.

Python library

  • opercmd.execute
    • The default value of the timeout parameter has been changed to 0. This means that the API will accept whatever the minimum timeout value is from the opercmd utility.

Version 1.2.4

Improvements

ZOAU v1.2.4 adds these capabilities and enhancements:

  • dcp
    • A new -f argument is added to force the copy operation, which can be used to override a shared lock on the destination dataset.
    • NOTE: If a dataset member has aliases, and is not a program object, copying that member to a dataset that is in use will result in the aliases not being preserved in the target dataset. When this scenario occurs an error message will be produced along with a non-zero return code.
    • A new -i argument is added to preserve the aliases of text-based members.
  • ddls
    • New -i flag to list SYSIN DDs, like INPUT ON in SDSF.
    • New error messages BGYSC3405E and BGYSC3406E are produced if a job is in a phase when DDs cannot be queried.
  • decho
    • Updates to the man page describe how to write a message starting with a dash.
  • dls
    • Automatically translates the dollar symbol to the pound sterling symbol when the locale is set to En_GB.IBM-285.
  • dtail
    • A new -b argument is added to view "binary" files. This allows for viewing of data that contains NULL or terminal control characters.
    • A new -l argument is added that suppresses newlines between dataset records.
  • hlq
    • The -d argument is now properly supported.
  • jls
    • New field <pgmname> in -l output shows the program name from the job's last completed step.
    • New option -o enables field selection and ordering.
  • mls
    • Automatically translates the dollar symbol to the pound sterling symbol when the locale is set to En_GB.IBM-285.
  • mvscmd
    • Hyphens are now supported in dataset names.
  • pcon
    • The -s argument is documented to support seconds in the timestamp.
    • Syntax help is displayed when pcon is invoked with no arguments.
  • pjdd
    • Now supports reading the contents of SYSIN DDs.
    • Special parsing of the EVENTLOG DD to show step information.
    • Error messages are now produced if a job is in a phase when DDs cannot be queried.
  • samples/binary_read.c
    • A new sample program that shows how to use the new binary read capability for reading data sets.
  • samples/zoau_sample.c
    • A new sample program is available that shows how to utilize the ZOAU shared library.
  • zoautil.so
    • The ZOAU shared library version has been updated to support binary streams.
    • An additional argument has been added to the function vector table to for a new options structure. This is used to modify the behavior of the shared library during a function call.
    • The zoau_response structure has been extended to handle binary streams.
  • The man page titles are updated to say "ZOAU" instead of "ZOA Utilities".

Python library

  • datasets.copy
    • The new boolean parameter force is added to force the copy.
    • NOTE: If a dataset member has aliases, and is not a program object, copying that member to a dataset that is in use will result in the aliases not being preserved in the target dataset. When this scenario occurs an exception will be raised, along with an error message and a non-zero return code.
  • datasets.listing
    • A new volume option has been added, this enables filtering by volume name.
  • jobs.list_dds
    • New sysin optional parameter that invokes ddls -i.
    • New DDQueryException based on job phases.
  • Job class
    • New attribute program_name.
  • volumes.list_vsam_datasets
    • A new migrated option has been added to optionally display VSAM datasets that have been migrated.
  • Python Samples
    • Python samples are now available within the samples directory.
    • A new multi-process asynchronous mvscmd sample is included.
  • Stub files
    • The ZOAU install now has a zoautil_py-stubs directory that contains *.pyi stub files for the python utilities. This allows you to import them into your IDE for enhanced language support.
  • ZOAU IO module
    • Addition of a new zoau_io module that provides IO interfaces to z/OS sequential and partitioned datasets.
    • The module currently supports reading operations over a dataset opened in a record stream model.
    • A new RecordIO class is defined, instances of this class represent a record stream in binary mode. This class provides a readrecord() method that returns a bytes object containing the data from the next record available in the stream.
    • A new RecordIO_TextWrapper class provides a decoding/encoding layer over a RecordIO object to output readable text strings.
    • The module provides a zopen() factory function that creates an instance of the previously mentioned classes depending on an optional encoding parameter.
    • All the classes in the module support the iterator protocol to read the stream in a record-by-record approach. These classes also suport the context manager protocol to automatically open and close a stream using the with operator.

Bug fixes

  • datasets.lineinfile
    • Fixed issue where the lineinfile() function was duplicating lines when the instruction was to replace them.
  • datasets.write
    • A string starting with a hyphen (-) character can now be written to a dataset.
  • dgrep
    • The -d argument is now properly supported.
    • The man page mentioned a -m argument that was never implemented. This has been removed.
  • dls
    • Fixed an issue that caused dinfo to return blank dataset names.
    • New error BGYSC2010E for failed memory allocation in dinfo.
  • jls
    • Fixed an issue that showed incorrect creation date under z/OS 2.3.
  • jsub
    • Submitting JCL from a file without a trailing newline now works correctly.
  • opercmd
    • It now waits the exact amount of time specified in the TIMEOUT argument while collecting messages. This allows it to collect more complete message responses from commands that produce multiple single line messages.
  • vls
    • The man page now documents the new -m argument, for displaying migrated VSAM data sets.
  • zoautil.so
    • Running a command when your LIBPATH points to a backlevel version of the ZOAU shared library no longer causes an abend.
    • The ZOAU version reported in SMF records now matches the build version.

Version 1.2.3.2

Bug fixes

ZOAU v1.2.3.2 fixes the following problem:

  • jdc
    • Julian dates with years between 2000-2009 are now handled properly.
    • The man page has been updated to mention the new input formats yyyy.ddd, yy.ddd, yyyyddd, and yyddd.

Version 1.2.3.1

Bug fixes

ZOAU v1.2.3.1 fixes the following problem:

  • zoautil.so
    • Temporary files are properly cleaned up when the shared library is invoked from an ASCII mode caller.

Version 1.2.3

Improvements

ZOAU v1.2.3 adds these capabilities and enhancements:

  • dmod
    • A new -j argument is added to produce JSON output.
  • dtouch
    • The -r argument now accepts record format F for creating fixed unblocked datasets.
  • jls
    • New -l option to show additional fields.
    • Verbose output shows a list header.
  • jdc
    • Supported input formats now include yyyy.ddd, yy.ddd, yyyyddd, and yyddd.
    • Now supports -? for syntax help.
    • New error message for invalid input length.
  • zoaversion
    • The APAR number is now displayed as part of the program output.

Python library

  • Python wheel packages now provide easier installation and eliminate the need for a C compiler to be available during installation.
  • Memory leaks are fixed in the Python extension module.
  • datasets.blockinfile()
    • Added a new as_json argument to display output in JSON format.
  • datasets.create()
    • Added support for record_format to accept a type of F (fixed unblocked).
  • datasets.read_head()
    • This new function displays the head content of a non-VSAM data set.
  • types.py.Job
    • New attributes are added to support the new jls -l option.
    • The rc attribute type is changed to str.

Bug fixes

ZOAU v1.2.3 fixes the following problems:

  • dcp
    • The -I and -d arguments are now properly supported.
  • dls
    • Fixes the error message that is displayed when a partitioned data set member is deleted but aliases that point to it remain.
  • dtouch
    • An example in the man page is fixed.
    • New message BGYSC1429E indicates an unknown dynParm type.
  • dzip
    • Message BGYSC3907I now prints correctly when AMATERSE fails with RC=0B37.
  • jls
    • Listing the caller's jobs is now working properly when executing jls '*'.
  • jsub
    • An attempt to submit invalid JCL now properly terminates with an error.
  • mls
    • Fixes the error message that is displayed when a partitioned data set member is deleted but aliases that point to it remain.
  • mvscmdmsg
    • Messages from the various utilities are properly displayed if the shell environment variable LANG is not set.

Version 1.2.2.1

Python library

The ZOAU Python libraries support IBM Open Enterprise SDK for Python version 3.11 and version 3.10. Both versions support multiple compilers, including the IBM C/C++ For Open Enterprise Languages on z/OS 2.0 Clang compiler. To use the Clang compiler with version 3.10, install Open Enterprise SDK 3.10 for Python with OCI artifact 3.10.0.5 or later.


Version 1.2.2

New commands

ZOAU version 1.2.2 adds the commands dcat and dhead.

  • dcat displays the contents of a data set to a z/OS UNIX terminal.
  • dhead displays a specified number of lines from a data set to a z/OS UNIX terminal.

Improvements

ZOAU v1.2.2 adds these capabilities and enhancements:

  • dgrep
    • A new -c option to count the number of matching lines.
  • dls
    • A new -V option to specify a volume for browsing.
    • A new -a option to list the data set members and member aliases.
  • mls
    • A new -H option to see or hide PDS member aliases.
  • mrm
    • A new -f option to delete PDS members that are in use.
  • parmwhence
    • Improves error message handling with incorrect member name input.

Python library

  • datasets.blockinfile()
    • Special shell characters are now properly escaped.
  • datasets.delete_members()
    • A new force argument is available to force the deletion of a dataset member that is in use.
  • datasets.listing()
    • A new name_only boolean argument is available to limit the returned object so that it only contains the names of matching data sets. This can improve performance if there are a large amount of matches. The detailed argument is removed because it is identical to the default behavior.
  • datasets.search()
    • A new count_lines argument is available to display the number of lines matched in the dataset.
  • ZOAUResponse.from_dict()
    • This is now a class method instead of a static method to improve code readability and Python conformance.

Bug fixes

ZOAU v1.2.2 includes the following fixes:

  • dls
    • Static system symbols used for indirect volume serial support are resolved.
  • jsub
    • Now displays an error message when the user tries to submit a directory, PDS, or PSDE.
  • mmv
    • An error is fixed that prevented renaming when a volume couldn't be mounted.
  • mvscmdauth
    • A message truncation issue when using the -d argument is fixed.
  • opercmd
    • The EMCS console created by opercmd now has MASTER authority. This allows opercmd to reply to WTOR messages issued by a different console.
    • Truncation of console command output is prevented in certain circumstances.
    • Error message text is improved.

Version 1.2.1

New commands

Use the new zinfo command to view z/OS system information from the z/OS UNIX terminal in human-readable or JSON formats. Learn more at zinfo.

Important notices

  • The utilities opercmd and jcan now require authorization before use. Users must obtain READ access to the MVS.MCSOPER.ZOAU facility in the OPERCMDS class. Running these commands without authorization results in an error message. Learn more at Installing and configuring ZOAU.
  • This version of ZOAU has been rebased on IBM Enterprise Python version 3.9. To use the Python language bindings with ZOAU, you must have version Python 3.9 or 3.10 installed.
  • The ZOAU license agreement is now located in the LICENSES directory.

Improvements

ZOAU v1.2.1 adds these capabilities and enhancements:

  • decho
    • Displays a new error message if passed a quoted data set name.
  • opercmd
    • Supports user-defined command timeout.
    • Allows user to influence console name to avoid console conflicts.

Bug fixes

ZOAU v1.2.1 fixes the following problems:

Core utilities

  • dgrep
    • Searching a data set for strings that contain single quotes (') now works correctly.
  • dls
    • A new error message is displayed for RC=12 condition.
    • Data sets with hyphens in the name are properly displayed.
  • dmod
    • Various constraints limiting input marker sizes are relaxed.
  • dtail
    • A file handle leak is fixed.
  • dwhence
    • A memory leak is fixed.
  • jls
    • Batch jobs that do not yet have an owner now display correctly.
  • mls
    • If the running user does not have a TSO user ID, the output now displays correctly.
  • pproc
    • The -a argument is now correctly honored.
    • Now strips trailing parenthesis from data set name.
  • opercmd
    • Now displays reply-ID and allows user response when a WTOR message is issued to the console.
    • Output header is now properly aligned regardless of system name length.
    • Julian date in header now displays correctly when the day in the year is less than 100.
  • zoautil.so
    • Memory leaks are fixed and string building code is improved.

Multiple utilities

  • Temporary HLQ prefix now gracefully handles the case when getlogin() returns NULL.
  • Help arguments for shell commands are more consistent.
  • Running commands without setting ZOAU LIBPATH first no longer results in 0C4 or 0C6 abends.

Python library

  • datasets.exists()
    • Is rewritten to reduce CPU consumption.
  • core.so
    • A rare abend is fixed.

Version 1.2.0

Important notices

Authorization required for jcan and opercmd

Starting with ZOAU v1.2.0.2, specific authorization is required to use jcan and opercmd. To learn more, see Configuring ZOAU.

Full reimplementation in C of ddls, jcan, jls, jsub, pjdd, opercmd, and pcon

The utilities ddls, jcan, jls, jsub, pjdd, opercmd, and pcon are fully re-implemented in C, which brings new benefits:

  • Significantly improves performance.
  • Removes dependency on SDSF by interacting directly with the subsystem.
  • Adds new features:
    • DSID (dataset id) to ddls and pjdd.
    • Providing JCL content from stdin or a UNIX System Services (USS) file to jsub.

Note: Some reimplemented utilities introduce options that are not compatible with previous versions. To learn more about these new options, run the utility with -h, or refer to Shell commands reference.

Protecting ZOAU for new APF authorized components

ZOAU v1.2.0 installs seven new programs with extended attributes enabled into the zoautil bin directory. These enabled attributes allow the programs to function as if loaded from an APF authorized library. To ensure use by authorized persons only, ZOAU utilities should be protected with adequate file-based permissions. To learn more, see Configuring ZOAU.

Return codes are standardized across utilities

ZOAU now features standardized return codes across utilities. To learn more about new or changed return codes, see Return codes.

Java API is removed

The ZOAU Java API, which was deprecated in v1.1.0, has been removed.

Improvements

ZOAU v1.2.0 adds these capabilities and enhancements:

  • dcp - Copy from a partitioned data set (PDS) to another PDS, or to a PDS target that does not yet exist. Learn more.
  • dsed, dmod, and decho - Write to a data set in shared mode (DISP=SHR).
  • dtouch - Create data sets in FBS or VBS format.
  • dunzip - Use the IMPORT option (-I) for cross-system unarchiving .
  • Enhanced argument parsing, code quality, debug/tracing info, and message printing.
  • Bug fixes and other improvements.