536 lines
15 KiB
HTML
536 lines
15 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
|
<title>Call Job Interrupt Program (QWCJBITP) API</title>
|
|
<!-- Begin Header Records -->
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
|
<!-- US Government Users Restricted Rights -->
|
|
<!-- Use, duplication or disclosure restricted by -->
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
|
<!-- End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<!-- Java sync-link -->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<a name="Top_Of_Page"></a>
|
|
|
|
|
|
<h2><img src="delta.gif" alt="Start of change">Call Job Interrupt Program (QWCJBITP) API</h2>
|
|
<div class="box" style="width: 80%;">
|
|
<br>
|
|
Required Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="50%">Input variable</td>
|
|
<td align="left" valign="top" width="20%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Input format name</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(8)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Error Code</td>
|
|
<td align="left" valign="top">I/O</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
|
|
<p>
|
|
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 <a href="#unotes">Usage Notes</a>.
|
|
</p>
|
|
|
|
<br>
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<dl>
|
|
|
|
<dt><em>Job Authority</em></dt>
|
|
<dd>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
The <strong>job user identity</strong> is the name of the user profile by
|
|
which a job is known to other jobs. It is described in more detail in the
|
|
<a href="../rzaks/rzaks1.htm">Work Management</a> topic.</p>
|
|
</dd>
|
|
|
|
<dt><em>Object Authority </em></dt>
|
|
<dd>
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
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
|
|
<a href="./xwcjbitp.htm">Call Job Interrupt Program Exit Program</a>
|
|
for the syntax of the user exit program.
|
|
</p>
|
|
|
|
<p>
|
|
Any programs that are called through this interface will not inherit authority from the source or target job.
|
|
</p>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
|
|
<dt><strong>Input variable</strong></dt>
|
|
<dd>INPUT; CHAR(*)
|
|
<p>
|
|
The variable that is used to specify the program and job details.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><strong>Input format name</strong></dt>
|
|
<dd>INPUT; CHAR(8)
|
|
<p>
|
|
The format name of the input variable. The possible format name is:
|
|
</p>
|
|
|
|
<dl>
|
|
<dt><em>JITP0100</em></dt>
|
|
<dd>Basic job and program details.</dd>
|
|
</dl>
|
|
|
|
<p>
|
|
See <a href="#fmt01">Format of Input Variable</a> for more information.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt><strong>Error code</strong></dt>
|
|
<dd>I/O; CHAR(*)
|
|
<p>
|
|
The structure in which to return error information. For the format of the
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.
|
|
</p>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<br>
|
|
<h3><a name="fmt01">Format of Input Variable</a></h3>
|
|
|
|
<p>
|
|
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 <a href="#FLDDESC1">Field Descriptions</a>.
|
|
</p>
|
|
<br>
|
|
<h3>JITP0100</h3>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="left" valign="bottom">Dec</th>
|
|
<th align="left" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">CHAR(10)</td>
|
|
<td align="left" valign="top" width="60%">Program name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="center" valign="top">A</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Program library</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="center" valign="top">14</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Target job name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="center" valign="top">1E</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Target job user</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">40</td>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="left" valign="top">CHAR(6)</td>
|
|
<td align="left" valign="top">Target job number</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">46</td>
|
|
<td align="center" valign="top">2E</td>
|
|
<td align="left" valign="top">CHAR(2)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">48</td>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Offset to program data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">52</td>
|
|
<td align="center" valign="top">34</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Length of program data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" rowspan="2" colspan="2"> </td>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Program data</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CHAR(*)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
<br>
|
|
<h3><a name="FLDDESC1">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Length of program data.</strong> 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.</p>
|
|
|
|
<p><strong>Offset to program data.</strong> 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.</p>
|
|
|
|
<p><strong>Program data.</strong> The data that is passed to the program.</p>
|
|
|
|
<p><strong>Program library.</strong> The name of the library containing the program to execute.</p>
|
|
|
|
<p><strong>Program name.</strong> The name of the program to execute.</p>
|
|
|
|
<p><strong>Reserved.</strong> An unused field. This field must be set to binary zeros.</p>
|
|
|
|
<p><strong>Target job name.</strong> The specific name of the job for the program to execute in.</p>
|
|
|
|
<p><strong>Target job number.</strong> The specific number of the job for the program to execute in.</p>
|
|
|
|
<p><strong>Target job user.</strong> The specific user name of the job for the program to execute in.</p>
|
|
|
|
<br>
|
|
<h3><a name="unotes">Usage Notes</a></h3>
|
|
|
|
|
|
<ol>
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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 <a href=
|
|
"../cl/addexitpgm.htm">Add Exit Program (ADDEXITPGM) command</a> or the <a
|
|
href="./qusaddep.htm">Add Exit Program (QUSADDEP, QusAddExitProgram) APIs</a>
|
|
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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The program should not be a long running program so as to limit the amount
|
|
of time that the target job is interrupted.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The program will run in the target job under the same user profile as the
|
|
caller of this API.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If the target job is in initiation or termination phase, the CPF180D
|
|
message will be returned by the API.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>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.
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>A successful return from the API does not guarantee that the exit program
|
|
will execute in the target job.</li>
|
|
</ol>
|
|
|
|
|
|
<br>
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top" width="15%">CPF1070 E</td>
|
|
<td valign="top" width="85%">Job &3/&2/&1 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF1343 E</td>
|
|
<td valign="top">Job &3/&2/&1 not valid job type for function.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF1344 E</td>
|
|
<td valign="top">Not authorized to control job &3/&2/&1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF136A E</td>
|
|
<td valign="top">Job &3/&2/&1 not active.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF180D E</td>
|
|
<td valign="top">Function &1 not allowed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF18CF E</td>
|
|
<td valign="top">Job &1/&2/&3 can not be interrupted.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF24B4 E</td>
|
|
<td valign="top">Severe error while addressing parameter list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C12 E</td>
|
|
<td valign="top">Length of data is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C21 E</td>
|
|
<td valign="top">Format name &1 is not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C36 E</td>
|
|
<td valign="top">Number of parameters, &1, entered for this API was not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C39 E</td>
|
|
<td valign="top">Value for reserved field not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C3C E</td>
|
|
<td valign="top">Value for parameter &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C54 E</td>
|
|
<td valign="top">Job &3/&2/&1 currently not available.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C80 E</td>
|
|
<td valign="top">An exit program was not called in a multithreaded job.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3CDE E</td>
|
|
<td valign="top">Exit program name &1 library &2 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3CF1 E</td>
|
|
<td valign="top">Error code parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3CF2 E</td>
|
|
<td valign="top">Error(s) occurred during running of &1 API.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9810 E</td>
|
|
<td valign="top">Library &1 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9811 E</td>
|
|
<td valign="top">Program &1 in library &2 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9820 E</td>
|
|
<td valign="top">Not authorited to use library &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9821 E</td>
|
|
<td valign="top">Not authorized to program &1 in library &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9872 E</td>
|
|
<td valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<img src="deltaend.gif" alt="End of change">
|
|
|
|
<hr>
|
|
API introduced: V5R4
|
|
<hr>
|
|
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> |
|
|
<a href="wm1.htm">Work Management APIs</a> | <a href="aplist.htm">APIs by
|
|
category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
</body>
|
|
</html>
|