Chapter 3: Method Signatures and Method Overloading in .NET

This chapter describes method signatures and method overloading in .NET.

Method Overloading

In .NET 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 and parameter passing mode (BY VALUE, BY REFERENCE, or BY OUTPUT) of each parameter.
• Type of the RETURNING data item. This type may be System.Void, which represents a method with no RETURNING item.

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. In fact, although .NET does allow multiple methods to exist in a class, where the methods differ only by returning type, this is not generally good practice, and COBOL will produce 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. See Operator-ID Paragraph.

Example of Simple Method Overloading

class-id. A.
repository.
     Class sys-datetime as “System.DateTime”.
static.
Method-id. Main.
01 obj-any object.                        *> define an item of type System.Object
01 obj-string string.                     *> define an item of type System.String
01 obj-datetime sys-datetime.             *> define an item of type System.DateTime

    Invoke self::”Method1”                *> invokes variant 1
    Invoke self::”Method1”(obj-any)       *> invokes variant 2
    Invoke self::”Method1”(obj-string)    *> invokes variant 3
    Invoke self::”Method1”(obj-datetime)  *> invokes variant 2
*> Note that the last invoke maps onto variant 2 because an object of type
*> System.DateTime can be assigned to a System.Object but not to a System.String
End method main.
Method-id. Method1.    *> Variant 1 (no parameters)
Procedure division.
…
End method method1.
Method-id. Method1.    *> Variant 2 (object parameter)
Procedure division using by value o1 as object.
…
End method method1.
Method-id. Method1.    *> Variant 3 (string parameter)
Procedure division using by value o1 as string.
…
End method method1.
End static.
End class a.

Method Signatures Defined by COBOL Programs

The type of a COBOL parameter may be specified by:

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

For REFERENCE and OUTPUT parameters, native .NET types are exposed directly as managed pointers to the corresponding .NET type. COBOL data types that do not correspond to native .NET types (such as PIC X fields, groups, numeric fields other than BINARY-LONG and so on) are exposed as COBOL pointers (objects of type MicroFocus.COBOL.Program.Reference).

For VALUE parameters, and RETURNING items, native .NET types are exposed as objects of the corresponding type.

Other COBOL data types used as VALUE parameters are exposed as follows:

• Numeric items with more than 19 decimal digit positions - MicroFocus.COBOL.Program.BigDecimal
• Numeric items with implied decimal point, such as PIC 9(9)v99, all sizes - System.Decimal
• Unsigned numeric items with no implied decimal point:
  • < 3 numeric digits - unsigned int8
  • < 5 numeric digits - unsigned int16
  • < 10 numeric digits - unsigned int32
  • < 19 numeric digits - unsigned int64
• Signed numeric items with no implied decimal point:
  • < 3 numeric digits - int8
  • < 5 numeric digits -int16
  • < 10 numeric digits - int32
  • < 19 numeric digits - int64
• All other types PIC X, group and so on - string

See COBOL Type Compatibility for details of the correspondence between native .NET types and COBOL data types.

Method Overload Resolution

In this discussion, the term arguments means the set of parameters specified in the invoking method (for example obj01 in the statement INVOKE self::”Method1”(obj01)). The term parameters means the formal parameters specified in each method definition (in the PROCEDURE DIVISION USING header).

Method overload resolution takes place in two phases:

1. Selection of all applicable methods, i.e. 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. If this process does not result in a unique best match, an error (ambiguous match error) is produced.

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 MicroFocus.COBOL.Program.Reference (generic COBOL data passed by reference), then any argument type is assumed to match except for .NET 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’. See Implicit Conversion.

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:

• If no methods are found to be applicable, then the Compiler will return an error (method not found).
• 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 an ‘ambiguous match’ error is returned.
• If any non-truncation matches are found, then all truncation matches are discarded.
• If exactly one member is found to be applicable, then that method is known to be the required method.
• If more than one method is found to be applicable, then an attempt is made to find the best method. See Selection from Multiple Applicable Methods.

