171 lines
6.2 KiB
HTML
171 lines
6.2 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>Error handling using ILE APIs</title>
|
||
|
|
<!-- 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 -->
|
||
|
|
<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>
|
||
|
|
<h2>Error handling using ILE APIs</h2>
|
||
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
||
|
|
for information pertaining to code examples.</p>
|
||
|
|
<p>Error handling with ILE APIs can be accomplished in two ways: use the error
|
||
|
|
code parameter or have exceptions signaled by the API to your application
|
||
|
|
program.</p>
|
||
|
|
<p>For information and the examples, see the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="#errcode">Error handling through the error code parameter</a></li>
|
||
|
|
|
||
|
|
<li><a href="#errordet">Example: Error determination</a></li>
|
||
|
|
|
||
|
|
<li><a href="#message">Example: Message data</a></li>
|
||
|
|
|
||
|
|
<li><a href="#signal">Error handling signaled by API</a></li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="errcode">Error handling through the error code parameter</a></h3>
|
||
|
|
|
||
|
|
<p>The error code parameter enables a user to have exceptions returned to the
|
||
|
|
program through the use of the parameter instead of having the exceptions
|
||
|
|
signaled. Some exceptions may be signaled to the caller regardless of the size
|
||
|
|
of the error code parameter. These exceptions are usually from errors that
|
||
|
|
occur with the error code parameter itself (that is, message CPF3CF1) or with
|
||
|
|
one of the other parameters (that is, message CPF9872). In the latter case,
|
||
|
|
message CPF9872 is always signaled and never returned through the error code
|
||
|
|
parameter because the API is unable to verify the error code parameter before
|
||
|
|
the exception occurs.</p>
|
||
|
|
|
||
|
|
<p>The caller of the API must initialize the error code parameter so that the
|
||
|
|
bytes provided field is set to the size, in bytes, of the error code parameter.
|
||
|
|
For example, the error_code_struct structure in the
|
||
|
|
<a href="ileGeneric.htm#HDRVLS">Example: Variable-length structure</a> sets the size at 116 bytes.
|
||
|
|
To initialize the
|
||
|
|
error code parameter, do the following:</p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
|
||
|
|
<li>Allocate storage for the error code parameter:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
error_code_struct error_code;
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Initialize the bytes provided field to the number of bytes that were
|
||
|
|
allocated for the parameter:
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
error_code.ec_fields.Bytes_Provided=sizeof(error_code_struct);
|
||
|
|
</pre>
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>If the bytes provided field is set to a value equal to or greater than 8,
|
||
|
|
the caller wants all exceptions returned through the error code parameter. The
|
||
|
|
API fills in all of the message information up to the size of the error code
|
||
|
|
parameter.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="errordet">Example: Error determination</a></h3>
|
||
|
|
|
||
|
|
<p>On the return from the call to the API, verify whether or not an error
|
||
|
|
occurred. If an error occurred, the bytes available field is set to something
|
||
|
|
other than zero. If the bytes available field is not zero, you can use the
|
||
|
|
message ID and the message data to determine what the program should do next.
|
||
|
|
To receive the message ID and data, you must provide enough storage on the
|
||
|
|
error code parameter for the information.</p>
|
||
|
|
|
||
|
|
<p>In the following example, the bytes available field is checked to determine
|
||
|
|
if an error occurred. In this case, if an error occurred, a message is printed,
|
||
|
|
which states the message ID and that the call to the API failed.</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
if (error_code.ec_fields.Bytes_Available != 0)
|
||
|
|
{
|
||
|
|
printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",
|
||
|
|
error_code.ec_fields.Exception_Id);
|
||
|
|
exit(1);
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="message">Example: Message data</a></h3>
|
||
|
|
|
||
|
|
<p>If your program needs to handle different exceptions in different ways, you
|
||
|
|
may need to make use of both the message data and the message ID. The message
|
||
|
|
data is returned in the same format as when you display the message description
|
||
|
|
on the system. For example, if message CPF3C1E is received, some of the message
|
||
|
|
data is printed. You can see message data that is associated with the message
|
||
|
|
by using the Display Message Description (DSPMSGD) command. The message data
|
||
|
|
for message CPF3C1E is defined as:</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>BIN(4)</strong></dt>
|
||
|
|
|
||
|
|
<dd><p>Parameter number</p></dd>
|
||
|
|
|
||
|
|
<dt><strong>CHAR(256)</strong></dt>
|
||
|
|
|
||
|
|
<dd><p>ILE entry point name</p></dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<p>To receive all of the message data for this exception, the exception data
|
||
|
|
field of the error code structure would need to be at least 260 bytes in size.
|
||
|
|
The following example uses only the number of bytes shown for the parameter
|
||
|
|
number of the exception in the message data; therefore, the exception data
|
||
|
|
field only needs to be 4 bytes.</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
int parm_number;
|
||
|
|
char *temp_ptr;
|
||
|
|
|
||
|
|
if (error_code.ec_fields.Bytes_Available != 0)
|
||
|
|
{
|
||
|
|
if (memcmp(error_code.ec_fields.Exception_Id,"CPF3C1E",7)==0)
|
||
|
|
{
|
||
|
|
printf("\nFAILED WITH CPF3C1E:");
|
||
|
|
temp_ptr=&(error_code.exception_data);
|
||
|
|
parm_number=*((int *)temp_ptr);
|
||
|
|
printf("\n Parameter number omitted: %d",parm_number);
|
||
|
|
}
|
||
|
|
else
|
||
|
|
{
|
||
|
|
printf("ATTEMPT TO REGISTER EXIT POINT FAILED WITH EXCEPTION: %.7s",
|
||
|
|
error_code.ec_fields.Exception_Id);
|
||
|
|
exit(1);
|
||
|
|
}
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="signal">Error handling signaled by API</a></h3>
|
||
|
|
|
||
|
|
<p>The second means of exception handling is by having all exceptions signaled
|
||
|
|
by the API to the calling program. To have all exceptions signaled by the API,
|
||
|
|
set the bytes provided field of the error code structure to zero. Refer to the
|
||
|
|
documentation of your specific programming language for information on
|
||
|
|
exception handling.</p>
|
||
|
|
<img src="v5r3end.gif" alt="End of change">
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
</body>
|
||
|
|
</html>
|