FUNCTION definitions

A FUNCTION definition defines a named procedure with a set of statements.

Syntax 1 (legacy function syntax):

[PUBLIC|PRIVATE] FUNCTION function-name ( [ parameter-name [,...] ] )
    [ DEFINE parameter-name data-type [...] ]
    [ local-declaration [...] ]
    [ instruction 
    | [ RETURN expression [,...] ]
        [...] 
    ]
END FUNCTION
  1. function-name is the function identifier.
  2. parameter-name is the name of a formal argument of the function.
  3. data-type can be a primitive data type, a user defined type, a built-in class, an imported package class, or a Java class.
  4. local-declaration is a DEFINE, CONSTANT or TYPE instruction.
  5. instruction is a language statement to be executed when the function is invoked.
  6. expression is a value to be returned by the function.

Syntax 2 (fully typed function):

[PUBLIC|PRIVATE] FUNCTION function-name (
     { parameter-name data-type [ attributes-list ]
     | record-name record-type INOUT
     }
     [,...]
  )
 [ attributes-list ]
 [ RETURNS returns-specification ]
    [ local-declaration [...] ]
    [ instruction 
    | [ RETURN expression [,...] ]
        [...] 
    ]
END FUNCTION
where attributes-list is:
ATTRIBUTES ( attribute [ = "value" ] [,...] )
where returns-specification is:
{ data-type [ attributes-list ]
| ( data-type [ attributes-list ] [,...] )
| ( )
}
  1. function-name is the identifier of the function.
  2. parameter-name is the name of a formal argument of the function.
  3. data-type can be a primitive data type, a user defined type, a built-in class, an imported package class, or a Java class.
  4. record-name is the name of a parameter defined with a record TYPE.
  5. record-type is a record TYPE.
  6. attributes-list is a comma-separated list of name = value pairs or name attributes.
  7. attribute is an attribute name to extend the function definition with properties.
  8. value is the value for the function attribute, it is optional for boolean attributes.
  9. local-declaration is a DEFINE, CONSTANT or TYPE instruction.
  10. instruction is a language statement to be executed when the function is invoked.
  11. expression is a value to be returned by the function.

Syntax 3 (methods):

[PUBLIC|PRIVATE] FUNCTION ( receiver-name receiver-type ) method-name (
     { parameter-name data-type
     | record-name record-type INOUT
     }
     [,...]
  )
 [ RETURNS returns-specification ]
    [ local-declaration [...] ]
    [ instruction 
    | [ RETURN expression [,...] ]
        [...] 
    ]
END FUNCTION
where returns-specification is:
{ data-type
| ( data-type [,...] )
| ( )
}
  1. A (receiver-name receiver-type) clause defines a function as a method for a user-defined type.
  2. receiver-name is the identifier of the receiver referenced in the method body.
  3. receiver-type is the user-defined type to be the target of this method.
  4. method-name is the identifier of the method.
  5. parameter-name is the name of a formal argument of the method.
  6. data-type can be a primitive data type, a user defined type, a built-in class, an imported package class, or a Java class.
  7. record-name is the name of a parameter defined with a record TYPE.
  8. record-type is a record TYPE.
  9. local-declaration is a DEFINE, CONSTANT or TYPE instruction.
  10. instruction is a language statement to be executed when the method is invoked.
  11. expression is a value to be returned by the method.

Function names

Like other identifiers, function names are case-insensitive. However, always consider using the same naming convention when defining and invoking functions.

Note: If the function name is also the name of a built-in function, an error occurs at link time, even if the program does not reference the built-in function.

Function definition using legacy syntax

The following example shows a function definition using the legacy syntax, with parameter definition in the function body:
FUNCTION split(str, len)
    DEFINE str STRING, len INT
    RETURN str.subString(1, len),
           str.subString(len+1, str.getLength())
END FUNCTION

This syntax does not define a function with a complete signature.

Function definition with complete function type

By specifying data types in the parameter list, you define a function with a complete function type.

This syntax allows better compilation checking:
FUNCTION split(str STRING, len INT) RETURNS (STRING, STRING)
    RETURN str.subString(1, len),
           str.subString(len+1, str.getLength())
END FUNCTION
Braces after the RETURNS clause are not required, when the function returns a single value:
FUNCTION count_items(sid INT) RETURNS INT
    DEFINE cnt INT
    SELECT COUNT(*) INTO cnt FROM stock WHERE stock_id = sid
    RETURN cnt
END FUNCTION

When the function returns a single value/type, it is also possible to enclose the type in parentheses:

FUNCTION count_items(sid INT) RETURNS (INT)
    ...

In the next example, the function has no parameters and does not return values:

FUNCTION clean_debug_log() RETURNS ()
    CALL os.Path.delete("log.txt")
END FUNCTION

Methods

A FUNCTION definition using a receiver identifier and type defines a method for this type. Specify the receiver identifier and type before the method name:
TYPE Rectangle RECORD
    height, width DOUBLE PRECISION
END RECORD

FUNCTION (r Rectangle) area() RETURNS DOUBLE PRECISION
    RETURN r.height * r.width
END FUNCTION

For more details see Methods.

Function with record passed as reference

The INOUT keyword can be used to pass records by reference:

FUNCTION init_cust(r CustRec INOUT)
    LET r.cust_id = 0
    LET r.cust_name = "<undefined>"
    LET r.cust_addr = "<undefined>"
    LET r.cust_crea = CURRENT
END FUNCTION

For more details see Function parameters.

Function with attributes

Function attributes can be used to complete the definition of the function itself, for its parameters and return values:

FUNCTION add(
    p1 INTEGER ATTRIBUTES(json_name = "parameter 1"),
    p2 INTEGER ATTRIBUTES(json_name = "parameter 2")
    )
    ATTRIBUTES(json_name = "function add")
    RETURNS INTEGER ATTRIBUTES(json_name = "return value 1")
        DEFINE var1 INTEGER
        LET var1 = (p1 + p2)
        RETURN var1
END FUNCTION
Note: Function attributes are especially useful to implement RESTful Web Services functions.

For more details see Function attributes.