Chapter 3. Events

Events drive jobs in a JobScheduler cluster. This chapter presents the concepts and terms of events in JobScheduler.

JobScheduler responds to four kinds of events:

Time events are points of time that can be used to trigger the scheduling of jobs. Time events are defined by calendars. See 'Calendars' for detailed descriptions about calendars.
Prior job events are the starting and completion of other jobs. See 'Inter-job Dependencies' for more detail.
File events are changes in the files residing in accessible file systems, such as the arrival (creation) of a specific file.
User events are site specific occurrences such as a tape mount defined by the JobScheduler administrators for your system.

File events and user events are handled by an Event Server (eeventd)^1.. The JobScheduler comes with an eeventd that handles file events. A site can modify the eeventd to monitor any other site specific events and use them to drive jobs.

Since file events and user events are events external to the JobScheduler, they are also referred to as external events, whereas time events and job events are referred to as built-in events.

Event Status

The status of an event has three possible values:

active: The event is considered to have occurred. The dependency condition for jobs waiting on the event will evaluate to TRUE.

inactive: The event is considered to have not occurred. The dependency condition for jobs waiting on the event is considered FALSE.

invalid: This applies to external events only. The event is invalid and thus is ignored by the Event Server. This usually occurs due to a syntax error in the event statement. The dependency condition for jobs waiting on the event will evaluate to FALSE.

At any moment, the event is either active, inactive, or invalid.

Built-in Events

Time Events

Time events are generated according to calendars. A calendar consists of one or more time expressions that define a sequence of time events. Each time event is featured by a starting time and a duration in which the event status is active. A calendar is said to be active if one or more of the time events produced by the calendar is active.

Calendars are JobScheduler entities that can be created, modified, and deleted. A calendar has an owner and a name. The calendar owner is the user who created it. Only the owner can modify or delete the calendar. The JobScheduler cluster administrators can create system calendars. The owner of a system calendar is the virtual user SYS. A user can use his/her own calendars, and system calendars, as well as other users' calendars to trigger his/her job scheduling.

See 'Calendars' for further details about time events and calendars.

Prior Job Events

In a production system, the status changes of some jobs can trigger the scheduling of other jobs. The event that the status of a job has changed is a job event. JobScheduler allows you to submit a job so that the scheduling of this job is dependent on the status of some prior job(s).

Unlike time events, you do not need to define job events before you refer to them to specify an inter-job dependency. Four job event functions are provided to specify an inter-job dependency when you submit a job:

started(job): The condition is TRUE if the specified job has started running or has already finished.

done(job): The condition is TRUE if the specified job has finished successfully in the DONE state. A job is considered to have finished successfully if it terminates with exit code 0 (zero).

exit(job): The condition is TRUE if the specified job has terminated abnormally in the EXIT state. A job is considered to have terminated abnormally if it terminates with a non-zero exit code.

ended(job): The condition is TRUE if the specified job has finished.

The parameter job is either a jobID or a jobname. See 'Inter-job Dependencies' for examples of using the above functions when submitting a job.

External Events

External events allow your jobs to be triggered by conditions external to JobScheduler. This provides a lot of flexibility for you to integrate your site specific conditions with the scheduling of your production jobs.

Typical examples of external events include the arrival of a file, the mount of a device, the detection of an exception situation in the system, etc.

External events are detected by the External Event Daemon (eeventd), which resides on the same server host as the master scheduler daemon (mbatchd). The eeventd communicates with mbatchd using a well-defined protocol. The JobScheduler comes with an eeventd that detects file events. A site can easily modify the eeventd to integrate other events by adding event processing functions.

File Events

A file event condition is specified as:

file(file_condition_expression)

where the keyword file() tells the master scheduler (mbatchd) that this is a file condition so that the parameter file_condition_expression should be passed to the eeventd for processing. The file_condition_expression is a logical expression in terms of the following four file status functions:

arrival(file_loc): This function evaluates to TRUE when file specified by file_loc arrives. The arrival of a file refers to the transition from non-existence to existence of the file.

exist(file_loc): This function evaluates to TRUE if the file specified by file_loc exists. Note that this function is different from arrival() in that a transition from a non-existence to existence is not needed. As long as the file exists, the function always evaluates to TRUE.

size(file_loc): This function evaluates to the size of the file specified by file_loc in bytes. If the file does not exist, this function evaluates to 0.

age(file_loc): This function evaluates to the age of the file specified by file_loc since the last modification in minutes. If the file does not exist, this function evaluates to 0.

The file_loc in the above functions takes the following form:

[hostname:]absolute_directory/filename

where hostname is the name of the host on which the file can be accessed. Note that this host does not have to be the same host on which the job executes. If hostname is not specified, then the Event Server assumes that the file is accessible from any host.

Note
You must specify the absolute path name of the file being evaluated in the above expressions.

An example of a file event condition using the above file event functions is:

file(exist(/tmp/core) && size(/tmp/core)>10M)

A file event is automatically created when a user submits a job with a file event dependency condition. The event is automatically removed when there are no dependent jobs.

See 'File Event Dependencies' for examples of how to use file event conditions when submitting a job.

User Events

JobScheduler provides an open mechanism for sites to implement site specific events by adding more event processing functions into the External Event Daemon (eeventd). A user event condition is specified as:

event(event_spec)

where the keyword event() tells the master scheduler (mbatchd) that this is a user event so that the parameter event_spec should be passed to eeventd for processing. The site is responsible for writing the function that parses and processes the event_spec. See 'External Event Management' of the LSF Administrator's Guide for details of how to modify eeventd.

A user event can be used to detect arbitrary site specific environmental status that can trigger production jobs. For example, a 'diskisfull' event could be designed to detect the fact that a critical file system is full, and therefore, an exception handling job should be triggered to correct the situation. In this case, the user event condition might be specified as:

event(diskisfull)

This will create an event 'diskisfull' which is monitored by diskisfull event processing function in the eeventd.

See 'User Event Dependencies' for examples of associating user events with job submissions.

Viewing External Events

You can view all the external events monitored by eeventd using bevents command.

% bevents
EVENT               OWNER   STATUS   SOURCE    ATTRIBUTE      LAST_UPDATE
arrival(/data/file) user1   active    file       -       Oct 31 14:30:15 1996
size(/tmp/core)>10M user1   inactive  file       -       Oct 31 14:30:15 1996
diskisfull          user2   inactive  user      /usr     Oct 22 11:23:02 1996

Note
ATTRIBUTE is optional information that your user event function in the eeventd can pass to jobs triggered by the event. This is implemented using the environment variable LSB_EVENT_ATTRIB.

^1. The administrators must install and configure an Event Server that interacts between JobScheduler and the site specific devices you need to monitor. For more details, see 'External Event Management' in the LSF Administrator's Guide.

[Contents] [Prev] [Next] [End]

doc@platform.com