179 lines
6.4 KiB
HTML
179 lines
6.4 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>Example: Keyed interface 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>Example: Keyed interface using ILE APIs</h2>
|
||
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
||
|
|
for information pertaining to code examples.</p>
|
||
|
|
<p>This example shows how to set key values for a keyed interface.</p>
|
||
|
|
<p>For information and the examples, see the following:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="#parameter">Exit program attributes parameter</a></li>
|
||
|
|
|
||
|
|
<li><a href="#key">Exit program attribute keys</a></li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="parameter">Exit program attributes parameter</a></h3>
|
||
|
|
|
||
|
|
<p>The interface for the Add Exit Program API is a keyed interface. One of the
|
||
|
|
parameters for the Add Exit Program API is the exit program attributes
|
||
|
|
parameter. The exit program attributes are provided to the API by means of a
|
||
|
|
variable-length record. Typically, APIs that use a variable-length record
|
||
|
|
interface use either a 3- or 4-field record. The Add Exit Program API makes use
|
||
|
|
of a 4-field variable-length record <strong>(4)</strong>. The exit program attributes
|
||
|
|
parameter for the API is defined as follows:</p>
|
||
|
|
|
||
|
|
<p><strong>(3)</strong></p>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Type</th>
|
||
|
|
<th align="left" valign="top">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top">Number of variable-length
|
||
|
|
records</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p><strong>(4)</strong></p>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Type</th>
|
||
|
|
<th align="left" valign="top">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top">Length of variable-length record</td>
|
||
|
|
</tr><tr>
|
||
|
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top">Exit program attribute key</td>
|
||
|
|
</tr><tr>
|
||
|
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top">Length of data</td>
|
||
|
|
</tr><tr>
|
||
|
|
<td align="left" valign="top">CHAR(*)</td>
|
||
|
|
<td align="left" valign="top">Data</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>The number of variable-length records field <strong>(3)</strong> is the first 4 bytes,
|
||
|
|
and this field tells the API how many variable-length records have been
|
||
|
|
specified. The fields defined in <strong>(4)</strong> are repeated (contiguously)
|
||
|
|
immediately following the number of variable-length records for each record
|
||
|
|
that is sent to the API. The API gets to each variable-length record by using
|
||
|
|
the length of variable-length record field to get to the next record, up to and
|
||
|
|
including the number of records specified.</p>
|
||
|
|
|
||
|
|
<p>The variable-length record structures are defined in the qus.h header file
|
||
|
|
(this C-language header file is included by the qusrgfa1.h header file). The
|
||
|
|
4-field variable-length record is defined as:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
typedef _Packed struct Qus_Vlen_Rec_4 {
|
||
|
|
int Length_Vlen_Record;
|
||
|
|
int Control_Key;
|
||
|
|
int Length_Data;
|
||
|
|
/*char Data[];*/ /* Varying length field */
|
||
|
|
} Qus_Vlen_Rec_4_t;
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>Because the data field is a varying-length field, it needs to be defined in
|
||
|
|
a new structure.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3><a name="key">Exit program attribute keys</a></h3>
|
||
|
|
|
||
|
|
<p>The Add Exit Program API has several exit program attributes that can be
|
||
|
|
set. The following table shows the valid exit program attribute keys for the
|
||
|
|
key field area of the variable-length record.</p>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Key</th>
|
||
|
|
<th align="left" valign="top">Type</th>
|
||
|
|
<th align="left" valign="top">Field</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">1</td>
|
||
|
|
<td align="left" valign="top">CHAR(27)</td>
|
||
|
|
<td align="left" valign="top">Qualified message file name and
|
||
|
|
message identifier for exit program description</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">2</td>
|
||
|
|
<td align="left" valign="top">CHAR(50)</td>
|
||
|
|
<td align="left" valign="top">Exit program text description</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">3</td>
|
||
|
|
<td align="left" valign="top">BINARY(4)</td>
|
||
|
|
<td align="left" valign="top">Exit program data CCSID</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">4</td>
|
||
|
|
<td align="left" valign="top">CHAR(1)</td>
|
||
|
|
<td align="left" valign="top">Replace</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>This example specifies only two attribute keys (replace_rec and CCSID_rec
|
||
|
|
fields) and lets the remaining attribute keys be set by the API to the default
|
||
|
|
value. When working with variable-length structures, each variable-length
|
||
|
|
record must start on a 4-byte boundary alignment. (The 4-byte boundary
|
||
|
|
alignment requirement is only true for the registration facility APIs, not all
|
||
|
|
keyed APIs.) The following new structure becomes the exit program attributes
|
||
|
|
parameter on the call to the Add Exit Program API:</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
typedef struct {
|
||
|
|
int num_rec;
|
||
|
|
Qus_Vlen_Rec_4_t replace_rec;
|
||
|
|
char replace;
|
||
|
|
char Reserved[3];
|
||
|
|
Qus_Vlen_Rec_4_t CCSID_rec;
|
||
|
|
int CCSID;
|
||
|
|
} addep_attributes;
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<p>The num_rec field is set to the value of 2 because the example specifies two
|
||
|
|
variable-length records. The replace_rec field contains the length of the
|
||
|
|
variable-length record (value of 16), the key (value of 4), and the length of
|
||
|
|
the data (value of 1). The replace field contains the data for the replace key.
|
||
|
|
The Reserved field reserves 3 bytes to force the next record to start on a
|
||
|
|
4-byte boundary alignment. The 3 bytes that are reserved are counted as part of
|
||
|
|
the length for the replace variable-length record. The next record then follows
|
||
|
|
the first record.</p>
|
||
|
|
<img src="v5r3end.gif" alt="End of change">
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|