Subprocedure Definition

A subprocedure is a procedure defined after the main source section.

A subprocedure differs from a cycle-main procedure in several respects, the main difference being that a subprocedure does not (and cannot) use the RPG cycle while running.

A subprocedure may have a corresponding prototype in the definition specifications of the main source section. If specified, the prototype is used by the compiler to call the program or procedure correctly, and to ensure that the caller passes the correct parameters. If not specified, the prototype is implicitly generated from the procedure interface.

Tip:

Although it is optional to specify a prototype within the module that defines the procedure, it should not be considered optional when it is exported from the module, and the procedure will be called from other RPG modules. In this case, a prototype should be specified in a copy file and copied into the module that defines the subprocedure and into every module that calls the subprocedure.

The following examples show a subprocedure, highlighting the different parts of it. It is shown first using free-form definitions, and second using fixed-form definitions.

The procedure performs a function on the 3 numeric values passed to it as value parameters. The example illustrates how a procedure interface is specified for a procedure and how values are returned from a procedure.

A subprocedure may optionally have an ON-EXIT section containing code that runs every time the procedure ends. This code runs whether the procedure ends normally or abnormally. See ON-EXIT (On Exit) for more information.

Figure 1. Example of a Free-Form Subprocedure

 // Prototype for procedure FUNCTION
  DCL-PR Function INT(10);         1 
    TERM1 INT(5) VALUE;
    TERM2 INT(5) VALUE;
    TERM3 INT(5) VALUE;
  END-PR;

  DCL-PROC Function;               2 
     DCL-PI *N INT(10);            3 
       TERM1 INT(5) VALUE;
       TERM2 INT(5) VALUE;
       TERM3 INT(5) VALUE;
     END-PI;
     DCL-S Result INT(10);         4 

     Result = Term1 ** 2 * 17
                  + Term2 * 7      5 
                  + Term3;
     return Result * 45 + 23;
  END-PROC;                        6

Figure 2. Example of a Fixed-Form Subprocedure

 * Prototype for procedure FUNCTION
D FUNCTION        PR            10I 0                     1 
D    TERM1                       5I 0 VALUE
D    TERM2                       5I 0 VALUE
D    TERM3                       5I 0 VALUE

P Function        B                                       2 
D Function        PI            10I 0                     3 
D    Term1                       5I 0 VALUE
D    Term2                       5I 0 VALUE
D    Term3                       5I 0 VALUE
D Result          S             10I 0                     4 

    Result = Term1 ** 2 * 17
                 + Term2 * 7                              5 
                 + Term3;
    return Result * 45 + 23;

P                 E                                       6

1: A Prototype which specifies the name, return value if any, and parameters if any. Since the procedure is not exported from this module, it is optional to specify the prototype.
2: A Begin-Procedure specification
3: A Procedure-Interface definition, which specifies the return value and parameters, if any. The procedure interface must match the corresponding prototype. The procedure-interface definition is optional if the subprocedure does not return a value and does not have any parameters that are passed to it. If the prototype had not been specified, the procedure-interface definition would be used by the compiler to implicitly define the prototype.
4: Other local definitions.
5: Any calculation specifications, standard or free-form, needed to perform the task of the procedure. The calculations may refer to both local and global definitions. Any subroutines included within the subprocedure are local. They cannot be used outside of the subprocedure. If the subprocedure returns a value, then the subprocedure must contain a RETURN operation.
6: An End-Procedure specification

Except for the procedure-interface definition, which may be placed anywhere within the definition specifications, a subprocedure must be coded in the order shown above.

No cycle code is generated for subprocedures. Consequently, you cannot code:

Prerun-time and compile-time arrays and tables
*DTAARA definitions
Total calculations

The calculation specifications are processed only once and the procedure returns at the end of the calculation specifications. See Subprocedure Calculations for more information.

A subprocedure may be exported, meaning that procedures in other modules in the program can call it. To indicate that it is to be exported, specify the keyword EXPORT on the Procedure-Begin specification. If not specified, the subprocedure can only be called from within the module.