The Job class represents a running job instance. This class defines functions for interacting with the server including handling notification of job state transitions, child job submission, managing joblets and for receiving and sending events from resources and from clients. A job writer defines a subclass of the Job class and uses the methods available on the Job class for scheduling joblets and event processing.
The following example job schedules a single joblet to run on one resource:
class Simple(Job):
def job_started_event(self):
self.schedule(SimpleJoblet)
class SimpleJoblet(Joblet):
def joblet_started_event(self):
print "Hello from Joblet"
For this example, the class Simple is instantiated on the server when a job is run either by client tools or by the job scheduler. When a job transitions to the started state, the method job_started_event is invoked. Here the job_started_event invokes the base class method schedule() to create a single joblet and schedule the joblet to run on a resource. The SimpleJoblet class is instantiated and run on a resource.
Each job has a set of events that are invoked at the state transistions of a job. For example, on the starting state of a job, the job_started_event is always invoked. The following events that might be associated with jobs:
Following is a list of job events that are invoked upon job state transitions:
job_started_event
job_completed_event
job_cancelled_event
job_failed_event
job_paused_event
job_resumed_event
The following lists job events that are invoked upon child job state transitions:
child_job_started_event
child_job_completed_event
child_job_cancelled_event
child_job_failed_event
The following lists provisioner events that are invoked upon provisioner state transitions:
provisioner_completed_event
provisioner_cancelled_event
provisioner_failed_event
The following lists joblet events that are invoked upon joblet state transitions:
joblet_started_event
joblet_completed_event
joblet_failed_event
joblet_cancelled_event
joblet_retry_event
NOTE:In each of the events listed above, only job_started_event event is required; the remainder are optional.
A job writer can also handle and invoke custom events within a job. Events can come from clients, other jobs, and from joblets.
Example of defining an event handler named mycustom_event in a job:
class Simple(Job):
def job_started_event(self):
...
def mycustom_event(self,params):
dir = params["directory_to_list"]
self.schedule(MyJoblet,{ "dir" : dir }
For this example, the event retrieves a element from the params dictionary that is supplied to every custom event. The dictionary is optionally filled by the caller of the event.
Example of invoking the custom event named 'mycustom_event' from the zos client command line tool:
zos event mycustom_event directory_to_list="/tmp"
In this example, a message is sent from the client tool to the job running on the server.
Example of invoking the same custom event from a joblet:
class SimpleJoblet(Joblet):
def joblet_started_event(self): ...
self.sendEvent("mycustom_event", { ... } )
In the example above, a message is sent from the joblet running on a resource to the job running on the server. The running job has access to a factset which is the aggregation of the job instance factset (jobinstance.*), the deployed job factset (job.*, jobargs.*), the User factset (user.*), the Matrix factset (matrix.*) and any jobargs or policy facts supplied at the time the job is started.
Fact values are retrieved using the GridObjectInfo functions that the Job class inherits.
Example of retrieving the value of the job instance fact state.string from the jobinstance namespace:
class Simple(Job):
def job_started_event(self):
jobstate = self.getFact("jobinstance.state.string")
print "job state=%s" % (jobstate)
Cancelled end state.
See Constant Field Values
The job is cancelling and transistions to Cancelled.
See Constant Field Values
The job has completed the end state.
See Constant Field Values
The job is completing and transitions to: Completing.
See Constant Field Values
The job failed end state.
See Constant Field Values
The job is failing and transitions to Failed.
See Constant Field Values
The job is paused and transitions to: Running/Completing/Failing/Cancelling.
See Constant Field Values
The job is queued and transitions to Starting/Failing/Cancelling.
See Constant Field Values
The job is running and transistions to Paused/Completing/Failing/Cancelling.
See Constant Field Values
The job is starting and transitions to Running/Failing/Cancelling.
See Constant Field Values
The job is submitted and transitions to Queued/Failing.
See Constant Field Values
Indicates the job was cancelled by the admin.
See Constant Field Values
Indicates the job was cancelled by a job function and only applies if the job is in CANCELLED_STATE. The value is obtained from the jobinstance.terminationtype fact.
See Constant Field Values
Indicates the job was cancelled due to exceeding the job timeout value and only applies if the job is in CANCELLED_STATE. The value is obtained from the jobinstance.terminationtype fact.
See Constant Field Values
Indicates the job was cancelled by a client user and only applies if the job is in CANCELLED_STATE. The value is obtained from the jobinstance.terminationtype fact.
See Constant Field Values
Cancel this job instance.
Cancel this job instance with a reason.
Cancel all joblets for this job instance. Any joblets that are running or waiting are cancelled. If the job is set to autoterminate, then the job will terminate normally.
Change priority of this job with the specified string priority name.
child_job_cancelled_event is fired when a child job has transitioned to the cancelled state. A job writer can optionally implement this event to handle job cleanup.
child_job_completed_event is fired when a child job has transitioned to the completed state. A job writer can optionally implement this event to handle any job cleanup.
child_job_failed_event is fired when a child job has transitioned to the failed state. A job writer can optionally implement this event to handle any job cleanup.
child_job_started_event is fired when a child job has transitioned to the running state. A job writer can optionally implement this event to handle job state transitions.
Retrieves a list of child jobs submitted by this job. The elements are instance of job.
Retrieves a scheduled joblet. joblet may not be running on a resource. The joblet factset is available using the base GridObjectInfo methods. Retrieves the state facts to determine the state of the joblet.
Parameters: jobletNumber - number of joblet.
Returns: Joblet instance..
Raises: Exception - if joblet number refers to a joblet that has not yet been created.
Fail this job instance.
Fail this job instance with a reason.
Parameters: reason - Reason message to put in job log.
Retrieve job identification assigned by server on job submission. Returns None until job is submitted or scheduled.
job_cancelled_event is fired when a job is transitioning to the cancelled state. A job writer can optionally implement this event to handle job cleanup.
job_completed_event is fired when the job is transitioning to the completed state. A job writer can optionally implement this event to handle any job cleanup.
job_failed_event is fired when the job is transitioning to the failed state. A job writer can optionally implement this event to handle any job cleanup.
Fired when a job is paused by user or administrator. A job writer can optionally implement this event to handle state changes.
Fired when a previously paused job is resumed. A job writer can optionally implement this event to handle state changes.
job_started_event is the first event to be called when a job is started. A job writer is required to implement this event. This event is not fired until a job instance has transitioned out of the queued state. After this event has completed, the job instance is in the running state. Job setup or scheduling of joblets is typically implemented in this event.
joblet_cancelled_event is fired when the joblet has had execution cancelled. The joblet may or may not have been running. A job writer can optionally implement this event to handle a joblet state change. Not that if the job has ended, this event will not be called.
Parameters:
jobletNumber - Joblet number that has been cancelled (0 based).
resourceId - ID of resource where joblet was cancelled. Can be None if was not running.
reason - ID of resource where joblet ran to completion.
joblet_completed_event is fired when the joblet has completed execution on a resource. A job writer can optionally implement this event to handle a joblet state change. Not that if the job has ended, this event will not be called.
Parameters:
jobletNumber - Joblet number that has completed (0 based).
resourceId - ID of resource where joblet ran to completion.
joblet_failed_event is fired when the joblet has failed execution on a resource. A job writer can optionally implement this event to handle a joblet state change. Not that if the job has ended, this event will not be called.
Parameters:
jobletNumber - Joblet number that has failed.
resourceId - ID of resource where joblet ran.
errorMsg - Error message for the joblet error.
joblet_retry_event is fired when the joblet is transitioning back to a waiting state after a failed execution on a resource. This event will not fire if the maximum retry settings have been met and joblet transitions to the failed state. A job writer can optionally implement this event to handle a joblet state change.
Parameters:
jobletNumber - Joblet number that is to be retried.
resourceId - ID of resource where joblet ran.
errorMsg - Error message for the joblet error.
joblet_started_event is fired when the joblet has started execution on a resource. A job writer can optionally implement this event to handle a joblet state change.
Parameters:
jobletNumber - Joblet number that is to be retried.
Pause this job instance.
provisioner_cancelled_event is fired when the provision operation submitted by this job has been cancelled. A job writer can optionally implement this event to handle any job response to provision cancellation.
Parameters:
params - Dictionary containing "action", "resource" and "provisionjob" keys.
provisioner_completed_event is fired when the provision operation submitted by this job has completed. A job writer can optionally implement this event to handle any job response to provision completion.
The following example demonstrates a handler for the completion of suspending a resource
def provisioner_completed_event(params):
if params["action"] == "Suspend":
print "Successfully suspended resource '%s'" % (params["resource"])
Valid “action” strings include:
"Provision" "Clone" "Move" "Shutdown" "Restart" "Destroy" "Suspend" "Pause" "Resume" "Personalize" "Save Config" "Apply Config" "Create Template" "Migrate" "Checkpoint" "Restore" "Install Agent" "Make Standalone" "Check Status" "Delete" "Cancel Action"
The "resource" key contains the resource ID of the resource the action was acted on. The "provisionjob" key contains the job ID of the provisioning adapter job that was run.
Parameters:
params - Dictionary containing “action”, “resource” and “provisionjob” keys.
provisioner_failed_event is fired when the provision operation submitted by this job has failed. A job writer can optionally implement this event to handle any job response to provision failure.
Parameters:
params - Dictionary containing “action”, “resource” and “provisionjob” keys.
Resume this job instance if it is currently paused.
Run a new child job using supplied policy text. The supplied policy text is aggregated with the child job's policies.
Parameters:
job - Name of job to run.
params - Dictionary of job arguments.
constraint - Constraint object.
Raises:
Job instance of new child job.
Run a new child job using supplied resource Constraint. The supplied constraint is aggregated with the child job's resource constraints.
Parameters:
job - Name of job to run.
params - Dictionary of job arguments.
policy - Policy text.
Raises:
Job instance of new child job.
Run a new child job. for processing optionally not returning until the child job's job_started_event has completed.
Run a new child job using attributes defined in the supplied RunJobSpec.
Run a new child job.
Run a new child job.
Schedule a single joblet.
Schedule one or more joblets.
Schedule one or more joblets with additional joblet facts.
Schedule a set of joblets using the passed ParameterSpace as the basis for joblet assignment.
Schedule a set of joblets using the passed ParameterSpace as the basis for joblet assignment.
Schedule as many joblets as there are matching resources using the job's resource constraints. Each created joblet is preassigned to run on only the specified resource. <p> Note that joblets created with scheduleSweep() will take precedence over regularly scheduled joblets and will prevent regular joblets from running until all preassigned ones are complete. For this reason it is not normally recommended to mix schedule() and scheduleSweep in the same job.
Schedule as many joblets as there are matching resources using the job's resource constraints. Each created joblet is preassigned to run on only the specified resource. <p> Note that joblets created with scheduleSweep() will take precedence over regularly scheduled joblets and will prevent regular joblets from running until all preassigned ones are complete. For this reason it is not normally recommended to mix <code>schedule() and scheduleSweep in the same job.
Send an event to the parent job.
Send an event to all children of this parent job.
Send an event to another job. This is typically used to communicate to a child job.
Send an event to the client. This allows communication from the job running on the server to a client that is listening to job events using the Client Toolkit.
The following example sends an event to a client with a payload consisting of integer and a string:
self.sendClientEvent("client_event",{ "param1": 1024, "param2":"hello world" })
Send an event from server to joblet execution on a resource. Joblet must be running on a resource or this event is ignored. Typically used to communicate state changes to a long running joblet.
Control whether a job auto terminates when all child jobs and joblets are finished. Setting to false makes the job a daemon and will not cease until an error or terminate() is called. Default is true.
Control whether a job auto terminates when all child jobs and joblets are finished. Setting to a value > 0 causes the job to terminate (cancel) after the specified number of seconds. A value =0 is equivalent to 'true'. This may be called multiple times to reset the termination timer.
Start a job that is queued.
Terminate this job instance. Typically used when the fact <code>job.autoterminate</code> has been set to <code>False</code>.
Assert instance is correctly initialized
Retrieve list of timers if any need to be cancelled on job end.
Javadoc: Job