Easytrieve RETURN — Control Flow for Called Programs

RETURN in the Control Flow Family

Easytrieve offers several ways to leave a block of logic. Each verb targets a different scope. Mixing them up is a common maintenance defect: a developer adds STOP where RETURN belonged and the nightly driver never reaches summary PRINT. Control-flow literacy means knowing which exit verb matches which entry verb—CALL pairs with RETURN, PERFORM pairs with END-PROC, activity flow may use EXIT, and STOP ends the run.

CALL and RETURN Lifecycle

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
* --- Caller (main Easytrieve program) ---
JOB INPUT PAYROLL
  MOVE GROSS-PAY TO WS-GROSS
  CALL TAXCALC USING (WS-GROSS, WS-TAX) RETURNS WS-RC
  IF WS-RC NE 0
     PERFORM TAX-ERROR
     GOTO JOB
  END-IF
  PRINT PAYRPT
 
* --- Callee (TAXCALC load module) ---
PROGRAM NAME TAXCALC
  * WS-GROSS and WS-TAX passed via USING linkage
  COMPUTE WS-TAX = WS-GROSS * TAX-RATE
  IF WS-GROSS LT 0
     RETURN 8
  END-IF
  RETURN 0

Caller prepares arguments, CALLs TAXCALC, waits implicitly until callee RETURNs, then tests WS-RC. Callee computes tax, RETURN 8 on validation failure, RETURN 0 on success. Caller never sees callee statements after RETURN—the linkage layer restores the caller's register and data context per platform ABI. USING field order and lengths must match callee linkage definitions on COBOL or Easytrieve side.

Return Code Contracts

Standardize meaning before mixing languages. A practical shop table: 0 success; 1–99 application validation errors documented per module; 100+ system or file errors; negative values reserved for abend-style failures if your integration guide allows. COBOL programmers set RETURN-CODE special register; Assembler uses register 15; Easytrieve callee sets numeric value RETURN passes or field callee documents. Caller must not ignore non-zero RC when callee modified output parameters—partial tax calculation with RC 8 should not PRINT as if valid.

RETURN Versus EXIT in Procedures

EXIT inside a JOB PROC may leave the procedure without ending the CALL target—EXIT is not RETURN. If your PROC CALLs a subprogram, only the subprogram's RETURN ends that CALL; EXIT afterward still runs inside caller when control returns from nested PERFORM. Draw call graphs on paper for complex jobs: PERFORM layers are stacks; CALL layers are separate modules. RETURN pops the module stack; END-PROC pops the PERFORM stack.

Parameter Passing and Side Effects

USING passes fields by reference when linkage expects it—callee updates to WS-TAX appear in caller after RETURN. Literals in USING pass fixed values callee cannot write back. Packed versus zoned decimal mismatches between Easytrieve DEFINE and COBOL PIC corrupt amounts without compile errors. Align type, length, and decimal positions in a shared copybook comment block both teams maintain. After RETURN, caller reads only fields callee documented as output—do not assume unrelated working storage survived callee execution.

Easytrieve Callee Module Pattern

1
2
3
4
5
6
7
8
9
PROGRAM NAME VALIDRPT
  IF INPUT-KEY EQ SPACES
     RETURN 4
  END-IF
  PERFORM VALIDATE-KEYS
  IF ERROR-COUNT GT 0
     RETURN 4
  END-IF
  RETURN 0

Compile VALIDRPT as separate load module. Main report driver CALL VALIDRPT USING (INPUT-KEY) RETURNS VAL-RC before expensive FILE processing. Reusable validation centralizes rules one team owns. Callee ends only with RETURN or fall-through to implicit return per release—never STOP unless module design ends entire task.

Static Versus Dynamic CALL

Environment PARM CALL and binder cards determine whether callee resolves at link-edit or runtime from STEPLIB. RETURN behavior is identical; which callee binary executes differs. Dynamic CALL lets tax module hotfix deploy without relinking payroll driver—verify STEPLIB order points to new TAXCALC level. Static CALL embeds callee address at link—caller must relink when callee changes. RETURN does not compensate for calling wrong module level.

CICS and Online RETURN Rules

Broadcom documents conversational requirements for programs CALLed under CICS. Callee must RETURN to preserve transaction context for pseudo-conversational SCREEN flows. STOP in callee may terminate CICS task unexpectedly, stranding terminal users. COBOL subprograms use EXEC CICS RETURN; Easytrieve callee uses RETURN per Language Reference. Coordinate with systems programming when mixing Easytrieve SCREEN, CALL, and Db2 commit boundaries—RETURN timing relative to COMMIT TERMINAL affects recoverability.

Nested CALL Chains

Caller A CALLs B; B CALLs C; C RETURNs to B; B RETURNs to A. Each level must RETURN to its immediate caller—C must not RETURN skipping B unless design uses non-standard linkage (rare and discouraged). Deep chains complicate return code propagation: B might map C's RC to B's RC before B RETURNs to A. Document aggregation rules—first non-zero wins, or highest severity wins.

Testing CALL and RETURN Integration

1. Test RC 0 path: caller continues; output fields populated.
2. Test each documented non-zero RC: caller branches correctly.
3. Verify callee STOP is absent from production modules.
4. Dynamic CALL: change callee STEPLIB level without relinking caller.
5. Online: confirm SCREEN transaction survives CALL RETURN cycle.

Common RETURN Mistakes

• STOP in callee instead of RETURN.
• Ignoring RETURNS field after CALL.
• Confusing RETURN with END-PROC after PERFORM.
• USING parameter layout mismatch with COBOL linkage.
• No return code documentation between teams.
• CALL from PROC without planning EXIT versus nested RETURN.

Explain It Like I'm Five

RETURN is hanging up the phone when someone called you for help. Your friend CALLs you to figure out tax on their allowance. You answer, do the math, say the answer and RETURN—that means hang up so they can continue their homework. If you STOP instead, you turn off the whole house phone and nobody can finish anything. END-PROC is just closing your notebook page when you were talking to yourself, not on the phone.

Exercises

1. Draw CALL/RETURN diagram for driver plus two callees.
2. Write caller IF branches for RC 0, 4, and 100.
3. List differences between RETURN, EXIT, END-PROC, STOP.
4. Document USING layout for Easytrieve caller and COBOL callee.
5. Explain why CICS callee should not STOP.