|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
[access] [function_mod ...] FUNCTION name[, return_type[size]][, options, ...] parameter_def . . . [ENDFUNCTION|END]
Arguments
access
(optional) One of the following access modifiers:
Access is not restricted. This is the most accessible option.
Access is limited to the containing class or types derived from the containing class.
Access is limited to the containing type. This is the least accessible option. (default)
Access is limited to the current assembly. (Synergy .NET only)
Access is limited to the current assembly and types derived from the containing class. (Synergy .NET only)
function_mod
(optional) One or more of the following modifiers (Synergy .NET only):
Accessed without a reference object. The method can be executed even if the class that contains the method hasn’t been instantiated.
More than the declared number of arguments can be passed to this routine.
name
The name of the function.
return_type
(optional) The return type of the function being defined. See Where data types can be used for the data types that are valid return types. If not specified, the return type defaults to the type of the variable or literal of the first FRETURN statement.
size
(optional) The size of the function return value.
options
(optional) One or more of the following modifiers:
Keep record contents constant for as long as the function is activated at one or more levels.
Make record contents unique for every activation of the function.
Keep record contents constant throughout every activation of the function.
Allow multiple active instances of the function.
Keep the function in memory, even when not in use. (Windows, Unix only)
Use rounding rules for implied-decimal data types within the function.
Use truncation rules for implied-decimal data types within the function. (traditional Synergy only)
More than the declared number of arguments can be passed to this routine.
parameter_def
Function parameter definitions. See Defining a parameter.
Discussion
The FUNCTION statement identifies the beginning of a user-defined function.
In traditional Synergy, function names of more than 30 characters are truncated when the routine is linked (although you can specify up to 255 characters as long as the first 30 characters are unique).
The LOCAL, STACK, and STATIC modifiers specify the default state of an unqualified RECORD statement. For example, given the following statement:
function fred ,STACK
all unqualified RECORD statements in function fred are treated as if they are STACK RECORD statements. LOCAL, STACK, and STATIC are mutually exclusive. If you don’t specify one, the default is LOCAL in traditional Synergy (unless the REENTRANT option is specified) and STACK in Synergy .NET. If REENTRANT is specified, unqualified RECORD statements default to stack data, rather than local data, for each instance of the function. For example, given the following statement:
function fred ,REENTRANT
all of the unqualified RECORD statements in function fred are treated as if they are STACK RECORD statements.
|
The REENTRANT modifier causes all local records to be stack records unless otherwise qualified. Fields in stack records do not allow default or explicit initial values. |
By default, a function cannot be re-entered. If you specify the REENTRANT option, however, the function can call itself.
|
|
Object handles are not allowed in local records in REENTRANT routines. |
For information about the precedence of storage qualifiers (LOCAL, STACK, STATIC, and REENTRANT) in the FUNCTION statement with those specified in the RECORD statement or on the compiler command line (-qlocal, -qstack, and -qstatic), see the Discussion for RECORD-ENDRECORD.
VARARGS is optional for unprototyped subroutines and functions, but if you want to pass more arguments than declared, it is required when using -qnet or strong prototypes (or internal routine prototyping unless -qrelaxed:param is set).
On Windows and Unix, by default, a function may be removed from memory when it is no longer in the calling chain. If you specify the RESIDENT modifier, the function stays in memory.
A program by default rounds all expression results. You can change the default to truncate in traditional Synergy by setting system option #11. However, specifying the ROUND or TRUNCATE option on a FUNCTION statement overrides the default rounding behavior for that function (including if system option #11 is set). You cannot specify both TRUNCATE and ROUND in the same statement. (Neither TRUNCATE nor system option #11 are supported in Synergy .NET.)
A function can be declared either inside or outside of a namespace or class. A function declared outside of a class is considered to be a global function. In Synergy .NET, when the compiler generates the .exe or .dll file, it puts any global functions in a new global class called _CL. If a function is also declared outside of a namespace, it is placed in _NS_assemblyname._CL.
See also
Examples
In this example, the implied-decimal values within avg are processed using truncation rules; therefore, the intermediate result of num1 + num2 (7.5) is truncated to 7. The final result of 7/2 is truncated to 3. However, if we specify ROUND instead of TRUNCATE (or if neither modifier is specified), the implied-decimal values are processed using rounding rules. Thus, the intermediate result (7.5) is rounded to 8 before being divided by 2, and the final result is 4.
.define TTCHN ,1
.define MINVAL ,3
external function ;Declare the function and
avg ,i ; specify an integer result
record
var1 ,d6.2, 3.4
var2 ,d6.2, 4.1
proc
xcall flags(7000000, 1)
open(TTCHN,i,"tt:")
if ((var1 = %avg(var1,var2)).GT.MINVAL)
writes(TTCHN, "Average = " + %string(var1))
endmain
function avg, i, TRUNCATE
num1 ,d.
num2 ,d.
record
rslt ,i4
proc
rslt = num1 + num2
freturn (rslt/2)
endfunction
