Job binding agents

Job Binding Agents provide the essential mechanism for establishing inter-job relationships. These Agents also allow you to associate jobs with the availability of a particular resource. One example is licensed software in a given processor, such as a compiler.

What is a binding agent?

Agents are self-describing logic elements. They contain information about their attributes and serve as anchors to jobs that are "bound" by these Agents.

A Binding Agent does not represent any physical resource. It represents whatever your installation chooses it to represent.

Binding Agent Names

Binding Agents have a name that is chosen by your installation. They also have attributes that indicate certain characteristics. These characteristics, to be explained below, make certain Agents more suitable than others for particular types of work.

The names follow data set naming conventions. They can be two levels. For example:

is a valid Binding Agent name.

is also a valid Binding Agent name.

is not a valid name.

Binding agent attributes

The attributes have been designed to address a variety of situations. You probably have only some of the requirements that these Agents can address. As a result, if some of the characteristics do not appear to have any applicability in your installation, simply ignore that feature.

Some attributes are assigned when an Agent is defined. This allows tight operational control. Some other attributes are assigned at activation time.

Attributes at definition time

The first distinction with Binding Agents is two-fold:

• Is the Agent intended to be job-related?
• Is it intended to be PERMANENT?

While all the Agents are used by jobs for scheduling purposes, the above attributes refer to activation:

If an Agent is to be activated by a job and deactivated at the end of the job then the type of Binding Agent to use is a Job-related Binding Agent. A good example of this situation is an IMS region.

If an Agent is to be activated with a command and remain active until explicitly deactivated, then you want a PERMANENT Agent. An example could be an Agent that is used to direct jobs to a processor (in a multi-CPU MAS complex) that has a licensed software package that is not available anywhere else. In this case a number of jobs want to be bound to that Agent, but its activation is associated with a particular CPU. Hence, the Agent is activated with a command. It stays active regardless of the status of the processor. Jobs are automatically assigned to that processor and are selected for execution whenever the processor is available.

The second distinction concerns uniqueness:

• Do you want an Agent to be unique in your MAS complex?
• Do you want an Agent to be able to appear more than once in your MAS complex?

If a given service is to be provided only in a single processor, then your Agent should have the attribute of UNIQUE. This prevents an accidental activation of the same Agent in another processor. Note that the attributes UNIQUE and MULTIPLE refer to a MAS complex. Regardless of the attribute, an Agent can be active only once on each processor.

The third distinction allows you to control which Binding Agents can be used to initiate NJE transmission. At definition time you establish whether or not an Agent can be activated with the XMIT attribute (only with an operator command).

Attributes at activation time

At activation time a Binding Agent can be given one of the following three attributes:

• GLOBAL
• LOCAL
• XMIT

GLOBAL indicates that the Agent is active in all the systems in a MAS complex. An example of a situation that requires a GLOBAL Agent is when you use the Binding Agent mechanism to signal an event such as "overnight processing can begin." In this case, it applies to all the systems in the MAS complex.

LOCAL indicates that the Binding Agent is to direct jobs to a particular system. The availability of an IMS online region is a good example.

XMIT indicates that jobs associated with this Binding Agent are to be transmitted to the designated NJE node. This attribute is valid only if the Agent was defined with that capability, and can only be activated with a command.

Note: Transmitted jobs are re-analyzed on the receiving node.

Agent definition

Before any Binding Agents can be activated or deactivated, they must be defined to Job Binding Services. Agents can be defined either individually with a command or using Group Definition Services from a file. For a detailed explanation, refer to the Operating-Guide publication for the JBS DEFINE commands.

It should be noted that this is required only when the Control File is cold started, or new Agents are to be added. Once the Agents have been defined, they exist until the Control File is reformatted.

If you plan to reformat the Control File but intend to redefine the same Agents, you simply invoke the Group Create Services to have a file created with all the necessary definitions.

Binding Agents can be defined as having one of the following characteristics:

• PERMANENT: This indicates that the Agent is not directly associated with an executing job. This type of Agent, once it is activated, must be explicitly deactivated.
• MULTIPLE: This type of Agent is Job Related. It normally remains activated while a particular job (or job step) is executing. Once the job that activated the Agent terminates, the Agent is automatically deactivated. MULTIPLE means that in a MAS complex there can be more than one Agent active with the same name; however, there can be only one per machine.
• UNIQUE: If an Agent has the UNIQUE attribute, JBS schedules only one job that activates/deactivates the Agent in the shared spool complex at any given time. This ensures that jobs using an Agent with this attribute are serialized.
• XMIT: This capability applies to PERMANENT Binding Agents. It allows the initiation of transmission to another NJE node for jobs that are bound to that type of Agent. The activation of an Agent with the XMIT keyword can be done only with an operator command. This provides complete operational control of the facility.

