513 lines
15 KiB
HTML
513 lines
15 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>Qp0zStartTerminal()--Start a Generic Terminal</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. -->
|
|
<!-- Begin Header Records ========================================== -->
|
|
<!-- file cleaned -->
|
|
<!-- UNIX11 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB at -->
|
|
<!-- RCHVMW2 on 1 Jun 1999 at 16:14:12 -->
|
|
<!-- Change History: -->
|
|
<!-- 030918 XZY1406: Changes for Job Name, 99276 -->
|
|
<!--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>Qp0zStartTerminal()--Start a Generic Terminal</h2>
|
|
|
|
<div class="box" style="width: 60%;">
|
|
<br>
|
|
Syntax
|
|
|
|
<pre>
|
|
#include <qp0ztrml.h>
|
|
|
|
int Qp0zStartTerminal( Qp0z_Terminal_T <em>*handle</em>,
|
|
char <em>*args[]</em>,
|
|
char <em>*envs[]</em>,
|
|
Qp0z_Terminal_Attr_T <em>attr</em>);
|
|
</pre>
|
|
|
|
Service Program Name: QP0ZTRML<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: No<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The <strong>Qp0zStartTerminal()</strong> function starts a new terminal
|
|
by:</p>
|
|
|
|
<ul>
|
|
<li>starting a new interpreter process running the program specified in <em>
|
|
args[0]</em>, <br>
|
|
</li>
|
|
|
|
<li>creating pipes connected to descriptors 0, 1, and 2 in the interpreter
|
|
process, and <br>
|
|
</li>
|
|
|
|
<li>starting a terminal window.</li>
|
|
</ul>
|
|
|
|
<p>The interpreter process is started with the environment variables specified
|
|
in <em>envs</em>. Using <em>attr</em>, you can set attributes for the terminal,
|
|
including the inheritance structure used by <a href="spawn.htm">spawn()</a> to
|
|
start the interpreter process, the title line and command key descriptions
|
|
in the terminal window, and the i5/OS simple job name of the interpreter process.
|
|
The program running in the interpreter process receives the arguments specified
|
|
in <em>args</em>.
|
|
</p>
|
|
|
|
<p>In the interpreter process, descriptors 0, 1, and 2 are connected to pipes
|
|
in the process that started the terminal. When a command is entered in the
|
|
terminal window, it is written to descriptor 0 in the interpreter process. When
|
|
a program in the interpreter process writes to descriptors 1 or 2, the data is
|
|
displayed in the terminal window.</p>
|
|
|
|
<p>After a new terminal is started, you must call <a href="runtrml.htm">
|
|
Qp0zRunTerminal()</a> to wait for the user to enter input at the command line,
|
|
press a command key, or for output from the interpreter process to be
|
|
displayed.</p>
|
|
|
|
<br>
|
|
<h3>Parameters</h3>
|
|
|
|
<dl>
|
|
<dt><strong><em>*handle</em></strong></dt>
|
|
|
|
<dd>(Output) A pointer to the area to store the terminal handle. When
|
|
successful, <strong>Qp0zStartTerminal()</strong> returns a handle to the
|
|
started terminal. <br>
|
|
</dd>
|
|
|
|
<dt><strong><em>*args</em></strong></dt>
|
|
|
|
<dd>(Input) A null-terminated array of pointers to the arguments passed to the
|
|
interpreter program. The first element in the array is a pointer to the path
|
|
name of the program to start in the interpreter process. <br>
|
|
</dd>
|
|
|
|
<dt><strong><em>*envs</em></strong></dt>
|
|
|
|
<dd>(Input) A null-terminated array of pointers to the environment variables
|
|
inherited by the interpreter process. If this parameter is NULL, the
|
|
environment variables currently defined when <strong>
|
|
Qp0zStartTerminal()</strong> is called are inherited by the interpreter
|
|
process. <br>
|
|
</dd>
|
|
|
|
<dt><strong><em>attr</em></strong></dt>
|
|
|
|
<dd>(Input) Attributes for the terminal session.
|
|
|
|
<p>The members of the <samp>Qp0z_Terminal_Attr_T</samp> structure are as
|
|
follows:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="30 70" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>struct inherit Inherit</em> </td>
|
|
<td align="left" valign="top">The inheritance structure used when calling <a
|
|
href="spawn.htm">spawn()</a> to start the interpreter process. Using the
|
|
inheritance structure you can control the attributes of the interpreter
|
|
process. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>int Buffer_Size</em> </td>
|
|
<td align="left" valign="top">Size of buffer for reading data from interpreter
|
|
process. If zero is specified, <strong>Qp0zStartTerminal()</strong> uses a
|
|
default buffer size of 4096 bytes. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>char DBCS_Capable</em> </td>
|
|
<td align="left" valign="top">This field is no longer used. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top" nowrap><em>char Return_Exit_Status</em> </td>
|
|
<td align="left" valign="top">Return the exit status of the interpreter process
|
|
from <a href="endtrml.htm">Qp0zEndTerminal()</a>. You must specify an optional
|
|
parameter when calling <a href="endtrml.htm">Qp0zEndTerminal()</a> to receive
|
|
the exit status. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>char Send_End_Msg</em> </td>
|
|
<td align="left" valign="top">Send message CPCA989 when the interpreter process
|
|
ends during <a href="runtrml.htm">Qp0zRunTerminal()</a>. The message is
|
|
displayed on the message line of the terminal window to alert the user that the
|
|
interpreter process has ended. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>char Return_On_End</em> </td>
|
|
<td align="left" valign="top">Return immediately from <a href=
|
|
"runtrml.htm">Qp0zRunTerminal()</a> when the interpreter process ends. By
|
|
default, <a href="runtrml.htm">Qp0zRunTerminal()</a> waits for the user to
|
|
press either the F3 or F12 command key before returning when the interpreter
|
|
process ends. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>char *Title</em> </td>
|
|
<td align="left" valign="top">Pointer to null-terminated string with the title
|
|
for the terminal window. If the string is too long to fit in the terminal
|
|
window, it is truncated to the width of the window. </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>char *Cmd_Key_Line1</em> </td>
|
|
<td align="left" valign="top">Pointer to null-terminated string with the first
|
|
line of command key descriptions for the terminal window. If the string is too
|
|
long to fit in the terminal window, it is truncated to the width of the window.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>char *Cmd_Key_Line2</em> </td>
|
|
<td align="left" valign="top">Pointer to null-terminated string with the second
|
|
line of command key descriptions for the terminal window. If the string is too
|
|
long to fit in the terminal window, it is truncated to the width of the window.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>char Interpreter_Process_Name[10]</em> </td>
|
|
<td align="left" valign="top">The 10 character i5/OS simple job name to use for
|
|
the interpreter process. If specified, this field must be uppercase, and contain
|
|
only those characters allowed for an i5/OS job name.
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">
|
|
<em>char reserved2[22]</em> </td>
|
|
<td align="left" valign="top">Reserved field that must be set to zero.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Authorities</h3>
|
|
|
|
<p><strong><a name="TBLASTARTR">Authorization Required for
|
|
Qp0zStartTerminal()</a></strong><br>
|
|
</p>
|
|
|
|
<table border cellpadding="5">
|
|
<tr>
|
|
<th align="left" valign="bottom">Object Referred to</th>
|
|
<th align="left" valign="bottom">Authority Required</th>
|
|
<th align="left" valign="bottom">errno</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Each directory in the path name
|
|
preceding the executable file that will run in the interpreter process</td>
|
|
<td align="left" valign="top">*X</td>
|
|
<td align="left" valign="top">EACCES</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Executable file that will run in the
|
|
interpreter process</td>
|
|
<td align="left" valign="top">*X</td>
|
|
<td align="left" valign="top">EACCES</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">If executable file that will run in
|
|
the interpreter process is a shell script</td>
|
|
<td align="left" valign="top">*RX</td>
|
|
<td align="left" valign="top">EACCES</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<h3>Return Value</h3>
|
|
|
|
<dl compact>
|
|
<dt><em>0</em></dt>
|
|
|
|
<dd><strong>Qp0zStartTerminal()</strong> was successful.</dd>
|
|
|
|
<dt><em>value</em></dt>
|
|
|
|
<dd><strong>Qp0zStartTerminal()</strong> was not successful. The value returned
|
|
is an errno indicating the failure.</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Error Conditions</h3>
|
|
|
|
<p>If <strong>Qp0zStartTerminal()</strong> is not successful, the return value
|
|
usually indicates one of the following errors. Under some conditions, the
|
|
return value could indicate an error other than those listed here.</p>
|
|
|
|
<dl>
|
|
<dt><em>[E2BIG]</em></dt>
|
|
|
|
<dd><p>Argument list too long.</p></dd>
|
|
|
|
<dt><em>[EACCES]</em></dt>
|
|
|
|
<dd><p>Permission denied.</p>
|
|
|
|
<p>An attempt was made to access an object in a way forbidden by its object
|
|
access permissions.</p>
|
|
|
|
<p>The thread does not have access to the specified file, directory, component,
|
|
or path.</p>
|
|
|
|
<p>If you are accessing a remote file through the Network File System, update
|
|
operations to file permissions at the server are not reflected at the client
|
|
until updates to data that is stored locally by the Network File System take
|
|
place. (Several options on the Add Mounted File System (ADDMFS) command
|
|
determine the time between refresh operations of local data.) Access to a
|
|
remote file may also fail due to different mappings of user IDs (UID) or group
|
|
IDs (GID) on the local and remote systems.</p>
|
|
</dd>
|
|
|
|
<dt><em>[EBUSY]</em></dt>
|
|
|
|
<dd><p>Resource busy.</p>
|
|
|
|
<p>An attempt was made to use a system resource that is not available at this
|
|
time. A terminal session is already active in the job and another one cannot be
|
|
started.</p>
|
|
</dd>
|
|
|
|
<dt><em>[ECONVERT]</em></dt>
|
|
|
|
<dd><p>Conversion error.</p>
|
|
|
|
<p>One or more characters could not be converted from the source CCSID to the
|
|
target CCSID.</p>
|
|
</dd>
|
|
|
|
<dt><em>[EFAULT]</em></dt>
|
|
|
|
<dd><p>The address used for an argument is not correct.</p>
|
|
|
|
<p>In attempting to use an argument in a call, the system detected an address
|
|
that is not valid.</p>
|
|
|
|
<p>While attempting to access a parameter passed to this function, the system
|
|
detected an address that is not valid.</p>
|
|
</dd>
|
|
|
|
<dt><em>[EINVAL]</em></dt>
|
|
|
|
<dd>The value specified for the argument is not correct.
|
|
|
|
<p>A function was passed incorrect argument values, or an operation was attempted
|
|
on an object and the operation specified is not supported for that type of
|
|
object.</p>
|
|
|
|
<p>An argument value is not valid, out of range, or NULL.</p>
|
|
</dd>
|
|
|
|
<dt><em>[EIO]</em></dt>
|
|
|
|
<dd><p>Input/output error.</p>
|
|
|
|
<p>A physical I/O error occurred.</p>
|
|
|
|
<p>A referenced object may be damaged.</p>
|
|
</dd>
|
|
|
|
<dt><em>[ELOOP]</em></dt>
|
|
|
|
<dd><p>A loop exists in the symbolic links.</p>
|
|
|
|
<p>This error is issued if the number of symbolic links encountered is more
|
|
than POSIX_SYMLOOP (defined in the limits.h header file). Symbolic links are
|
|
encountered during resolution of the directory or path name.</p>
|
|
</dd>
|
|
|
|
<dt><em>[EMFILE]</em></dt>
|
|
|
|
<dd><p>Too many open files for this process.</p>
|
|
|
|
<p>An attempt was made to open more files than allowed by the value of
|
|
OPEN_MAX. The value of OPEN_MAX can be retrieved using the sysconf()
|
|
function.</p>
|
|
|
|
<p>The process has more than OPEN_MAX descriptors already open (see the
|
|
<strong>sysconf()</strong> function).</p>
|
|
</dd>
|
|
|
|
<dt><em>[ENAMETOOLONG]</em></dt>
|
|
|
|
<dd><p>A path name is too long.</p>
|
|
|
|
<p>A path name is longer than PATH_MAX characters or some component of the name
|
|
is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For
|
|
symbolic links, the length of the name string substituted for a symbolic link
|
|
exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using the
|
|
<strong>pathconf()</strong> function.</p>
|
|
</dd>
|
|
|
|
<dt><em>[ENFILE]</em></dt>
|
|
|
|
<dd><p>Too many open files in the system.</p>
|
|
|
|
<p>A system limit has been reached for the number of files that are allowed to
|
|
be concurrently open in the system.</p>
|
|
|
|
<p>The entire system has too many other file descriptors already open.</p>
|
|
</dd>
|
|
|
|
<dt><em>[ENOENT]</em></dt>
|
|
|
|
<dd><p>No such path or directory.</p>
|
|
|
|
<p>The directory or a component of the path name specified does not exist.</p>
|
|
|
|
<p>A named file or directory does not exist or is an empty string.</p>
|
|
</dd>
|
|
|
|
<dt><em>[ENOMEM]</em></dt>
|
|
|
|
<dd><p>Storage allocation request failed.</p>
|
|
|
|
<p>A function needed to allocate storage, but no storage is available.</p>
|
|
|
|
<p>There is not enough memory to perform the requested function.</p>
|
|
</dd>
|
|
|
|
<dt><em>[ENOTDIR]</em></dt>
|
|
|
|
<dd><p>Not a directory.</p>
|
|
|
|
<p>A component of the specified path name existed, but it was not a directory
|
|
when a directory was expected.</p>
|
|
|
|
<p>Some component of the path name is not a directory, or is an empty
|
|
string.</p>
|
|
</dd>
|
|
|
|
<dt><em>[EUNKNOWN]</em></dt>
|
|
|
|
<dd><p>Unknown system state.</p>
|
|
|
|
<p>The operation failed because of an unknown system state. See any messages in
|
|
the job log and correct any errors that are indicated, then retry the
|
|
operation.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Usage Notes</h3>
|
|
|
|
<ol>
|
|
<li>Only one terminal at a time can be active in an interactive job. If a
|
|
terminal is currently active, <strong>Qp0zStartTerminal()</strong> returns
|
|
EBUSY.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If the interpreter program is a C or C++ program, it must be compiled for
|
|
Integrated File System I/O by specifying the SYSIFCOPT(*IFSIO) parameter on the
|
|
command used to create the program.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>If the interpreter program is a C or C++ program, the environment variable
|
|
QIBM_USE_DESCRIPTOR_STDIO=Y must be set in the interpreter process to enable
|
|
the program to use descriptors 0, 1, and 2 for standard input, standard output,
|
|
and standard error.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The interpreter program can always read and write directly to descriptors
|
|
0, 1, and 2 regardless of the language it is compiled with.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>It is the responsibility of the interpreter program to end and cleanup any
|
|
open resources when the descriptors are closed by the terminal, it receives the
|
|
SIGHUP signal, or it receives the SIGINT signal.<br>
|
|
<br>
|
|
</li>
|
|
</ol>
|
|
|
|
<br>
|
|
<h3>Related Information</h3>
|
|
|
|
<ul>
|
|
<li>The <<strong>qp0ztrml.h</strong>> file (see <a href="unix13.htm">
|
|
Header Files for UNIX-Type Functions</a>)<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="cntltrml.htm">Qp0zControlTerminal()</a>--Control a Generic
|
|
Terminal<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="endtrml.htm">Qp0zEndTerminal()</a>--End a Generic Terminal<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="gettrmlp.htm">Qp0zGetTerminalPid()</a>--Get Process ID for a Generic
|
|
Terminal<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="isatrml.htm">Qp0zIsATerminal()</a>--Determine Whether Descriptor Is
|
|
Connected to a Generic Terminal<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="runtrml.htm">Qp0zRunTerminal()</a>--Run a Generic Terminal<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="settrmlm.htm">Qp0zSetTerminalMode()</a>--Set Modes for a Generic
|
|
Terminal<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li><a href="spawn.htm">spawn()</a>--Spawn Process<br>
|
|
<br>
|
|
</li>
|
|
</ul>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V5R1
|
|
<hr>
|
|
<center>
|
|
<table cellpadding="2" cellspacing="2">
|
|
<tr align="center">
|
|
<td valign="middle" align="center">
|
|
<a href="#Top_Of_Page">Top</a> |
|
|
<a href="unix.htm">UNIX-Type APIs</a> |
|
|
<a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
</body>
|
|
</html>
|
|
|