gtpc2m76C/C++ Language Support User's Guide

system-Execute a Command

This function lets you run a TPF program segment under a new entry control block (ECB), wait for the program to be completed, and receive its exit status. You can also specify a standard input/output (I/O) stream using the system function. The ECB that calls the system function is also called the parent process; the new ECB that the system function creates is called the child process.

The child process runs in the same subsystem and on the same i-stream as the parent process when the parent process calls the system function.

Format

#include <stdlib.h>
int system(const char *string);

string
A specification of the program to be run, its parameters, and the files to be opened as standard streams.

The string argument has the following format:




Where:

name
The 4-character name of the TPF program segment to be run. The segment will be run in the same subsystem as the ECB at the time it calls the system function.

parm
A parameter string to be passed to name. Each parameter is delimited by 1 or more space characters.

< or 0<
Indicates redirection of the stdin stream.

> or 1>
Indicates redirection of the stdout stream. If the file exists, it is truncated to zero bytes.

2>
Indicates redirection of the stderr stream. If the file exists, it is truncated to zero bytes.

>> or 1>>
Indicates redirection of the stdout stream without truncation and with output appended to the end of the file.

2>>
Indicates redirection of the stderr stream without truncation and with output appended to the end of the file.

pathname
The name of the file from or to which the stream will be redirected.

The system function formats the string argument by removing and processing the redirections, and placing pointers to the name and parm strings into an argv array so that:

The system function then builds a parameter list that it passes to the entry point of the name program. This parameter list contains two parameters:

Normal Return

If the argument is a null pointer, the system function returns a value of 1. Otherwise, the system function returns the exit status that is returned when the child process exits. Table 16 lists the exit status for various ways that the child process can exit.

Error Return

If the system function detects an error in either the input string or in the running of the child process, it returns a value of -1 and sets errno to one of the following values:

EINVAL
The string parameter does not contain any nonblank characters (string must contain at least a program name) or it contains a vertical bar (|).
Note:
The TPF system reserves the use of vertical bars for possible future implementation of pipes between processes.

ETPFSYSERR
The child process exited because of a system error.

E2BIG
The string parameter is longer than 4094 bytes.

Table 16. Ways of Exiting a TPF Process and the Resulting Exit Status

How the Child Process Exits Exit Status Returned by system to Parent Process
return from the initial call to the main function. The returned value of rc (the return code)
exit(status) function The value of status
BAL EXITC RC=Rx The value contained in Rx
BAL EXITC (with no RC parameter) Indeterminate
abort() -1
Any system error that causes the ECB to exit -1, errno set to ETPFSYSERR

Programming Considerations

None.

Examples

The following example creates a new ECB that runs segment QRST. In the main function in QRST, argc will contain the value 4, argv[0] to argv[3] will contain pointers to the strings "QRST", "one", "two", and "three", stdin will read from "my.input", stdout will write to "my.output", and stderr will append to "error.log".

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <string.h>
 
int main(void)
{
    errno = 0;
    if (system("QRST one two three "
               "<my.input >my.output 2>>error.log") == -1 &&
        errno != 0)
    {
        printf("system() error:  %s.\n", strerror(errno));
        exit(8);
    }
    return 0;
}

Related Information

See Appendix E, Programming Support for the TPF File System for more information about TPF File System C Functions.