402 lines
14 KiB
HTML
402 lines
14 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>QP2SHELL() and QP2SHELL2()--Run an i5/OS PASE Shell 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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<h2>QP2SHELL() and QP2SHELL2()--Run an i5/OS PASE Shell Program</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <qp2shell.h>
|
||
|
|
|
||
|
|
void QP2SHELL(const char *pathName,
|
||
|
|
...);
|
||
|
|
|
||
|
|
|
||
|
|
#include <qp2shell2.h>
|
||
|
|
|
||
|
|
void QP2SHELL2(const char *pathName,
|
||
|
|
...);
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: No<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>Programs QP2SHELL and QP2SHELL2 run an i5/OS Portable Application Solutions
|
||
|
|
Environment (i5/OS PASE) program in the job where the API is called. They load
|
||
|
|
the i5/OS PASE program and any necessary shared libraries and then transfer
|
||
|
|
control to the program. QP2SHELL runs in a new ILE activation group, while
|
||
|
|
QP2SHELL2 runs in the caller's activation group. Control returns to the caller
|
||
|
|
when the i5/OS PASE program either 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.
|
||
|
|
|
||
|
|
<p>If the base name part of the pathName value (excluding any prefix path
|
||
|
|
qualifier) begins with a hyphen (-), QP2SHELL and QP2SHELL2 strip the hyphen
|
||
|
|
when locating the bytestream file, but pass the full string (with the hyphen)
|
||
|
|
to the i5/OS PASE program as the program name. Standard i5/OS PASE shell
|
||
|
|
programs (including sh and ksh) run as login shells when called with a hyphen
|
||
|
|
as the first character of the program name. Login shells look for a profile
|
||
|
|
file and run it automatically when the shell starts.</p>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>argument strings</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Optional pointers to null-terminated character strings that are
|
||
|
|
passed to the i5/OS PASE program as arguments. The system copies argument
|
||
|
|
strings into i5/OS PASE memory and converts them from the job default CCSID to
|
||
|
|
the CCSID specified by ILE environment variable QIBM_PASE_CCSID.<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> When calling QP2SHELL or QP2SHELL2 from CL, be sure
|
||
|
|
to quote any argument string that could be interpreted as a numeric value. CL
|
||
|
|
converts unquoted numeric arguments to decimal or floating-point format, which
|
||
|
|
does not match the assumption made by these APIs and i5/OS PASE programs that
|
||
|
|
all arguments are null-terminated character strings.</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>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p>QP2SHELL and QP2SHELL2 return no function result. Escape messages are sent
|
||
|
|
to report errors.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Error Messages</h3>
|
||
|
|
|
||
|
|
<p>Some of the more common error messages sent by QP2SHELL and QP2SHELL2
|
||
|
|
are:</p>
|
||
|
|
|
||
|
|
<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 not
|
||
|
|
compatible.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFB9C5 E</td>
|
||
|
|
<td align="left" valign="top">i5/OS PASE program name required by
|
||
|
|
QP2SHELL.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">CPFB9C6 E</td>
|
||
|
|
<td align="left" valign="top">i5/OS PASE ended for signal &1, error code
|
||
|
|
&2.</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>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>QP2SHELL and QP2SHELL2 provide callable program interfaces to ILE procedure
|
||
|
|
Qp2RunPase. See <a href="qp2runpase.htm">Qp2RunPase()--Run an i5/OS PASE
|
||
|
|
Program</a> for details about running an i5/OS PASE program.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>QP2SHELL and QP2SHELL2 set the ILE pthread cancel state and cancel type to
|
||
|
|
default values (PTHREAD_CANCEL_ENABLE and PTHREAD_CANCEL_DEFERRED) before
|
||
|
|
running the i5/OS PASE program. This is done to avoid unexpected behavior for
|
||
|
|
the i5/OS PASE program if the job changed ILE pthread attributes before
|
||
|
|
calling the API.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><img src="delta.gif" alt="Start of change">QP2SHELL, QP2SHELL2, and system processing for the i5/OS PASE fork function normally set up handlers for most ILE signals (replacing any prior handlers). QP2SHELL always restores original ILE signal handlers before returning to the caller. QP2SHELL2 restores original ILE signal handlers before returning if the i5/OS PASE program exits, but if the i5/OS PASE program returns without exiting, original ILE signal handlers are not restored until the system destroys the activation group that called QP2SHELL2.
|
||
|
|
|
||
|
|
<p>You can control how these interfaces handle signals by setting ILE environment variable <em>QIBM_PASE_MAP_SIGNALS</em> to one of these values:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="35 65" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>Y</em></td>
|
||
|
|
<td align="left" valign="top">Call Qp2SignalPase for any ILE signal (other than SIGCHLD) that corresponds to an i5/OS PASE signal. The pending i5/OS PASE signal that may result is not delivered until control transfers to the i5/OS PASE program in some thread that has not blocked the signal. This is the default behavior if QIBM_PASE_MAP_SIGNALS is not set.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<td align="left" valign="top"><em>I</em></td>
|
||
|
|
<td align="left" valign="top">Call Qp2SignalPase for any ILE signal (other than SIGCHLD) that corresponds to an i5/OS PASE signal, and attempt to deliver pending signals immediately by using Qp2CallPase to call an i5/OS PASE function (in the same thread). A signal may remain pending if no thread running i5/OS PASE code has the signal unblocked.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<td align="left" valign="top"><em>N</em></td>
|
||
|
|
<td align="left" valign="top">Do not map any ILE signals to i5/OS PASE. No ILE signal handlers are changed. i5/OS PASE runtime functions that rely on system-generated signals (such as asynchronous I/O use of SIGIO and SIGURG) may not work correctly.
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
<img src="deltaend.gif" alt="End of change"><br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>To avoid unpredictable results, do not not change ILE environment variables
|
||
|
|
QIBM_USE_DESCRIPTOR_STDIO or QIBM_PASE_DESCRIPTOR_STDIO in a job in which an
|
||
|
|
i5/OS PASE program is running.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>QP2SHELL and QP2SHELL2 initialize i5/OS PASE environment variables with a
|
||
|
|
modified copy of the entire ILE environment. An i5/OS PASE environment
|
||
|
|
variable is initialized for every ILE environment variable, but the initial
|
||
|
|
value of any i5/OS PASE variable (except those whose name begins with "PASE_")
|
||
|
|
can be overridden by the value of an ILE environment variable with a name that
|
||
|
|
concatenates the prefix PASE_ with the original variable name. This processing
|
||
|
|
avoids some interference between i5/OS PASE runtime and ILE runtime when they
|
||
|
|
require different values for the same environment variable (for example,
|
||
|
|
LANG).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>For a login shell (only), QP2SHELL and QP2SHELL2 set ILE environment
|
||
|
|
variable PASE_SHELL to the path name of the i5/OS PASE shell program.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>QP2SHELL and QP2SHELL2 initialize any of the following ILE environment
|
||
|
|
variables that are not already set, with default values as shown:<br>
|
||
|
|
<br>
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="25 75" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>HOME</em></td>
|
||
|
|
<td align="left" valign="top">If HOME is not already set, QP2SHELL and
|
||
|
|
QP2SHELL2 set it to the home directory path specified in the user profile
|
||
|
|
identified by the LOGIN variable. If the job is not currently authorized to the
|
||
|
|
LOGIN user profile, the HOME environment variable is set to a null string.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>LOGIN</em></td>
|
||
|
|
<td align="left" valign="top">If LOGIN is not already set, QP2SHELL and
|
||
|
|
QP2SHELL set it to the middle qualifier of the job name. For an interactive
|
||
|
|
job, this is the name of the user who did a signon to start the job.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PASE_PATH</em></td>
|
||
|
|
<td align="left" valign="top">(Default: "/QOpenSys/usr/bin:/usr/ccs/bin:/QOpenSys/usr/bin/X11:/usr/sbin:.:/usr/bin") Initial value for the i5/OS PASE
|
||
|
|
PATH environment variable.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PASE_LANG and QIBM_PASE_CCSID</em></td>
|
||
|
|
<td align="left" valign="top">Initial value for the i5/OS PASE LANG
|
||
|
|
environment variable and what coded character set identifier (CCSID) the i5/OS
|
||
|
|
PASE program will use. QP2SHELL and QP2SHELL2 set both these ILE environment
|
||
|
|
variables if either or both is absent. The default values are function of the
|
||
|
|
current LANGID and CNTRYID attributes of the job, but the system will use
|
||
|
|
PASE_LANG=POSIX and QIBM_PASE_CCSID=819 if it does not recognize the LANGID and
|
||
|
|
CNTRYID pair. The i5/OS PASE LANG environment variable controls the default
|
||
|
|
locale for an i5/OS PASE program. See <a href="pase_locales.htm">i5/OS PASE
|
||
|
|
Locales</a> to determine what locales are supported by i5/OS PASE.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PASE_LOCPATH</em></td>
|
||
|
|
<td align="left" valign="top">(Default:
|
||
|
|
"/usr/lib/nls/msg/%L/%N:/usr/lib/nls/msg/%L/%N.cat") Initial value for the
|
||
|
|
i5/OS PASE LOCPATH environment variable.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PASE_LC__FASTMSG</em></td>
|
||
|
|
<td align="left" valign="top">(Default: "true") Initial value for the i5/OS
|
||
|
|
PASE LC__FASTMSG environment variable.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>PASE_TZ</em></td>
|
||
|
|
<td align="left" valign="top">
|
||
|
|
(Default: based on the i5/OS job TIMZON attribute) Initial value for the i5/OS PASE TZ environment variable. If no timezone information is provided in environment variable TZ, the i5/OS PASE program sees UTC (Universal Standard Time) as local time. You can set ILE environment variable PASE_TZ at the system level to provide a default timezone other than the one determined from the job TIMZON attribute. For example, this CL command sets the default timezone to US Central time:<br>
|
||
|
|
<pre>
|
||
|
|
ADDENVVAR ENVVAR(PASE_TZ) VALUE('CST6CDT') LEVEL(*SYS)
|
||
|
|
</pre>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QIBM_IFS_OPEN_MAX</em></td>
|
||
|
|
<td align="left" valign="top">(Default: "66000") Maximum number of Integrated
|
||
|
|
File System open file descriptors desired in the job. QP2SHELL and QP2SHELL
|
||
|
|
call the DosSetRelMaxFH API to set the maximum number of file descriptors to
|
||
|
|
the value in this ILE environment variable, and updates the environment
|
||
|
|
variable to reflect the actual limit (in case the requested limit is not
|
||
|
|
currently allowed). Any change to the maximum number of file descriptors
|
||
|
|
persists after the API returns.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"></td>
|
||
|
|
<td align="left" valign="top">i5/OS PASE programs assume the ability to open 65 534 files and the system requires an open file for each i5/OS PASE executable it loads, so the default of 66 000 files accomodates a maximally large i5/OS PASE program with a fairly large number of loaded executables.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Related Information</h3>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="qp2callpase.htm">Qp2CallPase()--Call an i5/OS PASE Procedure</a><br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="qp2runpase.htm">Qp2RunPase()--Run an i5/OS PASE Program</a><br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="qp2signalpase.htm">Qp2SignalPase()--Post an i5/OS PASE Signal</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>
|
||
|
|
|