314 lines
10 KiB
HTML
314 lines
10 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>systemCL()--Run a CL Command 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 -->
|
||
|
|
<!-- 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>systemCL()--Run a CL Command for i5/OS PASE</h2>
|
||
|
|
|
||
|
|
<div class="box" style="width: 60%;">
|
||
|
|
<br>
|
||
|
|
Syntax
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
#include <as400_protos.h>
|
||
|
|
|
||
|
|
int systemCL(const char *command,
|
||
|
|
int flags);
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Library: Standard C Library (libc.a) <br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Conditional. See <a href="#usage_notes">Usage Notes</a>.<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<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>systemCL()</strong> function runs a CL command.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Parameters</h3>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><strong>command</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Pointer to a null-terminated string in the i5/OS PASE CCSID that
|
||
|
|
specifies the CL command with any parameters.<br>
|
||
|
|
<br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dt><strong>flags</strong></dt>
|
||
|
|
|
||
|
|
<dd>(Input) Specifies option flags that control how the CL command runs. flags
|
||
|
|
is a bit-wise OR of any of the following values:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="30 70" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_MSG_STDOUT</em> (0x00000001)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to receive i5/OS messages
|
||
|
|
after normal command completion, convert the text of each message from the job
|
||
|
|
default CCSID to the i5/OS PASE CCSID, and write converted text lines to
|
||
|
|
Integrated File System descriptor 1 (stdout).<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_MSG_STDERR</em> (0x00000002)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to receive i5/OS messages
|
||
|
|
after error command completion, convert the text of each message from the job
|
||
|
|
default CCSID to the i5/OS PASE CCSID, and write converted text lines to
|
||
|
|
Integrated File System descriptor 2 (stderr).<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_MSG_NOMSGID</em> (0x00000004)</td>
|
||
|
|
<td align="left" valign="top">Suppresses message identifiers in text lines
|
||
|
|
written to stdout or stderr for messages processed on behalf of
|
||
|
|
SYSTEMCL_MSG_STDOUT and SYSTEMCL_MSG_STDERR. When this option is omitted,
|
||
|
|
message text lines have the form "XXX1234: message text", where "XXX1234" is
|
||
|
|
the i5/OS message identifier.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_SPOOL_STDOUT</em> (0x00000008)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to process any spooled output
|
||
|
|
files created by the CL command by reading each file, converting file data from
|
||
|
|
the job default CCSID to the i5/OS PASE CCSID, and writing converted text
|
||
|
|
lines to Integrated File System descriptor 1 (stdout).<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_SPOOL_KEEP</em> (0x00000010)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to keep any spooled output
|
||
|
|
files after they are processed for option SYSTEMCL_SPOOL_STDOUT, instead of
|
||
|
|
deleting the files after their contents is written to stdout.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_FILTER_STDIN</em> (0x00000020)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to setup a filter thread that
|
||
|
|
converts from the i5/OS PASE CCSID to the job default CCSID for any data the
|
||
|
|
CL command reads from Integrated File System descriptor 0 (stdin).<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap><em>SYSTEMCL_FILTER_STDOUT</em>
|
||
|
|
(0x00000040)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to setup a filter thread that
|
||
|
|
converts any data the CL command writes to Integrated File System descriptor 1
|
||
|
|
(stdout) from the job default CCSID to the i5/OS PASE CCSID.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top" nowrap><em>SYSTEMCL_FILTER_STDERR</em>
|
||
|
|
(0x00000080)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to setup a filter thread that
|
||
|
|
converts any data the CL command writes to Integrated File System descriptor 2
|
||
|
|
(stderr) from the job default CCSID to the i5/OS PASE CCSID.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_SPAWN</em> (0x00000100)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to run the CL command in a
|
||
|
|
separate process. If this option is omitted, the CL command runs in the process
|
||
|
|
that calls the systemCL function.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_SPAWN_JOBLOG</em> (0x00000200)</td>
|
||
|
|
<td align="left" valign="top">Forces the system to generate an i5/OS job log
|
||
|
|
for the job submitted using option SYSTEMCL_SPAWN.<br>
|
||
|
|
<br>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>SYSTEMCL_ENVIRON</em> (0x00000400)</td>
|
||
|
|
<td align="left" valign="top">Directs the system to copy i5/OS PASE
|
||
|
|
environment variables to ILE environment variables before running the CL
|
||
|
|
command. This option sets ILE environment variables in the process that calls
|
||
|
|
the systemCL function, regardless of whether the command runs in this process
|
||
|
|
or a child process (created for option SYSTEMCL_SPAWN).</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
|
||
|
|
<p>No authority is needed to run the <strong>systemCL</strong> function, but
|
||
|
|
the caller must be authorized to run the specified CL command.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3>Return Value</h3>
|
||
|
|
|
||
|
|
<p>If the command argument is a null pointer, the function result is zero if
|
||
|
|
system support to call the i5/OS Command Analyzer is available, or a nonzero
|
||
|
|
value otherwise.</p>
|
||
|
|
|
||
|
|
<p>If option <strong>SYSTEMCL_SPAWN</strong> is specified, the function result
|
||
|
|
is the exit code from the spawned job (returned by the ILE
|
||
|
|
<strong>waitpid</strong> function), which is non-zero if any error occurred.</p>
|
||
|
|
|
||
|
|
<p>Otherwise, the function result is zero for normal command completion, or -1
|
||
|
|
if an error occurred. No errno value is set for CL command errors.</p>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="usage_notes">Usage Notes</a></h3>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li><strong>systemCL</strong> is only threadsafe in these two cases:<br>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>You use option <strong>SYSTEMCL_SPAWN</strong> and do not use
|
||
|
|
<strong>SYSTEMCL_ENVIRON</strong>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>You only run threadsafe CL commands and do not use
|
||
|
|
<strong>SYSTEMCL_SPAWN</strong>, <strong>SYSTEMCL_FILTER_STDIN</strong>,
|
||
|
|
<strong>SYSTEMCL_FILTER_STDOUT</strong>,
|
||
|
|
<strong>SYSTEMCL_FILTER_STDERR</strong>, or
|
||
|
|
<strong>SYSTEMCL_ENVIRON</strong>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>You must set ILE environment variable
|
||
|
|
<strong>QIBM_USE_DESCRIPTOR_STDIO</strong> to Y or I before the CL command does
|
||
|
|
any file I/O to stdin, stdout, or stderr if you need CCSID conversion
|
||
|
|
controlled by options <strong>SYSTEMCL_FILTER_STDIN</strong>,
|
||
|
|
<strong>SYSTEMCL_FILTER_STDOUT</strong>, and
|
||
|
|
<strong>SYSTEMCL_FILTER_STDERR</strong>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Processing for options <strong>SYSTEMCL_FILTER_STDIN</strong>,
|
||
|
|
<strong>SYSTEMCL_FILTER_STDOUT</strong>, and
|
||
|
|
<strong>SYSTEMCL_FILTER_STDERR</strong> creates ILE pthreads (not i5/OS PASE
|
||
|
|
threads) for CCSID conversion in the process that calls the
|
||
|
|
<strong>systemCL</strong> function. Integrated File System descriptors 0, 1,
|
||
|
|
and 2 are replaced in whatever job runs the CL command with pipes handled by
|
||
|
|
the filter threads. The original file descriptors are restored and the filter
|
||
|
|
threads are ended before the <strong>systemCL</strong> function returns.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Many CL commands are not supported in a job with multiple threads.
|
||
|
|
Processing for <strong>SYSTEMCL_SPAWN</strong> runs the CL command in a job
|
||
|
|
that is not multithread-capable, so it can run commands that do not work in a
|
||
|
|
job that is multithread-capable.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Processing for option <strong>SYSTEMCL_SPAWN</strong> uses the ILE
|
||
|
|
<strong>spawn</strong> API to run a batch job that inherits ILE attributes such
|
||
|
|
as Integrated File System descriptors and job CCSID, but the batch job does not
|
||
|
|
inherit any i5/OS PASE program (unlike a job created by the i5/OS PASE
|
||
|
|
<strong>fork</strong> function).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Processing for <strong>SYSTEMCL_ENVIRON</strong> uses the same name for the
|
||
|
|
ILE copy and the i5/OS PASE environment variable for most variables, but the
|
||
|
|
system adds a prefix "PASE_" to the name of the ILE copy of some environment
|
||
|
|
variables. You can control what variables names add the prefix by storing a
|
||
|
|
colon-delimited list of variable names in i5/OS PASE environment variable
|
||
|
|
<strong>PASE_ENVIRON_CONFLICT</strong>. If
|
||
|
|
<strong>PASE_ENVIRON_CONFLICT</strong> is not defined, the system defaults to
|
||
|
|
adding the prefix when copying i5/OS PASE environment variables
|
||
|
|
<strong>SHELL</strong>, <strong>PATH</strong>, <strong>NLSPATH</strong>, and
|
||
|
|
<strong>LANG</strong>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Processing for <strong>SYSTEMCL_ENVIRON</strong> sets two ILE environment
|
||
|
|
variables for each i5/OS PASE environment variable with a name prefix of
|
||
|
|
"ILE_". The i5/OS PASE environment variable value is used to set both a
|
||
|
|
variable with the same name and a variable with the name minus the prefix
|
||
|
|
"ILE_" in the ILE environment. For example, if the i5/OS PASE environment
|
||
|
|
contains a variable named <strong>ILE_PATH</strong>, the value of this variable
|
||
|
|
is used to set both <strong>ILE_PATH</strong> and <strong>PATH</strong> in the
|
||
|
|
ILE environment.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<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>
|
||
|
|
|