435 lines
12 KiB
HTML
435 lines
12 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>Register a User-Written Condition Handler (CEEHDLR) 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. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- ILE3A SCRIPT A converted by B2H R4.1 (346) (CMS) by NLJONES at -->
|
||
|
|
<!-- RCHVMX on 8 Mar 1999 at 11:01:18 -->
|
||
|
|
<!--Edited by Kersten Oct 2001 -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
|
||
|
|
<h2>Register a User-Written Condition Handler (CEEHDLR) API</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<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="30%">procedure</td>
|
||
|
|
<td align="left" valign="top" width="30%">Input</td>
|
||
|
|
<td align="left" valign="top" width="30%">HDLR_ENTRY</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">token</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">POINTER</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Omissible Parameter:<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
<table width="100%"><br>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top" width="10%">3</td>
|
||
|
|
<td align="left" valign="top" width="30%">fc</td>
|
||
|
|
<td align="left" valign="top" width="30%">Output</td>
|
||
|
|
<td align="left" valign="top" width="30%">FEEDBACK</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Service Program Name: QLEAWI<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe:<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>The Register a User-Written Condition Handler (CEEHDLR) API registers a
|
||
|
|
user-written condition handler for the current call stack entry.</p>
|
||
|
|
|
||
|
|
<h3>Required Parameter Group</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>procedure (input)</strong></dt>
|
||
|
|
|
||
|
|
<dd>An entry variable or constant for the procedure that is to be called to
|
||
|
|
process the conditions.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>token (input)</strong></dt>
|
||
|
|
|
||
|
|
<dd>A pointer passed to the user-written condition handler at the time the
|
||
|
|
procedure is called.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Omissible Parameter</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>fc (output)</strong></dt>
|
||
|
|
|
||
|
|
<dd>A 12-byte feedback code.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Feedback Codes and Conditions</h3>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CEE0000</td>
|
||
|
|
<td align="left" valign="top">The API completed successfully</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Severity: 00</td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CEE0256</td>
|
||
|
|
<td align="left" valign="top">Procedure already registered, registered
|
||
|
|
again</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Severity: 10</td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CEE0257</td>
|
||
|
|
<td align="left" valign="top">The procedure provided for &1 is not
|
||
|
|
valid</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Severity: 30</td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CEE9902</td>
|
||
|
|
<td align="left" valign="top">Unexpected user error occurred in &1</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Severity: 30</td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>
|
||
|
|
<p>CEEHDLR is implemented as a builtin and therefore cannot have its address
|
||
|
|
taken or be called through a procedure pointer.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
<p>A queue of handlers is maintained for each call stack entry. The handlers
|
||
|
|
are given control in LIFO order. That is, the handler most recently registered
|
||
|
|
is the first one used for the call stack entry from which the call to CEEHDLR
|
||
|
|
was made.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
<p>Any registered user-written condition handlers that were not unregistered by
|
||
|
|
the Unregister a User-Written Condition Handler (CEEHDLU) API, are unregistered
|
||
|
|
automatically by ILE upon removal of the associated call stack entry from the
|
||
|
|
call stack. For more information on unregistering user-written condition
|
||
|
|
handlers, see <a href="CEEHDLU.htm">Unregister a User-Written Condition Handler
|
||
|
|
(CEEHDLU) API</a>.</p>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>
|
||
|
|
<p>The message CEE0257 occurs if the pointer contained in <em>procedure</em> is
|
||
|
|
not a procedure pointer.</p>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3><a name="HDRUWCHI">ILE Condition Handler Interface</a></h3>
|
||
|
|
|
||
|
|
<p>Following is a description of the interface that the system uses to
|
||
|
|
communicate with ILE condition handlers.</p>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<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="30%">C_CTOK</td>
|
||
|
|
<td align="left" valign="top" width="30%">Input</td>
|
||
|
|
<td align="left" valign="top" width="30%">FEEDBACK</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">token</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">POINTER</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">result_code</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">INT4</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="center" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">new_condition</td>
|
||
|
|
<td align="left" valign="top">Output</td>
|
||
|
|
<td align="left" valign="top">FEEDBACK</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<!-- 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>C_CTOK (input)</strong></dt>
|
||
|
|
|
||
|
|
<dd>Identifies the current condition being processed.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>token (input)</strong></dt>
|
||
|
|
|
||
|
|
<dd>The token that was passed to the system with the call to CEEHDLR that
|
||
|
|
registered this condition handler.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>result_code (output)</strong></dt>
|
||
|
|
|
||
|
|
<dd>This field contains the instructions from the condition handler to the
|
||
|
|
system regarding the actions that the system should take.
|
||
|
|
|
||
|
|
<p>ILE condition handlers get control for all *ESCAPE, *STATUS, *NOTIFY, and
|
||
|
|
function check messages. Not all result code actions are valid for all types of
|
||
|
|
messages.</p>
|
||
|
|
|
||
|
|
<p>If the message is handled by the ILE condition handler, the result-code
|
||
|
|
action is not performed.</p>
|
||
|
|
|
||
|
|
<p>If a result code is returned that is not valid, the following message
|
||
|
|
occurs:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CEE0265</td>
|
||
|
|
<td align="left" valign="top">The result code received from a condition handler
|
||
|
|
is not valid</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Severity:30</td>
|
||
|
|
<td align="left" valign="top"> </td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>Valid result codes are:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Resume</strong></dt>
|
||
|
|
|
||
|
|
<dd>This result code can be used for all exception types.
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>10</em></td>
|
||
|
|
<td align="left" valign="top">Resume at the resume cursor, and handle the
|
||
|
|
condition, as follows:
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>Function Check (severity 4)</em></td>
|
||
|
|
<td align="left" valign="top">The message appears in the job log.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*ESCAPE (severity 2-4)</em></td>
|
||
|
|
<td align="left" valign="top">The message appears in the job log.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*STATUS (severity 1)</em></td>
|
||
|
|
<td align="left" valign="top">The message does not appear in the job log.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>*NOTIFY</em></td>
|
||
|
|
<td align="left" valign="top">The default reply is sent and the message appears
|
||
|
|
in the job log.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Percolate</strong></dt>
|
||
|
|
|
||
|
|
<dd>These result codes can be used for all exception types.
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>20</em></td>
|
||
|
|
<td align="left" valign="top">Percolate to the next condition handler.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>21</em></td>
|
||
|
|
<td align="left" valign="top">Percolate to the next call stack entry. This can
|
||
|
|
skip a high-level language condition handler for this call stack entry. Any
|
||
|
|
remaining user handlers in the queue for this call stack entry also can be
|
||
|
|
skipped.
|
||
|
|
|
||
|
|
<p>This handle cursor movement is in addition to any other handle cursor
|
||
|
|
movement done explicitly in the handler, for example by the CEEMRCR API.</p>
|
||
|
|
|
||
|
|
<p>The handle cursor is not moved past a call stack entry for a control
|
||
|
|
boundary. The default condition handling actions are applied to the message. <a
|
||
|
|
href="ile3a1TOC.htm#TBLCLCHMH2">Default Responses to Unhandled Exceptions</a>
|
||
|
|
summarizes the default condition handling actions.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Promote</strong></dt>
|
||
|
|
|
||
|
|
<dd>Only *ESCAPE and *STATUS messages may be promoted.
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>30</em></td>
|
||
|
|
<td align="left" valign="top">Promote to the next condition handler.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>31</em></td>
|
||
|
|
<td align="left" valign="top">Promote to the next call stack entry. This may
|
||
|
|
skip a high-level language condition handler for this call stack entry. Any
|
||
|
|
remaining user handlers in the queue for this call stack entry also can be
|
||
|
|
skipped.
|
||
|
|
|
||
|
|
<p>This handle cursor movement is in addition to any other handle cursor
|
||
|
|
movement done explicitly in the handler, for example by the CEEMRCR API.</p>
|
||
|
|
|
||
|
|
<p>The handle cursor is not moved past a call stack entry for a control
|
||
|
|
boundary. The default condition handling actions are applied to the new
|
||
|
|
message. <a href="ile3a1TOC.htm#TBLCLCHMH2">Default Responses to Unhandled
|
||
|
|
Exceptions</a> summarizes the default condition handling actions.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>32</em></td>
|
||
|
|
<td align="left" valign="top">Promote and restart condition handling with the
|
||
|
|
first condition handler for the call stack entry at which the handle cursor
|
||
|
|
currently points.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> It is not valid to promote a condition without
|
||
|
|
returning a new condition token. If the original condition is returned in <em>
|
||
|
|
new_condition</em>, the following message occurs:</p>
|
||
|
|
|
||
|
|
<table cellpadding="3">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CEE0262</td>
|
||
|
|
<td align="left" valign="top">The condition being promoted is not valid</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td>Severity:30</td>
|
||
|
|
<td> </td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>new_condition (output)</strong></dt>
|
||
|
|
|
||
|
|
<dd>The condition token representing the promoted condition. This field is used
|
||
|
|
only for <em>result_code</em> values of 30, 31, and 32 denoting <em>
|
||
|
|
promote</em> or <em>fix-up and resume</em>.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V2R3
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"ile1a1.htm">ILE CEE APIs</a> | <a href="aplist.htm">APIs by category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|