|
|||||
|
|||||
|
This document covers the following topics:
For an explanation of the symbols used in the syntax diagram, see Syntax Symbols.
Related Statement: DEFINE
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
| Syntax Element | Description |
|---|---|
[VARIABLE]
prototype-name
|
Prototype Name:
|
UNKNOWN
|
UNKNOWN Option:
The keyword |
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 |
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=) 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 |
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 For further information, see Array Dimension Definition in the
description of the |
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 For information on processing dynamic variables, see Introduction to Dynamic Variables and Fields in the Programming Guide. |
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 See also Defining Parameter
Data in the |
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 |
END-DEFINE |
End of Clause:
The Natural reserved word |
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.
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.
DPTEX1:
Function call: 3 6 9
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.
DPTEX2:
First character: A