systemCL()--Run a CL Command for i5/OS PASE

Syntax

 #include <as400_protos.h>

 int systemCL(const char  *command,
              int         flags);

  Default Public Authority: *USE

  Library: Standard C Library (libc.a)

  Threadsafe: Conditional. See Usage Notes.

Note: This function can only be used in an i5/OS PASE program. See i5/OS PASE for more information about creating i5/OS PASE programs.

The systemCL() function runs a CL command.

Parameters

command

(Input) Pointer to a null-terminated string in the i5/OS PASE CCSID that specifies the CL command with any parameters.

flags

(Input) Specifies option flags that control how the CL command runs. flags is a bit-wise OR of any of the following values:

SYSTEMCL_MSG_STDOUT (0x00000001)	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).
SYSTEMCL_MSG_STDERR (0x00000002)	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).
SYSTEMCL_MSG_NOMSGID (0x00000004)	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.
SYSTEMCL_SPOOL_STDOUT (0x00000008)	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).
SYSTEMCL_SPOOL_KEEP (0x00000010)	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.
SYSTEMCL_FILTER_STDIN (0x00000020)	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).
SYSTEMCL_FILTER_STDOUT (0x00000040)	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.
SYSTEMCL_FILTER_STDERR (0x00000080)	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.
SYSTEMCL_SPAWN (0x00000100)	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.
SYSTEMCL_SPAWN_JOBLOG (0x00000200)	Forces the system to generate an i5/OS job log for the job submitted using option SYSTEMCL_SPAWN.
SYSTEMCL_ENVIRON (0x00000400)	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).

Authorities

No authority is needed to run the systemCL function, but the caller must be authorized to run the specified CL command.

Return Value

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.

If option SYSTEMCL_SPAWN is specified, the function result is the exit code from the spawned job (returned by the ILE waitpid function), which is non-zero if any error occurred.

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.

systemCL is only threadsafe in these two cases:

You use option SYSTEMCL_SPAWN and do not use SYSTEMCL_ENVIRON.
You only run threadsafe CL commands and do not use SYSTEMCL_SPAWN, SYSTEMCL_FILTER_STDIN, SYSTEMCL_FILTER_STDOUT, SYSTEMCL_FILTER_STDERR, or SYSTEMCL_ENVIRON.

You must set ILE environment variable QIBM_USE_DESCRIPTOR_STDIO 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 SYSTEMCL_FILTER_STDIN, SYSTEMCL_FILTER_STDOUT, and SYSTEMCL_FILTER_STDERR.

Processing for options SYSTEMCL_FILTER_STDIN, SYSTEMCL_FILTER_STDOUT, and SYSTEMCL_FILTER_STDERR creates ILE pthreads (not i5/OS PASE threads) for CCSID conversion in the process that calls the systemCL 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 systemCL function returns.

Many CL commands are not supported in a job with multiple threads. Processing for SYSTEMCL_SPAWN 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.

Processing for option SYSTEMCL_SPAWN uses the ILE spawn 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 fork function).

Processing for SYSTEMCL_ENVIRON 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 PASE_ENVIRON_CONFLICT. If PASE_ENVIRON_CONFLICT is not defined, the system defaults to adding the prefix when copying i5/OS PASE environment variables SHELL, PATH, NLSPATH, and LANG.

Processing for SYSTEMCL_ENVIRON 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 ILE_PATH, the value of this variable is used to set both ILE_PATH and PATH in the ILE environment.