DEFINE PROTOTYPE [FOR] VARIABLE prototype-name

UNKNOWN [return-data-definition ] [parameter-definition] same-as-clause USING FUNCTION [DEFINITION [OF]] function-name

END-PROTOTYPE

This document covers the following topics:

• Function

• Syntax Description

• Examples

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

Related Statement: DEFINE FUNCTION

---

Function

The DEFINE PROTOTYPE statement is used to specify the properties for calling a function including the following:

• the parameters to be passed in the function call,

• the result value to be returned by the function call, and

• whether the function is called with the function name defined in the DEFINE FUNCTION statement, or with an alphanumeric variable that contains the function name.

This information is used to resolve a function call within a Natural object at compile time.

A DEFINE PROTOTYPE statement is only needed for a function call if any of the following is true:

• The specified function name is an alphanumeric variable which contains the name of the function to be called at execution time.

• An (IR=) clause is not specified in the function call and a cataloged object of the called function is not available.

• The parameters provided in the function call are to be validated and the cataloged object of the called function is not available.

The DEFINE PROTOTYPE statement can be included in a copycode object if the function is to be called from multiple objects.

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

• Natural object type Function

• Function Call

Syntax Description

Syntax Element	Description
[VARIABLE] prototype-name	Prototype Name: prototype-name is either of the following: the name of the prototype whose parameter and result field definitions are to be used. This name typically matches the function-name in the DEFINE FUNCTION statement of the referenced function; the name of an alphanumeric field specified as function-name in a function call if the keyword VARIABLE is specified. This field must contain the name of the function to be called at execution time. An array index expression must not be specified with the field name.
UNKNOWN	UNKNOWN Option: The keyword UNKNOWN specifies that the function interface is currently undefined. In this case, the cataloged object (if available) will not be used to extract the function result and the parameter description. When a function call is embedded in a Natural statement, this requires to give the result layout explicitly with an (IR=) clause. In addition, parameters provided in the function call are not checked.
return-data-definition	See Return Data Definition below.
parameter-definition	See Parameter Definition below.
same-as-clause	See SAME AS Clause below.
USING FUNCTION [DEFINITION [OF]] function-name	USING FUNCTION Clause: function-name is the name of an existing cataloged object of the type function. The parameters and the result field definitions of this function are used to resolve the function call.
END-PROTOTYPE	End of DEFINE PROTOTYPE Statement: The Natural reserved word END-PROTOTYPE must be used to terminate the DEFINE PROTOTYPE statement.

Return Data Definition

RETURNS [variable-name]		(format-length [/array-definition])
		[(array-definition)] HANDLE OF OBJECT
		[(array-definition)] HANDLE OF GUI
		(		A		[/array-definition])	DYNAMIC
				U
				B

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

When no return data definition is specified, a function call can only be used within a statement if an explicit (IR=) clause is provided. If such a clause is missing, the function can only be called as a statement, but not in place of an operand within a statement.

Syntax Element Description:

Syntax Element	Description
variable-name	Return Value Name: The optional variable-name has no meaning. It is just there to have a syntax structure similar to the Return Data Definition clause of the DEFINE FUNCTION statement.
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 Array Dimension Definition in the description of the DEFINE DATA statement.
HANDLE OF GUI	Handle of GUI: Used in conjunction with event-driven programming. See HANDLE OF GUI in Event-Driven Programming Techniques in the Programming Guide.
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.

Parameter Definition

DEFINE DATA
		PARAMETER UNKNOWN
		PARAMETER		USING parameter-data-area
				parameter-data-definition ...			...
END-DEFINE

The parameter-definition clause defines the parameters which are to be provided in a function call. This definition layout is checked against the parameters given in a function call. If this clause is omitted, this declares the function as free of parameters. In this case, every attempt to provide parameters in the function call is rejected.

The identifiers used to name the parameter fields have no meaning. They are just there to have a syntax structure similar to the DEFINE DATA PARAMETER syntax.

Syntax Element Description:

Syntax Element	Description
PARAMETER UNKNOWN	UNKNOWN Option: With this option, no parameter is specified and the parameter check in the function call is disabled. As a consequence, any number of parameters in the function call will be accepted.
USING parameter-data-area	PDA Name: The name of the parameter-data-area 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-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.
END-DEFINE	End of Clause: The Natural reserved word END-DEFINE must be used to end the parameter-definition clause.

SAME AS Clause

SAME AS [PROTOTYPE]

prototype-name

With the SAME AS clause you can use the parameter and result field definitions of another prototype which has been defined before in the same Natural object.

Examples

• Example 1 - DEFINE PROTOTYPE with a Defined Function Name

• Example 2 - DEFINE PROTOTYPE with a Variable Function Name

Example 1 - DEFINE PROTOTYPE with a Defined Function Name

This is a prototype definition for a function named F#FACTOR where the prototype-name corresponds to the function-name specified in the referenced DEFINE FUNCTION statement. The result returned by the function is of format (I2/1:3), and a single parameter of format (I2) is required.

** Example 'DPTEX1': DEFINE PROTOTYPE and function call                 
************************************************************************
DEFINE DATA LOCAL  
  1 #NUM (I2)
END-DEFINE                                                              
*
DEFINE PROTOTYPE F#FACTOR                                         
  RETURNS (I2/1:3)                                                      
  DEFINE DATA PARAMETER                                                 
    1 #VALUE (I2)                                                       
  END-DEFINE                                                            
END-PROTOTYPE                                                           
*                                                                       
#NUM := 3                                                              
*   
WRITE 'Function call:' F#FACTOR(<#NUM>)(*) 
*                                                                       
END

The function F#FACTOR is defined in the example function DFUEX2 in library SYSEXSYN. See Examples in the DEFINE FUNCTION statement description.

Output of Program DPTEX1:

Function call:      3      6      9

Example 2 - DEFINE PROTOTYPE with a Variable Function Name

Due to the keyword VARIABLE, this prototype specifies a function call where the referenced prototype-name is an alphanumeric variable which contains the function name at execution time.

** Example 'DPTEX2': DEFINE PROTOTYPE and function call
************************************************************************
DEFINE DATA LOCAL  
  1 #NAME (A20) 
  1 #TEXT (A10)
END-DEFINE                                                     
*  
DEFINE PROTOTYPE VARIABLE #NAME 
  RETURNS #RETURN (A1)          
  DEFINE DATA PARAMETER         
    1 #IN (A10)                                                
  END-DEFINE                    
END-PROTOTYPE                   
*                                                              
#NAME := 'F#FIRST-CHAR'                                        
#TEXT := 'ABCDEFGHIJ'                                          
*                                                              
WRITE 'First character:' #NAME(<#TEXT>)
*
END

The function F#FIRST-CHAR is defined in the example function DFUEX1 in library SYSEXSYN. See Examples in the DEFINE FUNCTION statement description.

Output of Program DPTEX2:

First character: A