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:
- intrinsic-function-name-1 is specified in the Repository paragraph
- 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:
- 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.
- 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.
- BY VALUE is assumed when the BY VALUE phrase is specified for the corresponding formal parameter.
- Evaluation of the function-identifier proceeds as follows:
- 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.
- 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.
- 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.
- 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.