SHELL

Execute the system command processor or create a subprocess

WTSupported in traditional Synergy on Windows

WNSupported in Synergy .NET on Windows

USupported on UNIX

VSupported on OpenVMS

xcall SHELL([shell], [command][, mode])

Arguments

shell

(optional) An expression indicating which shell to invoke. The following values are valid: (n)

command

(optional) A command line to be executed by the shell on Windows and UNIX, or a new CLI on OpenVMS. The maximum length is 1024 characters. (a)

mode

(optional) One or more of the following (Windows only): (n)

D_GAINFOCUS

Restore focus when the calling Synergy application resumes.

D_INHERIT

Allow subprocess to inherit handles such as standard input and output.

D_MINIMIZED

Start the program minimized.

D_NOACTIVATE

Don’t give the program keyboard focus.

D_NOCONSOLE

Prevent new console from being created for new processes. A new process inherits the parent’s console if possible.

D_NOWAIT

Let the program run asynchronously like RUNJB.

D_NOWINDOW

Prevent new console from being created for new processes. No DOS or command prompt window is displayed, not even on the task bar.

Discussion

The SHELL subroutine invokes a shell as a subprocess, which enables you to run more than one program simultaneously.

If command is specified, the command line is executed by the specified shell. If command is not specified, the shell specified by shell is invoked. If no arguments are specified, the default shell is invoked. (On Windows, the command prompt window appears.) Control returns to the calling program when the shell subprocess is finished.

If shell is not specified, the SHELL subroutine looks for the SHELL environment variable and uses that setting if it finds it. If the SHELL environment variable is not found, the SHELL subroutine uses the Bourne shell on UNIX or the default shell specified by the COMSPEC environment variable on Windows. If COMSPEC is not found, cmd.exe is used.

If you try to run more than the maximum number of processes, a “Too many processes” error ($ERR_MAXPRC) is generated.

On UNIX and OpenVMS, when using the Synergy windowing API, if screen attributes are set and a program calls the SPAWN or SHELL routines, escape sequences to turn off current attributes are sent to the screen.

SHELL on Windows

The default SHELL behavior is to start an interactive process with a window associated with it. The calling program is suspended until the requested task is completed. The mode D_NOWAIT specifies that no wait should occur. You can add the D_xxx options to combine any of the modes.

The shell set by COMSPEC does not return the exit status of the program run; therefore, if it follows SHELL, the XSTAT subroutine always reports zero.

D_NOACTIVATE and D_MINIMIZED are only effective when invoking a non-GUI program. D_NOCONSOLE eliminates the unnecessary console window that is created when invoking a GUI program. Note that when using D_NOCONSOLE, no command interpreter is invoked. Therefore, any commands that require shell functionality, like redirection, will not work. Use an OPEN statement with a pipe command instead.

On Windows, using the D_NOCONSOLE option with a command that is redirected to output may have unexpected results. Instead we recommend that you use a pipe command and READS to read through the output.

Command cannot contain a Synergy environment variable, as in “DBLDIR:lpque”, unless it’s being used as an argument to one of the Synergex-supplied programs or utilities (such as dbr, dbs, isutl, and so forth). If it’s not an argument to one of these, you must translate the environment variable using the GETLOG subroutine.

SHELL on UNIX

The Synergy runtime expects certain terminal (tty) settings for proper terminal I/O functionality. If a program run in the shell changes these settings to an undesirable state, the STTY subroutine can be used to restore the proper settings.

Command cannot contain a Synergy environment variable, as in “DBLDIR:lpque”, unless it’s being used as an argument to one of the Synergex-supplied programs or utilities (such as dbr, dbs, isutl, and so forth). If it’s not an argument to one of these, you must translate the environment variable using the GETLOG subroutine, or use the UNIX form “$DBLDIR/lpque” instead.

Due to shells of varying behavior, a shell alias or function contained in a command may not be recognized by the command execution shell. Instead, use command executables or executable shell scripts directly.

When SHELL is performed, the UNIX exec command creates a duplicate process which then closes channels that are open. If you have not flushed data for a file opened for output, the data may be duplicated due to the deferred flush of cached write data.

SHELL on OpenVMS

The SHELL routine creates an interactive subprocess with either the current controlling Command Language Interpreter (CLI) or with DCL or DECSHELL as the controlling CLI. If you specify command, Synergy DBL attempts to spawn to that CLI. If you don’t specify command, the shell argument specifies the CLI. When you enter the variable to which you want to spawn, you must provide the full path name of the CLI, such as SYS$SYSTEM:DCL.EXE.

Because SHELL requires the command line interpreter, if you are using xfServerPlus, you cannot XCALL this routine from within a shared image.

Examples

The following program invokes the Bourne shell on UNIX.

.define TTCHN   ,15
record
    dsh         ,d1                             ;Shell to invoke
    achar       ,a1
record  ,x
    ash         ,a1                             ;Overlay for DISPLAY
proc
    open(TTCHN, o, "TT:")
    dsh = 0                                     ;Set to 0 for Bourne shell
    onerror ($ERR_MAXPRC) nope, oops            ;Trap any errors
    xcall shell(dsh)                            ;Invoke the shell
    offerror
    display(TTCHN, "[Press Enter to continue] ")
    reads(TTCHN, achar)
    stop
nope,
    writes(TTCHN, "Too many processes")
    goto done
oops,
    display(TTCHN, "Shell error or invalid shell: ", ash)
done,
    stop
end

The following program invokes the cmd.exe shell.

.define TTCHN   ,15
record
    dsh         ,d1                             ;Shell to invoke
    achar       ,a1
proc
    open(TTCHN, o, "TT:")
    dsh = 0                                     ;Set to 0
    onerror ($ERR_MAXPRC) nope, oops            ;Trap any errors
    xcall shell(dsh)                            ;Invoke the shell
    offerror
    display(TTCHN, "[Press Enter to continue] ")
    reads(TTCHN, achar)
    stop
nope,
    writes(TTCHN, "Too many processes")
    goto done
oops,
    display(TTCHN, "Shell error or invalid shell " +%string(dsh))
done,
    stop
end