Need documentation of python API class zoautil_py.exceptions

[pjfarleyiii]

While performing challenges on the IBM zXplore student website, we have found that using the python API and the zoau jobs.submit function with "wait=True", the function generates the exception zoautil_py.exceptions.JobSubmitException. This can be caught in a python try/except, but the only information about the exception that can be printed without some detailed documentation is the class name, as in:

try: 
    job_response = jobs.submit(jcl_dataset, wait=True) 
except Exception as e: 
    print("Got Exception") 
    print("Exception classname={}, e={}".format(e.__class__, e)) 

Example result printed:

Got Exception
Exception classname=<class 'zoautil_py.exceptions.JobSubmitException'>, e= 

Regardless of the error, the job is actually submitted and executed successfully, but no intelligent handling of the exception is possible without documentation of the exception class(es).

Please fully document the python API exception classes.

Peter Farley
Brooklyn, NY

P.S. - No, I do not have S&S support, since I am encountering the error on the zXplore system.

[Edit] In a reply below it is shown that the exceptions as currently defined have no attributes other than the base class Exception has. It would be very helpful if the specific exceptions had attributes that describe the error in enough detail to analyze the problem and resolve it.

[EnsonoStevenPerva]

I have created a complete code sample for testing but with 2021/08/05 22:12:58 CUT V1.2.0 I am unable to reproduce the raised exception on my system. I haven't tried it on the Z Xplore system, so there is likely some discrepancy between the two hosts. Someone from IBM will likely be able to speak more to it. Here is the code I used to test:

jcl_dataset = '<fully qualified DSN for an IEFBR14 job>'

try:
    job_response = jobs.submit(jcl_dataset, wait=True)
    print(job_response)
except Exception as e:
    print("Got Exception")
    print("Exception classname={}, e={}".format(e.__class__, e))

exit()

When executed on my system, I receive a Job instance back as a response indicating successful submission and not an exception.

In digging into exceptions.py, it appears all the custom-defined exceptions are simply placeholders with nothing in them so there is likely nothing to be documented yet.

[rpagroot]

job_response is a zoautil_py.types.Job object.
Try:
print(job_response.rc, job_response.id,job_response.name,job_response.owner,job_response.status)

[rpagroot]

Hi Peter,

Think all ZOAU exceptions inherit from Exception. You can find file exceptions.py in a python subfolder /site-packages/zouautil_py :

`class ZOAUException(Exception):
pass

class DatasetVerificationError(Exception):
pass

class JobSubmitException(Exception):
pass

class JobPurgeException(Exception):
pass`

Is your jcl_dataset a file residing in a folder or a MVS (partitioned) dataset?

Regards,

Richard

[pjfarleyiii]

Hi rpagroot,

Thank you for the attributes of the Job object, that is helpful EXCEPT of course when the submit itself fails and you do not get one back.

In the example that fails on the zXplore site, the JCL is in a PDSE member on the z/OS system.

However, when I use jobs._submit and then print the __dict__ of the job response, I get this output:

Response classname=<class 'zoautil_py.types.ZOAUResponse'>, r=<zoautil_py.types.ZOAUResponse object at 0x50089C2C70>
Response dict={'rc': 0, 'stdout_response': 'JOB00499\n', 'stderr_response': '', 'command': 'jsub "ZXP.PUBLIC.JCL(CHKAUTO)"'}
Response.stdout=/JOB00499
/
Response.stderr=//

Peter

[MikeFultonDev]

I am curious what version of zoau you are using @pjfarleyiii . Can you issue: zoaversion from the command line and tell us the results?

[pjfarleyiii]

/z/zxxxxx > zoaversion
2021/12/22 23:02:11 CUT V1.1.1

This is on the IBM Z Xplore system hosted on Influitive.

[ddimatos]

Having done a fairly quick pass over the code I think the reason exception JobSubmitException is coming back empty is because the the exception is passing nothing along raise JobSubmitException(), similar I noticed that should you encounter the ZOAUException in job submit its defined as ZOAUException(response.stderr_response) and the issue here is that stderr is coming back from z/OS empty, it should be passing stdout.

For your particular issue @pjfarleyiii I believe the error results because the job is taking longer than the code is waiting, you can change that behavior to wait longer by using timeout jobs.submit('IMSTESTL.DIMATO.JCL(RACFCMD)', wait=True, timeout=30).

Optionally, if you really want to see the error since its getting lost in the exceptions implementation you can use the raw version of job submit like so (example of a good job submit):

>>> result=jobs._submit('IMSTESTL.DIMATO.JCL(RACFCMD)')
>>> print(result.stderr_response)

>>> print(result.stdout_response)
JOB00305

Example of a failure using raw submit:

>>> result=jobs._submit('IMSTESTL.DIMATO.JCL(RACFDD)')
>>> print(result.stderr_response)

>>> print(result.stdout_response)
submit 'IMSTESTL.DIMATO.JCL(RACFDD)'
MEMBER RACFDD NOT IN DATA SET IMSTESTL.DIMATO.JCL

The python docs will be getting much needed attention, they currently are very slim. I will note the issues I discovered here to be worked on in the near future.

[pjfarleyiii]

Thanks for the update. A small note however: the original issue was for jobs.submit(...) not for jobs._submit(...).

I will try using a larger timeout parameter for the jobs.submit(...) path and see if that resolves the issue at the zoau level currently available on the zXplore system. It may take a while for me to get back to that point of testing, as unfortunately I have had a complete loss of my USS files on the zXplore system and stupidly had no off-system backup of my work there, so I am in the painful process of re-creating a lot of work.

I will report back when I have re-created the situation.

Peter

[ddimatos]

Understood; In my comment I described ‘_submit’ as the ‘raw’ version , noting the difference. ‘_submit’ is not documented because it’s not intended to be a public interface indefinitely but using it now might help trouble shoot the error further, as it is now, the exception appears to not be sharing enough diagnostics.

I did have a typo in my snippet with the timeout as it should have read jobs.submit('IMSTESTL.DIMATO.JCL(RACFCMD)', wait=True, timeout=30), notice the removed underscore.

Hope when you have recreated that this helps.

[ddimatos]

I have captured this internally in JIRA NAZARE-8834 and it will be reviewed, thank you.