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 for output parameters 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.
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 graphical mode, if no interactive instruction was issued before the front call. Furthermore,
each front call will sync the AUI tree with the front
end.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.
[param1,param2,...]
):- Input and output parameters can be of any simple type like
INTEGER
, aRECORD
or aDYNAMIC 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
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
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.
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.
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.