In some circumstances, it might be important to know the source of the last request to activate or deactivate an Agent. To provide this information, you can also combine LOG with any of the above attributes:

LOG: This attribute requests recording in the system log for all ACTIVATE and DEACTIVATE requests by a job for this Agent.

A number of further definition attributes are provided for PERMANENT Agents. Each attribute is designed to deal with a particular situation, so if you do not recognize the purpose of an attribute, it is likely that you do not have that problem in your installation.

The following attributes apply to PERMANENT Agents only, and can be specified alone or together:

• WARN: This attribute causes a non-deletable message to be issued when the Agent is inactive and a job binding to that Agent enters the system. The message is issued on the system that has selected the job binding to the inactive Agent, but the Agent can be activated from any system in the complex. The system requiring the Agent detects that the Agent has been activated, and deletes the message.
• OPER: This attribute specifies that the Agent can be controlled only by operator commands. If a job includes activate or deactivate requests for an Agent with the OPER attribute, it is failed with a JCL error.

Finally, you can use the JBS REDEFINE command to change certain attributes for an existing Agent:

• LOG | NOLOG
• OPER | NOOPER
• WARN | NOWARN

Activating Binding Agents

There are four ways to activate Binding Agents, depending on the circumstances:

• JECL JES2 Control Statements.
• DD Subsystem Interface.
• Application Program Interface (API).
• Operator Commands.

The following sections provide a brief explanation of each method and the reasons for using it.

JECL JES2 control statements

Jobs that activate Binding Agents use the JECL statement mechanism. You can have up to 6 ACTIVATE JECL statements in a job.

The statements allow the activation of Agents either at job initiation or at the initiation of a named step.

For a comprehensive description of JBS JECL statements, refer to JECL-Reference-Guide.

DD subsystem interface

Started tasks can include JBS ACTIVATE and JBS DEACTIVATE JECL statements. The DD subsystem interface also provides started tasks with the ability to Activate and Deactivate Binding Agents.

Each DD SUBSYS request is the equivalent of a JECL statement for a job. The same rules apply.

For a detailed explanation of the DD subsystem interface, see Section 9- DD subsystem interface.

Application Program Interface (API)

Two different mechanism can be used with the API:

• A simple message (WTO) intercept with a predefined message ID and a pointer to the particular Binding Agent JECL reference. When the message is intercepted the specified Agent is activated or deactivated. This technique is normally used when you have control of the application, so you can issue the message.
• A message intercept where you specify a text pattern to be matched against messages generated by the address space where the job is running. When a message is generated in the particular address space that matches the text pattern, the specified Agent is activated or deactivated. This technique is normally used when you have no control over the application's messages, but you can uniquely identify parts of the message.

For a detailed description of the API, see Section 10- Application program interface.

Operator commands

Operator commands are provided to activate and deactivate Agents. If an Agent has been defined using the OPER attribute, it can be activated or deactivated only by using operator commands.

For a complete description of the JBS commands for activating and deactivating Agents, refer to the Operating-Guide.

Requesting BINDING

Jobs can request Binding in one of the following ways:

• The simplest method is using the JECL BIND statement. Jobs that want to use a Binding Agent for execution purposes include a JECL BIND statement in their JCL. Up to 24 BIND statements can appear in a job.
• In cases where transparency is desired, so that users do not have to take any action with their JCL, JAL can be used to insert BINDING statements for a particular job. Up to 24 BIND statements can be inserted by JAL.
• Again, started tasks can use the DD SUBSYS to request Binding. The same rules used for JECL statements apply.

• A list of Binding requests can be created using the pre-JAL exits (1-5 and 19). To use these Binding requests, your JAL must execute an action statement indicating that requests have been defined in exits:

  JBS BIND FROM_EXITS

  Complete details about how to use this facility can be found in theSystem Programming Guide: Exits manual.

A single JECL BIND statement allows for the inclusion of four Binding Agents. These four Agents represent alternatives, that is, they are OR conditions. Any one of them satisfies the Binding requirement.

Multiple Binding statements represent an AND condition, that is, each statement must be satisfied before the job can be scheduled. Between JECL statements and JAL, a maximum of 48 BIND statements can be associated with a job.