Function-identifier

A function-identifier references the unique data item that results from the evaluation of a function.

General Format

Syntax Rules

A function-identifier must not be specified as a receiving operand.
The word FUNCTION is required
unless either of the following apply:
1. intrinsic-function-name-1 is specified in the Repository paragraph
2. function-prototype-name-1 is specified.
Function-prototype-name-1 must be a function prototype specified in the Repository paragraph.
The word OMITTED must not be specified if intrinsic-function-name-1 is specified.
Argument-1 must be an identifier, a literal, or an arithmetic expression. Specific rules governing the number, class, and category of argument-1 are given for intrinsic functions in the definition of that intrinsic function in the section Definitions of Functions in the chapter Procedure Division - Intrinsic Functions
and for user-defined functions in the section Conformance for Parameters and Returning Items in the chapter Procedure Division
.
If the word OMITTED is specified, the OPTIONAL phrase must be specified for the corresponding formal parameter.
If function-prototype-name-1 is specified and the formal parameter corresponding to argument-1 is specified with a BY VALUE phrase, argument-1 must be of class numeric, object or pointer.
A numeric function must not be specified where an integer operand is required, even though a particular reference of the numeric function might yield an integer value.
An integer function other than the integer form of the ABS function must not be specified where an unsigned integer is required.
A function-identifier which references an integer or numeric function can only be used in an arithmetic expression.
If function-prototype-name-1 is specified, the rules for conformance specified in the section Conformance for Parameters and Returning Items in the chapter Procedure Division apply.
A reference modifier can be specified only for functions of the category alphanumeric
or national
.
If a function's definition permits arguments and a left parenthesis immediately follows function-prototype-name-1 or intrinsic-function-name-1, the left parenthesis is always treated as the left parenthesis of that function's arguments.
Note: For a function that may be referenced either with or without arguments, such as the RANDOM function, careful coding is necessary to ensure correct interpretation. For example, in the following:
```
 FUNCTION MAX (FUNCTION RANDOM (A) B)
```
'A' is treated as an argument to the RANDOM function. If 'A' is instead meant to be a second argument to the MAX function, different coding is necessary - either:
```
 FUNCTION MAX (FUNCTION RANDOM () A B)

   or
```
```
 FUNCTION MAX ( (FUNCTION RANDOM) (A) B)

   or
```
```
 FUNCTION MAX (FUNCTION RANDOM A B)
```

General Rules

A function-identifier references a temporary data item whose value is determined when the function is referenced at run time.
If intrinsic-function-name-1 is specified, the temporary data item is an elementary data item whose description and category are specified by the definition of that intrinsic function in the section Definitions of Functions in the chapter Procedure Division - Intrinsic Functions.

If function-prototype-name-1 is specified, the description, class, and category of the temporary data item is that specified by the description in the Linkage Section of the item specified in the RETURNING phrase of the PROCEDURE DIVISION header of the function prototype identified by function-prototype-name-1.
At the time reference is made to a function, its arguments are evaluated individually in the order specified in the list of arguments, from left to right. An argument being evaluated may itself be a function-identifier or may be an expression containing function-identifiers. There is no restriction preventing the function referenced in evaluating an argument from being the same function as that for which the argument is specified. In other words, recursion is permitted. Additional rules for intrinsic functions are given in the section Intrinsic Functions.
for user-defined functions in the sections The PROCEDURE DIVISION Header and Conformance for Parameters and Returning Items in the chapter Procedure Division

If a function is expecting an integer argument, then if a floating-point argument is provided, the value is rounded to the nearest integer, otherwise any fractional part is truncated.
If function-prototype-name-1 is specified, the function to be activated is identified by function-prototype-name-1 in accordance with the rules specified in the section The Repository Paragraph in the chapter Environment Division, and function-prototype-name-1 is used to determine the characteristics of the activated function.
If function-prototype-name-1 is specified, the manner used for passing each argument is determined as follows:
1. BY REFERENCE is assumed when the BY REFERENCE phrase is specified or implied for the corresponding formal parameter and argument-1 is an identifier that is permitted as a receiving operand, other than an object property, object data item or factory object data item.
2. BY CONTENT is assumed when the BY REFERENCE phrase is specified or implied for the corresponding formal parameter and argument-1 is a literal, an arithmetic expression, an object property, object data item, factory object data item or any identifier that is not permitted as a receiving operand.
3. BY VALUE is assumed when the BY VALUE phrase is specified for the corresponding formal parameter.
Evaluation of the function-identifier proceeds as follows:
1. Each argument-1 is evaluated at the beginning of the evaluation of the function-identifier. The values of argument-1 are made available to the activated function at the time control is transferred to that function.
2. The run-time system attempts to locate the function being activated.
  If function-prototype-name-1 is specified, the rules are specified in the section Conventions for Function-prototype-names. Additional rules are given in the section The Repository Paragraph in the chapter Environment Division.
3. If the function is located but the resources necessary to execute the function are not available, the function is not activated. The run-time resources that are checked in order to determine the availability of the function for execution are defined by the implementor.
4. The function specified by the function-identifier is made available for execution and control is transferred to the activated function in a manner consistent with the call convention specified for the function.
  If function-prototype- name-1 is specified and the function to be activated is a COBOL function, its execution is as described in the section The PROCEDURE DIVISION Header in the chapter Procedure Division.
  
  If intrinsic-function-name-1 is specified, its execution is as described in the chapter Procedure Division - Intrinsic Functions.
  
  If function-prototype-name-1 is specified and the function to be activated is not a COBOL function, the execution is as defined in your COBOL system documentation on interfacing.
If the word OMITTED is specified or a trailing argument is omitted, the omitted-argument condition for that parameter evaluates to TRUE in the activated function. (See the topic The Omitted-Argument Condition.)
If a parameter for which the omitted-argument condition is true is referenced in an activated function, except as an argument or in the omitted-argument condition, you will get runtime error 203.

Parent topic: Uniqueness of Reference

Related information

Definitions of Functions

Conformance for Parameters and Returning Items

Intrinsic Functions

The PROCEDURE DIVISION Header

The Repository Paragraph

Conventions for Function-prototype-names

Procedure Division - Intrinsic Functions

The Omitted-Argument Condition