| Command group | Flag affected | Reversible | Execute on client | Platform(s) |
|---|---|---|---|---|
| Methods | NO | NO | NO | All |
Do async method remote-task-class/method-name (parameters) Returns return-value
This command uses the Web Services server to execute a method asynchronously in the background, while the user continues to work with the application. Because it uses the Web Services server, you can only use this command if you meet some serial number requirements: you need a Web edition serial number, and for the development version, a Web Services serial number.
This command runs the specified remote task method. The method must have a name allowed for a Web Service method, and it must be marked as a static Web Service method. The method will only execute in the background if you have executed the Start server command to start the multi-threaded Web Client server. In a runtime, Do async method generates a runtime error if you use it before you have called Start server. In the development version, you can omit the call to Start server if you wish to debug the method; in this case, the method executes in the foreground, as if it were a normal method call.
The return-value is a long integer that uniquely identifies the call to the method. This is referred to as the asynchronous call id. You use the asynchronous call id to cancel the asynchronous method with the Cancel async method command, and to associate the completion message (see below) with the method call.
Passing Parameters
You can include a list of parameters with the Do async method command which are passed to the called method. If the called method has fewer parameters than values passed to it, the extra values are ignored.
Completion Message
When the method executing in the background finishes, Omnis sends a message to the task instance that was current when Do async method was called. The message is
$asynccomplete(iCallId,cErrText,vRetVal)
where iCallId is the asynchronous call id returned by Do async method, and vRetVal is the return value of the method executed in the background, unless an error occurred, in which case cErrText is not empty, and contains information about the error.
Notes
You can only call Do async method when running in the normal foreground thread.
Background threads pend while a message box is displayed.
The background threads only execute when the normal foreground thread is not executing.
The usual restrictions about remote task threads apply, for example you cannot debug a background thread, and you cannot use certain commands when running code in a background thread.
Execution of the remote task method occurs in the context of a remote task instance as usual. This means that the remote task $construct and $destruct methods are called before and after calling the specified method, and that the user count for the Web Client server must have an available connection.
If the library containing the remote task closes before the method finishes, Omnis stops its execution, and does not send the completion message. Note that if the method is in a critical block, Omnis will not stop its execution until it leaves the critical block. Also, execution will only stop after the current command being executed by the method completes.
Only use critical blocks for very short time periods in asynchronous methods, as the user interface will be unresponsive while code is running in a critical block.
# Run the method $backgroundmethod asynchronously in the background - it prints a report, which the completion message sends to the screen
# Returned long integer iCallId uniquely identifies the method call
Do async method REMOTETASK/$backgroundmethod ('rReport') Returns iCallId
# $backgroundmethod (implemented in remote task, and marked as a Web Service static method):
# Print the report identified by the parameter to memory, and return the resulting report
Calculate $devices.Memory.$visible as kTrue
Do $cdevice.$assign(kDevMemory)
Do $prefs.$reportdataname.$assign(iReport)
Set report name [pReportName]
# Note that Print report can be used in the multi-threaded Web Client server from Studio 4.1.5 onwards
Print report
Quit method iReport
# $asynccomplete(pCallId,pErrorText,pReport) in the task instance that was current when Do async method was called
If len(pErrorText)=0
Send to screen
Print report from memory pReport
End If