Back to Contents

Front End Functions

Summary:

• Basics
• The frontCall method
• Standard built-in front end functions

See also: Interface built-in class

Basics

The BDL language provides a specific method to call functions defined in the front end that will be executed locally on the workstation where the front end resides. When you call a user function from BDL, you specify a module name and a function name. Input and output parameters can be passed/returned in order to transmit/receive values to/from the front end. A typical example is an "open file" dialog window that allows you to select a file from the front end workstation file system.

A set of standard front end functions is built-in by default in the front end. It is possible to write your own functions in order to extend the front end possibilities. For example, you can write a set of functions to wrap an existing API, such as Window DDE or OLE. A set of user functions is defined in a module, implemented as a Windows DLL or UNIX shared library. These modules are loaded automatically according to the module name. See the front end documentation for more details about creating user function modules in the front end.

Tip: Regarding DDE/OLE APIs to manipulate Microsoft Office documents, note that there are freeware alternatives such as the Apache POI Java library which can be used with the Java Interface. See for example Java Interface: Example 2.

The frontCall method

Purpose:

The Interface built-in class provides a special method to perform front end calls.

Syntax:

Notes:

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.

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.

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 described in this page 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. Note that 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.

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.

Note that 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.

Some front calls like shellexec 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:

01   MAIN
02     DEFINE path STRING, res INTEGER
03     LET path = "\"c:\\work dir\\my report.doc\""
04     -- This is: "c:\work dir\my report.doc"
05     CALL ui.Interface.frontCall( "standard", "shellexec", [path], [res] )
06   END MAIN

Errors:

If the function could not be executed properly, one of the following exceptions might occur:

Example:

01   MAIN
02     DEFINE data STRING
03     CALL ui.Interface.frontCall( "mymodule", "connect", ["client1",128], [] )
04     LET data = "Hello!"
05     CALL ui.Interface.frontCall( "mymodule", "send", [data, data.getLength()], [] )
06     CALL ui.Interface.frontCall( "mymodule", "receive", [], [data] )
07     DISPLAY data
08     CALL ui.Interface.frontCall( "mymodule", "disconnect", ["client1"], [] )
09   END MAIN

Standard built-in front end functions

The following table shows the built-in functions implemented by the front ends in the "standard" module. Additional modules and functions are available for front-ends, but are specific to the front-end type. Please refer to the front-end documentation for more details.