317 lines
11 KiB
HTML
317 lines
11 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>Using Condition Management APIs</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 -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<h2>Using Condition Management APIs</h2>
|
||
|
|
|
||
|
|
<h3><a name="ile3a2">How Conditions Are Represented</a></h3>
|
||
|
|
|
||
|
|
A condition token is used to communicate information about a condition to ILE
|
||
|
|
CEE APIs. It is also used to communicate information to the condition manager,
|
||
|
|
to message services, and to procedures.
|
||
|
|
|
||
|
|
<p>The ILE <strong>condition token</strong> is a 12-byte compound data type
|
||
|
|
that contains structured fields to convey aspects of a condition. It conveys
|
||
|
|
aspects such as the severity, the associated message number, and information
|
||
|
|
that is specific to the given instance of the condition.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="ile3a3">Condition Token Layout</a></h3>
|
||
|
|
|
||
|
|
<p><a href="#FIGCECTOK1">ILE Condition Token
|
||
|
|
Layout</a> displays a map of the condition
|
||
|
|
token.</p>
|
||
|
|
|
||
|
|
<p><strong><a name="FIGCECTOK1">ILE Condition Token
|
||
|
|
Layout</a></strong><br>
|
||
|
|
<strong><br>
|
||
|
|
<img src="Rv3w220.gif" alt="ILE Condition Token Layout"><br>
|
||
|
|
</strong><br>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>Every condition token contains the components indicated in the figure
|
||
|
|
above.</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Condition_ID</strong></dt>
|
||
|
|
|
||
|
|
<dd>A 4-byte identifier that, with the Facility_ID, describes the condition
|
||
|
|
that the token communicates. ILE CEE APIs and most applications produce Case 1
|
||
|
|
conditions.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a name="SPTCASE">Case</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>A 2-bit field that defines the format of the Condition_ID portion of the
|
||
|
|
token. ILE conditions are always Case 1.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Severity</strong></dt>
|
||
|
|
|
||
|
|
<dd>A 3-bit binary integer that indicates the condition's severity. Severity
|
||
|
|
and MsgSev contain the same information. See <a href=
|
||
|
|
"ile3a1TOC.htm#TBLCLCHMH2">Table 1</a> for a list of ILE condition severities.
|
||
|
|
See <a href="ile3a1TOC.htm#TBLCHMAP1">Table 2</a> and <a href=
|
||
|
|
"ile3a1TOC.htm#TBLCHMAP2">Table 3</a> for the corresponding i5/OS<SUP>(TM)</SUP> message
|
||
|
|
severities.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a name="SPTCONTROL">Control</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>A 3-bit field containing flags that describe or control various aspects of
|
||
|
|
condition handling. The third bit specifies whether the Facility--ID has been
|
||
|
|
assigned by IBM.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a name="SPTFAC">Facility--ID</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>A 3-character alphanumeric string that identifies the facility that
|
||
|
|
generated the condition. Although all ILE languages use ILE message and
|
||
|
|
condition handling ILE CEE APIs, the actual run-time messages generated under
|
||
|
|
ILE still carry the HLL identification in the Facility--ID.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a name="SPTISI">I--S--Info</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>A 4-byte field that identifies the instance specific information associated
|
||
|
|
with a given instance of the condition. The instant specific information
|
||
|
|
contains the reference key to the instance of the message associated with the
|
||
|
|
condition token. If the message reference key is zero, there is no associated
|
||
|
|
message.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a name="SPTMSGSEV">MsgSev</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>A 2-byte binary integer that indicates the condition's severity. MsgSev and
|
||
|
|
Severity contain the same information. See <a href="ile3a1TOC.htm#TBLCLCHMH2">
|
||
|
|
Table 1</a> for a list of ILE condition severities. See <a href=
|
||
|
|
"ile3a1TOC.htm#TBLCHMAP1">Table 2</a> and <a href="ile3a1TOC.htm#TBLCHMAP2">
|
||
|
|
Table 3</a> for the corresponding i5/OS message severities.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong><a name="SPTMSGNO">MsgNo</a></strong></dt>
|
||
|
|
|
||
|
|
<dd>A 2-byte, hexadecimal number that identifies the message associated with
|
||
|
|
the condition. The combination of Facility_ID and MsgNo uniquely identifies a
|
||
|
|
condition.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<p><a href="ile3a1TOC.htm#TBLCLCHMH2">Table 1</a> contains default responses
|
||
|
|
that the condition manager takes when a handler attempts to percolate a
|
||
|
|
function check across a control boundary.</p>
|
||
|
|
|
||
|
|
<p><strong><a name="TBLCLCHMH2">Table 1. Default Responses to Unhandled
|
||
|
|
Exceptions</a></strong></p>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="bottom">Message Type</th>
|
||
|
|
<th align="left" valign="bottom">Severity of Condition</th>
|
||
|
|
<th align="left" valign="bottom">Condition Raised by the Signal a Condition
|
||
|
|
(CEESGL) Bindable API</th>
|
||
|
|
<th align="left" valign="bottom">Exception Originated from Any Other
|
||
|
|
Source</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Status</td>
|
||
|
|
<td align="left" valign="top">0 (Informative message)</td>
|
||
|
|
<td align="left" valign="top">Return the unhandled condition.</td>
|
||
|
|
<td align="left" valign="top">Resume without logging the message.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Status</td>
|
||
|
|
<td align="left" valign="top">1 (Warning)</td>
|
||
|
|
<td align="left" valign="top">Return the unhandled condition.</td>
|
||
|
|
<td align="left" valign="top">Resume without logging the message.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Notify</td>
|
||
|
|
<td align="left" valign="top">0 (Informative message)</td>
|
||
|
|
<td align="left" valign="top">Not applicable.</td>
|
||
|
|
<td align="left" valign="top">Log the notify message and send the default
|
||
|
|
reply.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Notify</td>
|
||
|
|
<td align="left" valign="top">1 (Warning)</td>
|
||
|
|
<td align="left" valign="top">Not applicable.</td>
|
||
|
|
<td align="left" valign="top">Log the notify message and send the default
|
||
|
|
reply.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Escape</td>
|
||
|
|
<td align="left" valign="top">2 (Error)</td>
|
||
|
|
<td align="left" valign="top">Return the unhandled condition.</td>
|
||
|
|
<td align="left" valign="top">Log the escape message and send a function check
|
||
|
|
message to the call stack entry of the current resume point.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Escape</td>
|
||
|
|
<td align="left" valign="top">3 (Severe error)</td>
|
||
|
|
<td align="left" valign="top">Return the unhandled condition.</td>
|
||
|
|
<td align="left" valign="top">Log the escape message and send a function check
|
||
|
|
message to the call stack entry of the current resume point.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Escape</td>
|
||
|
|
<td align="left" valign="top">4 (Critical ILE error)</td>
|
||
|
|
<td align="left" valign="top">Log the escape message and send a function check
|
||
|
|
message to the call stack entry of the current resume point.</td>
|
||
|
|
<td align="left" valign="top">Log the escape message and send a function check
|
||
|
|
message to the call stack entry of the current resume point.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">Function check</td>
|
||
|
|
<td align="left" valign="top">4 (Critical ILE error)</td>
|
||
|
|
<td align="left" valign="top">Not applicable</td>
|
||
|
|
<td align="left" valign="top">End the application, and send the CEE9901 message
|
||
|
|
to the caller of the control boundary.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> When the application is ended by an unhandled
|
||
|
|
function check, the activation group is deleted if the control boundary is the
|
||
|
|
oldest call stack entry in the activation group.</p>
|
||
|
|
|
||
|
|
<p><a href="ile3a1TOC.htm#TBLCHMAP1">Table 2</a> and <a href=
|
||
|
|
"ile3a1TOC.htm#TBLCHMAP2">Table 3</a> show how ILE condition severity maps to
|
||
|
|
i5/OS message severity.</p>
|
||
|
|
|
||
|
|
<p><strong><a name="TBLCHMAP1">Table 2. Mapping i5/OS *ESCAPE Message
|
||
|
|
Severities to ILE Condition Severities</a></strong></p>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="bottom">From i5/OS Message Severity</th>
|
||
|
|
<th align="left" valign="bottom">To ILE Condition Severity</th>
|
||
|
|
<th align="left" valign="bottom">To i5/OS Message Severity</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">0-29</td>
|
||
|
|
<td align="left" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">20</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">30-39</td>
|
||
|
|
<td align="left" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">30</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">40-99</td>
|
||
|
|
<td align="left" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">40</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong><a name="TBLCHMAP2">Table 3. Mapping i5/OS *STATUS and *NOTIFY
|
||
|
|
Message Severities to ILE Condition Severities</a></strong></p>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="bottom">From i5/OS Message Severity</th>
|
||
|
|
<th align="left" valign="bottom">To ILE Condition Severity</th>
|
||
|
|
<th align="left" valign="bottom">To i5/OS Message Severity</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">0</td>
|
||
|
|
<td align="left" valign="top">0</td>
|
||
|
|
<td align="left" valign="top">0</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">1-99</td>
|
||
|
|
<td align="left" valign="top">1</td>
|
||
|
|
<td align="left" valign="top">10</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3><a name="ile3a4">Condition Token Testing</a></h3>
|
||
|
|
|
||
|
|
<p>You can test a condition token that is returned from an ILE CEE API for the
|
||
|
|
following:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>Success</strong></dt>
|
||
|
|
|
||
|
|
<dd>To test for success, determine if the first 4 bytes are 0. If the first 4
|
||
|
|
bytes are 0, the remainder of the condition token is 0, indicating a successful
|
||
|
|
call was made to the ILE CEE API.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Equivalent Tokens</strong></dt>
|
||
|
|
|
||
|
|
<dd>To determine whether two condition tokens are equivalent (that is, the same
|
||
|
|
<em>type</em> of condition token, but not the same <em>instance</em> of the
|
||
|
|
condition token), compare the first 8 bytes of each condition token with one
|
||
|
|
another. These bytes are static and do not change depending upon the given
|
||
|
|
instance when the condition occurs.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>Equal Tokens</strong></dt>
|
||
|
|
|
||
|
|
<dd>To determine whether two condition tokens are equal (that is, they
|
||
|
|
represent the same <em>instance</em> of a condition), compare all 12 bytes of
|
||
|
|
each condition token with one another. The last 4 bytes can change from
|
||
|
|
instance to instance of a condition.</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<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>
|