ui.Interface.frontCall

Syntax

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

1. module defines the shared library where the function is defined.
2. function defines the name of the function to be called.
3. parameter-list is a list of input parameters.
4. 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:

1. The module name, identifying the shared library (.so or .DLL) to be used.
2. The function of the module the be executed.
3. The list of input parameters, using the square brace notation.
4. The list of output parameters, using the square brace notation.

Module and function names are case-sensitive.

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, while all output parameters must be variables only, to receive the returning values. An empty list is specified with [] . Output parameters are optional: If the front-end 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

When you specify "standard" as module name, it references built-in functions implemented by default by the front end component. Other module names identify .so or .DLL libraries which must be installed in the front-end installation directory (see front-end documentation for more details). If needed, you can customize front-end calls by writing your own modules.

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

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.

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

FUNCTION call()
   DEFINE info STRING
   TRY
       CALL ui.Interface.frontCall( "standard", "feinfo", ["fename"], [info] )
   CATCH
       DISPLAY STATUS, err_get(STATUS)
   END TRY
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-end 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.