syntax:

SElib.spawn(mode, execSpec[, arg[, ...]])

where:

mode - a number indicating how to spawn or execute the file named by execSpec. The parameter mode may be one of the following values though not all values are valid on all operating systems:

•

P_WAIT Wait for a child program to complete before continuing. (All platforms)

•

P_NOWAIT A script continues to run while a child program runs. In windows, a successful call with mode P_NOWAIT returns the window handle of the spawned process. (Windows and OS/2)

•

P_SWAP Like P_WAIT, but swap out ScriptEase to create more room for the child process. P_SWAP will free up as much memory as possible by swapping ScriptEase to EMS/XMS/INT15 memory or to disk (in TMP or TEMP or else current directory) before executing the child process (thanks to Ralf Brown for his excellent spawn library). (DOS only)

•

P_OVERLAY The script exits and the child program is executed in its place. (DOS 16-bit)

execSpec - a string with the path and filename of an executable file or a ScriptEase script.

arg - one or more values to be passed as parameters to the file to be executed.

return:

void - if the mode is P_OVERLAY.

number - if the mode is P_WAIT, the return is the exit code of the child process, else it is -1.

number - if the mode is P_NOWAIT or P_SWAP, the return is the identifier of the child process, else it is -1.

description:

Launches another application. The parameter mode determines the behavior of the script after the spawn call, while execSpec is the name of the process being spawned. Any arguments to the spawned process follow execSpec.

The parameter execSpec may be the path and filename of an executable file or the name of a ScriptEase script. If it is a script, the spawned script runs from the same instance of ScriptEase as the calling script. A spawned script does not cause another instance of the interpreter to be launched. A script that has been bound with the ScriptEase /bind function cannot be spawned from the same instance as the calling script.

The parameter execSpec is automatically passed as argument 0. ScriptEase implicitly converts all arguments to strings before passing them to the child process.

SElib.spawn() searches for execSpec in the current directory and then in the directories of the PATH environment variable. If there is no extension in execSpec, SElib.spawn() searches for file extensions in the following order: com, exe, bat, and cmd.

If a batch file is being spawned in 16-bit DOS and the environment variable COMSPEC_ENV_SIZE exists, the command processor is provided the amount of memory as indicated by COMSPEC_ENV_SIZE. If COMSPEC_ENV_SIZE does not exist, the command processor receives only enough memory for existing environment variables.

A return value of -1 results when Clib.errno is set to identify why the function failed.

see:

SElib.interpret(), SElib.interpretInNewThread(), winexec.jsh

example:

   // The following fragment

   // calls a mortgage program,

   // mortgage.exe, which takes

   // three parameters, initial debt,

   // rate, and monthly payment, and

   // returns, in its exit code,

   // the number of months needed to pay the debt.

var months = SElib.spawn(P_WAIT,

   "MORTGAGE.EXE 300000 10.5 1000");

if (months < 0)

   Screen.writeln( "Error spawning MORTGAGE");

else

   Clib.printf(

    "It takes %d months to pay off the mortgage\n",

    months);

   // The arguments could also

   // be passed to mortgage.exe as

   // separate variables, as in the following.

var months = SElib.spawn(P_WAIT,

   "MORTGAGE.EXE",300000,10.5,1000);

   // The arguments could be passed

   // to mortgage.exe in a

   // variable array, provided that

   // they are all of the same

   // data type, in this case strings.

var MortgageData;

MortgageData[0] = "300000";

MortgageData[1] = "10.5";

MortgageData[2] = "1000";

var ths = spawn(P_WAIT,

   "MORTGAGE.EXE", MortgageData);