Martin: Created page with "== 7. Error Handling == === 7.1 Return-Code Standard === All programs and DAL interfaces use the following result-code scheme via `DAL-RESULT` / `SESSION-RESULT` / `UI-RESULT`: {| class="wikitable" style="width:100%" ! Code !! Meaning !! Required Action |- | `0` || Success || Continue processing. |- | `1` || Error — recoverable || Log message; set result; return to caller for decision. |- | `2` || End..."

2026-03-25T11:16:30Z

Created page with "== 7. Error Handling == === 7.1 Return-Code Standard === All programs and DAL interfaces use the following result-code scheme via <code>DAL-RESULT</code> / <code>SESSION-RESULT</code> / <code>UI-RESULT</code>: {| class="wikitable" style="width:100%" ! Code !! Meaning !! Required Action |- | <code>0</code> || Success || Continue processing. |- | <code>1</code> || Error — recoverable || Log message; set result; return to caller for decision. |- | <code>2</code> || End..."

New page

== 7. Error Handling ==

=== 7.1 Return-Code Standard ===

All programs and DAL interfaces use the following result-code scheme via <code>DAL-RESULT</code> / <code>SESSION-RESULT</code> / <code>UI-RESULT</code>:

{| class="wikitable" style="width:100%"
! Code !! Meaning !! Required Action
|-
| <code>0</code> || Success || Continue processing.
|-
| <code>1</code> || Error — recoverable || Log message; set result; return to caller for decision.
|-
| <code>2</code> || End-of-data / not found || Handle gracefully; this is not an error condition.
|-
| <code>3</code> || Warning — processing continued || Log warning; continue.
|-
| <code>8</code> || Fatal error — terminate || Log; disconnect DB; PERFORM Z000-PROGRAM-END.
|-
| <code>16</code> || System error — abend || Emergency disconnect; STOP RUN with non-zero RETURN-CODE.
|}

'''Note''' — the pgcobol project uses only codes 0, 1, and 9/99 (EOF). Adopting the full scheme above provides finer-grained diagnostics and removes the ambiguity between ''error'' and ''end-of-data''.

=== 7.2 Mandatory Error Paragraph — E000-HANDLE-ERROR ===

Every program must implement an <code>E000-HANDLE-ERROR</code> paragraph:

<syntaxhighlight lang="cobol">
E000-HANDLE-ERROR.
MOVE 'E000-HANDLE-ERROR' TO ERR-PARAGRAPH
MOVE ERR-MESSAGE TO UI-SCREEN-MESSAGE
MOVE 'log-message' TO UI-METHODS
CALL 'programui' USING PROGRAM-UI
IF ERR-SEVERITY > 4
PERFORM Z000-PROGRAM-END
END-IF.
</syntaxhighlight>

=== 7.3 Prohibited Patterns ===

{| class="wikitable" style="width:100%"
! Prohibited Pattern !! Reason / Compliant Alternative
|-
| <code>STOP RUN</code> without DB disconnect || Leaves open transactions; always PERFORM Z000-PROGRAM-END first.
|-
| Ignoring SQLCODE after any EXEC SQL || Silent failures corrupt data; always EVALUATE SQLCODE.
|-
| <code>NEXT SENTENCE</code> (post-COBOL 85) || Ambiguous scope; use CONTINUE inside a scoped IF / EVALUATE.
|-
| Empty WHEN OTHER with no comment || Add at minimum: <code>*-- no action required because <reason></code>
|-
| <code>GO TO</code> (except structured exit) || Use PERFORM, EVALUATE, EXIT PARAGRAPH, EXIT PROGRAM.
|-
| <code>ALTER</code> statement || Prohibited entirely; dynamic paragraph modification is untestable.
|-
| <code>SELECT *</code> in EXEC SQL || Always name columns; column-order changes silently break host-variable binding.
|}

=== 7.4 Cleanup Always Attempted ===

Termination paragraphs (Z000-series) must always be performed before program exit, regardless of whether prior steps succeeded. This guarantees that database connections and print files are always closed. Guard with conditional logic inside Z000 rather than skipping Z000 itself.

----

----
''[[Cobol programming standards|← Back to index]]''

COBOL Std 7 Error Handling - Revision history