265 lines
8.7 KiB
HTML
265 lines
8.7 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>_PGMCALL()--Call an i5/OS Program 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 02 -->
|
||
|
|
<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>_PGMCALL()--Call an i5/OS Program for i5/OS PASE</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 70%;">
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
Syntax
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <as400_protos.h>
|
||
|
|
|
||
|
|
int _PGMCALL(const ILEpointer *<em>target</em>,
|
||
|
|
void **<em>argv</em>,
|
||
|
|
unsigned <em>flags</em>);
|
||
|
|
</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>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> This function can only be used in an i5/OS PASE
|
||
|
|
program. See <a href="../rzalf/rzalfintro.htm">i5/OS PASE</a> for more
|
||
|
|
information about creating i5/OS PASE programs.</p>
|
||
|
|
|
||
|
|
<p>The <strong>_PGMCALL()</strong> function calls an i5/OS program (object
|
||
|
|
type *PGM) from an i5/OS PASE program. It transfers control to the *PGM object
|
||
|
|
specified by a 16-byte tagged system pointer (passing any necessary arguments)
|
||
|
|
and resumes execution when control returns.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>target</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Pointer to a tagged system pointer that addresses the i5/OS
|
||
|
|
program (object type *PGM) to call. <em>target</em> must be a 16-byte aligned
|
||
|
|
i5/OS PASE memory address.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>argv</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input/Output) Array of pointers to arguments. <em>argv</em> is the address
|
||
|
|
of an array of pointers to argument variables that are (usually) passed by-address to the
|
||
|
|
i5/OS program. <em>argv</em> can be zero (null) if there are no arguments to
|
||
|
|
pass. The last element in the array must be a null pointer. A maximum of
|
||
|
|
<strong>PGMCALL_MAXARGS</strong> (255) arguments can be passed to an i5/OS
|
||
|
|
program unless <strong>PGMCALL_NOMAXARGS</strong> is specified.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>flags</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Specifies options to control how the i5/OS program is called. The
|
||
|
|
<em>flags</em> argument is a bitwise logical-or of one or more of the following
|
||
|
|
values:<br>
|
||
|
|
<br>
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="25 75" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PGMCALL_DIRECT_ARGS</em><br>
|
||
|
|
(0x00000001)</td>
|
||
|
|
<td align="left" valign="top">Specifies that the addresses in the <em>argv</em>
|
||
|
|
array are passed directly to the i5/OS program as formal arguments. If
|
||
|
|
<strong>PGMCALL_DIRECT_ARGS</strong> is omitted, the system builds tagged space
|
||
|
|
pointers to the argument memory locations identified in the <em>argv</em> array
|
||
|
|
and passes the space pointers as formal arguments (standard i5/OS program
|
||
|
|
linkage).</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PGMCALL_DROP_ADOPT</em><br>
|
||
|
|
(0x00000002)</td>
|
||
|
|
<td align="left" valign="top">Specifies that authorizations adopted by i5/OS
|
||
|
|
program invocations already in the stack are dropped so the called program only
|
||
|
|
benefits from authorizations available to the user and group profiles for the
|
||
|
|
thread.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PGMCALL_NOINTERRUPT</em><br>
|
||
|
|
(0x00000004)</td>
|
||
|
|
<td align="left" valign="top">Specifies that i5/OS PASE signals will not
|
||
|
|
interrupt the called i5/OS program. Some system functions (such as
|
||
|
|
<strong>select</strong>) can be interrupted by signals. Normally either an ILE
|
||
|
|
signal or an i5/OS PASE signal can interrupt such an operation, but
|
||
|
|
<strong>PGMCALL_NOINTERRUPT</strong> delays i5/OS PASE signal processing until
|
||
|
|
control returns from the called i5/OS program. This option has no effect on
|
||
|
|
ILE signal handling.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PGMCALL_NOMAXARGS</em><br>
|
||
|
|
(0x00000008)</td>
|
||
|
|
<td align="left" valign="top">Specifies that more than 255 arguments may be passed to the i5/OS program. Current system architecture limits the number of arguments to 16383 when this flag is set. Specifying <strong>PGMCALL_NOMAXARGS</strong> slightly increases system resource requirements even when no more than 255 arguments are provided.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PGMCALL_ASCII_STRINGS</em><br>
|
||
|
|
(0x00000010)</td>
|
||
|
|
<td align="left" valign="top">Specifies that all arguments are null-terminated ASCII character strings. The system converts argument strings from the i5/OS PASE CCSID to the job default CCSID and passes the converted (EBCDIC) strings to the i5/OS program. The converted strings are stored in an internal system buffer, so any changes made by the i5/OS program are <strong>not</strong> returned to the caller (by-value argument behavior).</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<!-- cols="80 20" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="bottom">Object Referred to</th>
|
||
|
|
<th align="center" valign="bottom">Authority<br>
|
||
|
|
Required</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">i5/OS program to call</td>
|
||
|
|
<td align="center" valign="top">*X</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p>Most errors from <strong>_PGMCALL</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, a function result of zero indicates the
|
||
|
|
i5/OS program was called and returned normally. A function result of -1
|
||
|
|
indicates an error that is further qualified by an errno value.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Conditions</h3>
|
||
|
|
|
||
|
|
<p>At least these errno values can be returned, with other values also possible
|
||
|
|
(such as i5/OS-unique ILE errno EAPAR):</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="25 75" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>[EINVAL]</em></td>
|
||
|
|
<td align="left" valign="top">An invalid <em>flags</em> value was specified, or
|
||
|
|
too many arguments were provided.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li><strong>_PGMCALL</strong> can only call i5/OS program objects (object type
|
||
|
|
*PGM). If your i5/OS PASE program needs to call a particular ILE procedure
|
||
|
|
inside a *PGM or *SRVPGM object, you must to use the <strong>_ILECALL</strong>
|
||
|
|
function.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>You can use the <strong>_RSLOBJ</strong> or <strong>_RSLOBJ2</strong>
|
||
|
|
function to obtain a system pointer to an i5/OS program (object type
|
||
|
|
*PGM).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Any i5/OS program that accepts arguments must be Teraspace-safe (created
|
||
|
|
using TERASPACE(*YES)) to be called using <strong>_PGMCALL</strong> because the
|
||
|
|
arguments are usually passed in Teraspace storage.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Arguments (addressed by pointers in the <em>argv</em> array) can be of any
|
||
|
|
data type. Arguments are passed by-address, so the called i5/OS program can
|
||
|
|
modify argument variables to return results to the i5/OS PASE program unless <strong>PGMCALL_ASCII_STRINGS</strong> is specified.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><strong>_PGMCALL</strong> does no character encoding conversions unless <strong>PGMCALL_ASCII_STRINGS</strong> is specified,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>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
|
||
|
|
<li><a href="pase__rslobj.htm">_RSLOBJ()--Resolve to an i5/OS Object for
|
||
|
|
i5/OS PASE</a></li>
|
||
|
|
<li><a href="pase__ilecall.htm">_ILECALLX()--Call an ILE Procedure 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_qp2setenv_ile.htm">Qp2setenv_ile()--Set ILE environment variables for i5/OS PASE</a></li>
|
||
|
|
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
API introduced: V5R2
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|