Invoking a service asynchronously from a Rich UI application

In Rich UI, the call statement is used to invoke a service asynchronously:

call serviceName.operationName(argumentList)
   returning to myCallbackFunction onException myExceptionHandler
   {timeout = milliseconds};

serviceName

The name of a variable that is based on an Interface part

operationName

The name of the Interface part function prototype

argumentList

A list of arguments, each of which is separated from the next by a comma

For restrictions on arguments, see “Restrictions in the prototypes used for service access.”

myCallbackFunction

The name of a callback function or delegate that is available to the call statement. In most cases, the function or delegate is in the same Rich UI handler or in a library. The callback function is described later in this topic.

myExceptionHandler

Optional. The name of an exception handler or a delegate that is available to the call statement. In most cases, the exception handler or delegate is in the same Rich UI handler or in a library. The exception handler is described later in this topic.

If you do not have your own exception handler, you can specify the following delegate: serviceLib.serviceExceptionHandler. Here are the implications:

By default, specifying that delegate automatically invokes a system function that writes the content of the exception message field to the standard output. In the product, the standard output is the console view. In an external browser, the standard output is the bottom of the web page.
Alternatively, the delegate might cause the invocation of a custom exception handler. You can even use this alternative to make custom error handling be consistent throughout a set of applications.
For example, you might do as follows:
1. Create a library named myLibrary and include both a custom exception handler named myExceptionHandler and a setup function.
2. In the setup function, include the following statement:
```
serviceLib.serviceExceptionHandler = myLibrary.myExceptionHandler;
```
3. Invoke the setup function in each of your Rich UI applications, in the on-construction function.
For every service that is invoked by a call statement (if the statement includes serviceLib.serviceExceptionHandler), the EGL runtime code responds to a runtime exception by running the customized exception handler; in this case, by running myLibrary.myExceptionHandler.

milliseconds

The maximum valid number of milliseconds that elapse between when the EGL Rich UI proxy (on the application server) invokes a web service and when the proxy receives a response. If more time elapses, the EGL runtime code throws a ServiceInvocationException. However, no timeout is enforced during access of a dedicated service.

To set a timeout:

Consider various factors, such as local network traffic, internet traffic, and server response time. Those factors mean that two invocations of the same service are likely to take a different amount of time under different conditions.
Consider the nature of your application. If your code is waiting for a credit approval, you might set a high timeout value to avoid charging the user twice. If your code is making a bid in an online auction, you might set a low timeout value so that the user can make another bid quickly.
Use timeout values that vary from one another by one or more seconds.

You can set a default value for milliseconds in the defaultServiceTimeout build descriptor option. The defaultServiceTimeout build descriptor option has no default value set. If you do not specify a value for either defaultServiceTimeout or for milliseconds, the service call will not time out. For more information, see “defaultServiceTimeout.”

Keystroke assistance for the call statement

The following kinds of keystroke assistance are available:

After you type the returning to or onException keyword in the call statement, you can request content assist by pressing Ctrl+Space. A list of functions is displayed, and you can select one.
If you type the call statement with the ending semicolon and include a reference to a callback or an onException function that does not exist, you can request that the workbench create the missing logic:
- Press Ctrl+1.
- Alternatively, right click after the semicolon and select Create Callback Functions.

Callback function

The callback function receives the values, if any, that are in the response sent by the service. The callback itself has no return value.

If the callback function is invoked from a third-party REST service, the function can have zero or one parameter. If a parameter is specified, its type must match the type of the return value that is specified in the Interface part, and the parameter modifier is IN.

If the callback function is invoked from a SOAP service or from an EGL REST-RPC service, the relationship of the function parameters and the service-invocation parameters is best described by an example:

Consider the following function prototype in an Interface part:

Interface EmployeeService {}
   Function GetEmployeeDetail(employeeCode STRING IN, 
                              employeeSalary FLOAT OUT, 
                              employeeStatus STRING INOUT) 
            returns(myEmployeeRecordPart);
end

This example shows an interface declaration and call statement used to invoke the service:

myInterface EmployeeService;

call myInterface.GetEmployeeDetail("A123", 25.8, "Full-time")
     returning to myCallback onException myExceptionHandler;

Here is the outline of a callback function:
```
Function myCallBack(salary FLOAT IN, 
                    status STRING IN, 
                    myRecord myEmployeeRecordPart IN)
    // statements here
end
```
The function includes one parameter for each service-operation parameter that is OUT or INOUT. The order of those parameters in the callback function is the same as the order in the service operation. The service-operation return value is represented as the last parameter in the callback function.

In general, the rules for designing the callback function for a web SOAP service or an EGL REST-RPC service are as follows:

The function has a series of parameters that are in the same order as the OUT and INOUT parameters in the service invocation
If the service invocation has a return value, the callback function includes an additional, last parameter to accept the return value
Each parameter in the function has the IN modifier

onException function

The onException function has the following characteristics:

No return value
The function accepts an Exception record of type AnyException, and you can test that record to determine the specific type received

Here is the outline of an onException function:

Function myExceptionHandler(exp AnyException)
   case 
      when (exp isa ServiceBindingException)
         ;
      when (exp isa ServiceInvocationException)
         ;
      otherwise
         ; 
   end
end

Errors might occur in the following places:

In a service binding; that is, in how the service access is specified in your code. This error might involve a problem in the deployment descriptor.
In the communication of the Rich UI application with the EGL Rich UI Proxy
In the EGL Rich UI Proxy
In the communication of the EGL Rich UI Proxy with the service
In the service

A problem in a service binding results in a ServiceBindingException. Other problems result in a ServiceInvocationException or a RuntimeException, which is less likely.