Guru: Overloading Subprocedures

October 5, 2020 Paul Tuohy

The ability to overload subprocedures in RPG is something I had been waiting for a long, long time. IBM finally made it available through a Technology Refresh (7.4, TR1 or 7.3 TR7). If you are not familiar with the term, overloading (in RPG) is the ability to create multiple subprocedures of the same name with different implementations.

Let’s have a look at how overloading might benefit us when it comes to writing programs and subprocedures. This is a portion of a prototype copy member that, amongst others, contains the prototypes of these three subprocedures:

dcl-pr format_from_Date varChar(10) extProc(*dclCase);
  dateIn date(*ISO) const;
end-pr;

dcl-pr format_from_Number varChar(10) extProc(*dclCase);
  dateIn zoned(8) const;
end-pr;

dcl-pr format_from_Character varChar(10) extProc(*dclCase);
  dateIn char(10) const;
end-pr;

The three subprocedures all do the same thing — return a character representation of a date in MDY format. The difference between the three is in the parameters passed. One takes a date, one takes a number containing a date and one takes a character containing a date.

This means that when we need to get our date format, we need to know which subprocedure to call based on the data type of the field containing the date.

dcl-s forDate date(*ISO) inz(D'2020-08-01');
dcl-s forNum  zoned(8)   inz(20200801);
dcl-s forChar char(10)   inz('2020-08-01');

dcl-s returnDate char(10);

returnDate = format_from_Date(forDate);
returnDate = format_from_Number(forNum);
returnDate = format_from_Character(forChar);

Overloading allows us to define a common prototype that combines the three prototypes we have already defined:

dcl-pr format_from_Date varChar(10) extProc(*dclCase);
  dateIn date(*ISO) const;
end-pr;

dcl-pr format_from_Number varChar(10) extProc(*dclCase);
  dateIn zoned(8) const;
end-pr;

dcl-pr format_from_Character varChar(10) extProc(*dclCase);
  dateIn char(10) const;
end-pr;

dcl-pr format_Date varChar(10) overLoad( format_from_Date
                                       : format_from_Number
                                       : format_from_Character);

This means that, in our calling program/subprocedure we can now use the same name for all three subprocedure calls, regardless of the parameters.

dcl-s forDate date(*ISO) inz(D'2020-08-01');
dcl-s forNum  zoned(8)   inz(20200801);
dcl-s forChar char(10)   inz('2020-08-01');

dcl-s returnDate char(10);

returnDate = format_Date(forDate);
returnDate = format_Date(forNum);
returnDate = format_Date(forChar);

Let’s add a new subprocedure to the mix. This subprocedure will also return a character representation of a date but will have an extra parameter that allows for the specification of the returned date format.

dcl-pr format_from_Date_With_Format varChar(10) extProc(*dclCase);
  dateIn   date(*ISO) const;
  toFormat char(4)    const;
end-pr;

Although this new procedure has an extra parameter, it can still be added to the overload list:

dcl-pr format_Date varChar(10) overLoad( format_from_Date
                                       : format_from_Number
                                       : format_from_Character
                                       : format_from_Date_With_Format);

Which means that we can use the existing (common) name for our new subprocedures:

dcl-s forDate date(*ISO) inz(D'2020-08-01');
dcl-s forNum  zoned(8)   inz(20200801);
dcl-s forChar char(10)   inz('2020-08-01');

dcl-s returnDate char(10);

returnDate = format_Date(forDate);
returnDate = format_Date(forNum);
returnDate = format_Date(forChar);
returnDate = format_Date(forDate: '*MDY');

Isn’t that nice?

Rules

These are the rules that apply when defining a prototype with the OVERLOAD keyword:

• Terminology: the name of the prototype containing the OVERLOAD keyword is the overloaded prototype. The subprocedure names listed in the OVERLOAD keyword are the candidate prototypes
• You cannot specify parameters for a prototype with the OVERLOAD keyword
• A prototype with the OVERLOAD keyword does not end with END-PR
• All the candidate prototypes must have the same (or no) return value type as the overloaded prototype
• The only other keywords allowed for the overloaded prototype are related to the data type of the return value
• The candidate prototypes can be any type of prototype. They can be for programs, procedures, and Java methods

Strict Compiler

