EXECUTE

ANSI

The EXECUTE instruction temporarily suspends program execution while performing another system function or program. Upon completion of the specified task, program execution resumes with the instruction following the EXECUTE statement. The instruction uses the following format:

[label]

EXECUTE

{command}[,{os}[,{keyword}]]

Where:

label

Optional. A Program Execution Label.

command

Required. A previously defined Character String Variable, a string Literal, or ARRAY element containing the command line that is executed.

Required. A previously defined Character String Variable that is ignored by the runtime.

keyword

Optional. A keyword from the table below.

Flags Affected: OVER

Note the following:

If {command} is a string variable, only the Logical String is used. Prior to runtime version 10.3A, the {command} string maximum length is 512 characters. Starting with version 10.3A, the {command} string maximum length is 4096 characters.
If {command} is a string literal, it may be continued on additional lines by ending the line with a colon pair (::).
A command line timeout character sequence may be specified as '[nnnnn]' at the beginning of the command. In this case, the 'nnnnn' specifies the number of seconds for a timeout that causes a child process to be terminated when the timeout expires. This timeout can avoid scenarios where the EXECUTE child process could hang indetinitely for some unknown reason.

Example:

EXECUTE "[240]c:\sunbelt\plbwin.102A\code\plbwin.exe program.plc"

The [240] timeout identifier allows the PL/B EXECUTE instruction to terminate the child process executing the 'program.plc' if it takes longer than four minutes to finish.

The optional {os} parameter is provided for language compatibility only and is ignored by the runtime. A warning message is displayed if the parameter is specified.
The optional {keyword} parameter must be one of the following values:

Keyword	The operation of the verb
FOREGROUND	does not change.
BACKGROUND	is the same as the BATCH verb. Note that BATCH is not supported for all OS environments.

The currently executing program is suspended with all variables, pointers, file conditions/pointers and Flags intact. The specified command line is executed and upon its completion, the program resumes at the next instruction following the EXECUTE.
The current screen display, including the attributes and cursor position, is neither saved nor restored by the EXECUTE instruction. Even if the command line that is executed does not provide any screen output, the operating system may arbitrarily force a line feed to the screen. Therefore, logic must be included to restore the screen status after an EXECUTE, if it is desired. A *SAVESW screen control prior to the instruction and a *RESTSCR control following it saves and restores the screen to the original state.
If the command line passed to the operating system generates undesired screen output, the screen output can be redirected to a file or to the operating system null device. This allows the current display to remain unchanged. This is accomplished as follows: Append a greater than sign `>' and the file or null device name to the command line (i.e., `> /dev/null' for Linux or `> NUL' for MS-DOS). If the screen output is re-directed to a file, the destination file may then be interrogated to determine the result of the task. Non-operating system controlled screen output (i.e., direct video RAM operations such as used by the window/sub-screening screen definition files in SUNDB86x) cannot be redirected since they bypass the operating system.
The suspended program is not unloaded from memory.
If the command fails to execute when using PLBWIN or SUNDB86A, EXECUTE automatically attempts to run the command using the current COMSPEC keyword if available.
If the command line given is a Null String, and the following conditions are met, the user is placed at the operating system level until the command `exit' is entered at a command prompt:

SUNDB86x and PLBWIN interrogate the User's Environment Table for a COMSPEC entry designating the COMMAND.COM to reload. If a COMSPEC entry is not found, the instruction fails.
PL/B:Linux interrogates the User's Environment Table for a SHELL entry designating the shell to load. If a SHELL entry is not found, the default Linux shell `/bin/sh' is used.

Under MS-DOS, the program that is executed may be another PL/B program or any other .EXE, .COM or .BAT file. Execution of shell intrinsic commands (dir, type, etc.) requires the user to specify the shell in the command line.
Under Linux, the program that is executed may be another PL/B program (if the program name is preceded by the name of the runtime), an executable program, or shell script.
It is possible to use the EXECUTE instruction to enter or change subdirectories without affecting the file status in the previous directory, provided the files in the previous directories may still be OPENed.
Programs that modify the memory allocation should not be performed by or during an EXECUTE. Such activity may cause indeterminate results.
Any data files open at the time of the EXECUTE should not be modified or the results may be indeterminate.
ROLLOUT should not be performed in a program invoked via an EXECUTE instruction.
When an EXECUTE is performed in a GUI environment, a new process is created for which the command is run. If an exclamation character (!) starts the command line, the process is started in an iconized state. If no extension is given on the command to execute, only .EXE and .PIF files are searched for the correct file to execute. When a process is executed in an iconized state, the .PIF file controlling the process should be changed to allow execution in the 'background'.
If a FILEPI instruction is active at the time of the EXECUTE instruction, the FILEPI is terminated.
The OVER flag is set if the program is unable to perform the EXECUTE.
EXECUTE is not supported by the PLBCE runtime.
When using the EXECUTE instruction in a PLBCLIENT/PLBSERVE application, this instruction does not execute at the client and does not show any command shell windows at the client. In this case, the EXECUTE instruction is only executed at the Application Server.