Call Job Interrupt Program (QWCJBITP) API
Required Parameter Group:
| 1 | Input variable | Input | Char(*) |
| 2 | Input format name | Input | Char(8) |
| 3 | Error Code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Yes
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 collection.
- 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
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(10) | Program name |
| 10 | A | CHAR(10) | Program library |
| 20 | 14 | CHAR(10) | Target job name |
| 30 | 1E | CHAR(10) | Target job user |
| 40 | 28 | CHAR(6) | Target job number |
| 46 | 2E | CHAR(2) | Reserved |
| 48 | 30 | BINARY(4) | Offset to program data |
| 52 | 34 | BINARY(4) | Length of program data |
| CHAR(*) | Program data | ||
| CHAR(*) | Reserved | ||
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
- 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.
- 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.
- 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. 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.
- The program should not be a long running program so as to limit the amount
of time that the target job is interrupted.
- The program will run in the target job under the same user profile as the
caller of this API.
- 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.
- If the target job is in initiation or termination phase, the CPF180D
message will be returned by the API.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- A successful return from the API does not guarantee that the exit program will execute in the target job.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF1070 E | Job &3/&2/&1 not found. |
| CPF1343 E | Job &3/&2/&1 not valid job type for function. |
| CPF1344 E | Not authorized to control job &3/&2/&1. |
| CPF136A E | Job &3/&2/&1 not active. |
| CPF180D E | Function &1 not allowed. |
| CPF18CF E | Job &1/&2/&3 can not be interrupted. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C12 E | Length of data is not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C39 E | Value for reserved field not valid. |
| CPF3C3C E | Value for parameter &1 not valid. |
| CPF3C54 E | Job &3/&2/&1 currently not available. |
| CPF3C80 E | An exit program was not called in a multithreaded job. |
| CPF3CDE E | Exit program name &1 library &2 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9810 E | Library &1 not found. |
| CPF9811 E | Program &1 in library &2 not found. |
| CPF9820 E | Not authorited to use library &1. |
| CPF9821 E | Not authorized to program &1 in library &2. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V5R4