ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/qthmctlt.htm

726 lines
21 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 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>Control Thread (QTHMCTLT) 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. -->
<!-- Created for V5R2 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- End Header Records -->
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
</head>
<body>
<a name="Top_Of_Page"></a>
<!-- Java sync-link -->
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
</script>
<h2>Control Thread (QTHMCTLT) API</h2>
<div class="box" style="width: 80%;">
<br>
&nbsp;&nbsp;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="55%">Receiver variable</td>
<td align="left" valign="top" width="15%">Output</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</td>
<td align="left" valign="top">Length of receiver variable</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Format of receiver information</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Job or thread identification information</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">5</td>
<td align="left" valign="top">Format of job or thread identification
information</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(8)</td>
</tr>
<tr>
<td align="center" valign="top">6</td>
<td align="left" valign="top">Action</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">7</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>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Control Thread (QTHMCTLT) API holds, releases, or ends the specified thread.</p>
<p>End thread cannot be specified for the initial thread of a job. Hold thread
or release thread cannot be specified for the initial thread of a system
job.</p>
<br>
<h3>Authorities and Locks</h3>
<dl>
<dt><em>Job Authority</em></dt>
<dd>If the action to be taken is hold thread or release thread, the caller of
the API must be running under a user profile that is the same as the job user
identity of the job containing the thread for which the specified action is to
be taken. Otherwise, the caller of the API must be running under a user profile
that has job control (*JOBCTL) special authority, or be authorized to the
Thread Control function of Operating System/400 through iSeries Navigator's
Application Administration support.
<p> If the action to be taken is end thread, the caller of the API must be
running under a user profile that has service (*SERVICE) special authority or
be authorized to the Thread Control function of Operating System/400 through
iSeries Navigator's Application Administration support.</p>
<p> The Change Function Usage Information (QSYCHFUI) API, with a function ID of
QIBM_SERVICE_THREAD, can be used to change the list of users that are allowed
to end, hold, or release a thread.</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>
</dl>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Receiver variable</strong></dt>
<dd>OUTPUT; CHAR(*)
<p>The receiver variable that receives the information requested. You can
specify the size of the area to be smaller than the format requested as long as
you specify the length parameter correctly. As a result, the API returns only
the data that the area can hold.</p>
</dd>
<dt><strong>Length of receiver variable</strong></dt>
<dd>INPUT; BINARY(4)
<p>The length of the receiver variable provided. The length of receiver
variable parameter may be specified up to the size of the receiver variable
specified in the user program. If the length of receiver variable parameter
specified is larger than the allocated size of the receiver variable specified
in the user program, the results are not predictable. The minimum length is 8
bytes.</p>
</dd>
<dt><strong>Format of receiver information</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the information returned in the receiver variable. The format
name is:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>CTLT0100</em></td>
<td align="left" valign="top">See <a href="#CTLT0100">CTLT0100 Format</a> for
details on the information returned.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Job or thread identification information</strong></dt>
<dd>INPUT; CHAR(*)
<p>The information that is used to identify the thread within a job for which
an action is to be taken. See <a href="#jobthreadiden">Format of job or thread
identification information</a> for details.</p>
</dd>
<dt><strong>Format of job or thread identification information</strong></dt>
<dd>INPUT; CHAR(8)
<p>The format of the job or thread identification information. The possible
format names are:</p>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>JIDF0100</em></td>
<td align="left" valign="top">See <a href="#JIDF0100">JIDF0100 Format</a> for
details on the job identification information.</td>
</tr>
<tr>
<td align="left" valign="top"><em>JIDF0200</em></td>
<td align="left" valign="top">See <a href="#JIDF0200">JIDF0200 Format</a> for
details on the job identification information.</td>
</tr>
</table>
<p><strong>Note:</strong> If the thread handle is available, Format JIDF0200
provides a faster method of accessing a thread that is not the current thread
than Format JIDF0100.</p>
</dd>
<dt><strong>Action</strong></dt>
<dd>INPUT; BINARY(4)
<p>The action to be taken against the thread. The following actions are
supported:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Hold thread</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Release thread</td>
</tr>
<tr>
<td align="left" valign="top"><em>3</em></td>
<td align="left" valign="top">End thread</td>
</tr>
</table>
<p> The end thread, hold thread, and release thread actions are asynchronous
operations. A portion of the action is done by the current thread, and the
remainder of the action is done by the target thread. When control is returned
to the current thread, the action may not have been performed in its entirety.
Since some processing must be performed in the target thread, the action could
be delayed for some period of time if higher priority threads in this or other
jobs prevent the target thread from running.</p>
<p> End thread cannot be specified for the initial thread of a job. Hold thread
or release thread cannot be specified for the initial thread of a system
job.</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="CTLT0100">CTLT0100 Format</a></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="center" valign="bottom">Dec</th>
<th align="center" 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%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Bytes returned</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Bytes available</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">UNSIGNED BINARY(4)</td>
<td align="left" valign="top">Hold count</td>
</tr>
</table>
<br>
<br>
<h3>Field Descriptions for CTLT0100 Format</h3>
<p><strong>Bytes available.</strong> The number of bytes of data available to
be returned. All available data is returned if enough space is provided.</p>
<p><strong>Bytes returned.</strong> The number of bytes of data returned.</p>
<p><strong>Hold count.</strong> The number of times the thread has been held
prior to performing the action. The hold count is the count of fully processed
hold operations currently in effect for the thread. The count is incremented by
one for every hold operation that is processed for the thread. It is
decremented by one for every release operation. If the count is greater than 0,
the thread was already held. Hold and release operations that have not
completed are not reflected in the count.</p>
<br>
<h3><a name="jobthreadiden">Format of job or thread identification
information</a></h3>
<p>The format of the information needed to identify the thread for which the
specified action will be taken.</p>
<br>
<h3><a name="JIDF0100">JIDF0100 Format</a></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="center" valign="bottom">Dec</th>
<th align="center" 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%">Job 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">User name</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Job number</td>
</tr>
<tr>
<td align="center" valign="top">26</td>
<td align="center" valign="top">1A</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Internal job identifier</td>
</tr>
<tr>
<td align="center" valign="top">42</td>
<td align="center" valign="top">2A</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Thread indicator</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Thread identifier</td>
</tr>
</table>
<br>
<br>
<h3><a name="JIDF0100fd">Field Descriptions for JIDF0100 Format</a></h3>
<p><strong>Internal job identifier.</strong> The internal identifier for the
job. The List Job (QUSLJOB) API returns this identifier. If you do not specify
*INT for the job name parameter, this parameter must contain blanks. With this
parameter, the system can locate the job more quickly than with a job name.</p>
<p><strong>Job name.</strong> A specific job name or one of the following
special values:</p>
<table cellpadding="5">
<!-- cols="10 90" -->
<tr>
<td align="left" valign="top"><em>*</em></td>
<td align="left" valign="top">The job in which this program is running. The job
number and user name must contain blanks.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INT</em></td>
<td align="left" valign="top">The internal job identifier locates the job. The
job number and user name must contain blanks.</td>
</tr>
</table>
<p><strong>Job number.</strong> A specific job number, or blanks when the job
name specified is a special value.</p>
<p><strong>Reserved.</strong> An unused field. This field must contain
hexadecimal zeros.</p>
<p><strong>Thread identifier.</strong> A value that uniquely identifies a
thread within a job. If the thread indicator is not 0, this field must contain
hexadecimal zeros.</p>
<p><strong>Thread indicator.</strong> A value that is used to specify the
thread within the job for which the action is to be taken. The following values
are supported:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">Action should be taken for the thread specified
in the thread identifier field.</td>
</tr>
<tr>
<td align="left" valign="top"><em>1</em></td>
<td align="left" valign="top">Action should be taken for the thread that this
program is running in currently. The combination of the internal job
identifier, job name, job number, and user name fields also must identify the
job containing the current thread.</td>
</tr>
<tr>
<td align="left" valign="top"><em>2</em></td>
<td align="left" valign="top">Action should be taken for the initial thread of
the identified job.</td>
</tr>
</table>
<p><strong>User name.</strong> A specific user profile name, or blanks when the
job name specified is a special value.</p>
<br>
<h3><a name="JIDF0200">JIDF0200 Format</a></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="center" valign="bottom">Dec</th>
<th align="center" 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%">Job 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">User name</td>
</tr>
<tr>
<td align="center" valign="top">20</td>
<td align="center" valign="top">14</td>
<td align="left" valign="top">CHAR(6)</td>
<td align="left" valign="top">Job number</td>
</tr>
<tr>
<td align="center" valign="top">26</td>
<td align="center" valign="top">1A</td>
<td align="left" valign="top">CHAR(16)</td>
<td align="left" valign="top">Internal job identifier</td>
</tr>
<tr>
<td align="center" valign="top">42</td>
<td align="center" valign="top">2A</td>
<td align="left" valign="top">CHAR(2)</td>
<td align="left" valign="top">Reserved</td>
</tr>
<tr>
<td align="center" valign="top">44</td>
<td align="center" valign="top">2C</td>
<td align="left" valign="top">UNSIGNED BINARY(4)</td>
<td align="left" valign="top">Thread handle</td>
</tr>
<tr>
<td align="center" valign="top">48</td>
<td align="center" valign="top">30</td>
<td align="left" valign="top">CHAR(8)</td>
<td align="left" valign="top">Thread identifier</td>
</tr>
</table>
<br>
<br>
<h3><a name="JIDF0200fd">Field Descriptions for JIDF0200 Format</a></h3>
<p><strong>Internal job identifier.</strong> The internal identifier for the
job. The List Job (QUSLJOB) API returns this identifier. If you do not specify
*INT for the job name parameter, this parameter must contain blanks. With this
parameter, the system can locate the job more quickly than with a job name.</p>
<p><strong>Job name.</strong> A specific job name or one of the following
special values:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td align="left" valign="top"><em>*</em></td>
<td align="left" valign="top">The job in which this program is running. The job
number and user name must contain blanks.</td>
</tr>
<tr>
<td align="left" valign="top"><em>*INT</em></td>
<td align="left" valign="top">The internal job identifier locates the job. The
job number and user name must contain blanks.</td>
</tr>
</table>
<p><strong>Job number.</strong> A specific job number, or blanks when the job
name specified is a special value.</p>
<p><strong>Reserved.</strong> An unused field. This field must contain
hexadecimal zeros.</p>
<p><strong>Thread handle.</strong> A value that is used to address a particular
thread within a job. While the thread identifier uniquely identifies the thread
within the job, the thread handle can imporve performance when referencing the
thread. A valid thread handle must be specified. The thread handle is returned
on several other interfaces.</p>
<p><strong>Thread identifier.</strong> A value that uniquely identifies a
thread within a job. A valid thread identifier must be specified.</p>
<p><strong>User name.</strong> A specific user profile name, or blanks when the
job name specified is a special value.</p>
<br>
<h3>Error Messages</h3>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top" nowrap>Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top" width="15%">CPF1071 E</td>
<td align="left" valign="top" width="85%">No authority to job
&amp;3/&amp;2/&amp;1.</td>
</tr>
<tr>
<td align="left" valign="top">CPF136A E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 not active.</td>
</tr>
<tr>
<td align="left" valign="top">CPF18BF E</td>
<td align="left" valign="top">Thread &amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF24B4 E</td>
<td align="left" valign="top">Severe error while addressing parameter
list.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF1 E</td>
<td align="left" valign="top">Error code parameter not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C19 E</td>
<td align="left" valign="top">Error occurred with receiver variable
specified.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C21 E</td>
<td align="left" valign="top">Format name &amp;1 is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C24 E</td>
<td align="left" valign="top">Length of the receiver variable is not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3B E</td>
<td align="left" valign="top">Value for parameter &amp;2 for API &amp;1 not
valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C3C E</td>
<td align="left" valign="top">Value for parameter &amp;1 not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C51 E</td>
<td align="left" valign="top">Internal job identifier not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C52 E</td>
<td align="left" valign="top">Internal job identifier no longer valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C53 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 not found.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C55 E</td>
<td align="left" valign="top">Job &amp;3/&amp;2/&amp;1 does not exist.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C58 E</td>
<td align="left" valign="top">Job name specified is not valid.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C59 E</td>
<td align="left" valign="top">Internal identifier is not blanks and job name is
not *INT.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3C90 E</td>
<td align="left" valign="top">Literal value cannot be changed.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB431 E</td>
<td align="left" valign="top">Ending the initial thread is not allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB438 E</td>
<td align="left" valign="top">Holding the initial thread of a system job is not
allowed.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB439 E</td>
<td align="left" valign="top">Releasing the initial thread of a system job is
not allowed.</td>
</tr>
</table>
<br>
<hr>
API introduced: V5R2
<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>