Python API jobs module

Description

• Representation of z/OS Job.

Bases: object

Defined in: zoautil_py.jobs

Attributes

• job_id (str) - Job ID.
• name (str) - Job Name.
• job_class (int) - Job class.
• asid (int) - The Address Space Identifier (ASID) is a unique descriptor for the job address space.
• priority (int) - Priority of job.
• queue_position (int) - Position of job on class queue or phase queue.
• owner (str, None) - Job Owner
• program_name (str, None) - Program name for the job's last completed step.
• return_code (str, None) - Last known return code of job.
• status (str, None) - Last known job status. Possible responses are as follows:
  • "AC": Job is active.
  • "ABEND": Job ended abnormally.
  • "CANCELED": Job was successfully canceled before completion.
  • "CC": Job completed normally.
  • None: Unknown.
• service_class (str, None) - WLM service class.
• creation_datetime (datetime, None) - Datetime object with the job's input start date and time.
• job_type (str, None) - The type of address space.
• purged (bool) - Set to True after the job is successfully purged. Exclusive to the ZOAU API.

Constructors

You can use the default constructor or an alternative constructor with the Job object.

Default constructor

The default constructor of the Job object supports building from string or the attribute internal datatype. Optional attributes default to None if they are not specified.

jobs.Job(job_id: str,
   name: str,
   job_class: str,
   asid: Union[str, int],
   priority: Union[str, int],
   queue_position: Union[str, int],
   owner: Union[str, None] = None,
   program_name: Union[str, None] = None,
   return_code: Union[str, None] = None,
   status: Union[str, None] = None,
   service_class: Union[str, None] = None,
   creation_datetime: Union[str, datetime, None] = None,
   job_type: Union[str, None] = None,
   purged: bool = False)

Alternative constructor (internal)

The alternative constructor allows the object to be constructed directly from the JSON data payload returned by a ZOAU C/Shell utility.

jobs.from_core_json(job_as_json: dict)

Methods

• Job.cancel(self, purge_job: bool = False, confirm_timeout: int = 0)
  • Description: Queues job for cancelation.
  • Parameters:
    • purge_job (bool) - Purges job after cancelation if True.
    • confirm_timeout (int) - Maximum time to wait for cancel confirmation. Disabled by default. If the cancelation cannot be confirmed within the given time, a JobCancelConfirmException is raised.
  • Returns: None.

• Job.purge(self, confirm_timeout: int = 0)
  • Description: Queues a job for purging.
  • Parameters:
    • confirm_timeout (int) - Maximum time to wait for cancel confirmation. Disabled by default. If the cancelation cannot be confirmed within the given time, a JobPurgeConfirmException is raised.
  • Returns: None.

• Job.refresh(self)
  • Description: Refreshes the status and rc of the job.
  • Parameters: None.
  • Returns: None.

• Job.wait(self,seconds_per_loop: float = 1)
  • Description: Waits until status of the job is no longer active (AC).
  • Parameters: None.
  • Returns: None.

• fetch_extended_fields(self)
  • Description: Fetches extended fields from the operating system to populate object attributes.
  • Parameters: None.
  • Returns: None.

Description

• Cancel (or purge) a z/OS Job.

Returns

• None

Raises

• JobCancelException - Error cancelling the job.

• JobPurgeConfirmException - Cannot confirm purge of given job.

• JobCancelConfirmException - Cannot confirm job cancelation.

Parameters

• job_id (str) - The Job ID to target.

• purge_job (bool) - False by default. When True, the job is queued to purge, and the function attempts to verify that the job was purged, up to confirm_timeout seconds.

• confirm_timeout (int) - Maximum amount of time to wait for the job to be purged from the system. Default is 0 seconds, which means that the function does not attempt to confirm that the operation was successful.

Other Parameters

• job_name (str) – Job name to specify (needed for some systems).

Description

• Check if a job exists on the system.

Returns

• bool - True if the job exists on the system; False otherwise.

Parameters

• job_id (str) - ID of the job to search for.

Description

• Returns single Job object for the given job ID.

Returns

• Job object.

Return type

• Job

Parameters

• job_id (str) – Specify a particular job_id to list.

Other Parameters

• fetch_max_retries (int) - Maximum number of times to query the job for information. There is a 1 second delay per retry. The default maximum number of retries is 2.

Raises

• JobFetchException - An error occurred when trying to fetch the job.

Notes

• fetch_max_retries can be set to 0 to disable any wait time. If set to 0, consider using a try-except block for JobFetchException.

Description

• Get the extended attributes for a Job object, in place.

Returns

• None

Parameters

• job (Job) – Job object to update.

Description

• Lists jobs on the system.

Returns

• List of jobs that match the given filters.

Return type

