SYSTEM

Usage

CALL "SYSTEM"
    USING MY-COMMAND-LINE,
    GIVING EXIT-STATUS

Parameters

MY-COMMAND-LINE PIC X(n)	Contains the operating system command line to execute.
EXIT-STATUS Any numeric data item	Returns the called program's exit status.

Comments

The SYSTEM routine takes a parameter, which is submitted to the host operating system as if it were a command typed in from a terminal.

Some operating systems place limits on the length of a command-line string. Under Windows, the limit is 128 bytes. When you issue a SYSTEM call using a variable, make sure that the length of the variable doesn't exceed the operating system's limit.

The user's terminal is set to its default operating state before this command is run and is reset after it's complete. The runtime system waits for the command to complete.

Note: On Windows systems, if you append an ampersand (&) character to the command line, the program will run asynchronously. This should not be done for programs providing input files, but is often useful for programs processing output files.

The status of a call to SYSTEM is placed into EXIT-STATUS. This is usually the exit status of the executed program, or is -1 if the SYSTEM routine failed.

Here's an example of a call to SYSTEM. On a UNIX machine, you could display a directory listing of the /usr directory with the following command:

CALL "SYSTEM" USING "ls /usr"

If your machine is running Windows and you want to execute MS-DOS operating system commands via SYSTEM, you must pass the Windows command name, as well as the operating system command. Use the syntax shown in this example to execute the DIR command:

CALL "SYSTEM" USING 
     "CMD.EXE /C DIR"

Note: On older Windows versions (pre-Windows 7), you must substitute CMD.EXE with COMMAND.COM.

When CALL "SYSTEM" is used to initiate a program, it looks only for files with a .EXE extension. If you want to call a .COM or .BAT file, you must explicitly add that extension in your code. For example:

CALL "SYSTEM" USING 
     "CMD.EXE /C MYBATCH.BAT"

The SYSTEM routine is provided in source form as a sample of a C subroutine.

Note: This routine causes ACUCOBOL-GT to forget the contents of the user's screen. This is done because the command executed may display information on the screen that ACUCOBOL-GT is not aware of. Because of this, pop-up windows made after a call to the SYSTEM routine may not correctly restore the screen contents when they are closed. You can avoid this problem by re-initializing the screen after you call the SYSTEM routine. You can do this by erasing the screen or by closing a pop-up window that covers the entire screen.

If the command to be executed will not perform any screen I/O, then you can request the SYSTEM routine to retain ACUCOBOL-GT's memory of the user's screen. This will avoid the problem mentioned in the preceding paragraph. To do this, simply pass a second argument to the SYSTEM routine. This may be any parameter you choose. For clarity, we suggest that the second argument be the literal "NO IO".