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
- Name of a variable that is based on an Interface part
- operationName
- Name of the Interface part function prototype
- argumentList
- List of arguments, each of which is separated from the next by
a comma
A change made to a parameter value in the service does
not affect the value of the argument variable that is provided in
the call statement.
For details about
the restrictions on parameters that are sent to a third-party REST
service, see "Specifying parameters for service access in Rich UI."
- myCallbackFunction
- 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. Name of a exception handler or 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.
Specifying that delegate has the following 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, you can make customized exception handling consistent
throughout a set of applications. Assign a different exception handler
to the delegate; for example, by writing a setup function in your
own library, such as in myLibrary, and by including
the following statement in that function:
serviceLib.serviceExceptionHandler = myLibrary.myExceptionHandler;
Invoke
the setup function in Rich UI handler on-construction functions. 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 Web server) invokes a service and when
the proxy receives a response. If more time elapses, the EGL runtime
code throws a ServiceInvocationException.
To
set a timeout:
- Take into account a variety of 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 bid, you might set a low timeout value so that the user can
make an additional 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, meaning that 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. In each case, a list of functions is
displayed and you can select one.
- If you type the call statement with
the ending semicolon and include reference to a callback or onException
function that does not exist, you can request the Workbench to 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 Web SOAP service or from an EGL REST service, the
relationship of the function parameters and the service-invocation
parameters is best described by 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, and 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 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
(less likely) a RuntimeException.