ui.Interface.frontCall

ui.Interface.frontCall performs a function call to the current front-end.

Syntax

ui.Interface.frontCall(
   module STRING,
   function STRING,
   [ parameter-list ],
   [ returning-list ] )

module defines the shared library or classpath where the function is implemented.
function defines the name of the function to be called.
parameter-list is a list of input parameters.
returning-list is a list of output parameters.
Important: The returning-list variables are passed by reference to the frontCall() method.

Usage

The ui.Interface.frontCall() class method can be used to execute a procedure on the front-end workstation through the front-end software component. You can for example launch a front-end specific application like a browser or a text editor, or manage the clipboard content.

The method takes four parameters:

The module, identifying the shared library (.so or .DLL) or the Java class (GMA) implementing the front call function.
The function of the module the be executed.
The list of input parameters, using the square brace notation.
The list of output parameters, using the square brace notation.

Input and output parameters are provided as a variable list of parameters, by using the square braces notation ([param1,param2,...] ). Input parameters can be an expression supported by the language; output parameters must be variables only, to receive the returning values. An empty list is specified with [] . Output parameters are optional: If the front call returns values, they will be ignored by the runtime system.

Simple front call example:

FUNCTION call()
  DEFINE info STRING
  CALL ui.Interface.frontCall( "standard", "feInfo", ["feName"], [info] )
END FUNCTION

Some front calls need a file path as parameter. File paths must follow the syntax of the front end workstation file system. You may need to escape backslash characters in such parameters. The next example shows how to pass a file path with a space in a directory name to a front-end running on a Microsoft™ Windows™ workstation:

FUNCTION call()
   DEFINE path STRING, res INTEGER
   LET path = "\"c:\\work dir\\my report.doc\""
   -- This is: "c:\work dir\my report.doc"
   CALL ui.Interface.frontCall( "standard", "shellExec", [path], [res] )
END FUNCTION

Front call error handling

Exception handling instructions can be used to check the execution status of a front call. Both WHENEVER ERROR directives or TRY/CATCH block can surround the front call to avoid program stop in case of error, and check the error number returned in the STATUS variable.

Note: There is not need to surround front calls with exception handlers such as TRY/CATCH, if the front call is always supposed to execute without error. For example, the feInfo front call will never produce an exception.

Example of front call error handling with a TRY/CATCH block:

FUNCTION takePhoto()
   DEFINE path STRING
   TRY -- This front call may fail if the front-end is not a mobile device:
       CALL ui.Interface.frontCall( "mobile", "takePhoto", [], [path] )
   CATCH
       MESSAGE "Cannot take photo: ", STATUS, " ", err_get(STATUS)
       LET path = NULL
   END TRY
   RETURN path
END FUNCTION

If the front call module name or the function name is invalid, the errors -6331 or -6332 will be raised, respectively.

If the front call execution failed for some reason, the error -6333 will be raised. The description of the problem can be found in the second part of the error message, returned by a call to the ERR_GET() function.

The error -6334 can be raised in case of input or output parameter mismatch. The control of the number of input and output parameters is in the hands of the front-end. Most of the standard front calls have optional returning parameters and will not raise error -6334, if the output parameter list is left empty. However, front-end specific extensions or user-defined front-end functions may return an invalid execution status in case of input or output parameter mismatch, raising error -6334. If the front-end sends an call execution status of zero (OK), and the number of returned values does not match the number of program variables, the runtime system will set unmatched program variables to NULL. As a general rule, the program should provide the expected input and output parameters as specified in the documentation.