SAS/C Library Reference, Vol. 1

system -- Execute a System Command

SYNOPSIS

 #include <stdlib.h>

 int system(const char *cmd);

DESCRIPTION

The system function executes a character string as a command by passing it to an operating-system-defined command processor. The cmd argument is a pointer to the command string, which consists of two parts: a prefix that contains an optional command type followed by a colon and a command.

Note: The case of the command name or its arguments or both may be significant, depending on the operating system and the command being executed.

RETURN VALUES

The system function returns an integer status code indicating the success or failure of the command. The status code for a successful command is normally 0. If called with a NULL argument, system returns 1 to indicate that command processing is available.

In the 370 implementation, the status code is normally the return code (or completion code) of the invoked program or command, unless an error is detected by the system function itself.

Certain status codes returned by system have special significance. These codes are given symbolic names by the header file <lclib.h>. Here are the names of these codes and their meanings:

SYS_ATTN: indicates the command was terminated by attention.
SYS_ABTM: indicates the command was abnormally terminated.
SYS_CUNK: indicates an unknown command.
SYS_CSYN: indicates a command syntax error.
SYS_INF: indicates a system interface failure.
SYS_TNAC: indicates the specified command environment was not active.
SYS_TSYN: indicates a command-type syntax error.
SYS_TUNK: indicates an unknown command type.
SYS_CHILD: indicates a problem creating an OpenEdition child process.

Some of these codes are meaningful only for one operating system, and the situations in which they are returned are dependent on the operating system.

CAUTION

If the TSO: prefix is used with the system function, unpredictable results may occur under MVS/XA when running in 31-bit addressing mode and TSO/E is not installed. (In this case, TSO commands cannot be invoked with the system function.)

Use system with the TSO: prefix in 31-bit mode programs only if TSO/E is installed.

DIAGNOSTICS

Errors in the command string can generate library messages, operating-system messages, or both.

PORTABILITY

The format of the command string and the meaning of the status code for system is completely system dependent, and it is unlikely that a program calling system can be moved to another system without modification.

system is a POSIX.2 function.

IMPLEMENTATION

MVS

Under MVS, system can use a prefix of PGM:, TSO: or SH:. If the prefix is omitted, SH: is assumed if the program was compiled with the posix option; otherwise, PGM: is assumed. For programs compiled with the posix option, the argument to system is always assumed to be a shell command, even if it appears to have an explicit prefix. To use the PGM: or TSO: prefix in a posix-compiled program, you must precede the prefix with "//", for example, system("//PGM:IEFBR14"). The "//" prefix is recognized whether or not a program is compiled with the posix option to enable you to write subroutines that call system and can be used in both posix-compiled and non-posix-compiled programs. The effect of using the PGM: and TSO: prefixes follows:

If the prefix PGM: is specified or defaulted, the first token of the command string is interpreted as the name of a load module and the remainder as a PARM string. For example, the following statement calls the load module IEBUPDTE, passing the PARM string "NEW":
```
 rc = system("PGM: IEBUPDTE NEW");
 
```
To put it another way, IEBUPDTE is called in the same way that it is called by the following JCL statement:
```
 // EXEC PGM=IEBUPDTE,PARM='NEW'
 
```
The PARM string always begins with the character after the separator following the program name.
When you use the TSO: prefix, the first token in the command string is invoked as a TSO command, with the rest of the string as its arguments. The system function can be used to invoke TSO CLISTs or REXX EXECs, provided that the CLIST ATTN statement is not used. (If this statement is used and an attention interrupt occurs, the results are unpredictable.)

It is recommended that a program that calls system using the TSO: prefix be executed as a TSO command. When a C program calls system to execute a TSO command, the library must locate TSO interface information, which is readily available to programs that have been called as commands. For programs that are not called as commands, this information must be extracted from unprotected system-control blocks. Because these control blocks are unprotected, it is possible for a malfunctioning TSO program (either the C program or one executed earlier) to overlay this information. Any attempt to execute a TSO command using the corrupted control blocks may result in a program ABEND, involuntary logoff, or incorrect results.

Under TSO, if an attention interrupt occurs during a call to system, the called program or command is immediately terminated.

When running with TSO/E Release 1.3 or higher under MVS/XA or MVS/ESA, system uses the TSO service routine IKJEFTSR to invoke TSO commands, CLISTs, or EXECs. This interface enables an unauthorized program to call commands that require authorization.

The IKJEFTSR interface is sensitive to TSO release and maintenance levels, and it can behave differently from release to release. You should be aware of these points:

For TSO/E Release 2 or greater, no message is produced when an attempt is made to execute a CLIST that cannot be located. The error is indicated by a return code of SYS_CUNK from the system. For earlier releases, the operating system generates the message COMMAND NOT FOUND in this situation, and system returns a code of 12.
If you use system to invoke the TSO CALL command, and any subtask of the called program terminates abnormally, all tasks of the called program are immediately terminated, and system returns with a code of SYS_ABTM.
For Versions 1.3 and 1.4 of TSO/E, IKJEFTSR creates a parallel terminal monitor program (TMP) to execute commands. For this reason, TASKLIBs defined for the executing C program are not available to the parallel command. If you are executing the CALL command, only the library specified by the CALL command is used as a TASKLIB. For Version 2 of TSO/E, this does not apply unless either the calling or the called program is authorized. For more information on IKJEFTSR, refer to the IBM publication, TSO Extensions Programming Services, (SC28-1875).
Do not use the system function to invoke C programs that use ISPF services. The attention handling of ISPF overrides the SAS/C library's attention handling, and you may be unable to use an attention interrupt to terminate the called program. ISPF applications should be invoked by the ISPF SELECT service.

