Call Job Interrupt Program Exit Program

The Call Job Interrupt Program exit program is indirectly called by the Call Job Interrupt Program (QWCJBITP) API. The QWCJBITP API is used to interrupt a specified target job to run a user-written program.

The user-written program is not called if any of the following conditions are true:

• The program has not been added to the registration facility for the QIBM_QWC_JOBITPPGM exit point.
• The target job is in initiation or termination phase.
• The target job is a system job, subsystem monitor job, spool reader job, or a spool writer job.
• The Allow jobs to be interrupted (QALWJOBITP) system value is set to '0'.
• The target job has been set to an uninterruptible status when becoming active or via the Change Job Interrupt Status (QWCCJITP) API.

Before the user-written exit program is run, the user profile of the initial thread of the target job is swapped to the user profile of the caller of the Call Job Interrupt Program (QWCJBITP) API. After the user-written exit program completes either due to normal exit conditions or due to an error, the user profile of the initial thread of the target job will be swapped back. In the case where the user profile of the initial thread of the target job can not be swapped back, the initial thread of the target job will continue to run under the user profile of the caller of the Call Job Interrupt Program (QWCJBITP) API.

This exit point supports any number of exit programs. (For information about adding an exit program to an exit point, see Registration Facility APIs.)

Notes:

1. While the program is running in the initial thread of the target job, other threads in the target job are still running. Care should be taken to ensure that the program to run in the initial thread is threadsafe. To help ensure that a program runs in a multithreaded job, the program should be registered as Threadsafe: *YES and Multithreaded job action: *RUN. See the Add Exit Program (ADDEXITPGM) command or the Add Exit Program (QUSADDEP, QusAddExitProgram) API for more information on properly adding threadsafe programs to the registration facility.
2. The program should not be a long running program so as to limit the amount of time that the target job is interrupted.
3. Programs cannot use the Set ASP Group (SETASPGRP) command to change the job's library name space. Programs called by the API must reside in *SYSBAS. The library containing the program does not need to be in the library list of the target job.
4. When the called program refers to objects being modified by the target job, the data may be in an indeterminate state. Access control mechanisms such as object locks are often scoped to the job or scoped to the thread. The program will have access to data that is being modified by the thread this program interrupts.
5. Programs called by this API are responsible for releasing any system and job resources they obtain. This includes such things as releasing any locks obtained by the program, freeing any storage allocated by the program, and closing any files opened by the program.
6. Programs called by this API should not change the environment of the target job or the environment of the system. Some examples of things not to do include changing the library list of the target job, issuing the Change Job (CHGJOB) command, or changing environment variables.
7. Typically anything that can already be done to the target job from a separate job should not be done by any program called from this API.
8. If the exit program encounters an error during processing, no error indicators are returned to the Call Job Interrupt Program (QWCJBITP) API or to the source job.
9. The user-written exit program will not inherit any authority from the programs that were interrupted and will gain no authority from the user profile governing thread execution before the interrupt occurs.

Authorities and Locks

A user must have all object (*ALLOBJ) and security administrator (*SECADM ) special authorities to add exit programs to the registration facility or to remove exit programs from the registration facility.

Required Parameter Group

Exit program data

INPUT; CHAR(*)

The data that is passed to the exit program. Pointer tags will not be preserved. If the length of exit program data is zero, this parameter will contain one byte that is set to binary zero.

Length of exit program data

INPUT; BINARY(4)

The length of the data sent to the exit program.

Security Related Considerations

• Programs added to the exit point could send a request message to *EXT. The request message will be executed as a command at a later time in a batch job or in an interactive job if and when a command entry screen is displayed.
  
  
• The exit program could create a new message queue and set it to have a break handling program. The exit program could also set an existing message queue to have a break handling program. Then from another job, messages could be sent to that message queue to cause the break handling program to run.
  
  
• The exit program could access QTEMP. It could add objects to QTEMP, rename objects, delete objects, and clear QTEMP. It could also move or copy objects out of QTEMP to another library. Some of these operations could cause problems for parts of the operating system or an application that is using an object in QTEMP.

[ Back to top | Work Management APIs | APIs by category ]