ui.Interface.frontCall

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

Syntax

ui.Interface.frontCall(
   moduleName STRING,
   functionName STRING,
   [ valueList ],
   [ variableList ] )

moduleName defines the shared library or classpath where the function is implemented.
functionName defines the name of the function to be called.
valueList is a list of input parameters.
variableList is a list of output parameters.
Important: The 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.

Important: When calling the ui.Interface.frontCall() method, the connection to the front-end is initiated, if it is not yet established. Consider avoiding front calls in batch programs and interactive programs using the text mode. This is also important to consider in grapical mode, if no interactive instruction was issued before the front call.

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 to 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 brackets notation ([param1,param2,...] ):

Input and output parameters can be of any simple type like INTEGER, a RECORD or a DYNAMIC ARRAY.
An empty list of input or output parameters is specified with [] .
Input parameters can be an expression such as (10 * var).
Output parameters must be variables only, to receive the returning values.
Output parameters are optional. If the front call returns values, these values will be ignored by the runtime system, if no output parameters are provided to receive these values.

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 following 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

When using RECORD and DYNAMIC ARRAY as front call input or output parameters, the runtime system will use JSON serialization, to pass and return such structured data to/from the front-end. This is important to know when implementing your own custom front calls. Note that one can use the json_null and json_name variable definition attributes to control JSON serialization:

DEFINE optrec RECORD
              mode INTEGER ATTRIBUTES(json_null="null"),
              filter STRING ATTRIBUTES(json_name="Data Filter")
          END RECORD
DEFINE flags DYNAMIC ARRAY OF INTEGER ATTRIBUTES(json_null="undefined")
DEFINE result_list DYNAMIC ARRAY OF STRING
LET optrec.mode = 999
LET optrec.filter = "*A*"
LET flags[1] = 111
LET flags[3] = 333
CALL ui.Interface.frontCall( "m1", "fc1", [optrec, flags], [result_list] )

Front call cost

A front call is a remote procedure call requiring a full network round trip between the server app and the front end.

Depending on the current network speed, this may result in delays in the millisecond to sub second range.

Note: In mobile application development or runOnServer mode, the execution time of a front can be much slower when running the app on the server, compared to embedded apps.

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 blocks can surround the front call to avoid program stopping in case of error, and to check the error number returned in the STATUS variable.

Note: There is no 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 fails 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 a 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, it is recommended that the program provides the expected input and output parameters as specified in the documentation.