252 lines
11 KiB
HTML
252 lines
11 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) 2004 by IBM Corporation">
|
|
<!-- 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. -->
|
|
<title>
|
|
system - Run a CL command for i5/OS PASE
|
|
</title>
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<!-- Java sync-link -->
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
<h2>
|
|
system - Run a CL command for i5/OS PASE
|
|
</h2>
|
|
<p>
|
|
<strong>Syntax</strong>
|
|
</p>
|
|
<pre>
|
|
<strong>system [-beEhiIkKnOpqsv]</strong> <var>CL-command</var> [ <var>CL-parameters</var> ... ]
|
|
</pre>
|
|
<p>
|
|
<strong>Description</strong>
|
|
</p>
|
|
<p>
|
|
The i5/OS<sup>R</sup> PASE <strong>system</strong> utility runs a CL command. By default, any spooled
|
|
output produced by the command is written to standard output, and any messages sent by the
|
|
command are written to standard output or standard error (depending on whether the CL command
|
|
sent an exception message).
|
|
</p>
|
|
<p>
|
|
You need to set ILE environment variable <strong>QIBM_USE_DESCRIPTOR_STDIO</strong> to Y or I
|
|
(so that i5/OS PASE runtime and ILE C runtime use descriptor standard I/O) to avoid
|
|
unpredicatable results. This is done by default in the i5/OS jobs that program
|
|
<strong>QP2TERM</strong> uses to run i5/OS PASE shells and utilities.
|
|
</p>
|
|
<p>
|
|
<strong>Options</strong>
|
|
</p>
|
|
<dl>
|
|
<dt>
|
|
<strong>-b</strong>
|
|
</dt>
|
|
<dd>
|
|
Force binary mode for standard streams used by the CL command. When this option is omitted, the
|
|
<strong>system</strong> command converts any data the CL command reads from standard input from
|
|
the i5/OS PASE CCSID to the job default CCSID, and converts data written to standard output or
|
|
standard error from the job default CCSID to the i5/OS PASE CCSID. This option avoids CCSID
|
|
conversion for all standard streams except those associated with any of the options
|
|
<strong>-E</strong>, <strong>-I</strong>, and <strong>-O</strong>.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-e</strong>
|
|
</dt>
|
|
<dd>
|
|
Copy i5/OS PASE environment variables to ILE environment variables before running the CL
|
|
command. When this option is omitted, no ILE environment variables are set, so the ILE
|
|
environment may be be missing variables or have different variable values than the i5/OS PASE
|
|
environment.<br>
|
|
<br>
|
|
For most variables, the copy has the same name as the original, but the system adds a prefix
|
|
"<strong>PASE_</strong>" to the name of the ILE copy of some environment variables. You can
|
|
control what variables add the name prefix by storing a colon-delimited list of variable names
|
|
in i5/OS PASE environment variable <strong>PASE_ENVIRON_CONFLICT</strong>, or 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>
|
|
Any i5/OS PASE environment variable name with a prefix "<strong>ILE_</strong>" is copied to
|
|
the ILE environment twice. The first copy uses the same variable name, and the second copy uses
|
|
the name without the prefix. 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.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-E</strong>
|
|
</dt>
|
|
<dd>
|
|
Force CCSID conversion for the standard error stream used by the CL command. When this option
|
|
is specified, the <strong>system</strong> command converts any data the CL command writes to
|
|
standard error from the job default CCSID to the i5/OS PASE CCSID. This option overrides
|
|
option <strong>-b</strong> for the standard error stream.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-h</strong>
|
|
</dt>
|
|
<dd>
|
|
Write a brief description of allowable syntax for the <strong>system</strong> command to
|
|
standard output.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-i</strong>
|
|
</dt>
|
|
<dd>
|
|
Run the CL command in the same process (i5/OS job) where the <strong>system</strong> utility
|
|
runs. When option <strong>-i</strong> is omitted, the CL command is run in a separate process
|
|
(created using the ILE <strong>spawn</strong> API) that is not multithread-capable and is not
|
|
running an i5/OS PASE program. Many CL commands are not supported in a multithreaded job.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-I</strong>
|
|
</dt>
|
|
<dd>
|
|
Force CCSID conversion for the standard input stream used by the CL command. When this option
|
|
is specified, the <strong>system</strong> command converts any data the CL command reads from
|
|
standard input from the i5/OS PASE CCSID to the job default CCSID. This option overrides
|
|
option <strong>-b</strong> for the standard input stream. CCSID conversion should only be used
|
|
for standard input if the CL command reads standard input because processing done by the
|
|
<strong>system</strong> command attempts to read and convert all standard input data regardless
|
|
of whether the CL command uses the data, so it may leave the standard input stream positioned
|
|
beyond what the CL command read.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-k</strong>
|
|
</dt>
|
|
<dd>
|
|
Keep all spool files generated by the CL command. When this option is omitted, spooled output
|
|
files are deleted after their contents is written as text lines to standard output. Option
|
|
<strong>-i</strong> has no effect when option <strong>-s</strong> is used.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-K</strong>
|
|
</dt>
|
|
<dd>
|
|
Force a job log for the i5/OS job where the CL command runs. If this option is omitted, a job
|
|
log may only be produced if an unexpected error occurs.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-n</strong>
|
|
</dt>
|
|
<dd>
|
|
Do not include i5/OS message identifiers in any text line written to standard output or
|
|
standard error for a message sent by the CL command. When this option is omitted, the format of
|
|
any text lines written for i5/OS pre-defined messages is "XXX1234: message text", where
|
|
"XXX1234" is the i5/OS message identifier. <strong>-n</strong> suppresses the message
|
|
identifier, so only "message text" is written to the stream. Option <strong>-n</strong> has no
|
|
effect when option <strong>-q</strong> is used.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-O</strong>
|
|
</dt>
|
|
<dd>
|
|
Force CCSID conversion for the standard output stream used by the CL command. When this option
|
|
is specified, the <strong>system</strong> command converts any data the CL command writes to
|
|
standard output from the job default CCSID to the i5/OS PASE CCSID. This option overrides
|
|
option <strong>-b</strong> for the standard output stream.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-p</strong>
|
|
</dt>
|
|
<dd>
|
|
This option is ignored. The i5/OS PASE <strong>system</strong> utility always handles only messages sent to the program that runs the CL command (the way the QShell <strong>system</strong> utility
|
|
works with option <strong>-p</strong>).
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-q</strong>
|
|
</dt>
|
|
<dd>
|
|
Do not write any text lines to standard output or standard error for i5/OS messages sent by
|
|
the CL command. If this option is omitted, messages sent by the CL command are received,
|
|
converted from the job default CCSID to the i5/OS PASE CCSID, and written as a text lines to
|
|
standard output or standard error, depending on whether the CL command sent an exception
|
|
message.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-s</strong>
|
|
</dt>
|
|
<dd>
|
|
Do not process spooled output files produced by the CL command. When this option is omitted,
|
|
spooled output generated by the CL command is converted from the job default CCSID to the
|
|
i5/OS PASE CCSID and written to standard output, and then the spooled output files are
|
|
deleted.
|
|
</dd>
|
|
<br>
|
|
<dt>
|
|
<strong>-v</strong>
|
|
</dt>
|
|
<dd>
|
|
Write the complete CL command string to standard output before running the CL command.
|
|
</dd>
|
|
</dl>
|
|
<br>
|
|
<p>
|
|
<strong>Operands</strong>
|
|
</p>
|
|
<p>
|
|
<em>CL-command</em> is concatenated with any <em>CL-parameters</em> operands (with a single
|
|
space between them) to form the CL command string. You may need to enclose CL command and
|
|
parameter values in quotes to prevent the i5/OS PASE shell from expanding special characters
|
|
(such as parentheses and asterisks).
|
|
</p>
|
|
<p>
|
|
If a CL command parameter value requires quotes (such as a text parameter with lowercase
|
|
characters or embedded blanks), you must specify those quotes inside a quoted string because
|
|
i5/OS PASE shells remove the outer quotes from any argument passed to the i5/OS PASE
|
|
<strong>system</strong> utility.
|
|
</p>
|
|
<br>
|
|
<p><strong>Exit status</strong></p>
|
|
<p>If any exception message is sent by the CL command analyzer or the command processing program, the <strong>system</strong> utility returns an exit status of 255. Error messages always appear in the job log of the i5/OS job that ran the command, and may also be sent to standard output or standard error (unless option <strong>-q</strong> is specified).</p>
|
|
<p>If CL command processing did not send an exception message, the <strong>system</strong> utility returns the exit status set by whatever program the the CL comand called, or zero if that program did not set exit status.</p>
|
|
<br>
|
|
<p>
|
|
<strong>Examples</strong>
|
|
</p>
|
|
<p>
|
|
This example shows three ways to run the <strong>CRTDTAARA</strong> CL command with the same
|
|
parameter values. Options <strong>-bOE</strong> force CCSID conversion for standard output and
|
|
standard error (but not standard input). The "*char" parameter value must be quoted to prevent
|
|
the i5/OS PASE shell from expanding it as a set of file names, and the TEXT parameter requires
|
|
two sets of enclosing quotes because it contains lowercase and embedded blanks:
|
|
</p>
|
|
<pre>
|
|
system -bOE "crtdtaara mydata *char text('Output queue text')"
|
|
or
|
|
system -bOE crtdtaara mydata "*char text('Output queue text')"
|
|
or
|
|
system -BOE crtdtaara mydata '*char' "text('Output queue text')"
|
|
</pre>
|
|
<p>
|
|
This example shows how the <strong>system</strong> utility can run the <strong>CALL</strong> CL
|
|
command to call a program that accepts two parameters. Option <strong>-i</strong> avoids the
|
|
overhead of creating an additional process to run the CL command. Since no other options are
|
|
specified, CCSID conversion is done for standard input, standard output, and standard error. The
|
|
called program sees the first parameter converted to uppercase (ARG1) and the second parameter
|
|
unchanged (arg2) because of the rules of CL:
|
|
</p>
|
|
<pre>
|
|
system -i "call mypgm (arg1 'arg2')"
|
|
</pre>
|
|
</body>
|
|
</html>
|
|
|