Procedure Division Header

    Procedure Division 
    Delegates and Events 
    Indexers

Parameters

Parameters are values or variable references that are passed to a method. The actual values of the parameters are specified when the method is invoked. Each parameter and its type is specified in the procedure division header in the USING clause.

When you invoke a method, you specify the parameters in the invocation. 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.
       procedure division using 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 of the USING clause.

The following types of parameters can be passed:

• Value parameters. These are used for input only. Any updates are not passed back to the invoking code.
• Reference parameters. These are used for both input and output. Unlike a value parameter, when the method finishes, any updates are passed back to the invoking code.
• Output parameters. These are similar to reference parameters. The main difference is that they don't need to be assigned on entry to the method, but they must be assigned on exit from the method.
• Returning items. These are for output only .

Parameters are passed by reference by default (except in extension methods where they are passed by value). You can change the default to be value parameters by setting the METHODDEFAULT (VALUE) 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 corresponds to 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.
       procedure division using value 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. Use a value parameter when you don't need to output the parameter from the method.
• To pass a parameter by value, specify the VALUE keyword for the parameter in the method signature in the procedure division using clause. When specifying multiple value parameters, the keyword VALUE is assumed for subsequent consecutive parameters.
• 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.

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.
       procedure division using 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.
       procedure division using value 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 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 .

RETURNING Items

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

        procedure division returning myReturn as condition-value.

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 object reference 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.
       01 h binary-long value 0.
       01 m binary-long value 0.
       procedure division using value a as type MyTimer 
                                      b as binary-long 
                            returning c as type MyTimer.
           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. 

The example above shows the inline invocation syntax, in the statement:

       set myTime to myTime::AddMins(myTime 70)

Here, the invoked method AddMins() returns an item, myTime. The invoked method specifies the returning item in its signature.