385 lines
13 KiB
HTML
385 lines
13 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>Set Timer (QOLTIMER) 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. -->
|
||
|
|
<!-- Print SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
||
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!--File Edited December 2001 -->
|
||
|
|
<!-- 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>Set Timer (QOLTIMER) API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 70%;">
|
||
|
|
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%">Return code</td>
|
||
|
|
<td align="left" valign="top" width="20%">Output</td>
|
||
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="LEFT" valign="TOP">Reason code</td>
|
||
|
|
<td align="LEFT" valign="TOP">Output</td>
|
||
|
|
<td align="LEFT" valign="TOP">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="LEFT" valign="TOP">Timer set</td>
|
||
|
|
<td align="LEFT" valign="TOP">Output</td>
|
||
|
|
<td align="LEFT" valign="TOP">Char(8)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="LEFT" valign="TOP">Timer to cancel</td>
|
||
|
|
<td align="LEFT" valign="TOP">Input</td>
|
||
|
|
<td align="LEFT" valign="TOP">Char(8)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">5</td>
|
||
|
|
<td align="LEFT" valign="TOP">Qualified queue name</td>
|
||
|
|
<td align="LEFT" valign="TOP">Input</td>
|
||
|
|
<td align="LEFT" valign="TOP">Char(20)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">6</td>
|
||
|
|
<td align="LEFT" valign="TOP">Operation</td>
|
||
|
|
<td align="LEFT" valign="TOP">Input</td>
|
||
|
|
<td align="LEFT" valign="TOP">Char(1)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">7</td>
|
||
|
|
<td align="LEFT" valign="TOP">Interval</td>
|
||
|
|
<td align="LEFT" valign="TOP">Input</td>
|
||
|
|
<td align="LEFT" valign="TOP">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">8</td>
|
||
|
|
<td align="LEFT" valign="TOP">Establish count</td>
|
||
|
|
<td align="LEFT" valign="TOP">Input</td>
|
||
|
|
<td align="LEFT" valign="TOP">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">9</td>
|
||
|
|
<td align="LEFT" valign="TOP">Key length</td>
|
||
|
|
<td align="LEFT" valign="TOP">Input</td>
|
||
|
|
<td align="LEFT" valign="TOP">Binary(4)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">10</td>
|
||
|
|
<td align="LEFT" valign="TOP">Key value</td>
|
||
|
|
<td align="LEFT" valign="TOP">Input</td>
|
||
|
|
<td align="LEFT" valign="TOP">Char(256)</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">11</td>
|
||
|
|
<td align="LEFT" valign="TOP">User data</td>
|
||
|
|
<td align="LEFT" valign="TOP">Input</td>
|
||
|
|
<td align="LEFT" valign="TOP">Char(60)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
Optional Parameter:<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<table width="100%">
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">12</td>
|
||
|
|
<td align="left" valign="top" width="50%">Queue type</td>
|
||
|
|
<td align="left" valign="top" width="20%">Input</td>
|
||
|
|
<td align="left" valign="top" width="20%">Char(1)</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
Threadsafe: No<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
|
||
|
|
<p>The Set Timer (QOLTIMER) API either sets or cancels a timer. Up to 128 timers, each uniquely identified by a name (timer handle), can be set in the job in which the application program is running.</p>
|
||
|
|
|
||
|
|
<p>When the QOLTIMER API is called to set a timer, a timer handle (timer set parameter) is returned to the application program. The timer handle, along with the user data supplied when the timer was set, is included in the timer-expired entry that is sent to the data queue or user queue when the specified amount of time for this timer has elapsed. The timer is then reestablished, if necessary.</p>
|
||
|
|
|
||
|
|
<p>For example, suppose a user-defined communications application program sets a timer with a five-second interval to be established two times. After five seconds, the timer-expired entry for this timer will be sent to the data queue or user queue specified when the timer was set. The timer will then be automatically reestablished, and five seconds later, another timer-expired entry for this timer will be sent to the data queue or user queue. See <a href="comm3.htm#HDRTMREXEN">Timer-Expired Entry</a> for the format of the timer-expired entry.</p>
|
||
|
|
|
||
|
|
<p>In addition to setting a timer, the application program can call the QOLTIMER API to cancel one or all timers currently set in the job in which the application program is running. User-defined communications support will implicitly cancel a timer in the following cases:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>After a timer has expired the specified number of times (establish count parameter)<br><br></li>
|
||
|
|
|
||
|
|
<li>When a job ends that had one or more timers set</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> User-defined communications support does not associate timers with links. If necessary, that association must be done by the application.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
|
||
|
|
<!-- Instead, use the commented out coding below to indicate NONE. -->
|
||
|
|
<h3>Authorities and Locks</h3>
|
||
|
|
|
||
|
|
<!-- Use this if there are no authorities and locks. -->
|
||
|
|
<p>None.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Return code</strong></dt>
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The recovery action to take. See <a href="#HDRTIMERRR">Return and Reason Codes</a>.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>Reason code</strong></dt>
|
||
|
|
<dd>OUTPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The error that occurred. See <a href="#HDRTIMERRR">Return and Reason Codes</a>.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>Timer set</strong></dt>
|
||
|
|
<dd>OUTPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The name of the timer (timer handle) that was set. TIMER001, TIMER002, ... , TIMER128 are the possible values.</p>
|
||
|
|
|
||
|
|
<p>The content of this parameter is only valid when setting a timer.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>Timer to cancel</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(8)
|
||
|
|
|
||
|
|
<p>The name of the timer (timer handle) to cancel. TIMER001, TIMER002, ... , TIMER128 may be used as values. The special value of *ALL (left-justified and padded on right with spaces) may be used to cancel all timers currently set in the job in which the user-defined communications application program is running.</p>
|
||
|
|
|
||
|
|
<p>The content of this parameter is only valid when canceling a timer.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>Qualified queue name</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(20)
|
||
|
|
|
||
|
|
<p>The name and library of the data queue or user queue where the timer-expired entry will be sent when the timer expires. The first 10 characters specify the name of the data queue or user queue and the second 10 characters specify the library in which the queue is located. Both entries are left-justified. The special values of *LIBL and *CURLIB may be used for the library name.</p>
|
||
|
|
|
||
|
|
<p>The content of this parameter is only valid when setting a timer.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>Operation</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(1)
|
||
|
|
|
||
|
|
<p>The timer operation to perform. The valid values are as follows:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>X'01'</em></td>
|
||
|
|
<td valign="top">Set a timer.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>X'02'</em></td>
|
||
|
|
<td valign="top">Cancel a timer.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Interval</strong></dt>
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The number of milliseconds for which to set this timer. Any value between 1,048 and 3,600,000 may be used.</p>
|
||
|
|
|
||
|
|
<p>The content of this parameter is only valid when setting a timer.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>Establish count</strong></dt>
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The number of times this timer will be established. Any value between 1 and 60 may be used. The special value of -1 may be used to always have this timer established after it expires.</p>
|
||
|
|
|
||
|
|
<p>The content of this parameter is only valid when setting a timer.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>Key length</strong></dt>
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>The key length when using a keyed data queue or user queue. Any value between 0 and 256 may be used, where 0 indicates the data queue or user queue is not keyed.</p>
|
||
|
|
|
||
|
|
<p>The content of this parameter is only valid when setting a timer.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>Key value</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(256)
|
||
|
|
|
||
|
|
<p>The key value when using a keyed data queue or user queue.</p>
|
||
|
|
|
||
|
|
<p>The content of this parameter is only valid when setting a timer.</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>User data</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(60)
|
||
|
|
|
||
|
|
<p>The user data that is to be included in the timer-expired entry when the timer expires.</p>
|
||
|
|
|
||
|
|
<p>The content of this parameter is only valid when setting a timer.</p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> This data is treated as character data only and should not contain pointers.</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Optional Parameter</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Queue type</strong></dt>
|
||
|
|
<dd>INPUT; CHAR(1)
|
||
|
|
|
||
|
|
<p>The type of queue you specified for the queue name parameter.</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>D</em></td>
|
||
|
|
<td valign="top">Data queue</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>U</em></td>
|
||
|
|
<td valign="top">User queue</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRTIMERRR">Return and Reason Codes</a></h3>
|
||
|
|
|
||
|
|
<table border width="80%">
|
||
|
|
<tr>
|
||
|
|
<th valign="top">Return/Reason Code</th>
|
||
|
|
<th valign="top">Meaning</th>
|
||
|
|
<th valign="top">Recovery</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">0/0</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Operation successful.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Continue processing.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">81/9999</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Internal system error detected. Escape message CPF91F0 will be sent to the application program when this return and reason code is received.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">See messages in the job log for further information. Report the problem using the ANZPRB command.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">82/1011</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Queue type not valid.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Correct the queue type parameter. Try the request again.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">83/1001</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Key length not valid.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Correct the key length parameter. Try the request again.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">83/1009</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Timer operation not valid.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Correct the operation parameter. Try the request again.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">83/1010</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Timer interval not valid.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Correct the interval parameter. Try the request again.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">83/1011</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Number of times to establish timer not valid.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Correct the establish count parameter. Try the request again.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">83/3400</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Timer not valid on cancel operation.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Correct the timer to cancel parameter. Try the request again.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">83/3401</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">All timers are currently set for the requested set operation.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Cancel a timer. Try the request again.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="TOP" width="20%">83/3402</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Timer not set on cancel operation.</td>
|
||
|
|
<td align="LEFT" valign="TOP" width="40%">Continue processing.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br><br>
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<table width="100%" cellpadding="3">
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Message ID</th>
|
||
|
|
<th align="left" valign="top">Error Message Text</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF3C90 E</td>
|
||
|
|
<td valign="top">Literal value cannot be changed.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF91F0 E</td>
|
||
|
|
<td valign="top">Internal system error.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
|
<td valign="top">Program or service program &1 in library &2 ended. Reason code &3.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V2R1
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center"><td valign="middle" align="center">
|
||
|
|
<a href="#Top_Of_Page">Top</a>
|
||
|
|
| <a href="comm.htm">Communications APIs</a>
|
||
|
|
| <a href="aplist.htm">APIs by category</a>
|
||
|
|
|
||
|
|
</td></tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|