• list[Job] - List of Job objects found, or an empty list (list[]) if no jobs are found.

Parameters

• job_id (str) ID of the jobs to list. Use with wildcards.

• job_owner (str) Owner of the jobs to list.

• job_name (str) Name of the job to list.

• include_extended (bool) False by default. When True, includes the following fields in Job fetch:

  • program_name This field is not included by default because it can cause a significant delay for long lists.

Raises

• JobFetchException - An error occurred when trying to fetch jobs.

Description

• Lists jobs on the system.

Returns

• List of jobs that match the given filters, with only the requested attributes.

Return type

• dict - A dictionary containing a dictionary for each job found. The returned dictionary has the following form:

  {
  "<JOB ID>": {
      "<ATTRIBUTE NAME>": "VALUE",
      ...
  },
  ...
  }
  

Parameters

• job_id (str) ID of the jobs to list. Use with wildcards.
• job_owner (str) Owner of the jobs to list.
• job_name (str) Name of the job to list.
• included_fields (list[str]) List of field names to retrieve. Uses the ZOAU jls field names. Defaults to: ['owner', 'name', 'id', 'status', 'ccode'] Available Fields:
  • owner
  • name
  • id
  • status
  • ccode
  • jobclass
  • serviceclass
  • priority
  • asid
  • creationdate
  • creationtime
  • queueposition
  • programname. Note that including this field can significantly increase the execution time for long lists.
  • jobtype

Raises

• JobFetchException - An error occurred when trying to fetch jobs.

Description

• List DDs for a z/OS Job.

Parameters

• job_id (str) – Job ID to pull DDs from.

Other Parameters

• owner (str) – ISFOWNER parameter (needed for some systems).

• prefix (str) – ISFPREFIX parameter (needed for some systems).

• sysin (bool) – When True, the list includes SYSIN DDs.

Returns

• list[dict] - List of Data Definitions (DD) as dictionaries, or an empty list (list[]) if no DDs are present.
  • step_name (str)
  • dd_name (str)
  • format (str)
  • length (str)
  • recnum (str)
  • dsid (str)
  • procstep (str)

Raises

• DDQueryException To get more information on the error, read the exception's response.stderr_response string:
  • BGYSC3505E - If the job is not ready for DD querying yet.
  • BGYSC3506E - If the job is at a transmission phase.

Description

• Purge a z/OS Job.

Returns

• None

Raises

• JobPurgeException - Error purging the job.

• JobPurgeConfirmException - Cannot confirm purge of given job.

Parameters

• job_id (str) - The Job ID to target.

• confirm_timeout (int) - Maximum amount of time to wait for the job to be purged from the system. Default is 0 seconds, which means that the function does not attempt to confirm that the operation was successful.

Other Parameters

• job_name (str) – Job name to specify (needed for some systems).

Description

• Read output from one or more DDs for a z/OS Job.

Returns

• Content read from the job DD.

Return type

• str

Parameters

• job_id (str) – Job ID to pull DDs from.

• stepname (str) – Stepname to specify. Defaults to '*' to allow correctly setting the positional parameters for pjdd.

• dd_name (str) – Dataset to read from. Defaults to an empty string ("") to allow correctly setting the positional parameters for pjdd.

Other Parameters

• dataset_id (str, int) - Name or numerical ID for the DD to read. If provided, any other filters are ignored.

• owner (str) – ISFOWNER parameter (needed for some systems).

• prefix (str) – ISFPREFIX parameter (needed for some systems).

• procstep (str) – For jobs with multiple steps per DD.

Description

• Updates the status of the job.

Returns

• None - If job has been purged.

Parameters

• job (Job) - Job object to update. Must have been generated from a previous fetch() or fetch_multiple() call.

Description

• Submit a z/OS JCL Job.

Returns

• zoautil_py.types.Job – Job object representing the submitted dataset. To submit a job and get only the ID back, use submit_return_job_id().

Raises

• JobSubmitException – Job failed to submit.

Parameters

• source (str) - Fully qualified dataset name or path to the z/OS UNIX file to submit.

• is_unix (bool) - True if source refers to a z/OS UNIX file. False if it refers to a data set.

Other Parameters

• fetch_max_retries (int) - Maximum number of times to query the job for information. There is a 1 second delay per retry. The default maximum number of retries is 2.

• include_extended (bool) - Includes the program_name field in Job fetch. The default setting of False means that program_name is not included because it can cause a significant delay for long lists.

Description

• Submit a z/OS JCL Job.

Returns

• str - Job ID.

Raises

• JobSubmitException – Job failed to submit.

Parameters

• source (str) - Fully qualified dataset name or path to the z/OS UNIX file to submit.

• is_unix (bool) - True if source refers to a z/OS UNIX file. False if it refers to a data set.