The function can be used to start a program synchronous and asynchronous mode as well. When the timeout value passed to the function is zero the function starts the new process, but does not wait it to finish, but raises an error. In this case the BASIC program can catch this error using the ON ERROR GOTO structure and get the pid of the started process from the variable pid_v. In this case the function does not "return" any value because a BASIC error happened. For example:
ON ERROR GOTO NoError
a = EXECUTE("ls",0,PID)
print "The program 'ls' is running under the pid: ",PID,"\n"
If the argument time_out is -1 the function will wait for the subprocess to finish whatever long it takes to run. For example:
a = EXECUTE("ls",-1,PID)
print "ls was executed and the exit code was:",a
Note that the string passed as first argument containing the executable program name and the arguments (the command line) should not contain zero character (a character with ASCII code 0) for security reasons. If the command line string contains zero character an error is raised.
This function should be used to start an external program and wait for it to finish.
The first argument of the function is the executable command line to start. The second argument is the number of seconds that the BASIC program should wait for the external program to finish. If the external program finishes during this period the function returns and the return value is the exit code of the external program. If the argument specifying how many seconds the BASIC program has to wait is -1 then the BASIC program will wait infinitely.
If the program does not finish during the specified period then the function alters the third argument, which has to be a variable and raises error. In this case the argument pid_v will hold the PID of the external program. This value can be used in the error handling code to terminate the external program.