Function Call

call-name
  (< [([prototype-cast] [intermediate-result-definition])] [parameter] [,[parameter]] ... >)
  [array-index-expression]

This document covers the following topics:

Related topics:


Calling User-Defined Functions

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:

Symbolic Function Call

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.

Variable Function Call

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.

Function Result

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)

Evaluation Sequence

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.

Restrictions

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.);

  • in an AT BREAK or IF BREAK statement;

  • 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).

Syntax Description

A function call may consist of the following syntax elements:

call-name

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:

function-name is the name of the function to be called. 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. If a prototype with the same name has already been defined before, this prototype is used to pick up the function interface; that is, the result layout definition and the required parameters.

variable-name
Variable Function Name:

variable-name is the name of the variable containing the real name of the function to be called at runtime. In order to declare the call name as a variable name, a prototype with the same name, which is classified with keyword VARIABLE, must be defined before.

prototype-cast

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:

Syntax Element Description
prototype-name
Prototype Name:

prototype-name is the identifier of the prototype whose result and parameters layouts are to be used.

prototype-variable-name
Prototype Variable Name:

prototype-variable-name is the name of an alphanumeric field used as function name in a function call. At execution time it has to contain the name of the function to be called.

The name has to follow the same rules which apply for a variable reference, including field qualification, but without array index references.

intermediate-result-definition

  IR=

format-length [/array-definition]

[(array-definition)] HANDLE OF OBJECT
(

A
U
B

[/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.

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 DYNAMIC.

For further information on processing dynamic variables, see Introduction to Dynamic Variables and Fields.

Parameter(s)

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      

 

 

M
O
A

 

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 nX you can specify that the next n parameters are to be skipped (for example, 1X to skip the next parameter, or 3X to skip the next three parameters); this means that for the next n parameters no values are passed to the function.

A parameter that is to be skipped must be defined with the keyword OPTIONAL in the function's DEFINE DATA PARAMETER statement. OPTIONAL means that a value can - but need not - be passed from the invoking object to such a parameter.

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 AD=O.

Note:
Internally, AD=O is processed in the same way as BY VALUE (see the section parameter-data-definition in the description of the DEFINE DATA statement).

AD=M
Modifiable:

See session parameter AD=M.

This is the default setting.

AD=A
Input only:

See session parameter AD=A.

Note:
If operand is a constant, the attribute definition AD cannot be explicitly specified. For constants, AD=O always applies.

array-index-expression

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.

Example

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 

Output of Program FUNCEX01

Sum of #B,#C      5        
Character A found                             
     2 is an even number            
*** Hello world ***                 
Good morning