Call Job Interrupt Program (QWCJBITP) API

The Call Job Interrupt Program (QWCJBITP) API will execute an exit program in the initial thread of a specified job. For additional information on API and exit program restrictions, see Usage Notes.

Authorities and Locks

Job Authority

The caller of the API must be running under a user profile that is the same as the job user identity of the job that is being interrupted. Otherwise, the caller of the API must be running under a user profile that has job control (*JOBCTL) special authority.

The job user identity is the name of the user profile by which a job is known to other jobs. It is described in more detail in the Work Management topic.

Object Authority

The caller of the API must have *USE authority to any programs called through this interface and must have *EXECUTE authority to the library containing any such program.

Any user-defined exit programs that are called through this interface must be added to the registration facility for the QIBM_QWC_JOBITPPGM exit point. See Call Job Interrupt Program Exit Program for the syntax of the user exit program.

Any programs that are called through this interface will not inherit authority from the source or target job.

Required Parameter Group

Input variable

INPUT; CHAR(*)

The variable that is used to specify the program and job details.

Input format name

INPUT; CHAR(8)

The format name of the input variable. The possible format name is:

JITP0100

Basic job and program details.

See Format of Input Variable for more information.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Format of Input Variable

The following table describes the order and format of the data that is specified in the input variable. For detailed descriptions of the fields in this table, see Field Descriptions.

JITP0100

Field Descriptions

Length of program data. The length of the data sent to the program. The length may be zero if there is no data to pass to the program. The maximum length of program data is 2000 bytes.

Offset to program data. The length from the start of the format to the start of the program data. The offset may be zero if there is no data to pass to the program.

Program data. The data that is passed to the program.

Program library. The name of the library containing the program to execute.

Program name. The name of the program to execute.

Reserved. An unused field. This field must be set to binary zeros.

Target job name. The specific name of the job for the program to execute in.

Target job number. The specific number of the job for the program to execute in.

Target job user. The specific user name of the job for the program to execute in.

Usage Notes

1. This API will not wait for the program to be called in the target job. There could be a long delay between the time the API sends the request to run the program to the target job and the time the program is actually run.
   
   
2. If multiple programs are sent to run in the same target job, it is not guaranteed that the programs will run in the same order they were submitted in. Also, it is not guaranteed that a program will run to completion before another program is run.
   
   
3. 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) APIs for more information on properly adding threadsafe programs to the registration facility. Depending on how the user-defined exit program is added to the registration facility, the CPF3C80 message may be returned by the API or the CPI3C80 message may be left in the job log of the job that called the API.
   
   
4. The program should not be a long running program so as to limit the amount of time that the target job is interrupted.
   
   
5. The program will run in the target job under the same user profile as the caller of this API.
   
   
6. Any success or error conditions reported by the program in the target job will not be reported back to the QWCJBITP API. Checking the job log of the target job can help in determining the success or failure of the program run in the target job.
   
   
7. If the target job is in initiation or termination phase, the CPF180D message will be returned by the API.
   
   
8. If the target job is on a job queue or not active, the CPF136A will be returned by the API. If the target job is not available, the CPF3C54 will be returned by the API. Conditions where the target job is not available includes but is not limited to the following; the target job is in transition or the target job is being transferred.
   
   
9. Programs will be prohibited from running when the target job is a system job, subsystem monitor job, spool reader job, or a spool writer job. The API will issue the CPF1343 message.
   
   
10. 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.
    
    
11. 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.
    
    
12. 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.
    
    
13. 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.
    
    
14. Typically anything that can be done to the target job from a separate job should not be done by any program called from this API.
    
    
15. If the program needs more than 2000 bytes of data, the program could be given the name of a user space or data queue that is used to hold and send data to the program. Sockets could also be used to send data to the program. The program would have to be written to accept data from these sources. Pointer data cannot be passed to the program.
    
    
16. If the target job being interrupted is running an application that sends messages and that (or some other) application expects sequential messages, running a user-defined exit program will disrupt this interface by injecting messages. This can cause application failures, but only if the application expects certain message patterns.
    
    
17. The API will issue the CPF18CF message if the Allow jobs to be interrupted (QALWJOBITP) system value is set to disallow job interrupts; if the job interrupt status of the target job is set to uninterruptible; or if the job is currently running a function that can not be interrupted.
    
    
18. A successful return from the API does not guarantee that the exit program will execute in the target job.

Error Messages