DEFINE PROTOTYPE prototype-name [FOR] VARIABLE prototype-variable-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 an explanation of the symbols used in the syntax diagram, see Syntax Symbols.

Related Statement: DEFINE FUNCTION

---

Function

The prototype definition can be used to describe the call interface of a certain function. This includes the parameters which are to be passed in a function call, the result value returned by the function call, and the calling mode of the function (symbolic or variable). This information is used to resolve a function call within a programming object.

The information provided by a DEFINE PROTOTYPE statement can also be obtained partly from another source by the compiler. When a corresponding DEFINE PROTOTYPE statement is missing and the cataloged version of the called function is available, the result layout and parameter layout are extracted from the function object.

A variable function call, where the function name is an alphanumeric variable which contains the function name, can only be indicated with a DEFINE PROTOTYPE statement.

Therefore, a DEFINE PROTOTYPE statement is only needed for a function call,

• if a variable function call is to be coded;

• if an (IR=) option is not specified in the function call and the cataloged version of the called function is not available;

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

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

• Natural object type Function

• Function Call

• User-Defined Functions

Syntax Description

Syntax Element	Description
prototype-name	Prototype Name: prototype-name is the identifier of the function which is described by this prototype. If the name matches an existent function name, this prototype is used to resolve the function calls with this name. A prototype definition can also be used in the (PT=) option of a function call. Then the referenced prototype will overrule the result und parameter layouts. The name has to follow the same rules which apply for a function name. This means the name has to start with a letter or a hash (#), and the maximum length is 32 characters.
VARIABLE 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.
UNKNOWN	UNKNOWN Option: The keyword UNKNOWN can be used to specify 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=) option. 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-clause	See SAME AS Clause below.
USING FUNCTION [DEFINITION [OF]] function-name	See USING FUNCTION Clause below.
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
		(		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=) option is provided. If such a clause is missing, the function can only be called stand-alone, but not in place of an operand in 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 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	Direct Parameter Data Definition: Instead of defining a parameter data area, parameter data can also be defined directly within a function call. See also Direct 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
		prototype-variable-name

With the same-as-clause clause you may use the result layout and the parameter layout of another prototype, which has been defined before in the same programming object.

Syntax Element Description:

Syntax Element	Description
prototype-name	Name of Referenced Prototype: prototype-name is the identifier of the prototype whose result and parameters layouts are to be used.
prototype-variable-name	Variable Name of Referenced Prototype: 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.

USING FUNCTION Clause

USING FUNCTION [DEFINITION [OF]] function-name

This clause offers the possibility to reference a function, which is used to extract the result and parameter layouts. The function-name provided has to be the name of an existing cataloged function object.

Be aware, the function-name is defined in the DEFINE FUNCTION statement (see function-name) and does not necessarily have to match the name of the module in which the function is defined.

Examples

• Example 1 - DEFINE PROTOTYPE for a Symbolic Function Call

• Example 2 - DEFINE PROTOTYPE for a Variable Function Call

Example 1 - DEFINE PROTOTYPE for a Symbolic Function Call

This is a prototype definition of a function named F#FACTOR. Since the keyword VARIABLE is missing, the function call to F#FACTOR will be treated as a symbolic function call. 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 for a Variable Function Call

Due to the keyword VARIABLE, this prototype specifies a variable function call. In this case, the prototype-name referenced is not the name of the called function, but the name of 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