DEFINE FUNCTION

DEFINE FUNCTION function-name

[return-data-definition]

[function-data-definition]

statement...

END-FUNCTION

This document covers the following topics:

DEFINE FUNCTION Usage
DEFINE FUNCTION Syntax Description
DEFINE FUNCTION Examples

For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statement: DEFINE PROTOTYPE

DEFINE FUNCTION Usage

The DEFINE FUNCTION statement is used to define a function which is stored as a Natural object of the type function. A function object may contain only one DEFINE FUNCTION statement.

The DEFINE FUNCTION statement defines the function name, the parameters, the local and application-independent variables, the function result and the statements forming the operation logic. These statements are executed when the function is called.

For further information, see the following sections in the Programming Guide:

Natural object type Function
Function Call

DEFINE FUNCTION Syntax Description

Syntax Element	Description
`function-name`	Function Name: `function-name` is the name of the function to be called. It must comply with the naming conventions for user-defined variables described in the Using Natural documentation. `function-name` is not necessarily the same as the name of the stored object that contains the function definition. You may not use the same function name twice in one library.
`return-data-definition`	Return Data Definition Clause: For details on this clause, see Return Data Definition.
`function-data-definition`	Function Data Definition Clause: For details on this clause, see Function Data Definition.
`statement...`	Statement(s) to be Executed: Defines the operation section which is executed when the function is called. It forms the function logic.
`END-FUNCTION`	End of DEFINE FUNCTION Statement: The Natural reserved word `END-FUNCTION` must be used to terminate the `DEFINE FUNCTION` statement.

Return Data Definition

`RETURNS` [`variable-name`]	(`format-length`[/`array-definition`])				[`BY VALUE`]
	[(`array-definition`)] `HANDLE OF`		`dialog-element-type` `OBJECT`
	(	`A`	[/`array-definition`])	`DYNAMIC`
		`U`
		`B`

The return-data-definition clause defines the format/length and, if applicable, the array structure of the result value returned by the function.

Syntax Element Description:

Syntax Element	Description
`variable-name`	Return Value Name: Optionally, you may specify a name which is used to access the return field within the function coding. If no such name is specified, the function name is used instead.
`format-length`	Format/Length Definition: The format and length of the result field. For information on format/length definition of user-defined variables, see Format and Length of User-Defined Variables in the Programming Guide.
`array-definition`	Array Dimension Definition: With `array-definition`, you define the lower and upper bounds of a dimension in an array-definition, if the function result is an array field. For further information, see `DEFINE DATA` statement, Array Dimension Definition.
`HANDLE OF` `dialog-element-type`	Dialog Element Type: The type of dialog element. Its possible values are the values of the `TYPE` attribute.
`HANDLE OF OBJECT`	Handle of Object: Used in conjunction with NaturalX. For further information, see NaturalX in the Programming Guide.
`A`, `U` or `B`	Data Type: Alphanumeric (A), Unicode (U) or binary (B) for a dynamic result.
`DYNAMIC`	Dynamic Variable: The function result may be defined as `DYNAMIC`. For information on processing dynamic variables, see Introduction to Dynamic Variables and Fields in the Programming Guide.
`BY VALUE`	BY VALUE Option: If `BY VALUE` is specified, the format/length of the "sending" field (defined inside the return-data-definition clause) and the "receiving" field (which receives the result at the place where the function is called) must only be transfer compatible. The format/length of the "receiving" field is either defined via an explicit `(IR=)` clause in the function call; or defined with a `DEFINE PROTOTYPE` statement; or taken over from the `RETURNS` field of the function object, which must already exist. For data transfer compatibility the rules outlined in Rules for Arithmetic Assignment and Data Transfer in the Programming Guide apply. If `BY VALUE` is not specified, the format and length of the "receiving" field must exactly match the characteristics of the "sending" field.

Function Data Definition

`DEFINE DATA`
	`PARAMETER`	`USING` `parameter-data-area` `parameter-data-definition`
	`LOCAL`	`USING`	`local-data-area` `parameter-data-area`
		`local-data-definition`
[`INDEPENDENT` `aiv-data-definition` ]
`END-DEFINE`

The function-data-definition clause defines the parameters which are to be provided when the function is called, and the data fields used by the function, such as local and application-independent variables. A global data area (GDA) cannot be referenced inside the function definition.

Syntax Element Description:

Syntax Element	Description
`PARAMETER USING parameter-data-area`	PDA Name: Specify the name of the parameter data area (PDA) that contains data elements which are used as parameters in a function call. See also Defining Parameter Data in the `DEFINE DATA` statement description.
`PARAMETER parameter-data-definition`	Parameter Data Definition: Instead of defining a parameter data area, parameter data can also be defined directly within a function call. See also Parameter Data Definition in the `DEFINE DATA` statement description.
`LOCAL USING local-data-area`	LDA Name: Specify the name of the local data area (LDA) to be referenced. See also Defining Local Data in the `DEFINE DATA` statement description.
`LOCAL USING parameter-data-area`	PDA Name: Specify the name of a parameter data area (PDA). Note: A data area referenced with `DEFINE DATA LOCAL` may also be a parameter data area (PDA). By using a PDA as an LDA you can avoid the extra effort of creating an LDA that has the same structure as the PDA. See also Defining Local Data in the `DEFINE DATA` statement description.
`LOCAL local-data-definition`	Local Data Definition: For information on how to define elements or fields within the statement itself, that is, without using an LDA or PDA, see the section Local Data Definition in the `DEFINE DATA` statement description.
`INDEPENDENT aiv-data-definition`	AIV Data Definition: Can be used to define a single or multiple application-independent variables (AIVs). See Defining Application-Independent Variables in the `DEFINE DATA` statement description.
`END-DEFINE`	End of Clause: The Natural reserved word `END-DEFINE` must be used to end the `function-data-definition` clause.

DEFINE FUNCTION Examples

Example 1 - DEFINE FUNCTION
Example 2 - DEFINE FUNCTION with Result Value Array

Example 1 - DEFINE FUNCTION

** Example 'DFUEX1': DEFINE FUNCTION                                    
************************************************************************
DEFINE FUNCTION F#FIRST-CHAR                                                   
  RETURNS #RESULT (A1)                                                
  DEFINE DATA PARAMETER                                                 
    1 #PARM (A10)                                                       
  END-DEFINE                                                            
  /*                                                                    
  #RESULT := #PARM        /* First character as return value.     
END-FUNCTION                                                            
*                                                                       
END

The function F#FIRST-CHAR is used in the example program DPTEX2 in library SYSEXSYN. See Examples in the DEFINE PROTOTYPE statement description.

Example 2 - DEFINE FUNCTION with Result Value Array

** Example 'DFUEX2': DEFINE FUNCTION                                    
************************************************************************
DEFINE FUNCTION F#FACTOR                                                  
  RETURNS (I2/1:3)                                                      
  DEFINE DATA PARAMETER                                                 
    1 #VALUE (I2)                                                       
  END-DEFINE                                                            
  /*                                                                    
  F#FACTOR(1) := #VALUE * 1                                                
  F#FACTOR(2) := #VALUE * 2                                                
  F#FACTOR(3) := #VALUE * 3                                                
  /*                                                                    
END-FUNCTION                                                            
*                                                                       
END

The function F#FACTOR is used in the example program DPTEX1 in library SYSEXSYN. See Examples in the DEFINE PROTOTYPE statement description.