DEFINE PROTOTYPE

#### Search Results

Search

# DEFINE PROTOTYPE

`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:

- DEFINE PROTOTYPE Usage

- DEFINE PROTOTYPE Syntax Description

- DEFINE PROTOTYPE Examples

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

Related Statement: `DEFINE FUNCTION`

## DEFINE PROTOTYPE Usage

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

## DEFINE PROTOTYPE 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.

## DEFINE PROTOTYPE 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

### On this page

- DEFINE PROTOTYPE Usage
- DEFINE PROTOTYPE Syntax Description
- DEFINE PROTOTYPE Examples