Selection from Multiple 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. For example, suppose class A derives from class B, which itself derives from System.Object. 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 X.
Static.
Method-id. Method1.
Procedure division using by value arg1 as object.   *> method (i)
End method method1.
Method-id. Method1.
Procedure division using by value arg1 as B.   *> method (ii)
End method method1.
End static.
End class X.
Class Y.
Static.
Method-id. Main.
01 obj1 object.
01 obj2 type “B”.
01 obj3 type “A”.
      Invoke type “X”::”Method1”(obj1)  *> Uses method (i)
      Invoke type “X”::”Method1”(obj2)  *> Uses method (ii)
      Invoke type “X”::”Method1”(obj3)  *> also uses method (ii) since type B is ‘closer’ 
                                                                 *> to type A than System.Object…
End method main.
End static.
End class Y.

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. See Better Method Overload.

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

Better Conversion

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

• If T1 and T2 are the same type, neither conversion is better
• If S is the same type as T1, T1 is the better conversion
• If S is the same type as T2, T2 is the better conversion
• If there is an implicit conversion from T1 to T2 but no such conversion exists from T2 to T1, then T1 is the better conversion
• If there is an implicit conversion from T2 to T1 but no such conversion exists from T1 to T2, then T2 is the better conversion
• If T1 is BINARY-CHAR and T2 is BINARY-CHAR UNSIGNED, BINARY-SHORT UNSIGNED, BINARY-LONG UNSIGNED or BINARY-DOUBLE UNSIGNED, T1 is the better conversion
• If T2 is BINARY-CHAR and T1 is BINARY-CHAR UNSIGNED, BINARY-SHORT UNSIGNED, BINARY-LONG UNSIGNED or BINARY-DOUBLE UNSIGNED, T2 is the better conversion
• If T1 is BINARY-SHORT and T2 is BINARY-SHORT UNSIGNED, BINARY-LONG UNSIGNED or BINARY-DOUBLE UNSIGNED, T1 is the better conversion
• If T2 is BINARY-SHORT and T1 is BINARY-SHORT UNSIGNED, BINARY-LONG UNSIGNED or BINARY-DOUBLE UNSIGNED, T2 is the better conversion
• If T1 is BINARY-LONG and T2 is BINARY-LONG UNSIGNED or BINARY-DOUBLE UNSIGNED, T1 is the better conversion
• If T2 is BINARY-LONG and T1 is BINARY-LONG UNSIGNED or BINARY-DOUBLE UNSIGNED, T2 is the better conversion
• If T1 is BINARY-DOUBLE and T2 is BINARY-DOUBLE UNSIGNED, T1 is the better conversion
• If T2 is BINARY-DOUBLE and T1 is BINARY-DOUBLE UNSIGNED, T2 is the better conversion
• otherwise neither conversion is better

If the conversion from S to T1 is better than the conversion from S to T2, then it is also true that the conversion from S to T2 is worse than the conversion from S to T1.

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 (SET obj-T TO obj-S).

The following types of implicit conversion are available in the .NET system:

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

  In the case of the .NET native types proper implicit conversions include:

  • BINARY-CHAR to BINARY-SHORT, BINARY-LONG, BINARY-DOUBLE, FLOAT-SHORT, FLOAT-LONG and DECIMAL
  • BINARY-CHAR UNSIGNED to all the above, plus BINARY-SHORT UNSIGNED, BINARY-LONG UNSIGNED, BINARY-DOUBLE UNSIGNED
  • BINARY-SHORT to BINARY-LONG, BINARY-DOUBLE, FLOAT-SHORT, FLOAT-LONG and DECIMAL
  • BINARY-SHORT UNSIGNED to all the above, plus BINARY-LONG UNSIGNED, BINARY-DOUBLE UNSIGNED
  • BINARY-LONG to BINARY-DOUBLE, FLOAT-SHORT, FLOAT-LONG and DECIMAL
  • BINARY-LONG UNSIGNED to all the above, plus BINARY-DOUBLE UNSIGNED
  • BINARY-DOUBLE to FLOAT-SHORT, FLOAT-LONG and DECIMAL
  • BINARY-DOUBLE UNSIGNED to all the above
  • CHARACTER to BINARY-SHORT UNSIGNED, BINARY-LONG, BINARY-LONG UNSIGNED, BINARY-DOUBLE, BINARY-DOUBLE UNSIGNED, FLOAT-SHORT, FLOAT-LONG and DECIMAL
  • FLOAT-SHORT to 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 System.Object, since all types derive from System.Object
  • 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 System.Array
  • Any delegate type may be assigned to type System.Delegate
  • Null may be assigned to any reference type
• Boxing conversions

  Any value type can be converted to a System.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.

Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.