Sometimes it is useful to pass workareas to a remote task, and receive values back again after the task has completed. If the requesting client executed the remote task without waiting for it to finish, Equinox does not do this automatically. The ExecuteSetData, ExecuteSetDataIn and ExecuteSetDataOut statements specify the list of workareas to transfer, and the ExecuteFalTorPan statement retrieves the values that were written by the remote task after it finished.

The parameter TaskHandle should contain the value which was returned in SysReply after ExecuteSetMode and Execute statements were used to execute a remote task without waiting.

If the task has not finished, no results will be returned and SysError will contain a nonzero value, otherwise SysError will contain zero, SysResult will contain the result returned from the task, and any workareas specified via the ExecuteSetDataIn and ExecuteSetData commands will contain the values written by the remote task.

The possible values for SysResult are:

• -4 Operational error. The remote client is improperly configured or installed.
• -3 Unable to execute. For example, the parameter file did not exist.
• -2 Did not start. The remote client executed and logged in, but was unable to initialise.
• -1 Running
• 0 Finished ok
• 1 Finished with an error. SysError was nonzero after the task finished in the remote client.
• 2+ Finished with a user defined result. The remote task executed a statement SysResult = value.

Use the ExecuteGetStatus or ExecuteWaitForTask statements to determine the task state. This statement can be used more than once to retrieve the values returned from a completed task. The server (or the last peer-to-peer client to exit) deletes the task information when it terminates.

N.B. FalTorPan was the ceremony on Vulcan during which Spock's memories were transferred back to him from Doctor McCoy (Star Trek III: The Search For Spock)

This example executes an process called MonthEnd remotely, which writes a value into the workarea MonthTotal. While the process is executing, the client runs a query locally, and then waits for the process to complete. It then loads the returned value for MonthTotal and prints it out.

handle MonthEndTask

block

ExecuteSetDataIn MonthTotal
ExecuteSetMode -1
Execute Process "MonthEnd"

if SysError then Exit Block

MonthEndTask = SysReply
Execute Query "NewCustomers"
ExecuteFalTorPan MonthEndTask

end block

if SysResult <> 0 then

ReportError 20, "MonthEnd failed with " & SysResult, 2
exit method

end if

Print "Month's total was", MonthTotal