Procedure Division Header

Parameters

Parameters are values or variable references that are passed to a method. They can be specified in the procedure division header, or for some types of method, they can be specified in the method header itself; in which case, you must omit the procedure division header from the 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.

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.
       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.

       invoke type MyClass::MyMethod(param y = 3.141592, param x = "Pi")
       ...
       method-id MyMethod.
       procedure division using 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.

       invoke type MyClass::MyMethod(a)
       ...
       method-id MyMethod.
       procedure division using 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 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 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 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.
       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.

• 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.
       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 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:

        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.