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 capabilities of SYSTEM and C$RUN:
CALL "C$SYSTEM"
USING CMD-LINE, FLAGS
GIVING EXIT-STATUS
C$SYSTEM can be used to execute a program in Thin Client environments. To execute a program on the display host in a thin client environment, add the prefix "@[DISPLAY]:" to the name of any program that resides on the client machine. For Example:
C$SYSTEM "@[DISPLAY]:C:\notepad myfile.txt"
| 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. |
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.
Note: On UNIX machines, specifying CSYS-ASYNC with a program that tries to do input or output to the terminal is not supported.
|
| CSYS-NO-IO (value 2) | For character-based systems, the runtime normally sets the terminal to its default state prior to running the command, and
resets it back to the state needed by the runtime when the command finishes. This option ensures that the called application
runs correctly if the application uses the screen. However, CSYS-NO-IO also causes the runtime to "forget" the contents of
the screen. This happens because the command executed may display information on the screen that ACUCOBOL-GT is not aware
of. Because of this, windows created after a call to C$SYSTEM may not correctly restore the screen contents when these windows
are closed. You can avoid this problem by re-initializing the screen after C$SYSTEM returns. You can do this by erasing the
screen or closing a floating or pop-up window that covers the entire screen (the window must have been created by the C$SYSTEM
call).
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". |
| CSYS-DESKTOP (value 128) | This option is for applications running in the thin client environment. It indicates that the application wants to run the
command on the client system rather than the application server. When the command executes, unless the CSYS-ASYNC option is
also specified, the thin client appears to "hang" while the application waits for the command's termination status. This behavior
can be avoided with the CSYS-ASYNC flag. The CSYS-ASYNC flag causes the command to be run asynchronously.
If CSYS-DESKTOP is specified but the calling program is not running under thin client, the flag is ignored and the command is run on the same machine as the calling application. |
| CSYS-INHERIT-HANDLES (value 256) | This option causes the new process to inherit each inheritable handle owned by the calling process. This includes
stdin,
stdout,
stderr, and other file handles that the calling process has open.
Note that because the called process inherits many open files, it is vulnerable to running out of file handles. This option is needed when an Alternate Terminal Manager runtime calls C$SYSTEM to run a batch program which in turn calls another Alternate Terminal Manager runtime. Without this option, the called program will not display any output to the screen. |
The C$SYSTEM routine submits CMD-LINE to the host operating system as if it were a command keyed in from the terminal. The maximum allowable length for the command line is 1024 bytes.
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 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.