system - Run a CL command for i5/OS PASE

Syntax

  system [-beEhiIkKnOpqsv] CL-command [ CL-parameters ... ]

Description

The i5/OS^R PASE system 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).

You need to set ILE environment variable QIBM_USE_DESCRIPTOR_STDIO 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 QP2TERM uses to run i5/OS PASE shells and utilities.

Options

-b

Force binary mode for standard streams used by the CL command. When this option is omitted, the system 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 -E, -I, and -O.

-e

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.

For most variables, the copy has the same name as the original, but the system adds a prefix "PASE_" 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 PASE_ENVIRON_CONFLICT, or the system defaults to adding the prefix when copying i5/OS PASE environment variables SHELL, PATH, NLSPATH, and LANG.

Any i5/OS PASE environment variable name with a prefix "ILE_" 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 ILE_PATH, the value of this variable is used to set both ILE_PATH and PATH in the ILE environment.

-E

Force CCSID conversion for the standard error stream used by the CL command. When this option is specified, the system 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 -b for the standard error stream.

-h

Write a brief description of allowable syntax for the system command to standard output.

-i

Run the CL command in the same process (i5/OS job) where the system utility runs. When option -i is omitted, the CL command is run in a separate process (created using the ILE spawn 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.

-I

Force CCSID conversion for the standard input stream used by the CL command. When this option is specified, the system 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 -b 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 system 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.

-k

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 -i has no effect when option -s is used.

-K

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.

-n

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. -n suppresses the message identifier, so only "message text" is written to the stream. Option -n has no effect when option -q is used.

-O

Force CCSID conversion for the standard output stream used by the CL command. When this option is specified, the system 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 -b for the standard output stream.

-p

This option is ignored. The i5/OS PASE system utility always handles only messages sent to the program that runs the CL command (the way the QShell system utility works with option -p).

-q

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.

-s

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.

-v

Write the complete CL command string to standard output before running the CL command.

Operands

CL-command is concatenated with any CL-parameters 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).

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 system utility.

Exit status

If any exception message is sent by the CL command analyzer or the command processing program, the system 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 -q is specified).

If CL command processing did not send an exception message, the system utility returns the exit status set by whatever program the the CL comand called, or zero if that program did not set exit status.

Examples

This example shows three ways to run the CRTDTAARA CL command with the same parameter values. Options -bOE 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:

      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')"

This example shows how the system utility can run the CALL CL command to call a program that accepts two parameters. Option -i 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:

      system -i "call mypgm (arg1 'arg2')"