systemCL()--Run a CL Command for IBM PASE for i

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 IBM^® i PASE program. See the IBM PASE for i topic collection for more information about creating IBM PASE for i programs.

The systemCL() function runs a CL command.

Parameters

command

(Input) Pointer to a null-terminated string in the IBM PASE for i 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 IBM i messages after normal command completion, convert the text of each message from the job default CCSID to the IBM PASE for i CCSID, and write converted text lines to Integrated File System descriptor 1 (stdout).

SYSTEMCL_MSG_STDERR (0x00000002)

Directs the system to receive IBM i messages after error command completion, convert the text of each message from the job default CCSID to the IBM PASE for i 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 IBM i 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 IBM PASE for i 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 IBM PASE for i 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 IBM PASE for i 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 IBM PASE for i 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 IBM i job log for the job submitted using option SYSTEMCL_SPAWN.

SYSTEMCL_ENVIRON (0x00000400)

Directs the system to copy IBM PASE for i 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 IBM i 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 the return code set by the command, or zero if the command does not set a return code, or -1 if the command throws an exception. No errno value is set for CL command errors.

Usage Notes

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 IBM PASE for i 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 unless you set ILE environment variable QIBM_MULTITHREADED=Y.
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 IBM PASE for i program (unlike a job created by the IBM PASE for i fork function).
Processing for SYSTEMCL_ENVIRON uses the same name for the ILE copy and the IBM PASE for i 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 IBM PASE for i environment variable PASE_ENVIRON_CONFLICT. If PASE_ENVIRON_CONFLICT is not defined, the system defaults to adding the prefix when copying IBM PASE for i environment variables SHELL, PATH, NLSPATH, and LANG.
Processing for SYSTEMCL_ENVIRON sets two ILE environment variables for each IBM PASE for i environment variable with a name prefix of "ILE_". The IBM PASE for i 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 IBM PASE for i 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.

API introduced: V4R5

[ Back to top | IBM PASE for i APIs | APIs by category ]