This routine combines the functionality of "SYSTEM" and "C$RUN". It allows you to run other programs from inside a COBOL application in a variety of ways.
C$SYSTEM adds the following capabilities to the original functionalities of SYSTEM and C$RUN:
1. Uniform programming interface for all options
2. Asynchronous operation (C$RUN) added to UNIX hosts
3. Windows hosts can specify minimized, maximized, or hidden windows
4. Smart shell selection for Windows and Windows NT
Usage
CALL "C$SYSTEM" USING CMD-LINE, FLAGS
GIVING EXIT-STATUS
Parameter
CMD-LINE PIC X(n)
Contains the operating system command line to execute.
FLAGS Numeric unsigned (optional)
Supplies the options for the operation. If omitted, acts as if "0" was specified.
EXIT-STATUS Any numeric data item
Returns the called program's exit status.
Comments
The "C$SYSTEM" routine submits CMD-LINE to the host operating system as if it were a command keyed in from the terminal. The length of the command that you can specify is limited depending on the host system, as follows:
Extended DOS 123 bytes
Windows 126 bytes
Other 1024 bytes
The FLAGS field specifies various options about how the command should be run. Determine the value of the FLAGS field by adding together the values corresponding to the following options:
CSYS-ASYNC (value 1): This option causes the command to run independently of the COBOL program. After starting the command, the COBOL program continues. When this option is specified, EXIT-STATUS returns undefined results. When this flag is not used, the COBOL program waits for the command executed to finish before the COBOL program continues. CSYS-ASYNC is functional only on Windows and UNIX systems.
If the command to be executed will not perform any screen I/O, then you can request that C$SYSTEM retain ACUCOBOL-GT's memory of the original screen by using the CSYS-NO-IO option. This will avoid the problem described above. The option has no effect in Windows, where the command runs in its own window.
CSYS-MAXIMIZED (value 4): This option causes the command to run in a maximized window. This is functional only when you are running under Windows.
CSYS-MINIMIZED (value 8): This option causes the command to run in a minimized window. In addition, the COBOL program remains the active program retaining the keyboard focus and keeping the active appearance. This is functional only when you are running under Windows.
CSYS-COMPATIBILITY (value 16): This option causes the command to run in a window that is compatible with the way the SYSTEM library routine works. Use this option if you want to modify a call to SYSTEM and change this call to C$SYSTEM. There are very few differences between the default behavior of SYSTEM and C$SYSTEM, so this option is rarely needed. The only known difference involves the Microsoft Word application. If you use SYSTEM to start Microsoft Word, it always starts in a "normal" sized window, that is, the window size suggested by Windows. If you use C$SYSTEM to start Microsoft Word (with no FLAGS specified), then Word adopts the last window size it previously used. Supplying a flag of CSYS-COMPATIBILITY causes C$SYSTEM to behave the same as SYSTEM. Of course, if you prefer the behavior of C$SYSTEM, the flag should not be used. In comparison with SYSTEM, C$SYSTEM generally conforms more closely to the way Windows itself launches programs. The CSYS-COMPATIBILITY flag is recommended only if you change a SYSTEM call to a C$SYSTEM call and you observe a difference you do not like.
CSYS-HIDDEN (value 32): This option runs the command in a hidden window. Note that some applications, particularly those that routinely interact with the user, may get confused if you "hide" the command. This works well, however, for executing system tasks that do not have a user interface, such as executing a batch file that renames a series of files. This option is functional only when you are running under Windows.
CSYS-SHELL (value 64): When this option is specified, C$SYSTEM uses the host's command line processor (the host's shell) to execute the command. Otherwise, the command may be executed without the command line processor. This option affects only Windows (non-Windows versions always use the host's shell). For Windows applications that create their own windows, you should avoid using the shell - the application will not receive the initial window size request specified in FLAGS. For ".COM" and ".BAT" programs, and other built-in shell commands such as COPY and DIR, you must use the shell or the command may not execute.
The effect of this option is to prefix the command with the value of the COMSPEC environment variable and " /C ". Under Windows, this will usually result in a prefix like "C:\COMMAND.COM /C ". Under Windows NT, the prefix will typically be "CMD.EXE /C ".
You should specify only one window size flag (CSYS-MAXIMIZED, CSYS-MINIMIZED, CSYS-COMPATIBILITY, or CSYS-HIDDEN). In the absence of any window size flag, the command runs in a "normal" window whose size is determined by the operating system. Windows programs can set their own window size. This will override the window size suggested by FLAGS. Essentially, the value of FLAGS is only a "suggestion" to the application. You can find possible values of FLAGS in "acucobol.def".
Options that are not meaningful to the host system are ignored. Meaningful options in the same FLAGS setting are still applied.
The status of a call to C$SYSTEM is placed in EXIT-STATUS. This is usually the exit status of the executed program, or is "-1" if C$SYSTEM failed. Note that MS-DOS and Windows will return "-1" from commands that are built into COMMAND.COM because COMMAND.COM does not return an exit status for built-in functions.