| Standards / Extensions | C or C++ | Dependencies |
|---|---|---|
ISO C |
both |
#include <stdlib.h>
int system(const char *string);The system() function has two different behaviors. These behaviors are designated as ANSI system() and POSIX system(). The ANSI system() behavior is based on the ISO C standard definition of the function, whereas the POSIX system() behavior is based on the POSIX standard definition. The ANSI system() behavior is used when a) running POSIX(OFF) or b) when running POSIX(ON) and environment variable __POSIX_SYSTEM is set to NO. Otherwise the POSIX system() behavior is used.
Using the ANSI system() function, you can call commands, EXECs, CLISTs, or executable modules under MVS and TSO/E. You cannot use the ANSI system() function to invoke z/OS® UNIX services shell programs.
The string argument can take one of the two formats:
command_name parm1 parm2 … system("user_pgm1 1234 abcd xyz");If the string argument is in the command-line format, the system() function passes the given string to the command processor, if available, for execution.
"PGM=program_name[,PARM='....']"system("PGM=user_pgm1, PARM='1234 abcd xyz'");If the string argument is a named-program format, the system() function calls program_name with the parameters following “PARM=”, if any.
The two formats are supported under both MVS and TSO/E, but not all targets can be called from all environments. For example, TSO/E commands cannot be called in an MVS environment. As a result, the two formats are equivalent under MVS, but are different under TSO/E. The details of each are provided below. For maximum portability when invoking executable modules under the different environments, use the named-program format.
If the specified executable module is a z/OS XL C or z/OS XL C++ module, full initialization and termination will be performed: including, but not limited to, automatic closing of files and releasing of fetched modules. In addition, if the ANSI system() call uses the named-program format under either MVS or TSO/E, or the command-line format under MVS, information can be passed across the program boundary using memory files. Memory files are not removed until either the highest level (root) program in the call chain terminates or the clrmemf() function is used. Standard streams are also shared in this environment.
ANSI MVS considerations: Under MVS, the ANSI system() function accepts either command-line or named-program format strings. However, the command-line string is restricted to specifying only executable modules (that is, TSO/E commands, EXECs, and CLISTs cannot be specified). Because of this restriction, both formats provide the same functionality.
In the case of either a command-line or named-program string, the ANSI system() function will search the usual MVS sources (STEPLIB/JOBLIB concatenation, Link Pack Area (LPA), Extended Link Pack Area (ELPA), and the link libraries) for the specified program name. The LINK SVC is used to give control to the program.
Under MVS, using ATTACH instead of ANSI system() will prevent you from sharing memory files or standard streams between the programs.
ANSI TSO/E considerations: Under TSO/E, the ANSI system() function accepts either command-line or named-program format strings.
Therefore, if a command-line format string is used and a CLIST or EXEC exists with the same name as a TSO/E command or user module, the TSO/E EXEC command must be used to specifically invoke the CLIST or EXEC.
If the command-line format string is used to call a user module, it effectively uses ATTACH to execute the program. As with MVS, when using ATTACH, memory files and standard streams are not shared between the programs. This is the reason that named-program format strings should be used for maximum portability. The named-program format provides the same memory file and standard stream sharing in both the MVS and TSO/E environments.
Named-program format strings are not presented to the TSO/E command processor and can only be used to execute user modules.
POSIX system() function: Using the POSIX system() function, you can call z/OS UNIX services shell programs. You cannot use the POSIX system() function to call commands, EXECs, CLISTs, or executable modules under MVS and TSO/E.
The POSIX system() function passes string to the sh shell command for execution. The environment is established by the runtime library through a spawn() of the shell.
The POSIX system() function ignores the SIGINT and SIGQUIT signals, and blocks the SIGCHILD signal while it waits for the command specified by string argument to end.
stdin = fopen("/tmp/sys.stdin","r");
stdout = fopen("/tmp/sys.stdout","w");
stderr = fopen("/tmp/sys.stderr","w");Mixed environments across an ANSI system() call: The mixing of z/OS Language Environment®, C/370™ Library Version 1 or Version 2, and System Programming C (SPC) environments across a system() call is not supported. Whichever of these environments is active when the first system() call is made is the only one that is tolerated in the system() call chain. Results are undefined if this restriction is violated.
If the string argument is a NULL pointer, the system() function returns nonzero if a command processor exists, or 0 if one does not exist.
ANSI MVS considerations: The returned value from ANSI system() will be that from the user module, if successfully called. If system() cannot call the specified module, the returned value is -1 and errno is set appropriately.
ANSI TSO/E considerations: The returned value from ANSI system() will be nonzero if the command processor cannot execute the command or user module. The macros __abendcode and __rsncode will contain the abend code and reason code from a failing TSO/E command, EXEC, or CLIST.
POSIX considerations: If the string argument is a NULL pointer, the POSIX system() function returns nonzero. If the string argument is not NULL, the POSIX system() function returns the termination status of the command language interpreter in the format specified by waitpid(). If a child process cannot be created, or if the termination status for the command language interpreter cannot be obtained, system() returns -1.
If system() returns -1, errno may be set to one of the following:
/* This example illustrates how to use system() to execute a command which
returns the time. The example works only under TSO.
*/
#include <stdlib.h>
int main(void)
{
int rc;
rc = system("time");
exit(0);
}/* This example may only be used in a POSIX program. */
#include <stdlib.h>
int main(void)
{
int result;
result = system("date | tee result.log");
}