Synopsis:

        ret_code=task_exec(task_name{, arg1 {, arg2 {,..arg15}}})

Arguments:

        task_name – The name of the task to spawn (with or without the .TEX) extension)

        arg1..arg15 – Optional arguments to pass to spawned task (up to 15)

Description:    This function creates a new task from the compiled byte code file given in task_name.   If the new task starts successfully then the calling task will be suspended (i.e. will block) until the new task stops (either by encountered a stop statement, or reaching the end of the program instructions, or by calling a task_return() function, or if it explicitly killed (say by a task_kill() call) or if the child task chains to another task..

The calling task   If the .TEX extension is omitted it will be added automatically.   

If the TEXDIR environment variable is set, then the semi-colon delimited list of directories specified in this environment variable will be searched in order for the file specified in task_name.   If TEXDIR is not set then the only current directory will be searched.

If any of arg1..arg15 are specified then these arguments will be passed to the new task which can then be read using the task_arg() function.

If the child task chains to another task then the child is deemed to have stopped and the parent will be woken.  If the child task encounters a restart statement then the parent task will not be woken up ans the child is deemed to be still active.

Return Value:

If the new task could not be started then the function will return a negative error code.    If the new task was started successfully then the function will only return once this new task is stopped or killed.      The return values will then be as follows:

Empty string “” is returned if the task encountered a stop or the end of program reached or if the task was expicitly killed, or the child chained to another task.

“?” is returned if the task stopped due to a fatal error (like stack overflow).

If task_return(str) is called from the new task then the return value given is this call will become the return value of the task_exec() function call.    It would be advisable not to return a negative value or one of the above string values from this call to avoid confusion.