What’s new and noteworthy

The following updates are available for IBM Z Open Automation Utilities (ZOAU). To view APAR/PTF and related support information, see Fix list for IBM Z Open Automation Utilities.


Version 1.2.5.10

Bug fixes

ZOAU 1.2.5.10 fixes the following problem:

  • dcp
    • dcp failed when a PDS or PDSE target dataset was already in use by another job that opened the dataset in a shared disposition. This has been fixed.

Version 1.2.5.9

Bug fixes

ZOAU 1.2.5.9 fixes the following problem:

  • jcan
    • If a user is not authorized to submit console commands and attempts to use jcan, an abend may occur. This has been fixed.

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 now support IBM Enterprise Python 3.11 with the IBM C/C++ for Open Enterprise Languages compiler.

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 data set 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 data set.
  • 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.1

Bug fixes

ZOAU v1.2.1.1 fixes the following problems:

  • configure.py
    • The script is properly tagged with ISO8859-1 encoding and has the execute bit set. It also supports an optional argument to a different Python installation.

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 Installing and 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 (data set 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 Installing and 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.

Version 1.1.1

Improvements

Python API

  • pip installation method: Ability to pip install without XLC requirement.
  • set PYTHONPATH environment method: Added Python APIs and prebuilt ZOAU Cpython binary under lib directory to be set by PYTHONPATH environment variable.
  • Other API improvements.

Shell

  • Eliminated most use of temporary USS files and improved clean up when allocation was inevitable.
  • Added TMPDIR environment variable to override the temporary USS files path (default: /tmp).
  • Added TMPHLQ environment variable to override the user’s high-level qualifier.
  • mvscmd - Added dsorg parameter, which allows the user to override the default dsorg.
  • dcp - Improved handling of in-use data sets.
  • dls - Improved listing of migrated data sets.
  • dsed - Added '#' as an alternative delimiter to '/'.
  • Enhanced argument parsing.

Optimizations

  • decho - Fully reimplemented in C for issuing direct I/O to data sets, which significantly improves performance. Also added the option for passing the content through stdin.

Version 1.1.0

Important notices

Java API is deprecated

The ZOAU Java API has been deprecated. Beginning with v1.1.0, feature enhancements in ZOAU will not be available through Java. The Java API might be removed in future releases.

Python API in v1.1.0 is not compatible with an earlier version

The Python API provided in v1.1.0, which is enhanced as described below, is not compatible with an earlier version of the ZOAU Python API. If you want your application that was previously written leveraging ZOAU Utilities v1.0.x Python API to work with a z/OS host with ZOAU v1.1.0 installed, you must modify the application to adopt the new interface.

New features

  • Enhanced Python API - The Python API now supports custom return types and improved error handling. Module names follow PEP8 standards. The Python API now ships as a pip installable package. For more information about installing the Python API package, see Configuring ZOAU.

  • New text manipulation utility - The dmod command allows multi-line insert, replace, and delete by using surrounding unique markers. For more information, see Modify text blocks in data sets.

  • Utility for Authorized Program Facility (APF) administration - ZOAU adds tools for managing the APF list. See Perform APF administration tasks for details.

  • New option for dls (list data set) command - The quiet mode that suppresses output is added. This allows the scripted use of dls to test for the existence of a data set.

  • Enhancements to dzip and dunzip - You can now back up and restore to a data set. Include and exclude patterns are now supported. With the new options, you can specify target volumes. SMS management and storage class are supported for both destination and temporary data sets.


Version 1.0.3

Important notices

ZOAU must be added to the LIBPATH environment variable.

In past releases, adding ZOAU to the LIBPATH environment variable was only necessary if you plan to use Python or Java APIs. Beginning in v1.0.3, you must add ZOAU to the LIBPATH environment variable for all APIs including Shell commands. For more information, see Configuring ZOAU.

The shared library provided in this release is upgraded to version 0x020000.

A new function free_response is provided, and the interfaces of all the provided functions are changed from the previous version 0x010000. For more information about using the shared library interface to create libraries in other languages, see Extending ZOAU to other languages.

New features

  • Enhancements for the dcp (data set copy) command - The binary and load module copy is now supported.
  • New option for dtouch (create data set) command - You can now specify a volume option when creating data sets.

Version 1.0.2

New features

  • Utilities to archive and restore data sets - You can now archive data sets to binary files and unarchive data sets from binary files. For the sample code, see Archive data sets and Restore data sets.
  • New option for the dtouch command - You can now specify directory blocks and secondary space allocation with the dtouch command. For more information, refer to the API specification.
  • Enhancement for the Jobs.submit Python function - The Jobs.submit Python function now times out if job submission fails.

Version 1.0.1

New features

  • Utilities for JCL submission and retrieval - You can use the new utilities to submit, cancel and purge JCL jobs as well as view active JCL jobs and retrieve JES output. For more information, see JES utilities functionality overview.
  • Utilities to execute operator commands and read console log - You can use the new utilties to execute operator commands and see the results immediately as well as retrieve sections of the console log. For more information, see Submit an operator command and Display the console log.
  • Utilities to search system concatenations - You can use the new utiilties to list, search, and find members in the PROCLIB, PARMLIB and LINKLIST system concatenations. For more information, see System concatenation utilities functionality overview.