|
|||||
|
|||||
|
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 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
| Syntax Element | Description |
|---|---|
prototype-name
|
Prototype Name:
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:
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 |
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 |
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=)
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 |
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
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 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 |
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 |
END-DEFINE |
End of Clause:
The Natural reserved word |
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:
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.
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.
DPTEX1:
Function call: 3 6 9
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.
DPTEX2:
First character: A