The compiler is very, very strict when it comes to checking parameters. All of the candidate prototypes must be truly unique. For example, the compiler would not allow the following overload procedure. Even though the definition of the parameters are different, the use of the CONST keyword means that either subprocedure could be called.

dcl-pr oneParm varChar(10) extProc(*dclcase);
  parm_1 char(1) const;
end-Pr;

dcl-pr twoParm varChar(10) extProc(*dclcase);
  parm_1 char(10) const;
end-Pr;

dcl-pr formatParm varChar(10) overload(twoParm: oneParm);

The Compile Listing

The compile list now contains an Overloaded Prototypes section at the end of the listing. The amount of information shown in this section can be controlled using the /OVERLOAD DETAIL or /OVERLOAD NODETAIL compiler directive. The default is /OVERLOAD NODETAIL. The /OVERLOAD compiler directive can be specified multiple times in a source member.

This is an example of the Overloaded Prototypes section when /OVERLOAD DETAIL is specified:

                    O V E R L O A D E D   P R O T O T Y P E S
     CALLS TO PROTOTYPES FOR FORMATPARM
         CALLED PROTOTYPE                     REFERENCES (D=DETAILS BELOW)
           TWOPARM                                48D
           ONEPARM
     DETAILED DETERMINATION FOR CALLS TO FORMATPARM
       CALL AT STATEMENT 48 COLUMN 14
         SELECTED PROTOTYPE: TWOPARM
     CALLS TO PROTOTYPES FOR FORMAT_DATE
         CALLED PROTOTYPE                     REFERENCES (D=DETAILS BELOW)
           FORMAT_FROM_DATE...
           FORMAT_FROM_NUMBER...
                                                  45D
           FORMAT_FROM_CHARACTER...
                                                  46D
     DETAILED DETERMINATION FOR CALLS TO FORMAT_DATE
       CALL AT STATEMENT 45 COLUMN 14
         ERROR MESSAGES ISSUED FOR PARAMETER 1 FOR FORMAT_FROM_DATE
*RNF7536 30     45 004500  The type of parameter 1 specified for the call does not
                           match the prototype.
         ERROR MESSAGES ISSUED FOR PARAMETER 1 FOR FORMAT_FROM_CHARACTER
*RNF7536 30     45 004500  The type of parameter 1 specified for the call does not
                           match the prototype.
         SELECTED PROTOTYPE: FORMAT_FROM_NUMBER
       CALL AT STATEMENT 46 COLUMN 14
         ERROR MESSAGES ISSUED FOR PARAMETER 1 FOR FORMAT_FROM_DATE
*RNF7536 30     46 004600  The type of parameter 1 specified for the call does not
                           match the prototype.
         ERROR MESSAGES ISSUED FOR PARAMETER 1 FOR FORMAT_FROM_NUMBER
*RNF7536 30     46 004600  The type of parameter 1 specified for the call does not
                           match the prototype.
         SELECTED PROTOTYPE: FORMAT_FROM_CHARACTER
 * * * * *   E N D   O F   O V E R L O A D E D   P R O T O T Y P E S   * * * * *  

And when /OVERLOAD NODETAIL is specified:

                    O V E R L O A D E D   P R O T O T Y P E S
     CALLS TO PROTOTYPES FOR FORMATPARM
         CALLED PROTOTYPE                     REFERENCES (D=DETAILS BELOW)
           TWOPARM                                48
           ONEPARM
     CALLS TO PROTOTYPES FOR FORMAT_DATE
         CALLED PROTOTYPE                     REFERENCES (D=DETAILS BELOW)
           FORMAT_FROM_DATE...
           FORMAT_FROM_NUMBER...
                                                  45
           FORMAT_FROM_CHARACTER...
                                                  46
 * * * * *   E N D   O F   O V E R L O A D E D   P R O T O T Y P E S   * * * * *  

The /OVERLOAD compiler directive can be specified multiple times in a source member to indicate the amount of detail shown for individual subprocedure calls.

Overloaded subprocedures can make the use of subprocedures that little bit easier. I am sure you will find a use for them.

Paul Tuohy, IBM Champion and author of Re-engineering RPG Legacy Applications, is a prominent consultant and trainer for application modernization and development technologies on the IBM Midrange. He is currently CEO of ComCon, a consultancy firm in Dublin, Ireland, and partner at System i Developer. He hosts the RPG & DB2 Summit twice per year with partners Susan Gantner and Jon Paris.