The general format of a function-identifier is:
argument-1 cannot be a windowed date field, except in the UNDATE intrinsic function.
A function-identifier can be specified wherever a data item of the type of the function is allowed. The argument to a function can be any function or an expression containing a function, including another evaluation of the same function, whose result meets the requirements for the argument.
Within a procedure division statement, each function-identifier is evaluated at the same time as any reference modification or subscripting associated with an identifier in that same position would be evaluated.
The class and characteristics of a function, and the number and types of arguments it requires, are determined by its function definition. These characteristics include:
For some functions, the class and characteristics are determined by the arguments to the function.
The evaluation of any intrinsic function is not affected by the context in which it appears; in other words, function evaluation is not affected by operations or operands outside the function. However, evaluation of a function can be affected by the attributes of its arguments.
Within a procedure division statement, each function-identifier is evaluated at the same time as any reference modification or subscripting associated with an identifier in that same position would be evaluated.
COBOL has the following types of functions:
Alphanumeric functions are of class and category alphanumeric. The value returned has an implicit usage of DISPLAY without the NATIVE phrase. The number of character positions in the value returned is determined by the function definition.
National functions are of class and category national. The value returned has an implicit usage of NATIONAL and is represented in national characters (UTF-16). The number of character positions in the value returned is determined by the function definition.
Numeric functions are of class and category numeric. The returned value is always considered to have an operational sign and is a numeric intermediate result. For more information, see the COBOL for Windows Programming Guide.
Integer functions are of class and category numeric. The returned value is always considered to have an operational sign and is an integer intermediate result. The number of digit positions in the value returned is determined by the function definition. For more information, see the COBOL for Windows Programming Guide.
Reference modification of an alphanumeric function is allowed. If reference modification is specified for a function, the evaluation of the reference modification takes place immediately after the evaluation of the function; that is, the function's returned value is reference-modified.
An alphanumeric function cannot be used:
A national function can be used as an argument for any function that allows a national argument.
Reference modification of a national function is allowed. If reference modification is specified for a function, the evaluation of the reference modification takes place immediately after the evaluation of the function; that is, the function's returned value is reference-modified.
A national function cannot be used:
A numeric function can be referenced as an argument for a function that allows a numeric argument.
A numeric function cannot be used where an integer operand is required, even if the particular reference would yield an integer value. The INTEGER or INTEGER-PART functions can be used to force the type of a numeric argument to be an integer.
An integer function can be referenced as an argument for a function that allows an integer argument.
Usage notes:
The value returned by some functions is determined by the arguments specified in the function-identifier when the functions are evaluated. Some functions require no arguments; others require a fixed number of arguments, and still others accept a variable number of arguments.
An argument must be one of the following:
See Function definitions for function-specific argument specifications.
The types of arguments are:
Values that can be specified as alphanumeric arguments only for the DISPLAY-OF and NATIONAL-OF functions are described in Appendix F. Code page names.)
Some functions place constraints on their arguments, such as the acceptable range of values. If the values assigned as arguments for a function do not comply with specified constraints, the returned value is undefined.
If a nested function is used as an argument, the evaluation of its arguments is not affected by the arguments in the outer function.
Only those arguments at the same function level interact with each other. This interaction occurs in two areas:
When a function is evaluated, its arguments are evaluated individually in the order specified in the list of arguments, from left to right. The argument being evaluated can be a function-identifier or an expression that includes function-identifiers.
If an arithmetic expression is specified as an argument and if the first operator in the expression is a unary plus or a unary minus, the expression must be immediately preceded by a left parenthesis.
Floating-point literals are allowed wherever a numeric argument is allowed and in arithmetic expressions used in functions that allow a numeric argument.
Internal floating-point items and external floating-point items (both display floating-point and national floating-point) can be used wherever a numeric argument is allowed and in arithmetic expressions as arguments to a function that allows a numeric argument.
Floating-point items and floating-point literals cannot be used where an integer argument is required or where an argument of class alphanumeric or national is required (such as in the LOWER-CASE, REVERSE, UPPER-CASE, NUMVAL, and NUMVAL-C functions).
The following statement illustrates the use of intrinsic function UPPER-CASE to replace each lowercase letter in an alphanumeric argument with the corresponding uppercase letter.
MOVE FUNCTION UPPER-CASE('hello') TO DATA-NAME.
This statement moves HELLO into DATA-NAME.
The following statement illustrates the use of intrinsic function LOWER-CASE to replace each uppercase letter in a national argument with the corresponding lowercase letter.
MOVE FUNCTION LOWER-CASE(N'HELLO') TO N-DATA-NAME.
This statement moves national characters hello into N-DATA-NAME.
The following statement illustrates the use of a numeric intrinsic function:
COMPUTE NUM-ITEM = FUNCTION SUM(A B C)
This statement uses the numeric function SUM to add the values of A, B, and C and places the result in NUM-ITEM.
When a function allows an argument to be repeated a variable number of times, you can refer to a table by specifying the data-name and any qualifiers that identify the table. This can be followed immediately by subscripting where one or more of the subscripts is the word ALL.
Tip: The evaluation of an ALL subscript must result in at least one argument or the value returned by the function will be undefined; however, the situation can be diagnosed at run time by specifying the SSRANGE compiler option and the CHECK runtime option.
Specifying ALL as a subscript is equivalent to specifying all table elements possible using every valid subscript in that subscript position.
For a table argument specified as Table-name(ALL), the order of the implicit specification of each table element as an argument is from left to right, where the first (or leftmost) argument is Table-name(1) and ALL has been replaced by 1. The next argument is Table-name(2), where the subscript has been incremented by 1. This process continues, with the subscript being incremented by 1 to produce an implicit argument, until the ALL subscript has been incremented through its range of values.
For example,
FUNCTION MAX(Table(ALL))
is equivalent to
FUNCTION MAX(Table(1) Table(2) Table(3) ... Table(n))
where n is the number of elements in Table.
If there are multiple ALL subscripts, Table-name(ALL, ALL, ALL), the first implicit argument is Table-name(1, 1, 1), where each ALL has been replaced by 1. The next argument is Table-name(1, 1, 2), where the rightmost subscript has been incremented by 1. The subscript represented by the rightmost ALL is incremented through its range of values to produce an implicit argument for each value.
Once a subscript specified as ALL has been incremented through its range of values, the next subscript to the left that is specified as ALL is incremented by 1. Each subscript specified as ALL to the right of the newly incremented subscript is set to 1 to produce an implicit argument. Once again, the subscript represented by the rightmost ALL is incremented through its range of values to produce an implicit argument for each value. This process is repeated until each subscript specified as ALL has been incremented through its range of values.
For example,
FUNCTION MAX(Table(ALL, ALL))
is equivalent to
FUNCTION MAX(Table(1, 1) Table(1, 2) Table(1, 3) ... Table(1, n)
Table(2, 1) Table(2, 2) Table(2, 3) ... Table(2, n)
Table(3, 1) Table(3, 2) Table(3, 3) ... Table(3, n)
...
Table(m, 1) Table(m, 2) Table(m, 3) ... Table(m, n))
where n is the number of elements in the column dimension of Table, and m is the number of elements in the row dimension of Table.
ALL subscripts can be combined with literal, data-name, or index-name subscripts to reference multidimensional tables.
For example,
FUNCTION MAX(Table(ALL, 2))
is equivalent to
FUNCTION MAX(Table(1, 2)
Table(2, 2)
Table(3, 2)
...
Table(m, 2))
where m is the number of elements in the row dimension of Table.
If an ALL subscript is specified for an argument and the argument is reference-modified, then the reference-modifier is applied to each of the implicitly specified elements of the table.
If an ALL subscript is specified for an operand that is reference-modified, the reference-modifier is applied to each of the implicitly specified elements of the table.
If the ALL subscript is associated with an OCCURS DEPENDING ON clause, the range of values is determined by the object of the OCCURS DEPENDING ON clause.
For example, given a payroll record definition such as:
01 PAYROLL.
02 PAYROLL-WEEK PIC 99.
02 PAYROLL-HOURS PIC 999 OCCURS 1 TO 52
DEPENDING ON PAYROLL-WEEK.
The following COMPUTE statements could be used to identify total year-to-date hours, the maximum hours worked in any week, and the specific week corresponding to the maximum hours:
COMPUTE YTD-HOURS = FUNCTION SUM (PAYROLL-HOURS(ALL)) COMPUTE MAX-HOURS = FUNCTION MAX (PAYROLL-HOURS(ALL)) COMPUTE MAX-WEEK = FUNCTION ORD-MAX (PAYROLL-HOURS(ALL))
In these function invocations the subscript ALL is used to reference all elements of the PAYROLL-HOURS array (depending on the execution time value of the PAYROLL-WEEK field).