Calling External Programs (EXTPGM)

inter-program calls, parameter passing, BNDDIR

Triton RPG supports calling one compiled RPG program from another using the EXTPGM keyword. This is the standard RPG mechanism for inter-program communication on IBM i.

Caller Side

Declare a procedure prototype with EXTPGM to specify the target program:

**FREE
DCL-PR CUSTEDIT EXTPGM('CUSTEDIT');
  CustNo PACKED(5:0);
  Mode   CHAR(1) CONST;
END-PR;

DCL-S SelCust PACKED(5:0);
SelCust = 42;
CALLP CUSTEDIT(SelCust : 'E');
// After the call, SelCust may have been modified by the callee (by-ref)

If the program name matches the prototype name, the string argument to EXTPGM can be omitted: EXTPGM().

Callee Side

The called program declares a procedure interface (DCL-PI) at the top level to define the parameters it receives:

**FREE
DCL-PI CUSTEDIT;
  CustNo PACKED(5:0);
  Mode   CHAR(1);
END-PI;

// CustNo and Mode are available as program variables
IF Mode = 'E';
  // edit mode logic...
ENDIF;
RETURN;

Parameter Passing

Parameters follow standard RPG semantics:

Fixed-Format CALL / CALLB / PARM / PLIST

In fixed-format C-specs, the CALL opcode dynamically calls another program and CALLB calls a bound procedure in a service module. Both use PARM to specify parameters, all passed by reference.

Caller:

     D Num1            S              5P 0 INZ(10)
     D Num2            S              5P 0 INZ(20)
     D Result          S              5P 0
     C                   CALL      'CALCADD'
     C                   PARM                    Num1
     C                   PARM                    Num2
     C                   PARM                    Result

A named PLIST can group parameters for reuse:

     C     ADDLST        PLIST
     C                   PARM                    Num1
     C                   PARM                    Num2
     C                   PARM                    Result
     C                   CALL      'CALCADD'     ADDLST

Error indicator (positions 73-74):

An error indicator in the CALL C-spec's LO position (columns 73-74) traps a failed call: if the called program cannot be found or ends abnormally, the indicator is set on and control continues to the next statement instead of the error halting the program. A successful call sets the indicator off. With no error indicator, an unmonitored call error propagates (an escape), matching IBM i.

     C                   CALL      'MAYFAIL'                     50
     C   50              EXSR      HandleError

Callee (entry parameter list):

The called program uses *ENTRY PLIST to declare its entry parameters:

     D Num1            S              5P 0
     D Num2            S              5P 0
     D Result          S              5P 0
     C     *ENTRY        PLIST
     C                   PARM                    Num1
     C                   PARM                    Num2
     C                   PARM                    Result

This is the fixed-format equivalent of DCL-PI.

CALLB - bound procedure call:

CALLB calls a bound procedure in a service module (compiled with --lib). Factor 2 holds the procedure name (quoted string). Parameters are passed by reference via PARM, and the binding is resolved through the activation group at runtime:

     D MYVAL           S             10P 0 INZ(21)
     C                   CALLB     'DOUBLE'
     C                   PARM                    MYVAL
     C     MYVAL         DSPLY

The (D) extender includes operational descriptors; (E) enables %ERROR trapping. Named PLIST references in the Result field are also supported, matching CALL syntax.

Multi-File Compilation

Each program must be compiled separately, and compilation order does not matter - the caller can be compiled before the callee exists, because EXTPGM targets are resolved dynamically at run time:

rpgc -o out CUSTEDIT.rpgle
rpgc -o out CUSTMAINT.rpgle

At runtime, all compiled classes must be on the same classpath:

java -cp out:triton-rpg.jar CUSTMAINT

When you compile with --package, the callee is resolved in the caller's package: a caller and callee compiled with the same --package (the normal case - programs of one application are built and deployed together) call each other without any extra configuration. If the qualified class is not found, the plain program name is tried as a fallback, so a packaged caller can still reach a callee that was compiled into the default (no---package) package.

SQL Connection Sharing

When the caller has an active SQL connection (from EXEC SQL statements), it is automatically shared with the callee. Both programs see the same database state, enabling patterns where the caller inserts data and the callee queries it within the same transaction.

Screen Handler Sharing

If the caller has a screen handler configured (for display file I/O), it is automatically passed to the callee. This allows multi-program applications to share a single terminal session.

Limitations