Method Overloading in Managed COBOL

About Overloading

Overloading is a programming technique where you overload a method name with more than one implementation.

For example, there may be a method called CalculateBill, taking as a parameter a list of purchases. We may want to have a variant of this method which, in addition to the list of purchases, has another parameter representing a discount code. The two methods can have the same name, and, when the method is invoked, the required one is selected based on the presence or absence of the discount code parameter.

Method Overloading in Managed COBOL

In managed COBOL, it is permissible (and very common practice) for a given class or interface to have multiple methods with the same name, which are distinguished from each other by having different signatures. The signature of a method is determined by the:

• Number of parameters
• Type of each parameter
• Passing mode (BY VALUE, BY REFERENCE, or BY OUTPUT) of each parameter
• Return type

When code written in COBOL, or any other language, attempts to invoke a method in some class or interface, and more than one method with the given name exists, then a choice of the available methods is made. The choice is based on the number of parameters and the ‘best’ type match for the parameters (the precise definition of ‘best’ is complex and is treated later). If no method with a suitable signature can be found, a ‘method not found’ error results. If there is no method that provides a better match than all the other possible methods with this name, an ‘ambiguous match’ error is given.

Although the type of the RETURNING item is a part of the method's signature, the choice of method to be invoked is never based on the RETURNING type. This is different from .NET and JVM, which allow a class to have multiple methods that differ only by returning type. This is not generally good practice, and COBOL produces an error if it finds such multiple methods within a single class. The only time when such multiple methods can arise from a COBOL program is in the case of the explicit and implicit operators.

Method Signatures

The type of a COBOL parameter may be specified by:

• Referencing the type explicitly in the PROCEDURE DIVISION phrase using the AS syntax
• Declaring a linkage section item with a given type and referencing that linkage section item in the PROCEDURE DIVISION USING phrase

For REFERENCE and OUTPUT parameters, managed types are exposed directly as managed pointers to the corresponding managed type. COBOL data types 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.

For VALUE parameters, and RETURNING items, types are exposed as follows:

Method Overload Resolution

Method overload resolution takes place in two phases:

1. Selection of all applicable methods, that is, selection of all those methods with the given name for which the arguments specified in the invoking program are compatible with the parameters of the target methods. If no such applicable method is found, then an error (method not found) is produced.
2. Selection of the ‘best’ match from within the set of applicable methods. The general intent of the selection process is to produce the best match (in the sense of most specific match) for the given set of arguments.

   Formally, the method overload that is ‘better’ than any other of the applicable method overloads is chosen. If no single overload is determined to be better than any other overload, then the match is considered to be ambiguous, and a compiler error results.

   If this two-phase process does not result in a unique best match, an error (ambiguous match error) is produced

INVOKE Method1(obj01)

Selection of Applicable Methods

We start with the complete set of all methods with the required name that exist in the target class or in any of its parent classes (excluding those with identical signatures). From this set, any methods that are not visible from the invoking program, based on the visibility attribute encoded into the method, are discarded as follows:

Next, if the required method is an instance method (a method that is applied to an object instance), all static methods are discarded. Similarly, if the required method is a static method, all instance methods are discarded.

Now each method is examined in turn to see whether it is applicable in normal form. This is determined as follows:

1. If the number of arguments is different from the number of parameters in the method, then this method is discarded.
2. If the type of the parameter in the target method is generic COBOL data passed by reference , then any argument type is assumed to match except for JVM native types.
3. For each argument with an explicit parameter passing mode (BY CONTENT, BY VALUE or BY OUTPUT), that mode must correspond to the definition of the parameter in the method being examined.

4. For a REFERENCE or OUTPUT parameter, the type of the argument must be exactly the same as the parameter type.

   For a VALUE parameter, an implicit conversion must exist from the type of the argument to the type of the corresponding parameter. If any of these implicit conversions require truncation, this method is said to be a ‘truncation match’.

If a method is not applicable according to these rules, an attempt is made to match the method in expanded form, if both the following are true:

• The last parameter of the method is an array with the ‘params’ attribute
• The total number of method parameters (excluding this array parameter) is less than or equal to the number of arguments

The expanded form of the method is derived from the normal form by replacing the array parameter by zero or more value parameters of the same type as the array element, so that the total number of parameters is the same as the number of invoking arguments. If the class already contains a method in normal form with this same expanded signature, then this method is determined to be not applicable. Otherwise the expanded form is tested for applicability in the same way as the test for normal form above.

After the above selection procedure:

1. If exactly one member is found to be applicable, then that method is known to be the required method.
2. If more than one method is found to be applicable, then an attempt is made to find the best method.
3. If any non-truncation matches are found, then all truncation matches are discarded.
4. If the only matches found are truncation matches, then if only one such match has been found, this becomes the chosen method and a warning is produced. If more than one truncation match is found, then the Compiler returns an error:

   ambiguous match

