537 lines
18 KiB
HTML
537 lines
18 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>_ILECALLX()--Call an ILE Procedure for i5/OS PASE</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 -->
|
|
<!-- Created by V2DCIJB on 23 Nov 1999 -->
|
|
<!--Edited by Kersten Jan 2002 -->
|
|
<!-- 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>_ILECALLX()--Call an ILE Procedure for i5/OS PASE</h2>
|
|
|
|
<br>
|
|
<div class="box" style="width: 70%;">
|
|
<br>
|
|
Syntax
|
|
|
|
<pre>
|
|
#include <as400_protos.h>
|
|
|
|
|
|
int _ILECALLX(const ILEpointer *target,
|
|
ILEarglist_base *ILEarglist,
|
|
const arg_type_t *signature,
|
|
result_type_t result_type,
|
|
int flags);
|
|
|
|
|
|
int _ILECALL(const ILEpointer *target,
|
|
ILEarglist_base *ILEarglist,
|
|
const arg_type_t *signature,
|
|
result_type_t result_type);
|
|
</pre>
|
|
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Library: Standard C Library (libc.a)<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p><strong>Note:</strong> These functions can only be used in an i5/OS PASE
|
|
program. See <a href="../rzalf/rzalfintro.htm">i5/OS PASE</a> for more
|
|
information.</p>
|
|
|
|
<p>The <strong>_ILECALLX()</strong> and <strong>_ILECALL()</strong> functions
|
|
call an ILE procedure from an i5/OS PASE program. They transfer control to an
|
|
ILE procedure specified by a 16-byte tagged ILE procedure pointer, passing
|
|
arguments and returning the function result.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong>target</strong></dt>
|
|
|
|
<dd>(Input) Pointer to a tagged procedure pointer that addresses the ILE
|
|
procedure to call. target must be a 16-byte aligned i5/OS PASE memory
|
|
address.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>ILEarglist</strong></dt>
|
|
|
|
<dd>(Input/Output) Pointer to a 16-byte aligned ILE argument list structure.
|
|
ILEarglist is the address of the structure that contains any argument values to
|
|
pass to the ILE procedure, as well as memory for a function result returned by
|
|
the ILE procedure. ILEarglist must be long enough to contain all arguments
|
|
required by the target ILE procedure to avoid unpredictable results.
|
|
|
|
<p>The base structure of an ILE argument list (including a function result
|
|
area) is specified by type ILEarglist_base. Any argument values for the ILE
|
|
procedure are stored in memory immediately following the ILEarglist_base type.
|
|
The specific format of the argument list is determined by the list of
|
|
arg_type_t values addressed by the signature argument. The alignment
|
|
requirements for each argument value in the ILE argument list depends on its
|
|
length:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="25 75" -->
|
|
<tr>
|
|
<th align="center">Argument Length</th>
|
|
<th align="center">Alignment</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center">1 byte</td>
|
|
<td align="center">any</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center">2 bytes</td>
|
|
<td align="center">2 bytes</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center">3-4 bytes</td>
|
|
<td align="center">4 bytes</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center">5-8 bytes</td>
|
|
<td align="center">8 bytes</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center">9 or more bytes</td>
|
|
<td align="center">16 bytes</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
|
|
<dt><strong>signature</strong></dt>
|
|
|
|
<dd>(Input) Pointer to a list of arg_type_t values that specify the sequence
|
|
and type of arguments passed to the ILE procedure. ILE procedures can accept a
|
|
maximum of 400 arguments. The actual number of arguments processed by the
|
|
_ILECALLX or _ILECALL function is determined by the number of entries in the
|
|
signature list, which is determined by the location of the first ARG_END value
|
|
in the list. The following values are supported in the signature list:<br>
|
|
<br>
|
|
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="25 75" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_END (0)</em></td>
|
|
<td align="left" valign="top">Specifies the end of the signature list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_INT8 (-1)</em></td>
|
|
<td align="left" valign="top">Signed 1-byte integer argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_UINT8 (-2)</em></td>
|
|
<td align="left" valign="top">Unsigned 1-byte integer argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_INT16 (-3)</em></td>
|
|
<td align="left" valign="top">Signed 2-byte integer argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_UINT16 (-4)</em></td>
|
|
<td align="left" valign="top">Unsigned 2-byte integer argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_INT32 (-5)</em></td>
|
|
<td align="left" valign="top">Signed 4-byte integer argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_UINT32 (-6)</em></td>
|
|
<td align="left" valign="top">Unsigned 4-byte integer argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_INT64 (-7)</em></td>
|
|
<td align="left" valign="top">Signed 8-byte integer argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>ARG_UINT64 (-8)</em></td>
|
|
<td align="left" valign="top">Unsigned 8-byte integer argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">ARG_FLOAT32 (-9)</td>
|
|
<td align="left" valign="top">4-byte floating-point argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>ARG_FLOAT64 (-10)</em></td>
|
|
<td align="left" valign="top">8-byte floating-point argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_MEMPTR (-11)</em></td>
|
|
<td align="left" valign="top">The argument is a field of type ILEpointer into
|
|
which the caller has stored an i5/OS PASE memory address (in member address).
|
|
_ILECALLX and _ILECALL convert the i5/OS PASE memory address to an equivalent
|
|
teraspace address, except that address zero is converted to a special value for
|
|
a null pointer. The converted result is passed as the argument value to the
|
|
target ILE procedure.
|
|
Both functions may update the ILEpointer value so it contains a tagged space pointer.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_SPCPTR (-12)</em></td>
|
|
<td align="left" valign="top">The argument is a field of type ILEpointer where
|
|
the i5/OS PASE program has stored a tagged space pointer (or an untagged or
|
|
null pointer).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><img src="delta.gif" alt="Start of change"><em>ARG_SPCPTRI (-16)</em></td>
|
|
<td align="left" valign="top">The argument is a field of type ILEpointer into which the caller has stored the i5/OS PASE memory address (in member address) of a tagged space pointer (or an untagged or null pointer) that is passed to the target ILE procedure.
|
|
The ILEpointer in the argument list may be overlayed with a copy of the space pointer.<img src="deltaend.gif" alt="End of change"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>ARG_OPENPTR (-13)</em></td>
|
|
<td align="left" valign="top">The argument is a field of type ILEpointer where
|
|
the i5/OS PASE program has stored a 16-byte pointer of any type (including
|
|
possibly an untagged or null pointer).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><img src="delta.gif" alt="Start of change"><em>ARG_OPENPTRI (-17)</em></td>
|
|
<td align="left" valign="top">The argument is a field of type ILEpointer into which the caller has stored the i5/OS PASE memory address (in member address) of a 16-byte pointer of any type (including possibly an untagged or null pointer) that is copied into the argument list (overlaying the original ILEpointer value) and passed as the argument to the target ILE procedure.<img src="deltaend.gif" alt="End of change"></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_MEMTS64 (-14)</em></td>
|
|
<td align="left" valign="top">The argument is a field of type ts64_t into which the caller has stored an i5/OS PASE memory address.
|
|
_ILECALLX and _ILECALL convert the i5/OS PASE memory address to an equivalent 64-bit teraspace pointer, except that null (address zero) is unchanged.
|
|
The converted result is passed as the argument value to the target ILE procedure.
|
|
The ts64_t value in the argument list may be overlayed with the converted address.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ARG_TS64PTR (-15)</em></td>
|
|
<td align="left" valign="top">The argument is a field of type ts64_t where
|
|
the i5/OS PASE program has stored a 64-bit teraspace address.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>Any positive number<br>
|
|
(1-32767)</em></td>
|
|
<td align="left" valign="top">The argument is an aggregate (structure or
|
|
union). The value in the signature list is the length, in bytes, of the
|
|
aggregate.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>result_type</strong></dt>
|
|
|
|
<dd>(Input) Specifies the type of function result returned by the ILE
|
|
procedure.
|
|
|
|
<p>The following values are supported:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="25 75" -->
|
|
<tr>
|
|
<td valign="top"><em>RESULT_VOID(0)</em> </td>
|
|
<td valign="top">No function result.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RESULT_INT8 (-1)</em></td>
|
|
<td align="left" valign="top">Signed 1-byte integer result, returned in field
|
|
result.s_int8.r_int8 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RESULT_UINT8 (-2)</em></td>
|
|
<td align="left" valign="top">Unsigned 1-byte integer result, returned in field
|
|
result.s_uint8.r_uint8 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RESULT_INT16 (-3)</em></td>
|
|
<td align="left" valign="top">Signed 2-byte integer result, returned in field
|
|
result.s_int16.r_int16 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RESULT_UINT16 (-4)</em></td>
|
|
<td align="left" valign="top">Unsigned 2-byte integer result, returned in field
|
|
result.s_uint16.r_uint16 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RESULT_INT32 (-5)</em></td>
|
|
<td align="left" valign="top">Signed 4-byte integer result, returned in field
|
|
result.s_int32.r_int32 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RESULT_UINT32 (-6)</em></td>
|
|
<td align="left" valign="top">Unsigned 4-byte integer result, returned in field
|
|
result.s_uint32.r_uint32 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RESULT_INT64 (-7)</em></td>
|
|
<td align="left" valign="top">Signed 8-byte integer result, returned in field
|
|
result.r_int64 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>RESULT_UINT64 (-8)</em></td>
|
|
<td align="left" valign="top">Unsigned 8-byte integer result, returned in field
|
|
result.r_uint64 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>RESULT_FLOAT64 (-10)</em></td>
|
|
<td align="left" valign="top">8-byte floating-point result, returned in field
|
|
result.r_float64 in the ILEarglist argument.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>Any positive number<br>
|
|
(1-32767)</em></td>
|
|
<td align="left" valign="top">The function result is an aggregate (structure or
|
|
union). result_type is the length, in bytes, of the aggregate. An aggregate
|
|
function result is returned in a buffer allocated by the caller and passed to
|
|
the target ILE procedure using a special field in the argument list. The caller
|
|
must provide a buffer large enough for the result returned by the target ILE
|
|
procedure to avoid unpredictable results. An i5/OS PASE program must set field
|
|
result.r_aggregate.addr in type ILEarglist_base to the i5/OS PASE memory
|
|
address of the result buffer before calling an ILE procedure that returns an
|
|
aggregate result. _ILECALLX and _ILECALL convert the i5/OS PASE memory address
|
|
to a teraspace address the same way they convert ARG_MEMPTR arguments.</td>
|
|
<td></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>flags</strong></dt>
|
|
|
|
<dd>(Input) Specifies options to control how the ILE procedure program is
|
|
called. The flags argument is a bitwise logical-or of one or more of the
|
|
following values:<br>
|
|
<br>
|
|
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="25 75" -->
|
|
<tr>
|
|
<td valign="top"><em>ILECALL_NOINTERRUPT<br>
|
|
(0x00000004)</em> </td>
|
|
<td valign="top">Specifies that i5/OS PASE signals will not interrupt the
|
|
called ILE procedure. Some system functions (such as select) can be interrupted
|
|
by signals. Normally either an ILE signal or an i5/OS PASE signal can
|
|
interrupt such an operation, but ILECALL_NOINTERRUPT delays i5/OS PASE signal
|
|
processing until control returns from the called ILE procedure. This option has
|
|
no effect on ILE signal handling.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br></dd>
|
|
</dl>
|
|
<br>
|
|
|
|
|
|
<h3>Authorities</h3>
|
|
|
|
<p><strong>_ILECALL</strong> and <strong>_ILECALLX</strong> require no
|
|
authority.</p>
|
|
|
|
<br>
|
|
<h3>Return Value</h3>
|
|
|
|
<p>Most errors from <strong>_ILECALLX</strong> and <strong>_ILECALL</strong>
|
|
are reported with i5/OS exception messages that are converted to i5/OS PASE
|
|
signals. See <a href="pase_signals.htm">i5/OS PASE Signal Handling</a> for
|
|
information about handling i5/OS exceptions.</p>
|
|
|
|
<p>If no i5/OS PASE signal is sent, one of these values is returned:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="25 75" -->
|
|
<tr>
|
|
<td valign="top"><em>ILECALL_NOERROR(0)</em> </td>
|
|
<td valign="top">The target ILE procedure was called and returned
|
|
normally.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ILECALL_INVALID_ARG (1)</em> </td>
|
|
<td align="left" valign="top">An invalid value was found in the signature
|
|
list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ILECALL_INVALID_RESULT (2)</em> </td>
|
|
<td align="left" valign="top">The result_type value is invalid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>ILECALL_INVALID_FLAGS (3)</em> </td>
|
|
<td align="left" valign="top">The flags value is invalid.</td>
|
|
</tr>
|
|
</table><br>
|
|
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Usage Notes</h3>
|
|
|
|
<ol>
|
|
<li><strong>_ILECALLX</strong>
|
|
and <strong>_ILECALL</strong> can only call ILE procedures in an i5/OS bound
|
|
program. If your i5/OS PASE program needs to call an i5/OS program object
|
|
(object type *PGM), you must use the <strong>_PGMCALL</strong> function or use
|
|
the <strong>systemCL</strong> function to run the CL CALL command.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Every module in a *PGM or *SRVPGM object containing a function directly
|
|
called by PASE (using <strong>_ILECALLX</strong> or <strong>_ILECALL</strong>)
|
|
must be Teraspace-safe. If any module in the program was created as
|
|
TERASPACE(*NO), then i5/OS PASE will not be able to call any procedure in that
|
|
program (even a procedure in a module created as TERASPACE(*YES)).<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><strong>_ILECALLX</strong> and <strong>_ILECALL</strong> do no character
|
|
encoding conversions, so the i5/OS PASE program may need to convert argument
|
|
and result character strings between ASCII and EBCDIC. i5/OS PASE runtime
|
|
function <strong>iconv</strong> can be used for character conversions.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>An i5/OS PASE program can pass tagged space pointer arguments to an ILE
|
|
procedure using either ARG_SPCPTR or ARG_OPENPTR unless the target ILE
|
|
procedure uses ARGOPT linkage, in which case ARG_SPCPTR must be used.
|
|
ARG_MEMPTR can be used for space pointer arguments regardless of what linkage
|
|
is used by the target ILE procedure.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>ILE procedure pointers address resources inside an ILE activation group.
|
|
The machine prohibits use of activation group resources from a process other
|
|
than the owner of the activation group. This means that the child process of a
|
|
<strong>fork</strong> cannot use ILE procedure pointers inherited from the
|
|
parent process. The child process can, however, use <strong>_ILELOADX</strong>
|
|
to load the bound program (creating a new activation in the child process) and
|
|
then use <strong>_ILESYMX</strong> to obtain ILE procedure pointers into the new
|
|
activation.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>See <a href="pase__setspp.htm">Set Space Pointer for i5/OS PASE</a>
|
|
(_SETSPP) for more information about tagged space pointers and sharing tagged
|
|
pointers between processes.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><strong>_ILECALL</strong> is
|
|
equivalent to <strong>_ILECALLX</strong> with the
|
|
<strong>ILECALL_NOINTERRUPT</strong> flag.<br>
|
|
<br>
|
|
</li>
|
|
</ol>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li> <a href="pase__pgmcall.htm">_PGMCALL()--Call an i5/OS Program for i5/OS PASE</a><br>
|
|
</li>
|
|
<li><a href="pase__ilesym.htm">_ILESYMX()--Find an Exported ILE Symbol for
|
|
i5/OS PASE</a>
|
|
</li>
|
|
<li><a href="pase__ileload.htm">_ILELOADX()--Load an ILE Bound Program for
|
|
i5/OS PASE</a>
|
|
</li>
|
|
<li><a href="pase_size_ilearglist.htm">size_ILEarglist()--Compute ILE Argument
|
|
List Size for i5/OS PASE</a>
|
|
</li>
|
|
<li><a href="pase_build_ilearglist.htm">build_ILEarglist()--Build an ILE
|
|
Argument List for i5/OS PASE</a>
|
|
</li>
|
|
<li><a href="pase__cvtspp.htm">_CVTSPP()--Convert Space Pointer for i5/OS
|
|
PASE</a></li>
|
|
<li><a href="pase__cvtts64.htm">_CVTTS64()--Convert Teraspace Address for i5/OS
|
|
PASE</a></li>
|
|
<li><a href="pase__getts64.htm">_GETTS64() and _GETTS64_SPP--Get Teraspace Address for i5/OS
|
|
PASE</a></li>
|
|
<li><a href="pase__getts64m.htm">_GETTS64M()--Get Multiple Teraspace Addresses for i5/OS
|
|
PASE</a></li>
|
|
<li><a href="pase__setspp.htm">_SETSPP() and _SETSPP_TS64()--Set Space Pointer for i5/OS
|
|
PASE</a></li>
|
|
<li><a href="pase__setsppm.htm">_SETSPPM()--Set Multiple Space Pointers for i5/OS
|
|
PASE</a></li>
|
|
<li> <a href="pase_systemcl.htm">systemCL()--Run a CL Command for i5/OS PASE</a></li>
|
|
</ul>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V4R5
|
|
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
|
"pase1.htm">i5/OS PASE APIs</a> | <a href="aplist.htm">APIs by category</a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
</body>
|
|
</html>
|
|
|