CALL

Syntax

CALL { built-in-function
     | built-in-class.class-method
     | [ module. ] variable-of-built-in-class.object-method
     | extension-class.class-method
     | [ module. ] variable-of-extension-class.object-method
     | [ cext-module. ] cext-function
     | java-class.java-class-method
     | variable-of-java-class.java-object-method
     | [ module. ] user-function
     | [ module. ] function-reference
     | [ module. ] variable-of-user-type.user-method
     }
       (
          [ [ parameter-name : ] parameter-value
              [,...] ]
       )
      [ RETURNING variable  [,...] ]

1. built-in-function is a built-in function.
2. built-in-class is a built-in class.
3. class-method is a method invoked by class name.
4. module is an imported module.
5. variable-of-built-in-class is a variable defined from a built-in class.
6. object-method is a method invoked by object reference.
7. extension-class is a class from an extension package.
8. variable-of-extension-class is a variable defined from an extension-class.
9. cext-module is an imported C extension module.
10. cext-function is a C function defined in a cext-module.
11. java-class is a imported Java class.
12. java-class-method is a method of a java-class invoked by class name.
13. variable-of-java-class is a variable defined from a java-class.
14. java-object-method is a method of a java-class invoked by object reference.
15. user-function is a function defined in one of the modules of the program.
16. function-reference is a variable referencing a function.
17. variable-of-user-type is a variable defined from a user-type that is associated to a user-defined method.
18. user-method is a method associated to a user type.
19. parameter-name is the name of a function parameter, as specified in the function definition. The parameter name is optional.
20. parameter-value can be any valid expression, including object references of built-in classes or Java classes.
21. variable is a variable receiving a value returned by the function.

Usage

The CALL instruction invokes the function or class/object method specified and passes the program flow control to that function/method. After the called function is executed, the flow control goes back to the caller, the runtime system executing the next statement that appears after the CALL instruction.

Function arguments can be any expression supported by the language. Use a double-pipe operator || to pass the concatenation of character string expressions as a parameter.

CALL my_function( TODAY, 20*0.5435, 'abc'||'def'||var1 )

The RETURNING clause assigns values returned by the function to variables in the calling routine. The RETURNING clause is only needed when the function returns parameters.

MAIN
  DEFINE var1 CHAR(15)
  DEFINE var2 CHAR(15)
  CALL foo() RETURNING var1, var2
  DISPLAY var1, var2
END MAIN

FUNCTION foo() 
  DEFINE r1 CHAR(15)
  DEFINE r2 CHAR(15)
  LET r1 = "return value 1"
  LET r2 = "return value 2"
  RETURN r1, r2
END FUNCTION

If the function returns a unique parameter, the function can be used in an expression and can be directly assigned to a variable with LET var = function(...) statement.

MAIN
  DEFINE var1 CHAR(10)
  DEFINE var2 CHAR(2)
  LET var1 = foo()
  DISPLAY "var1 = " || var1
  CALL foo() RETURNING var2
  DISPLAY "var2 = " || var2
END MAIN

FUNCTION foo() 
  RETURN "Hello"
END FUNCTION

The value of a receiving variable may be different from the value returned by the function, following the data conversion rules.

MAIN
  DEFINE s STRING
  LET s = div(10,2)
END MAIN

FUNCTION div(x,y)
  DEFINE x,y INTEGER
  RETURN x / y
END FUNCTION

If the IMPORT FGL instruction is used to import a module, function can be prefixed with the name of the module followed by a dot (i.e. module.function). The module prefix is required to fully-qualify the function in case of conflicts (i.e. when functions with the same name are defined in several modules).

-- main.4gl
IMPORT FGL module1
IMPORT FGL module2
MAIN
  CALL module1.show("aaa")
  CALL module2.show("aaa")
END MAIN

-- module1.4gl
FUNCTION show(s)
  DEFINE s STRING
  DISPLAY s
END FUNCTION

-- module2.4gl
FUNCTION show(s)
  DEFINE s STRING
  DISPLAY s
END FUNCTION

The symbol following the CALL keyword can be a program variable that references a function.

TYPE t_func_ref FUNCTION (p1 INT, p2 INT) RETURNS INT

DEFINE fr t_func_ref,
       r INT

LET fr = FUNCTION add  -- Function with the same signature as t_func_ref
CALL fr(100,200) RETURNING r

LET fr = FUNCTION sub  -- Function with the same signature as t_func_ref
CALL fr(100,200) RETURNING r

To improve code readability, function parameters can be qualified with the name specified in the function definition:

CALL cleanup( mode: "full", verbose: TRUE )