RUN

The RUN instruction executes the command passed as argument.

Syntax

RUN command 
  [ IN {FORM|LINE} MODE ]
  [ RETURNING variable | WITHOUT WAITING ]

command is a string expression with the command to be executed.
variable is an integer variable receiving the execution status of the command.

Understanding the RUN command

The RUN instruction hands the argument command to the command interpreter. When not specifying the WITHOUT WAITING clause, the calling process waits for the called process to finish execution. Otherwise, the calling process waits for the command termination.

RUN and GUI resources

When executing in GUI mode, resources such as images may be sent asynchroneously by fglrun to the front-end, typically at the beginning of the program execution.

If a RUN command is executed at this time, it will suspend the parent program execution and block the resource transfers.

Consider starting child programs with the RUN command, when the parent program is alive for a couple of seconds, to make sure that all GUI resources have been transmitted to the front-end.

Mobile applications

When running an embedded app on a mobile device (or emulator), the RUN cmd and

RUN cmd WITHOUT
WAITING

instructions are not supported. To implement apps running on a server, see the runOnServer front call.

Defining the command execution shell

In order to execute the command line, the RUN instruction uses the OS-specific shell defined in the environment of the current user:

On UNIX™, the shell program is defined by the SHELL environment variable.
On Windows®, the shell program is defined by COMSPEC environment variable, and this program must support the /c option (hardcoded).

Passing command-line arguments

The command provided to the RUN instruction can use arguments.

The next example will pass the -l option and 3 file names to the ls command:

RUN "ls -l file1 file2 file3"

In order to pass arguments containing blanks, use the single or double-quote argument delimiters. These delimiters can have different semantics depending on the used OS shell:

RUN 'ls -l "file name with spaces" '

Note: On Windows, when using the (default) COMSPEC CMD.EXE command interpreter, special consideration needs to be taken with double quotes in the command string. Depending on several conditions, the first and the last " quotation marks will be removed before executing the command string. This can lead to command execution failure, when arguments using space characters need to be enclosed in double quotes:

RUN '"C:\\Program Files\\Tools\\bin\\cleanup.exe" "C:\\tmp\\my dir"'

Above instruction will actually try to execute the following command:

C:\Program Files\Tools\bin\cleanup.exe" "C:\tmp\my dir

A typical workaround (on Windows only) is to surround the whole command again in double quotes:

RUN '" "C:\\Program Files\\Tools\\bin\\cleanup.exe" "C:\\tmp\\my dir" "'

See MSDN documentation for CMD.EXE details.

Using OS shell features

The command provided to the RUN instruction can use any possibilities supported by the OS shell, such as output redirection, chaining commands, etc:

RUN "grep -h name *.txt | sort -u > zz"

Waiting for the subprocess

By default, the runtime system waits for the end of the execution of the command, suspending the execution of the current program. After executing the command, the display of the parent program is restored.

If you specify WITHOUT WAITING, the specified command line is executed as a background process, and generally does not affect the visual display. This clause can be used when the command takes some time to execute, and the parent program does not need the result to continue. It is also typically used in GUI mode to start another program. Do not use this clause in TUI mode when the sub-program displays forms, otherwise both programs would run simultaneously on the same terminal.

Catching the execution status

The RETURNING clause saves the termination status code of the command that RUN executes in a program variable of type SMALLINT. Examine the variable after execution to determine the next action to take. A status code of zero usually indicates that the command has terminated normally. A non-zero exit status indicates an error.

Important:

The execution status provided by the RETURNING clause is platform-dependent.

On UNIX systems, the value is composed of two bytes having different meanings: The lower byte (x mod 256) of the return status defines the termination status of the RUN command. The higher byte (x / 256) of the return status defines the execution status of the program.
On Windows platforms, the execution status is zero for success, or a non-zero value if an error occurred: The value of the return status only defines the execution status of the program.

GUI rendering of child programs

