IBM PASE for i system utility

The PASE for i system utility runs a CL command. By default, any spooled output produced by the command is written to standard output; any messages sent by the command are written to standard output or standard error (depending on whether the CL command sends an exception message).

To avoid unpredictable results, set the ILE environment variable QIBM_USE_DESCRIPTOR_STDIO to Y or I so that PASE for i run time and ILE C run time use descriptor standard I/O. This variable is set to Y or I by default in the IBM® i jobs that the QP2TERM program uses to run PASE for i shells and utilities.

Syntax

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

Options

-b

Force binary mode for standard streams used by the CL command.

When this option is omitted, the system command converts any data that the CL command reads from standard input from the PASE for i CCSID to the job default CCSID. The system command converts data written to standard output or standard error from the job default CCSID to the PASE for i CCSID. This option avoids CCSID conversion for all standard streams except those associated with option -E, -I, or -O.

-e

Copy PASE for i environment variables to ILE environment variables before running the CL command.

When this option is omitted, no ILE environment variables are set, and the ILE environment might have missing variables or might have different variable values from the PASE for i environment.

For most variables, the copy has the same name as the original, but the system adds the prefix PASE_ to the name of the ILE copy of some environment variables. By default, the system adds the prefix when copying PASE for i environment variables SHELL, PATH, NLSPATH, and LANG. To control what variables the name prefix is added to, store a colon-delimited list of variable names in the PASE for i environment variable PASE_ENVIRON_CONFLICT.

Any PASE for i environment variable names with the prefix ILE_ are 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 PASE for i environment contains a variable named ILE_PATH, the value of this variable is used to set both the ILE_PATH and PATH variables 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 that the CL command writes to standard error from the job default CCSID to the PASE for i 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 (IBM i job) where the system utility runs.

When option -i is omitted, the CL command is run in a separate process that is created using the ILE spawn API. This separate process is not multithread-capable unless you set the ILE environment variable QIBM_MULTI_THREADED to Y. 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 that the CL command reads from standard input from the PASE for i 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. This is because the 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 might leave the standard input stream positioned beyond what the CL command read.

-k

Keep all spooled files generated by the CL command.

When this option is omitted, spooled output files are deleted after their contents are written as text lines to standard output. Option -i has no effect when option -s is used.

-K

Force a job log for the IBM i job where the CL command runs.

If this option is omitted, a job log can only be produced if an unexpected error occurs.

-n

Do not include IBM i message identifiers in any text line that is 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 IBM i predefined messages is XXX1234: message text, where XXX1234 is the IBM i 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 that the CL command writes to standard output from the job default CCSID to the PASE for i CCSID. This option overrides option -b for the standard output stream.

-p

This option is ignored.

The PASE for i 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 IBM i 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 PASE for i CCSID, and written as text lines to standard output or standard error, depending on whether the CL command sends 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 PASE for i CCSID and written to standard output. 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 need to enclose CL command and parameter values in quotation marks to prevent the PASE for i shell from expanding special characters (such as parentheses and asterisks).

If a CL command parameter value requires quotation marks (such as a text parameter with lowercase characters or embedded blanks), you must specify those quotation marks inside a quoted string. This is because PASE for i shells remove the outer quotation marks from any argument that is passed to the PASE for i system utility.

Exit status

If any exception message is sent by the CL command analyzer or by the command processing program, the system utility returns an exit status of 255. Error messages always appear in the job log of the IBM i job that runs the command, and might also be sent to standard output or standard error unless option -q is specified.

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

Examples

The following example shows several 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 PASE for i shell from expanding it as a set of file names. The TEXT parameter requires two sets of enclosing quotation marks 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')"

The following example shows how the system utility runs 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. Because no other options are specified, CCSID conversion is done for standard input, standard output, and standard error. The called program sees the first parameter as converted to uppercase (ARG1) and the second parameter as unchanged (arg2) because of the CL rules.

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