Interrupt Job Exit - Invoking a Program in Another Job

In last week's blog on QTEMP, I mentioned at the very end that I'd write about the interrupt job exit program this week.

Introduced in the 5.4 release, the interrupt job capability allows a program to be run within a specified job. A user wanting to run a program in a different job prior to 5.4 was essentially limited to using the submit job command to start a new job to run the program; however, sometimes there was a need to run a program in a job that had already been started. The interrupt job support enabled this capability.

There are two major components to this function:

• The ability to control whether the function is allowed
• The programmatic interfaces to request and execute the program in the target job

The Allow jobs to be interrupted (QALWJOBITP) system value is the systemwide control for whether you can interrupt another job to call a program. This system value has three options:

• 0 – jobs cannot be interrupted (the default)
• 1 – jobs can be interrupted but new jobs default to be uninterruptible
• 2 – jobs can be interrupted and new jobs default to be interruptible

This system value is the “big switch” -- setting it to 0 disables this capability systemwide. The system value must be set to either 1 or 2 in order to call a program in another job. This system value is further controlled since it is one of the system values that can be “locked” -- that is, set so it cannot be changed during normal system processing. The lock function of security system values page in the Information Center discusses this topic. If you need to change a system value that is locked in this manner, you need to change the “Allow security-related system value changes” parameter in system service tools (SST).

If this system value is set to 1 or 2, controlling this function then goes down to the job level. The default interruptible attribute for new jobs is taken from the system value when the job is started; the Change Job Interrupt Status (QWCCJITP) API can be used to change the interruptible status of a given job. The change job interrupt status API retrieves and optionally modifies the interrupt status of the job in which it is run. If the job is modified to be interruptible, programs called by the interrupt job API will be able to run in this job.

Calling a program in another job has two parts -- the API called in a job to specify the target job and the program to be run, and the exit program in the target job to actually run the program.

The requesting job uses the Call Job Interrupt Program (QWCJBITP) API to specify the program and the job in which the program is to be invoked. The target job must be active and must not be a system job, a subsystem job, or a spool reader or writer job. This API will return with an error if the “Allow jobs to be interrupted” system value is set to 0. If the system value is set to 1 or 2, the actual interruptibility status of the target job determines whether the function is allowed.

The target job, if interruptible, would then run the specified program through the Call Job Interrupt Exit Program (exit point QIBM_QWC_JOBITPPGM) exit program. This exit point must be defined in the system registration information. The program runs in the initial thread of the target job and if that job has multiple threads, secondary threads will continue unaffected. In addition, the exit program will run under the user profile of the requesting job; that is, the user profile in the target job is swapped to the same user profile of the job that invoked the call job interrupt program API.

If any errors occur during the running of the program in the target job, it is that job which needs to be looked at for those errors; for example, any messages logged in the job log.

As you can see, there are many elements to running a program in a target job and the capability to do so is not enabled by default. This feature is probably not something you need very often, but it can be useful when developing tools that help with specific systems management challenges, particularly when one job needs programmatic interfaces to manipulate or manage other jobs.

 

 

 

 

Comments

[Nathan Andelin]

That's a cool new feature, Dawn. Thanks for blogging about it.

[Tim Hawkins]

Dawn,

What are some example uses that you see for this capability?

[Dawn]

Tim,

Two common examples we use are:

- A job has been left running after the user has left for the day. You don’t need to end the job, but need to control it in order to run a cleanup program in it.
- To list or manipulate the contents of another job’s QTEMP library

At a higher level, you can think of this capability as way to:
- Control another job
- Target work for a specific job
- Manage running jobs
- Information retrieval

This capability is probably not something that is needed often.

Dawn