ZOAU Python exceptions

A Python exception is an error detected during execution. There are built-in exception types for errors caused by incorrect use of data types, bad indexing in lists or dictionaries, and many other situations. A Python exception is not always fatal.

ZOAU extends Python's Exception class to define errors that might be encountered in the ZOAU Python API library modules. Because the ZOAU Python API extends Python's Exception class, a ZOAU exception can be handled in the same way as a built-in exception.

Starting with ZOAU v1.3, the ZOAUException exception and its inherited exceptions are raised only when a proper ZOAU interaction encounters an error. All proper ZOAU Exceptions are inherited from the _ZOAUExtendableException(Exception) interface exception, which ensures that they follow the same internal design.

to To diagnose a ZOAUException, use the class attributes to gather information on the error that occurred.

ZOAU exception list

The following table lists the exceptions specific to ZOAU and describes the situations in which they are raised. Notice that the ZOAUException exception covers general errors encountered during ZOAU core calls, and that subsequent exceptions inherit from ZOAUException.

Exception	Description
`ZOAUException`	General errors encountered during ZOAU core calls.
`DatasetCreateException`	Errors while trying to create a dataset.
`DatasetFetchException`	Errors during dataset queries.
`DatasetFormatException`	Dataset content does not match expected formats.
`DatasetWriteException`	Errors while trying to write into a Dataset.
`DatasetVerificationError`	Failure when trying to verify the creation of the dataset after ZOAU call.
`GenerationDataGroupDeleteException`	Errors while trying to delete a GDG.
`GenerationDataGroupClearException`	Errors while trying to clear a GDG.
`GenerationDataGroupFetchException`	Errors during GDG queries.
`GenerationDataGroupViewInvalidName`	Invalid GDG name provided.
`GenerationDataGroupViewInvalidState`	The GDG view state is invalid.
`GenerationDataGroupCreateException`	Errors while creating a GDG.
`JobFetchException`	Errors during job fetch.
`JobSubmitException`	Job submission errors.
`JobCancelException`	Job cancelling errors.
`JobPurgeException`	Job purging errors.
`DDQueryException`	Errors during a Job's DD querying.
`MissingEnvironmentVariable`	Missing environment variables (during build only).
`MissingFunctionParameter`	Missing parameter (parameters with dependencies).

ZOAUException Schema

A ZOAU Exception always contains both a message string and a ZOAUResponse object. By default, the message string displays the information within the ZOAUResponse object.

The Python docstring of the exception interface is as follows:

Attributes
----------
message: str
  ZOAUResponse as string (Printed as output by `raise`)
response : ZOAUResponse
  Addressable ZOAUResponse object

Notes
-----
`ZOAUResponse` attributes
  - rc: str
    Return code
  - stdout_response: str
    Stdout
  - stderr_response: str
    Stderr
  - command: str
    Command performed during a ZOAU core call
  - response_format: str
    Response encoding

The ZOAUResponse object represents the payload used between the core (C and shell libraries) and the Python API.

Handling exceptions

Use the response attribute to handle exceptions. For instance, when a call is surrounded with a try-except call, the response object can be called from a caught exception and each of its attributes can be accessed. Retrieving and using response attributes in your code gives you more options for resolution when an error is detected. Example:

from zoautil_py import jobs
from zoautil_py.exceptions import JobFetchException

try:
    jobs.submit("path/to/job.jcl",is_unix=True)
except JobFetchException as fetch_exception:
    if fetch_exception.response.rc == 42:
        print("Known error, move along")