SYSTEM Routine

The SYSTEM library routine provides a method of executing an operating system command.

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 MS-DOS, 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.

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. (Note that on MS-DOS machines, the SYSTEM routine will return "-1" if you execute only commands that are built into COMMAND.COM, because MS-DOS does not return a status value for built-in functions. You'll receive a normal return value from programs loaded from disk.)

Here's an example of a call to SYSTEM. On an MS-DOS machine, you could print a directory listing of the C drive with the following command:

CALL "SYSTEM" USING "DIR C:"

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

CALL "SYSTEM" USING
     "COMMAND.COM /C DIR"

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
     "COMMAND.COM /C MYBATCH.BAT"

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

Note that this routine will cause 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 I-O".