| call-name |
(< [([prototype-cast]
[intermediate-result-definition])]
[parameter]
[,[parameter]]
... >) |
| [array-index-expression] |
This document covers the following topics:
Related topics:
Object type Function
DEFINE
FUNCTION statement
DEFINE
PROTOTYPE statement
A function call performs an invocation of a user-defined function, a special kind of a subroutine which is implemented in a separate programming object of type function.
Usually, a function call is provided with parameters and returns a result. It may be used within a Natural statement instead of a read-only operand. In this case, the function has to return a result, which is then processed by the statement like a field containing the same value.
It is also possible to use a function call stand-alone in place of a Natural statement. Then the function call need not return a result value.
There are different ways to call a function:
When the specified call-name
represents the name of the function to be executed, the function call is
denoted as a symbolic function call. Be aware, the function name is
defined in the DEFINE
FUNCTION statement and does not necessarily have to match the
name of the module in which the function is defined. The function interface
result and parameter layouts used to resolve a function call are either
specified by a DEFINE
PROTOTYPE statement with the same name or loaded
automatically if the cataloged version of the called function exists.
A function can also be called in an indirect form, denoted as a
variable function call. In this case, the specified
call-name
is an alphanumeric variable, which contains the name of the called function at
execution time. This variable has to be referenced in a prototype definition
(DEFINE PROTOTYPE
statement) in conjunction with the keyword
VARIABLE.
If this prototype does not contain the right result layout or parameter layout,
another prototype can be assigned with the
(PT=)
option.
According to the function definition, a function call may return a
single result field. This can be a scalar value or an array field, which is
processed like a temporary field in the statement where the function call is
embedded. If the result is an array, the function call must be immediately
followed by an array-index-expression
addressing the required occurrences.
For example, to access the first occurrence of the array returned:
#FCT(<#A,#B>)(1)
If a single or multiple function calls are used within a statement, the evaluation of all functions is performed in a separate step before the statement execution will be started. The function calls are executed in the same order in which they appear in the statement.
Function calls are not allowed in the following situations:
in positions where the operand value is changed by the Natural
statement (for example, MOVE 1 TO #FCT(<..>) );
in a DEFINE
DATA statement;
in a database access statement (READ,
FIND,
SELECT,
UPDATE,
STORE, etc.);
as an argument of Natural system functions (AVER,
SUM,
*TRIM, etc.);
as an array index notation;
as a parameter of a function call.
If a function call is used in an INPUT statement, the return value
will be treated like a constant value. This leads to an automatic assignment of
attribute (AD=O)
to make this field write-protected (for output only).
A function call may consist of the following syntax elements:
|
|
function-name |
|
| variable-name |
Operand Definition Table:
| Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
variable-name
|
S | A | A | U | yes | no | |||||||||||||
Syntax Element Description:
| Syntax Element | Description |
|---|---|
function-name
|
Function Name:
|
variable-name
|
Variable Function Name:
|
PT=
|
|
prototype-name |
|
| prototype-variable-name |
For every function call, Natural tries to get information on the
function result and the calling parameters. This leads to a search for a
prototype with the same name as the call name. If such a prototype is not
available or if this prototype does not contain the right result layout or
parameter layout, another prototype can be linked to the function call with a
(PT=) clause. In this case, the referenced prototype steps in
place and is used to define the function result layout and the parameter
layout. The calling mode (symbolic or
variable)
declared in the referenced prototype is ignored.
Syntax Element Description:
IR=
|
|
format-length [/array-definition] |
|
||||||
[(array-definition)]
HANDLE OF OBJECT |
|||||||||
| ( |
|
|
[/array-definition])
DYNAMIC
|
||||||
This clause can be used to specify the
format-length/array-definition of the
return value for a function call without using an explicit or implicit
prototype definition, that is, it enables the explicit specification of the
function result layout. If a prototype is available for this function call or
if the cataloged version of the called function exists, the result format given
in the (IR=) clause is checked for move compatibility.
Syntax Element Description:
| Syntax Element | Description |
|---|---|
format-length |
Format/Length Definition:
The format and length of the field. For information on format/length definition of user-defined variables, see Format and Length of User-Defined Variables. |
array-definition |
Array Dimension Definition:
With an array-definition, you define the lower and upper bounds of the dimensions in an array definition. See Array Dimension Definition in the Statements documentation. |
HANDLE OF
OBJECT |
Handle of Object:
Used in conjunction with NaturalX. For further information, see NaturalX in the Programming Guide. |
A,
B or U |
Data Format:
Possible formats are alphanumeric, binary or Unicode for dynamic variables. |
DYNAMIC |
Dynamic Variable:
A field may be defined as For further information on processing dynamic variables, see Introduction to Dynamic Variables and Fields. |
Parameters are the data values passed to the function. They can be
provided as a constant value or a variable, depending on what is defined in the
DEFINE DATA
PARAMETER section of the function definition. The semantic
and syntactic rules which apply to the function parameters are the same as
described in the parameters section of subprograms; see
Parameters
in the description of the CALLNAT statement.
|
|
nX
|
|
|||||||
|
|
|
|
|
|
|||||
| operand | (AD=
|
)
|
|||||||
Operand Definition Table:
| Operand | Possible Structure | Possible Formats | Referencing Permitted | Dynamic Definition | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
operand
|
C | S | A | G | A | N | P | I | F | B | D | T | L | C | G | O | yes | no | |
Syntax Element Description:
| Syntax Element | Description | |
|---|---|---|
nX
|
Parameters to be Skipped:
With the notation A parameter that is to be skipped must be defined with the keyword
|
|
AD=
|
Attribute Definition:
If operand is a variable, you can mark it in one of the following ways: |
|
AD=O
|
Non-modifiable:
See session parameter
Note: |
|
AD=M
|
Modifiable:
See session parameter
This is the default setting. |
|
AD=A
|
Input only:
See session parameter
|
|
|
Note: |
||
If the result returned by the function call is an array, an index notation must be provided to address the demanded array occurrences.
For details, refer to Index Notation in User-Defined Variables in the Programming Guide.
The example FUNCEX01 uses the functions
F#ADDITION, F#CHAR, F#EVEN and
F#TEXT, which are defined in the sample functions
FUNCEX02, FUNCEX03, FUNCEX04 and
FUNCEX05.
** Example 'FUNCEX01': Function call (Program)
************************************************************************
DEFINE DATA LOCAL
1 #NUM (I2) INIT <5>
1 #A (I2) INIT <1>
1 #B (I2) INIT <2>
1 #C (I2) INIT <3>
1 #CHAR (A1) INIT <'A'>
END-DEFINE
*
IF #NUM = F#ADDITION(<#A,#B,#C>) /* Function with three parameters.
WRITE 'Sum of #A,#B,#C' #NUM
ELSE
IF #NUM = F#ADDITION(<1X,#B,#C>) /* Function with optional parameters.
WRITE 'Sum of #B,#C' #NUM
END-IF
END-IF
*
DECIDE ON FIRST #CHAR
VALUE F#CHAR (<>)(1) /* Function with result array.
WRITE 'Character A found'
VALUE F#CHAR (<>)(2)
WRITE 'Character B found'
NONE
IGNORE
END-DECIDE
*
IF F#EVEN(<#B>) /* Function with logical result value.
WRITE #B 'is an even number'
END-IF
*
F#TEXT(<'Hello', '*'>) /* Function used as a statement.
*
WRITE F#TEXT(<(IR=A12) 'Good'>) /* Function with intermediate result.
*
END
The function F#ADDITION is defined in the sample function
FUNCEX02 in library SYSEXPG.
** Example 'FUNCEX02': Function call (Function)
************************************************************************
DEFINE FUNCTION F#ADDITION
RETURNS (I2)
DEFINE DATA PARAMETER
1 #PARM1 (I2) OPTIONAL
1 #PARM2 (I2) OPTIONAL
1 #PARM3 (I2) OPTIONAL
END-DEFINE
/*
RESET F#ADDITION
IF #PARM1 SPECIFIED
F#ADDITION := F#ADDITION + #PARM1
END-IF
IF #PARM2 SPECIFIED
F#ADDITION := F#ADDITION + #PARM2
END-IF
IF #PARM3 SPECIFIED
F#ADDITION := F#ADDITION + #PARM3
END-IF
/*
END-FUNCTION
*
END
The function F#CHAR is defined in the example function
FUNCEX03 in library SYSEXPG.
** Example 'FUNCEX03': Function call (Function) ************************************************************************ DEFINE FUNCTION F#CHAR RETURNS (A1/1:2) /* F#CHAR(1) := 'A' F#CHAR(2) := 'B' /* END-FUNCTION * END
The function F#EVEN is defined in the example function
FUNCEX04 in library SYSEXPG.
** Example 'FUNCEX04': Function call (Function)
************************************************************************
DEFINE FUNCTION F#EVEN
RETURNS (L)
DEFINE DATA
PARAMETER
1 #NUM (N4) BY VALUE
LOCAL
1 #REST (I2)
END-DEFINE
/*
DIVIDE 2 INTO #NUM REMAINDER #REST
/*
IF #REST = 0
F#EVEN := TRUE
ELSE
F#EVEN := FALSE
END-IF
/*
END-FUNCTION
*
END
The function F#TEXT is defined in the sample function
FUNCEX05 in library SYSEXPG.
** Example 'FUNCEX05': Function call (Function)
************************************************************************
DEFINE FUNCTION F#TEXT
RETURNS (A20) BY VALUE
DEFINE DATA
PARAMETER
1 #TEXT1 (A5) BY VALUE
1 #TEXT2 (A1) BY VALUE OPTIONAL
LOCAL
1 #FRAME (A3)
END-DEFINE
/*
IF #TEXT2 SPECIFIED
MOVE ALL #TEXT2 TO #FRAME
/*
COMPRESS #FRAME #TEXT1 'world' #FRAME INTO F#TEXT
/*
WRITE F#TEXT
ELSE
COMPRESS #TEXT1 'morning' INTO F#TEXT
/*
END-IF
/*
END-FUNCTION
*
END
FUNCEX01Sum of #B,#C 5
Character A found
2 is an even number
*** Hello world ***
Good morning