SPAWN

Execute a command or program

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
xcall SPAWN(command[, mode]) 

Arguments

command

An expression that contains the command string to be processed. The maximum length is 1024 characters. (a)

mode

(optional) One or more of the following, combined using .BOR. or a vertical bar (|) (Windows only): (n)

D_DETACHED

Force a detached process when SPAWN is called from the dbs runtime running in a console window.

D_GAINFOCUS

Restore focus when the calling Synergy application resumes.

D_INHERIT

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

D_MINIMIZED

Start the program minimized.

D_NOACTIVATE

Doesn’t give the spawned 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.

mode

(optional) An expression that indicates whether tty will be reset. It can contain the following values (Unix only): (n)

0 = Do not reset tty.

1 = Reset tty. (default)

Discussion

The SPAWN routine’s functionality differs according to operating system. On all systems, the return status from the executed command (if available) can be obtained from XSTAT. If the value for XSTAT is -1, the process creation failed and the creation system error code can be found in %SYSERR.

SPAWN on Windows

The SPAWN subroutine executes a program directly without using the command processor (cmd.exe) and returns control to the calling program upon exit. The SPAWN subroutine executes the command string as if the string were typed directly at the command prompt window. The calling Synergy program waits until the command is finished before it continues. The return value of the program that you run is set for the XSTAT subroutine.

The default SPAWN behavior is to start an interactive process with a window associated with it. The calling program is suspended until the requested task is complete. The mode D_NOWAIT specifies that no wait should occur.

The D_NOCONSOLE option prevents a new independent console from being created; it does not prohibit a DOS window from being displayed. To keep the DOS window from appearing, combine D_NOCONSOLE with D_MINIMIZED. For example:

xcall spawn("my_prog.exe", D_NOCONSOLE+D_MINIMIZED)

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

Command redirection requires you to use the command processor or the SHELL subroutine.

The SPAWN subroutine does not run Windows’ internal commands such as dir or copy (since they are command processor functions); you must use the SHELL subroutine for these commands.

Command cannot contain an environment variable, as in “DBLDIR:lpque.bat”. You must translate the environment variable using the GETLOG subroutine.

SPAWN on Unix

The SPAWN subroutine executes a command in a child process. It executes the command string as if the string were typed directly at the terminal. The calling Synergy program waits until the command is finished before it continues.

If you try to run more than the maximum number of processes (which is determined by the configuration of your Unix kernel), you’ll get a “Too many processes” error ($ERR_MAXPRC).

Because terminal (tty) settings are controlled by the runtime, they are reset by default when SPAWN is executed to allow “normal” terminal functionality. If you need to retain the Synergy DBL terminal settings, specify a mode reset value of 0 or use the STTY subroutine.

Command cannot contain an environment variable, as in “DBLDIR:lpque”. You must translate the environment variable using the GETLOG subroutine.

SPAWN handles only simple shell meta characters (such as input and output redirection). Use the SHELL subroutine if you want to make full use of the shell meta characters.

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 executing a shell script, the first line must begin with #! or the script will not execute. For example:

#! /bin/bash

If you are using option #22 for LPQUE, make sure the first line of dblpq includes this line.

Note

When SPAWN 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.

Note

We recommend that you do not call SPAWN to execute a program with dbr if the original program is started with dbs because it may render the terminal unresponsive or result in unexpected behavior.

SPAWN on OpenVMS

The SPAWN subroutine executes a program and returns control to the calling program when the program exits. It executes the command string as if the string were typed directly at the terminal. The calling Synergy program waits until the command is finished before it continues.

The SPAWN subroutine executes a DCL command string. It sends the command string to the Command Language Interpreter (CLI) as input.

The second argument, mode, is ignored.

If you try to run more than the maximum number of processes (which is determined by the process limit argument (PRCLM), you’ll get a “Too many processes” error ($ERR_MAXPRC).

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

Examples

The following program (on Windows) checks the current drive.

proc
    open(15, o, "tt:")
    writes(15, "Disk check:")
    xcall spawn("chkdsk")               ;Execute chkdsk
    close(15)
    stop
end

The following example (on Unix) suspends its own execution while the spawned program runs, and then it resumes with the next statement.

.define TTCHN   ,15
proc
    open(TTCHN, o, "tt:")
    writes(TTCHN, "List of who's using the system:")
    onerror ($ERR_MAXPRC)nope, oops
    xcall spawn("who")                  ;Execute the "who" command
    offerror
    writes(TTCHN, "Now back to our program...")
    xcall menu                          ;We get here after SPAWN is done
    close(TTCHN)
    goto done
nope,
    writes(TTCHN, "Too many processes")
    goto done
oops,
    writes(TTCHN, "Error creating subprocess")
done,
    stop
end