OpenEdition

In addition to its use for invoking MVS load modules and TSO commands, you can use the system function to invoke shell commands if OpenEdition is installed and available.

Note: If a program uses any OpenEdition features, such as HFS files or POSIX signals, you should not use the system function prefixes PGM: or TSO: to invoke another program that also uses OpenEdition. OpenEdition will treat both programs as comprising a single process, which can cause confusing behavior in file access, signal handling, and other areas. In general, use the system function with the SH: prefix or the oeattach function to invoke one OpenEdition application from another.

For programs that are not compiled with the posix option, invocation of a shell command is requested by prepending the command name with the prefix "SH:". For instance, for a non-POSIX-compiled program, the call system("SH:ps -e") invokes the shell command "ps" with the argument string "-e".
For programs that are compiled with the posix option, all calls to system are treated as "SH:" style, unless the argument string begins with the escape characters "//". Thus, for programs compiled with the posix option, the call system("ps -e") invokes the shell command ps, while the call system("//pgm:iefbr14") invokes the MVS load module IEFBR14.
As with filenames, the "//" prefix is recognized whether or not a program is compiled with posix, so that the form system("//SH:ps -e") can be used to call a shell command regardless of the compilation mode of the program.
When the system function is called to invoke a shell command, it does so by forking a child, which then calls one of the exec programs from the shell to run the command. This is in accordance with the POSIX 1003.2 definition of the system function. If the program catches the SIGCHLD signal, an instance of this signal is raised as a result of the termination of the shell invoked by the system function; therefore, the program must be prepared to deal appropriately with the signal. Note that the system function temporarily ignores the POSIX SIGINT and SIGQUIT signals when it invokes the shell, as required by the 1003.2 draft standard.
When system is called to invoke a shell command, it invokes the file /bin/sh, which is normally the OpenEdition shell. If the OpenEdition shell is not installed, /bin/sh may be some other shell, or it may not exist. If /bin/sh does not exist, system invokes the program defined by the user's uid definition as the initial user program. If this program (or /bin/sh) is not a POSIX-conforming shell program, the behavior of a POSIX-conforming program that uses system may deviate from the standard.

If the system function is successful at calling a shell command, its return value is the exit status code of the shell, which can be interpreted by the <wait.h> macros such as WEXITSTATUS and WTERMSIG. If no child process can be created, system returns - 1, which is given the symbolic name SYS_CHLD in <lclib.h>.

CMS Under CMS, system can use a prefix of CMS:, CP:, SUBSET:, or XEDIT:. If the prefix is omitted, CMS: is assumed. The prefix can also be preceded by "//" for MVS compatibility. These paragraphs describe the effects of each of these prefixes:

The CMS: prefix has no effect, and the command string is executed as if it were entered from the command line.
system issues the command with the CMS command-search function, which uses the entire CMS command-search hierarchy. (See the VM/ESA CMS User's Guide for more information.) For example, the IMPEX and IMPCP settings are respected. The command string does not have to be uppercase when you use the CMS: prefix.
The system function always passes both tokenized and untokenized parameter lists to the command. Be careful not to use system to invoke a program that runs in the user area if the calling program is already running in the user area.
If you use the CP: prefix, system assumes the command is a CP command and assures that CP is called explicitly.
system uppercases the command and issues it with DIAGNOSE X'08'. In this example, the calls to system are not the same:
```
 rc = system("CP Q DASD");
 rc = system("CP:Q DASD");
 
```
The first call invokes the CMS command CP and the second call invokes DIAGNOSE X'08'.
A command with the SUBSET: prefix is not executed unless it is a CMS SUBSET command. Commands other than SUBSET cause system to return SYS_CUNK. Using the SUBSET: prefix prevents CMS user area commands from overlaying the C program if the C program is already running in the user area. For more information about the CMS SUBSET command, refer to the appropriate IBM publication.
If you use the XEDIT: prefix is used, system issues the command as an XEDIT subcommand. If XEDIT is not active, system returns SYS_TNAC.

If the command prefix is unknown (that is, it is not one of the prefixes listed here), it is treated as the name of a subcommand environment. A subcommand environment is a program that has been named with the CMS SUBCOM function. If the subcommand environment is active, the command is transferred (with the CMS command search function) to the subcommand environment. If the subcommand environment is not active, system returns SYS_TNAC. For more information about subcommand environments, refer to the appropriate IBM publication.

EXAMPLE

This example creates a new PDS named EXAMPLE.OUTPUT and writes member README. If the PDS already exists, it is not changed.

  #include <stdlib.h>
  #include <stdio.h>

  main()
  {
     int sysrc;
     FILE *readme;

     puts("Calling the TSO allocate command to create EXAMPLE.OUTPUT");
     sysrc = system("tso: allocate da(example.output) new sp(1 1) tr "
                    "dir(1)");       /* Allocate example.output NEW. */
     if (sysrc != 0){
           puts("Unable to allocate EXAMPLE.OUTPUT. File probably "
                "already exists.");
           exit(EXIT_FAILURE);
     }
     readme = fopen("tso:example.output(readme)", "w");
     fputs("This file was created by a SAS/C example program.n",
            readme);
     fclose(readme);
     exit(EXIT_SUCCESS);
  }

RELATED FUNCTIONS

fork, oslink, popen