Add signals keyword to declare that exceptions may be raised by RPG procedures

Summary

RPGLE currently offers no syntactic or compiler-level mechanism to indicate that a procedure may raise an exception (*ESCAPE). Developers must either read the source of every invoked procedure (when available) or defensively wrap every call in monitor / on-error blocks, which hurts readability and does not guarantee real error coverage.

This idea proposes two additions to the language:

1. A new signals(...) keyword on dcl-proc and dcl-pr to document the exception message IDs a procedure may raise.

2. A new ctl-opt signal(...) control option so developers or corporate standards can define the level of compiler enforcement applied to that metadata.

Motivation

Modern enterprise architectures on IBM i (layered SOA: controller → interface → business logic) rely on service modules exposing dozens of exportable procedures, many of which raise exceptions through CEE* APIs, snd-msg *ESCAPE, or custom wrappers. Today there is no standard way to:

• Document that a procedure may fail with an exception.

• Warn the caller if the call is not wrapped in a monitor block.

• Enable static analysis or IDE quick-fixes in RDi or VS Code (Code for IBM i).

• Enforce an explicit contract between service layers.

This proposal closes a language-expressiveness gap that other languages have already addressed (Java throws, Swift throws, C++ noexcept, Python type stubs Raises:).

Proposed syntax

Compiler control option:

ctl-opt signal(*NONE);   // Default — full backward compatibility, allow percolate to caller
ctl-opt signal(*WARN);   // Compiler emits severity 10 message on mismatch (allow percolate to caller)
ctl-opt signal(*STRICT); // Compiler emits severity 30+ message (fails the build)

Prototype and procedure declaration:

dcl-pr GetClientStatus ind extproc(*dclcase) signals('CPF9898' : 'BAC0001');
end-pr;

dcl-proc GetClientStatus export signals('CPF9898' : 'BAC0001');
  // ...
  throwProc();  // sends an *ESCAPE message that percolates to the caller
end-proc;

Control option usage

/// Compilation list

// Caller with Strict signal control option
ctl-opt signal(*strict);

if GetClientStatus();   
  // Do miracles 
endif;

// RNFXXXX Procedure GetClientStatus may raise exception messages CPF9898, 
//         BAC001 surround with a valid RPG handler

Suggested special values:

• signals(*NONE) — explicitly declares the procedure raises no exceptions (analogous to C++ noexcept).

• signals(*ANY) — declares the procedure may raise any exception (useful for QCMDEXC, MI API, CEE* wrappers).

• Wildcard support: signals('CPF*' : 'BAC*').

Suggested monitor semantics:

• A monitor with catch-all on-error; satisfies any declared signals().

• on-error 'CPFxxxx' satisfies only the matching ID.

Benefits

1. Explicit contract documentation for each procedure.

2. Enables static analysis in RDi, VS Code, ARCAD, SonarQube.

3. IDE quick-fixes ("wrap in monitor", "add signals()").

4. Enforced contracts between service layers in modern IBM i architectures.

5. Gradual adoption: *NONE default keeps 100% backward compatibility.

6. Alignment with recent language additions (dcl-enum, on-exit, %LIST, EXTPROC(*DCLCASE)).

Backward compatibility

Fully backward compatible. Default signal(*NONE) ensures no existing program is affected. The signals() keyword is opt-in per procedure.

Any suggestions or alternatives to add this functionality are welcome.