OS.EXECUTE

The OS.EXECUTE statement executes an operating system command.

Format

OS.EXECUTE expr {CAPTURING var} {SILENT}

where

The OS.EXECUTE statement allows a QMBasic program to execute an operating system command. The program does not continue execution until the command terminates. QM attempts to redirect any output from the command back to the user's terminal but this is not always possible. Some commands may cause output to appear on the server system.

The CAPTURING clause captures output that would otherwise have gone to the terminal or phantom log file, saving it in the named variable with field marks in place of newlines. Alternatively, all command output can be suppressed by use of the SILENT clause.

The OS.EXECUTE statement returns two error codes. The STATUS() function returns a non-zero value if QM detected an error and was unable to execute the command. For a zero STATUS() value, the OS.ERROR() function returns the termination status of the executed command. The interpretation of this value will depend on the command being executed.

If the command to be executed on a Windows ECS mode system contains characters outside the 8-bit set, it is necessary to create a .bat file that starts with

chcp 65001

to select Unicode mode followed by the commands to be executed. The OS.EXECUTE statement should then reference this .bat file.

Example

OS.EXECUTE "MKDIR TEMPDIR"

This statement uses the operating system MKDIR command to create a directory named TEMPDIR.

Quoting on Windows systems

There is a well documented problem in Windows where command lines that need multiple sets of double quotes are not handled reliably. A command that references the Windows Program Files directory must include quotes around the pathname because it contains a space. Thus a command to be executed by OS.EXECUTE might be something like

“C:\Program Files\XXX\YYY.EXE” AAA BBB

where the pathname of the executable needs quotes.

Conversely, a command might need to quote arguments that contain quotes

MYPROG.EXE  “AAA BBB”

The problem occurs when there is a need to do both together

“C:\Program Files\XXX\YYY.EXE” “AAA BBB”

which looks as though it should work but actually fails with an error indicating that C:\Program is not a valid executable name.

The only reliable solution appears to be to write the command out to a batch (.bat) file and then use OS.EXECUTE to run that. The steps to do this might be something like

OPEN '$ACC' TO ACC.F THEN

  SCRIPT.NAME = 'MYSCRIPT' : @USERNO : '.BAT'

  SCRIPT = '"C:\Program Files\XXX\YYY.EXE” “AAA BBB”’

  WRITE SCRIPT TO ACC.F, SCRIPT.NAME

  OS.EXECUTE SCRIPT.NAME

  DELETE ACC.F, SCRIPT.NAME

  CLOSE ACC.F

END

Note the use of @USERNO to ensure that the script name is unique across multiple QM sessions.