When starting a new child program in GUI mode, different rendering options can be used to show the application windows. For example, the windows/forms of each application can be displayed in a tabbed container.

For more details, see Window container interfaces.

IN LINE MODE and IN FORM MODE

The IN {LINE|FORM} MODE clause of the RUN instruction defines how the dumb terminal behaves when running the child process. This clause has no particular impact on GUI front-ends, but should be considered when the same program can run in TUI or GUI mode.

Tip: A good practice is to encapsulate child program and system command execution in functions.

The concept of line mode / form mode comes from the TUI and tty terminal raw mode / cooked mode concept.

No matter if you are in TUI or GUI mode, run silent (batch) programs in form mode, and if the program to run is interactive, or displays messages to the terminal, or if you don't known what it does, use the line mode.

If no LINE/FORM MODE clause is specified in the RUN command, it defaults to the last OPTIONS IN FORM/LINE MODE setting, which is by default IN LINE MODE. However, as many UI instructions (such as OPTIONS) take the program into form mode, typical interactive programs are actually in form mode most of the time (they start in line mode and after the first UI instruction, they are in form mode)

Important: Executing an interactive Genero program with

RUN … IN FORM MODE
WITHOUT WAITING

(or with RUN … WITHOUT WAITING and the

FORM
MODE

is set by OPTIONS), can lead to unexpected behavior.

When the RUN statement specifies IN FORM MODE, the program remains in form mode, if it is currently in form mode, but it does not enter form mode if it is currently in line mode. When the prevailing RUN option specifies IN LINE MODE, the program remains in line mode if it is currently in line mode, and it switches to line mode, if it is currently in form mode. This also applies to the PIPE option of START REPORT.

To run another interactive program, you must use the line mode:

In TUI mode, the terminal is in the same state (in terms of tty options) as when the program began. Usually the terminal input is in cooked mode, with interrupts enabled and input not becoming available until after a newline character is typed.
In GUI mode, if the WITHOUT WAITING clause in used, the front-end is warned that a new interactive child program is started. If the RUN command waits for child termination (i.e. no WITHOUT WAITING clause is used), no particular action is taken by the parent fglrun to warn the front-end, and the new child fglrun will connect to the front-end.

To execute a subprocess running silently (batch program without output), you must use the form mode:

In TUI mode, the screen stays in form mode, if it was in form mode, which saves a clear / redraw of the screen. The form mode specifies the terminal raw mode, in which each character of input becomes available to the program as it is typed or read.
In GUI mode, no particular action is taken to warn the front-end (there is no need to warn the front-end for batch program execution).

Note: Besides RUN, the OPTIONS,

START
REPORT

and

START REPORT... TO
PIPE

instructions can explicitly specify a screen mode. With

START
REPORT

using PIPE specifications, the default screen mode is

IN
FORM MODE

Example

MAIN
  DEFINE result SMALLINT
  CALL runApplication("app2 -p xxx")
  CALL runBatch("ls -l", FALSE) RETURNING result 
  CALL runBatch("ls -l > /tmp/files", TRUE) RETURNING result 
END MAIN

FUNCTION runApplication(pname)
  DEFINE pname, cmd STRING
  LET cmd = "fglrun " || pname 
  IF fgl_getenv("FGLGUI") == 0 THEN
    RUN cmd 
  ELSE
    RUN cmd WITHOUT WAITING
  END IF
END FUNCTION

FUNCTION runBatch(cmd, silent)
  DEFINE cmd STRING
  DEFINE silent STRING
  DEFINE result SMALLINT
  IF silent THEN
    RUN cmd IN FORM MODE RETURNING result 
  ELSE
    RUN cmd IN LINE MODE RETURNING result 
  END IF
  IF fgl_getenv("OS") MATCHES "Win*" THEN
    RETURN result 
  ELSE
    RETURN ( result / 256 )
  END IF
END FUNCTION