The Job class is a representation of 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.
For more information about the methods this class uses, see Section 7.3.1, Job State Transition Events.
The following example demonstrates a job that 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 the above 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. A resource is a physical or virtual machine on which the Orchestrator Agent is installed and running and where the Joblet code is executed.
Each job has a set of events that are invoked at the state transitions of a job. On the starting state of a job, the job_started_event is always invoked.
The 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 is a list of 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 is a list of provisioner events that are invoked upon provisioner state transitions:
provisioner_completed_event
provisioner_cancelled_event
provisioner_failed_event
The following is a list of joblet events that are invoked as the joblet state transitions:
joblet_started_event
joblet_completed_event
joblet_failed_event
joblet_cancelled_event
joblet_retry_event
NOTE:Only the job_started_event is required; other events 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.
The following example defines 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 } )
In 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.
The following example invokes the custom event named mycustom_event from the PlateSpin Orchestrate client command line tool:
zos event <jobid_of_running_job> mycustom_event directory_to_list="/tmp"
In this example, a message is sent from the client tool to the job running on the server.The following example invokes the same custom event from a joblet:
class SimpleJoblet(Joblet):
def joblet_started_event(self):
...
self.sendEvent("mycustom_event", {"directory_to_list":"/tmp"} )
In this example, 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.
The following example retrieves 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)
For further details about each of the events above, see Section B.1, Job Class.
The following example uses the joblet_started_event to determine the resource a Joblet is running on. If you implement the joblet_started_event job method, your job is notified when a Joblet has started execution:
1 class test(Job): 2 def job_started_event(self): 3 self.schedule(TestJoblet) 4 5 def joblet_started_event(self,jobletNum,resourceId): 6 print "joblet %d is running on %s" % (jobletNum, resourceId) 7 8 class TestJoblet(Joblet): 9 def joblet_started_event(self): 10 import time 11 time.sleep(10)
In lines 5 and 6, the joblet_started_event is notified when the instance of TestJoblet is executing on a resource.