Migrating to ZOAU v1.3 from v1.2.x or earlier

To support several new capabilities, ZOAU v1.3 includes changes that are incompatible with previous versions of ZOAU. For an overview of additions and changes introduced by ZOAU release 1.3, see What's new with ZOAU.

To migrate to ZOAU v1.3, review the following changes and perform all relevant actions.


Migration actions for all users

Starting with ZOAU v1.3, the opercmd utility argument -T <TIMEOUT> returns time in hundredths of a second (0.01 sec) rather than seconds. Ensure that this new unit of time produces expected results in any scripts or applications that use opercmd -T.


ZOAU v1.3 enables several utilities to support JSON output with a new schema. In previous versions of ZOAU, the utilities apfadm, dmod, dsed, and zinfo supported limited JSON output with a schema that is now obsolete, so any use of previous output must be updated. To learn more, see ZOAU JSON schema and examples.


ZOAU v1.3 does not document internal functions because they are not programming interfaces and can change at any time. Internal functions are denoted by a leading underscore, such as datasets._copy().

Migration actions for Python language pack users

ZOAU v1.3 brings changes and new functionality to the Python API. If you use the ZOAU Python language pack, review the following API changes and adjust your scripts and applications as needed. To learn more about new functionality, see Python APIs.

ZOAU v1.3 provides an updated approach to Python exception handling and a revised exception schema. To learn more, see exceptions.


Python API changes

The following changes affect the function of specific Python API modules.


Module definition changes

  • Module types.py is renamed to ztypes.py.

  • The contents of module volumes.py are moved to datasets.py. The volumes.py module is no longer available.


Changes to the datasets module

The datasets module includes changes to arguments, attributes, functions, and parameters. Migration-related changes are described as follows. To learn more about new dataset capabilities, see Python APIs - New capabilities in datasets.

For a full description of the datasets module, see Python API datasets module.


Changes to datasets classes and module attribute names are as follows:

  • The dataset class is relocated to zoautil_py.datasets.Dataset.

  • Attribute dsorg is renamed to organization.

  • Attribute recfm is renamed to record_format.

  • Attribute lrecl is renamed to record_length.


Changes to datasets module arguments, functions, and parameters are as follows:

  • The function datasets.hlq() is renamed to datasets.get_hlq().

  • The function datasets.listing() is renamed to list_datasets().

  • The function datasets.unzip() is renamed to datasets.dunzip().

  • The function datasets.zip() is renamed to datasets.dzip().

  • In the function datasets.tmp_name() the parameter hlq is renamed to high_level_qualifier.

  • In the functions datasets.blockinfile() and datasets.lineinfile(), the parameter ins_bef is renamed to insert_before, and the parameter ins_aft is renamed to insert_after.

  • In the function datasets.create() the parameter type is renamed to dataset_type.

  • In the function datasets.write() the parameter dataset is renamed to dataset_name.

  • The function Dataset.to_dict() is deprecated. Use vars(Dataset) or Dataset.__dict__ to get a dictionary containing all dataset attributes.

  • The dictionary key stepname is renamed to step_name in the output of jobs.list_dds().

  • The dictionary key dataset is renamed to dd_name in the output of jobs.list_dds().

  • The new function list_dataset_names() replaces the name_only parameter in the deprecated datasets.listing() function, and should be used instead. To learn more, see Python API datasets module.

Changes to the jobs module

The jobs module includes changes to arguments, attributes, functions, and parameters. Migration-related changes are described as follows. To learn more about new jobs capabilities, see Python APIs - New capabilities in jobs.

For a full description of the jobs module, see Python API jobs module.



Job class and module attribute names changes


Changes to job classes and module attribute names are as follows:

  • The job class is relocated from zoautil_py.types to the zoautil_py.jobs module.

  • The id attribute is renamed to job_id.

  • The rc attribute is renamed to return_code.

  • The new purged attribute is available to indicate purged jobs. This variable is exclusive to ZOAU's Python lib.

  • The function Job.to_dict() is deprecated. To get a dictionary containing all the dataset attribute, use vars(Job) or Job.__dict__ .



Changes to jobs module functions


Changes to jobs module arguments, functions, and parameters are as follows:

  • The wait parameter is removed.

  • The hfs parameter is renamed to is_unix.

  • The parameter name dataset is renamed to source in jobs.submit().

  • Several changes and new capabilities affect job fetch functionality. Learn more about the new capabilities at Python APIs - New capabilities in jobs. Changes include the following:

    • The jobs.get() function is renamed to jobs.fetch()

    • The jobs.listing() function is renamed to jobs.fetch_multiple().

  • Several changes and new capabilities affect job canceling and purging. To learn more about the new capabilities, see Python APIs - New capabilities in jobs. Changes include the following:

    • The jobs.cancel() function now includes a confirmation timeout that allows the user to wait until the job appears as cancelled on the system.

    • A new jobs.purge() function is available to purge canceled or finished jobs.

    • As a migration action, note that the updated jobs.cancel() function and the new jobs.purge() function always return None, whereas the return code from jcan was previously used. Details are described at Python APIs - New capabilities in jobs.