5. If no methods are found to be applicable, then the Compiler returns an error:

   method not found

Better Method Overload

Suppose we have an argument list A with a set of argument types (A1, A2,…An) and two applicable method overloads Mp and Mq with parameter types (P1…Pn) and (Q1,…Qn), where if necessary the parameters have been converted to expanded form (see above).

Then, Mp is said to be a better method overload than Mq if both the following are true:

• For each argument, the implicit conversion from Ax to Px is not worse than the conversion from Ax to Qx (see below for definition of better conversion)
• There is at least one argument for which the conversion from Ax to Px is better than the conversion from Ax to Qx

Suppose we have two conversions, from type S to types T1 and T2, then T1 is the better conversion when T1 and T2 are as follows:

Otherwise neither conversion is better.

Example of Simple Method Overloading

The following example shows how, even in the case where the supplied argument is not exactly the same as that for any of the target methods, the “most specific” rule takes effect.

       class-id Class1 static.
       method-id main static.
       01 objAnyObject object.
       01 objString string.
       01 objDateTime type DateTime.         *> .NET COBOL 
      * 01 objDateTime type java.util.Date.  *> JVM COBOL
       01 ref1 type Class1.
       procedure division.
           set ref1 to new Class1
           invoke ref1::method1                *> uses variant 1 
           invoke ref1::method1(objAnyObject)  *> uses variant 2 
           invoke ref1::method1(objString)     *> uses variant 3
           invoke ref1::method1(objDateTime)   *> also uses variant 2, 
               *> because an object of type DateTime can be assigned  
               *> to an Object but not to a String. 
       end method.

       method-id method1.     *> Variant 1 (no parameters)
       procedure division.   
           display "variant 1"
       end method.

       method-id method1.     *> Variant 2 (object parameter)
       procedure division using by value objAnyObject as object.  
           display "variant 2"
       end method.

       method-id method1.     *> Variant 3 (string parameter)
       procedure division using by value objString as string.   
           display "variant 3"
       end method.

       end class.

Implicit Conversion

An implicit conversion exists from type S to type T if it is possible to assign an object of type S to an object of type T, with the equivalent of the following statement:

SET obj-T TO obj-S

The following types of implicit conversion are available:

Identity conversions

This simply means that S is the same type as T

Implicit numeric conversions

COBOL generally allows any numeric item to be assigned to any other, with any loss of data being the responsibility of the user. However, when determining if a conversion exists for the purposes of method overloading, we distinguish between proper conversions and truncation conversions. Proper conversions are those for which no loss of data magnitude should result, though even in this case precision can be lost when converting between fixed point and floating point.

For managed COBOL types, proper implicit conversions include:

binary-char	binary-short binary-long binary-double float-short float-long decimal
binary-char unsigned	The same as binary-char, plus: binary-short unsigned binary-long unsigned binary-double unsigned
binary-short	binary-long binary-double float-short float-long decimal
binary-short unsigned	The same as binary-short, plus: binary-long unsigned binary-double unsigned
binary-long	binary-double float-short float-long decimal
binary-long unsigned	The same as binary-long, plus: binary-double unsigned
binary-double	float-short float-long decimal
binary-double unsigned	The same as binary-double
character	binary-short unsigned binary-long binary-long unsigned binary-double binary-double unsigned float-short float-long decimal
float-short	float-long

Implicit enumeration conversions

The value 0 may be converted to any enum type

Implicit reference conversions

If S and T are reference types, S may be assigned to T when:

• Type S is derived (directly or indirectly) from type T. This includes the case where T is java.lang.Object since all types derive from that
• Type S implements interface type T
• If S is an array type with element type E1 and T is an array type with element type E2, then S can be assigned to T provided:
  • S and T have the same number of dimensions
  • Both E1 and E2 are reference types
  • An implicit conversion exists from E1 to E2
• Any array type may be assigned to type java.util.Array in JVM COBOL
• Null may be assigned to any reference type

Boxing conversions

Any value type can be converted to a java.lang.Object type by a process known as boxing. As part of this process the value is copied onto the object heap and a reference is created

Implicit constant expression conversions

Any numeric constant can be converted to any type capable of containing the full value of that constant. For instance the value 1 can be converted both to BINARY-CHAR UNSIGNED and to BINARY-CHAR.

User defined implicit conversions

A user defined implicit conversion consists of an optional implicit numeric conversion from S to S1 followed by the execution of a user defined implicit conversion operator resulting in T1, followed by another optional implicit numeric conversion to T. User defined implicit conversion operators are defined in COBOL with OPERATOR-ID IMPLICIT and result in methods with the name op_Implicit.