Method Signature

Context:

   Constructors
   Delegates and Events
   Indexers
   Iterators  
   Methods

signature

method-signature

Each parameter must specify a parameter passing mode before it, otherwise passing mode defaults to by VALUE.
If you are passing a parameter by PARAMS, it must be last, and must be a one-dimensional array.
Indexers or constructors cannot specify returning items.
Iterators specify YIELDING items, not RETURNING items; for example, iterator-id GetEven yielding res as binary-long static.

Parameters

Parameters are values or variable references that are passed to a method. They can be specified in the method header or in the procedure division header. If they are specified in the method header, you must omit the procedure division header from the method.

The actual values of the parameters are specified when the method is invoked.

Typically, when you invoke a method, you specify the parameters in the invocation, and the invoked method receives the parameters in the same order as in the invocation. For example:

       invoke type MyClass::MyMethod(a,b)
       ...
       method-id MyMethod (x as string y as binary-long).
       ...
       end method.

The arguments a and b above are passed to the invoked method, and these correspond to the parameters x and y respectively, in the invoked method. The types of the parameters are specified in the AS phrase.

If you use named parameters, the invocation does not need to specify them in the same order as they are specified in the method header.

       invoke type MyClass::MyMethod(param y = 3.141592, param x = "Pi")
       ...
       method-id MyMethod (value x as string, y as decimal).
       ...
       end method.

As long as the parameters x and y are named during invocation, the invoked method receives and uses them appropriately. If you use a mixture of positional and named arguments during invocation, the named arguments must be specified after any positional arguments.

If your method contains optional parameters (also known as default parameters), you do not need to pass all the arguments during invocation. The default values specified in the method signature are used.

       invoke type MyClass::MyMethod(a)
       ...
       method-id MyMethod (value x as string, y as decimal = 3.141592).
       ...
       end method.

The invocation above only passes one positional argument (which corresponds to parameter x), so the value specified for optional parameter y is used in the method. Optional parameters can only be used as value parameters.

Parameter passing mode

Parameters are passed into a method using one of the following modes, specified after the USING phrase:

VALUE. Parameters that are passed by value do not pass back any changes in value to the invoking code.
REFERENCE. Parameters that are passed by reference pass back any changes to their value during execution of the method, to the invoking code when the method finishes. These are used for both input and output.
OUTPUT. This mode is similar to REFERENCE. The main difference is that parameters don't need to be assigned on entry to the method, but they must be assigned on exit from the method.
PARAMS. Only one parameter may be passed using PARAMS mode. It must be a single dimensional array and it must be the last input parameter.

If no passing mode is specified, parameters specified in the method header use the VALUE mode by default, and parameters specified in the procedure division header use the REFERENCE mode by default (except in extension methods where they are passed by value). You can change the default by setting the METHODDEFAULT Compiler directive.

When specifying multiple value parameters, the keyword VALUE is assumed for subsequent consecutive parameters. In the following example, v and vv are passed by value, and the others are passed by reference:

       procedure division using a as binary-long
                          value v as binary-long
                                vv as binary-long
                      reference r as binary-long
                                rr as binary-long.

VALUE Parameters

A value parameter behaves like a local variable. Its initial value is established when the method is invoked. When the method processes, it can change the value of the local variable. When the method finishes, the original argument in the invoking code remains unchanged. For example:

       declare a as binary-long = 3
       invoke type MyUtils::CheckByValue(a)
       display a              *> a is still 3

       method-id CheckByValue static (x as binary-long).
       set x to x + 1          *> x is now 4
       end method.

In the above example, the parameter a is passed by value. The invoked method increments the value. However, on return to the invoking code, the variable a remains unchanged.

Usage:

Use a value parameter for input to a method, and when you don't need to output the parameter from the method.
Value parameters that are managed types are exposed as the corresponding COBOL types. For example, signed numeric items with no implied decimal point are exposed as int8, int16, int32, int64, depending on the size.
Value parameters that are not managed types but are other COBOL data types are exposed as defined in the COBOL Type Compatibility table. For example: PIC X fields and groups are exposed as string. See Type Compatibility of Managed COBOL with Other Managed Languages.
Value parameters may include the optional syntax '= constant-expression'. Such parameters are optional parameters, and the expression represents the value in the case where the parameter is not supplied by the invoking code.
All optional parameters must be specified following any non-optional parameters.

