515 lines
18 KiB
HTML
515 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>Qp2RunPase()--Run an i5/OS PASE Program</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 -->
|
|
<!-- Edited by Kersten Jan 02 -->
|
|
<!-- Created by V2DCIJB on 23 Nov 1999 -->
|
|
<!--End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="Top_Of_Page"></a>
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<h2>Qp2RunPase()--Run an i5/OS PASE Program</h2>
|
|
|
|
<div class="box" style="width: 70%;">
|
|
<br>
|
|
Syntax
|
|
|
|
<pre>
|
|
#include <qp2user.h>
|
|
|
|
int Qp2RunPase(const char *pathName,
|
|
const char *symbolName,
|
|
const void *symbolData,
|
|
unsigned int symbolDataLen,
|
|
int ccsid,
|
|
const char *const *argv,
|
|
const char *const *envp);
|
|
</pre>
|
|
|
|
<br>
|
|
Service Program Name: QP2USER<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Qp2RunPase() function runs an i5/OS Portable Application Solutions
|
|
Environment (i5/OS PASE) program in the job where the API is called. It loads
|
|
the i5/OS PASE program and any necessary shared libraries and then transfers
|
|
control to the program. Control returns to the caller when the i5/OS PASE
|
|
program exits, terminates due to a signal, or returns without exiting.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong>pathName</strong></dt>
|
|
|
|
<dd>(Input) Pointer to a null-terminated character string that identifies the
|
|
stream file in the Integrated File System that contains the i5/OS PASE program
|
|
to run. The pathName string may include an absolute or relative path qualifier
|
|
in addition to the stream file name. Relative path names are resolved using the
|
|
current working directory.<br>
|
|
<br>
|
|
</dd>
|
|
|
|
<dt><strong>symbolName</strong></dt>
|
|
<dd>(Input) This argument must be a null pointer.
|
|
<br><br>
|
|
</dd>
|
|
|
|
<dt><strong>symbolData</strong></dt>
|
|
<dd>(Input) This argument is ignored.
|
|
<br><br>
|
|
</dd>
|
|
|
|
<dt><strong>symbolDataLen</strong></dt>
|
|
<dd>(Input) This argument is ignored.
|
|
<br><br>
|
|
</dd>
|
|
|
|
<dt><strong>ccsid</strong></dt>
|
|
|
|
<dd>(Input) The coded character set identifier (CCSID) initially used by the
|
|
i5/OS PASE program. ccsid must specify a single-byte encoding (normally an
|
|
ASCII CCSID) that i5/OS can convert to and from the job default CCSID, or a
|
|
value of 1208 to indicate that the i5/OS PASE program uses UTF-8 encoding.
|
|
|
|
<p>The system uses ccsid to set the CCSID of any bytestream file created by the
|
|
i5/OS PASE program, and also to control character encoding conversions done
|
|
for i5/OS PASE runtime interfaces that use i5/OS services.</p>
|
|
</dd>
|
|
|
|
<dt><strong>argv</strong></dt>
|
|
|
|
<dd>(Input) Pointer to an array of pointers to null-terminated character
|
|
strings that are passed as arguments to the i5/OS PASE program. The last
|
|
element in the array must be a null pointer. An error is reported if the argv
|
|
parameter pointer is null.
|
|
|
|
<p>The system copies argument strings into i5/OS PASE memory and converts them
|
|
from the job default CCSID to the CCSID specified by the ccsid parameter. By
|
|
convention, the first argument string passed to an i5/OS PASE program should
|
|
be the same as the pathName string.</p>
|
|
</dd>
|
|
|
|
<dt><strong>envp</strong></dt>
|
|
|
|
<dd>(Input) Pointer to an array of pointers to null-terminated character
|
|
strings that are passed as environment variables to the i5/OS PASE program.
|
|
The last element in the array must be a null pointer. envp can be a null
|
|
pointer if no environment variables need to be initialized for the i5/OS PASE
|
|
program.
|
|
|
|
<p>The system copies environment variable strings into i5/OS PASE memory and
|
|
converts them from the job default CCSID to the CCSID specified by the ccsid
|
|
parameter. By convension, environment variable strings take the form
|
|
"NAME=value".</p>
|
|
</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">Each directory in the path to the i5/OS PASE
|
|
program and shared libraries</td>
|
|
<td align="center" valign="top">*X</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">i5/OS PASE program (not a shell script) in a
|
|
local file system</td>
|
|
<td align="center" valign="top">*X</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">i5/OS PASE program in a remote file system or
|
|
shell script</td>
|
|
<td align="center" valign="top">*RX</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">i5/OS PASE shared library</td>
|
|
<td align="center" valign="top">*R</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3>Return Value</h3>
|
|
|
|
<p>The function result may be one of these special values:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="35 65" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>QP2RUNPASE_ERROR (-1)</em></td>
|
|
<td align="left" valign="top">An internal error occurred during Qp2RunPase
|
|
processing.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>QP2RUNPASE_RETURN_NOEXIT (-2)</em></td>
|
|
<td align="left" valign="top">The i5/OS PASE program returned without exiting
|
|
(by calling the i5/OS PASE <strong>_RETURN</strong> function).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If the result is not one of the special values above, it is a value that
|
|
contains status information about how the i5/OS PASE program ended, in the
|
|
same format as the stat_val parameter for the ILE waitpid function. You can use
|
|
these macros in file <sys/wait.h> to interpret such a result:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="25 75" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>WIFEXITED(stat_val)</em> </td>
|
|
<td align="left" valign="top">Evaluates to a nonzero value if i5/OS PASE
|
|
program ended normally.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>WEXITSTATUS(stat_val)</em></td>
|
|
<td align="left" valign="top">If the value of the WIFEXITED(stat_val) is
|
|
nonzero, evaluates to the low-order 8 bits of the value the i5/OS PASE program
|
|
specified as the argument to exit or the function result returned by main.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>WIFSIGNALED(stat_val)</em></td>
|
|
<td align="left" valign="top">Evaluates to a nonzero value if i5/OS PASE
|
|
program ended because of the receipt of a terminating signal that was not
|
|
caught by the process.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>WTERMSIG(stat_val)</em></td>
|
|
<td align="left" valign="top">If the value of WIFSIGNALED(stat_val) is nonzero,
|
|
evaluates to the number of the i5/OS PASE signal that caused the program to
|
|
end. i5/OS PASE programs use the same signal numbers as AIX (which differ from
|
|
ILE signal numbers).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%" cellpadding="5">
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td width="15%" valign="top">CPF9872 E</td>
|
|
<td width="85%" valign="top">Program or service program &1 in library
|
|
&2 ended. Reason code &3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB9C0 E</td>
|
|
<td align="left" valign="top">Error loading program &1. See previous
|
|
messages.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB9C1 E</td>
|
|
<td align="left" valign="top">System support for i5/OS Portable Application
|
|
Solutions Environment not available.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB9C2 E</td>
|
|
<td align="left" valign="top">Hardware support for i5/OS Portable Application
|
|
Solutions Environment not available.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB9C3 E</td>
|
|
<td align="left" valign="top">i5/OS PASE CCSID and job default CCSID are
|
|
incompatible.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB9C7 E</td>
|
|
<td align="left" valign="top">i5/OS PASE already running in this job.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB9C8 E</td>
|
|
<td align="left" valign="top">File descriptors 0, 1, and 2 must be open to run
|
|
the i5/OS PASE program.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">CPFB9CB E</td>
|
|
<td align="left" valign="top">Qp2RunPase second argument must be a null pointer.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3>Usage Notes</h3>
|
|
|
|
<ol>
|
|
<li>Qp2RunPase works like the AIX execve function, including the ability to run
|
|
shell scripts and the rules for resolving shared libraries (which may include
|
|
using i5/OS PASE environment variable LIBPATH).<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If an absolute path
|
|
(starting with "/") is specified for the pathName string or in the first line
|
|
of a shell script identified by pathName and that path cannot be opened or is
|
|
not a regular bytestream file, the system generally searches the /QOpenSys file
|
|
system for the file. See environment variable
|
|
<strong>PASE_EXEC_QOPENSYS</strong> in <a href="pase_environ.htm">i5/OS PASE
|
|
Environment Variables</a> for more information.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Qp2RunPase cannot run an i5/OS PASE program or shared library stored in a
|
|
file system that is not threadsafe in a job that is multithread capable. Any
|
|
job started by the i5/OS PASE fork function is multi-thread capable.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>You can set these ILE environment variables before calling Qp2RunPase to
|
|
control the i5/OS PASE operation:<br>
|
|
<br>
|
|
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="35 65" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>QIBM_USE_DESCRIPTOR_STDIO</em> </td>
|
|
<td align="left" valign="top">When this ILE environment variable is set to Y or
|
|
I, both i5/OS PASE runtime and ILE C runtime use Integrated File System file
|
|
descriptors 0, 1, and 2 for stdin, stdout, and stderr. Otherwise, i5/OS PASE
|
|
file descriptors 0, 1, and 2 are mapped to ILE C runtime files stdin, stdout,
|
|
and stderr (which may not use any Integrated File System file descriptors).
|
|
|
|
<p>i5/OS PASE and ILE generally use different descriptor numbers for the same
|
|
open file, but when QIBM_USE_DESCRIPTOR_STDIO is set to Y or I, any operation
|
|
against i5/OS PASE file descriptors 0, 1, or 2 is also done for the same
|
|
Integrated File System file descriptor number so i5/OS PASE and ILE C use the
|
|
same files for stdin, stdout, and stderr.</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>QIBM_PASE_DESCRIPTOR_STDIO</em> </td>
|
|
<td align="left" valign="top">This ILE environment variable controls
|
|
ASCII/EBCDIC conversion for data read or written through i5/OS PASE files
|
|
stdin, stdout, and stderr to Integrated File System file descriptors 0, 1, and
|
|
2. ASCII/EBCDIC conversion is always done (and this variable is ignored) unless
|
|
QIBM_USE_DESCRIPTOR_STDIO is set to either Y or I. If
|
|
QIBM_PASE_DESCRIPTOR_STDIO is set to B, the PASE program processes binary data
|
|
(without ASCII/EBCDIC conversion). Otherwise, ASCII/EBCDIC conversion is done
|
|
for any data read from or written to i5/OS PASE file descriptors 0, 1, or
|
|
2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>QIBM_PASE_FLUSH_STDIO</em> </td>
|
|
<td align="left" valign="top">This ILE environment variable controls whether i5/OS PASE runtime flushes every write to a standard output stream attached to a Data Management file (such as a spooled printer file) or to the Dynamic Screen Manager in an interactive job. QIBM_PASE_FLUSH_STDIO must be set before starting i5/OS PASE, and only applies when i5/OS PASE is NOT using IFS descriptors for standard I/O (QIBM_USE_DESCRIPTOR_STDIO is not set). It is usually only needed for interactive programs that require immediate display of output that does not end with newline. These values are supported:
|
|
<p></p>
|
|
<dl>
|
|
<dt>Y</dt>
|
|
<dd>flush both stdout and stderr</dd>
|
|
<dt>1</dt>
|
|
<dd>flush only stdout (i5/OS PASE descriptor 1)</dd>
|
|
<dt>2</dt>
|
|
<dd>flush only stderr (i5/OS PASE descriptor 2)</dd>
|
|
</dl>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>QIBM_PASE_USE_PRESTART_JOBS</em> </td>
|
|
<td align="left" valign="top">When this ILE environment variable is set to Y,
|
|
i5/OS PASE runtime uses prestarted jobs for child processes created by fork
|
|
and for any job started by the systemCL i5/OS PASE runtime function (to run a
|
|
CL command). You should add prestarted job entries (ADDPJE command) for
|
|
programs QP0ZSPWT (used by fork) and QP0ZSPWP (used by systemCL) to any
|
|
subsystem description that will run jobs that use this support.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>i5/OS PASE environment variables are independent of ILE environment
|
|
variables. See <a href="pase_environ.htm">i5/OS PASE Environment Variables</a>
|
|
for more information, including i5/OS PASE environment variables you can set
|
|
to control runtime behaviors that differ from AIX.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The ccsid parameter provides the initial i5/OS PASE CCSID value, but the
|
|
i5/OS PASE program can use the _SETCCSID function to change the i5/OS PASE
|
|
CCSID or to rebind to a change in the job default CCSID. The i5/OS PASE CCSID
|
|
should generally be the CCSID equivalent of the code set for the current
|
|
locale. See <a href="pase_locales.htm">i5/OS PASE Locales</a> to determine
|
|
what locales are supported by i5/OS PASE.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>You may want to increase the number of file descriptors in the job by
|
|
calling DosSetRelMaxFH before you call Qp2RunPase. By default, i5/OS jobs
|
|
support only 200 open file descriptors, while i5/OS PASE programs generally
|
|
expect to be able to open 32 767 file descriptors, and the system requires
|
|
file descriptors to open bytestream files that contain the i5/OS PASE program
|
|
and any shared libraries it uses.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>You may want to establish Qp2SignalPase as the handler for any ILE signal
|
|
that needs to be visible to the i5/OS PASE program. For example, system
|
|
support for Sockets (used by i5/OS PASE runtime) only sends SIGIO and SIGURG
|
|
as ILE signals, so ILE signal handling must be set up before calling an i5/OS
|
|
PASE program that relies on SIGIO or SIGURG as i5/OS PASE signals. i5/OS PASE
|
|
runtime automatically establishes Qp2SignalPase as the handler for every ILE
|
|
signal in a fork child process.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>You may want to call ILE interfaces pthread_setcancelstate and
|
|
pthread_setcanceltype to set pthread cancel state and cancel type before
|
|
calling Qp2RunPase in a process that did prior pthread work. i5/OS PASE
|
|
pthreads use ILE pthreads and Qp2RunPase assumes that ILE pthread cancel state
|
|
and cancel type are set to defaults (PTHREAD_CANCEL_ENABLE and
|
|
PTHREAD_CANCEL_DEFERRED). The state of these attributes when a program ends is
|
|
whatever value was last set by either ILE or i5/OS PASE code.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>
|
|
Time-of-day information in an i5/OS PASE program depends on the value of i5/OS PASE environment variable TZ, which provides information about timezone name and offset from UTC (Universal Coorodinated Time).
|
|
For example, the correct TZ setting for Central Time in the USA is TZ=CST6CDT.
|
|
See AIX documentation for more information about environment varble TZ.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Any credentials changes (user, group, or group list changes) made by an
|
|
i5/OS PASE program are generally persistent in the job. The job (thread)
|
|
credentials before and after a call to Qp2RunPase may not be the same if the
|
|
i5/OS PASE program calls any of the setuid or setgid family of interfaces.
|
|
However, the system saves credentials before running any i5/OS PASE program
|
|
with the S_ISUID or S_ISGID attribute, and automatically restores the saved
|
|
credentials before returning to the caller of Qp2RunPase.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Character conversions controlled by the ccsid parameter only handle the
|
|
single-byte component of an EBCDIC-mixed CCSID (for the job default CCSID).
|
|
This restricts the i5/OS PASE program name specified by the pathName
|
|
parameter, argument strings passed through the argv parameter, and environment
|
|
variables passed through the envp parameter to single-byte characters.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If an i5/OS PASE program needs to use DBCS characters for i5/OS PASE
|
|
runtime functions such as file system interfaces, it must run with the i5/OS
|
|
PASE CCSID (ccsid parameter) set to 1208 because i5/OS PASE runtime provides
|
|
complete support for DBCS characters using UTF-8 encoding only.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Older versions of <strong>Qp2RunPase</strong> used <em>symbolName</em>,
|
|
<em>symbolData</em>, and <em>symbolDataLen</em> to pass inputs other
|
|
than character string arguments and environment variables to the i5/OS PASE
|
|
program.
|
|
An i5/OS PASE program can retrieve any inputs that cannot be
|
|
expressed as null-terminated strings (such as tagged pointers) by calling
|
|
ILE or OPM code (using _ILECALL or _PGMCALL) with by-address arguments.</li>
|
|
</ol>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li>The <sys/wait.h> file (see <a href="unix13.htm">Header Files for
|
|
UNIX-Type Functions</a>)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="dossrmfh.htm">DosSetRelMaxFH()</a>--Change Maximum Number of File
|
|
Descriptors<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="users_44.htm">pthread_setcancelstate()--Set Cancel State</a><br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="users_45.htm">pthread_setcanceltype()--Set Cancel Type</a><br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="qp2shell.htm">QP2SHELL()--Run an i5/OS PASE Shell Program</a><br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="qp2term.htm">QP2TERM()--Run an i5/OS PASE Terminal
|
|
Session</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>
|
|
|