Chapter Contents
Previous
Next
|
Chapter Contents |
Previous |
Next |
| system |
| Portability: | ISO/ANSI C conforming, UNIX compatible, POSIX.1 conforming |
| SYNOPSIS | |
| DESCRIPTION | |
| RETURN VALUE | |
| CAUTION | |
| DIAGNOSTICS | |
| PORTABILITY | |
| IMPLEMENTATION | |
| EXAMPLE | |
| RELATED FUNCTIONS | |
| SEE ALSO |
| 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.
| RETURN VALUE |
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:
| 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 |
Under OS/390,
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:
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");
// EXEC PGM=IEBUPDTE,PARM='NEW'
The PARM string always begins with the character after the separator following the program name.
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.
COMMAND NOT FOUND
in this situation, and
system
returns a code of 12.
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.
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.
In addition to its use for
invoking OS/390 load modules
and TSO commands, you can use the
system
function to invoke shell commands if USS is installed and available.
Note:
If a program uses any USS 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
USS. USS 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 USS application from another. ![[cautionend]](../common/images/cautend.gif)
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"
.
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 OS/390 load module IEFBR14.
"//"
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.
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.
system
is called to invoke a shell command, it invokes the file
/bin/sh
, which is normally the USS shell. If the USS 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>
.
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 OS/390 compatibility. These paragraphs describe the effects
of each of these prefixes:
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.
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'.
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.
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 |
#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 |
| SEE ALSO |
|
Chapter Contents |
Previous |
Next |
 Top of Page |
Copyright © 2001 by SAS Institute Inc., Cary, NC, USA. All rights reserved.