|
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
VSupported on OpenVMS
|
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)
Force a detached process when SPAWN is called from the dbs runtime running in a console window.
Restore focus when the calling Synergy application resumes.
Allow the subprocess to inherit handles such as standard input and output.
Start the program minimized.
Doesn’t give the spawned program keyboard focus.
Prevent new console from being created for new processes. A new process inherits the parent’s console if possible.
Let the program run asynchronously like RUNJB.
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 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. |
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