REFERENCE Parameters

A reference parameter contains a reference to the required value rather than the value itself.

A reference parameter corresponds to a local variable, whose value is established when the method is invoked, and whose value can change while the method is processing. Unlike a value parameter, when the method finishes, the value of the original argument in the invoking code is changed accordingly.

Note, that a reference parameter does not necessarily create a copy of the variable local to the method. Instead, it might refer to the original argument in the location in use when the method was invoked. While the method is processing, the variable can change locally, but the original argument in the invoking code does not necessarily change. It might change or it might not. The value of the original argument is unknown until the method finishes. When the method finishes and returns to the invoking code, the value of the original argument in the invoking code is updated.

For example:

       declare a as binary-long=3
       invoke type MyUtils::CheckByReference(a)
       display a              *> a is now 4

       method-id CheckByReference static (reference x as binary-long).
       set x to x + 1          *> x is now 4
       end method.

In the above example, the parameter a is passed by reference. The invoked method increments the variable a. On return to the invoking code, the variable a is updated with the incremented value.

Usage:

Use a reference parameter for both input and output. Use it to input a value to the method and to output the resulting value to the invoking code.
Parameters are passed by reference by default, except where the previous parameter in the method signature is not a reference parameter. In this case, the keyword REFERENCE is required.
While the method is running, the value of a sending argument that corresponds to a reference parameter might change. The value is unknown. To lock the sending argument so that it does not change while the method is running, use the SYNC clause. When the method finishes, the lock is released and the sending argument is updated as necessary.
Reference parameters that refer to managed types are exposed directly as managed pointers to the corresponding managed type.
Reference parameters that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than binary-long and so on) are exposed as COBOL pointers .

OUTPUT Parameters

Like reference parameters, output parameters don't create a new storage location, but use the storage location of the variable specified on the invocation.

Output parameters are very similar to reference parameters. The main difference is that they must be assigned before returning to the invoking code.

For example:

       declare a as binary-long=4
       declare b as binary-long
       invoke type MyUtils::CheckByOutput(a,b)
       display "Value Param a = " &  a          *> a is still 4
       display "Output Param b = " & b          *> b is 16

       method-id CheckByOutput static (x as binary-long, output y as binary-long).
           set x to x + 10     *> x is now 14
           set y to x + 2      *> y is now 16
       end method.

In the above example, two parameters are passed, where variable b is not initialized and is passed by output. The method CheckByOutput updates the variables x and y. On return, the output variable b is updated but the variable a remains unchanged.

Usage:

Typically used in methods where there are multiple return values.
Can optionally be initialized or assigned a value for input to the method.
Must be assigned for return, when the method finishes.
Output parameters that refer to managed types are exposed directly as managed pointers to the corresponding managed type.
Output parameters that do not correspond to managed types (such as PIC X fields, groups, numeric fields other than binary-long and so on) are exposed as COBOL pointers.

PARAMS Parameters

Only one parameter may be passed with the PARAMS keyword, and it must be the last parameter. The parameter type must be a single dimensional array.

Programs that invoke this method may pass this parameter in the normal way as an array of the given type. Alternatively the program may pass zero or more parameters corresponding to the PARAMS parameter, where each parameter passed has the same type (or a compatible type) as the element type of the array. In this case the compiler will automatically generate code to create an array from the specified parameters (containing 0 or more elements), and pass this array to the invoked method.

RETURNING Items

Returning items pass the results of a method back to the invoking code. For example:

       method-id AddMins (a as type MyTimer, b as binary-long) returning c as type MyTimer.

Each method can have only one returning item. However you can package a set of return information in an object. For example, the following AddMins() method receives and returns an instance of type myTime :

       program-id ParamAsObject.
       01 myTime type MyTimer value new MyTimer(5 45).
     
       procedure division.
           set myTime to myTime::AddMins(myTime 70) *> inline invocation
           display myTime::anHour & ":" myTime::aMin
       end program.
       
       class-id MyTimer.
       01 anHour binary-long property.  *> property keyword enables get/set
       01 aMin binary-long property.
       ...
       method-id AddMins (a as type MyTimer, b as binary-long) returning c as type MyTimer.
       01 h binary-long value 0.
       01 m binary-long value 0.
           set b to a::aMin + b
           divide b by 60 giving h remainder m
           set c to new MyTimer(a::anHour + h , m)
       end method.

       end class.