Easytrieve CALL Statement

Statement Format

1
2
3
CALL program-name
CALL program-name USING (field-a, field-b)
CALL program-name USING ('LITERAL', USERFLD) RETURNS RC-FIELD

Program-name identifies load module. USING lists one or more parameters in parentheses, comma-separated. Each entry is field-name or quoted literal. RETURNS names numeric receive field for return code.

Parameter Passing

Parameters must be system-defined fields, working storage, or fields on accessible files per Broadcom. Match called program linkage section—length, type, order. COBOL BY REFERENCE expects Easytrieve fields at correct offsets. Literals pass fixed values such as file name tokens. Document parameter contract in comment block both sides maintain during change control.

Examples From Broadcom Documentation

1
2
3
4
5
6
CALL ASMPGM
CALL ASMPGM USING ('USERFIL', USERFLD)
 
IF RC NE 0
   DISPLAY 'CALL FAILED RC=' RC
END-IF

Static Versus Dynamic Binding

PARM CALL on Environment statement sets default binding for all CALL statements in program. z/OS and Windows default dynamic if not overridden—runtime loads module from STEPLIB or PATH. Unix default static—subprogram bound at link. Wrong assumption causes module not found at runtime or stale level not picked up after subprogram fix. Operations documents which style production uses; developers test CALL after subprogram promote.

Return Code Handling

RETURNS field should be numeric W storage. After CALL, IF RETURNS GT 0 branch to error PROC. COBOL programs set RETURN-CODE in special register; Assembler uses R15; C returns integer. Align semantics with called language—some shops use zero success, others zero failure. Standardize per integration guide.

CALL Versus PERFORM

CICS Conversational Requirement

Broadcom warns mainframe programs called in CICS must execute conversational—called program must not terminate the task. Easytrieve online transactions relying on CALL must coordinate with CICS program definition and EXEC CICS RETURN patterns in subprogram. Batch CALL has no this restriction.

Link-Edit and STEPLIB

Dynamic CALL resolves module at runtime from load libraries in STEPLIB or job LIBDEF. Static CALL requires subprogram in link step. Missing STEPLIB entry causes abend U1210-class module not found—operations add library to JCL. Version skew when Easytrieve passes new field layout but COBOL still expects old length causes storage overlay—regression test CALL after any linkage change.

Testing CALL Integration

1. Standalone call subprogram with test JCL before Easytrieve embed.
2. Verify return code zero on happy path.
3. Force error path in subprogram—confirm Easytrieve handles non-zero RETURNS.
4. Dump parameter fields before and after CALL for layout proof.
5. Retest after dynamic subprogram reload without Easytrieve recompile.

Common CALL Mistakes

• Parameter order mismatch with COBOL linkage.
• Passing alphabetic where binary expected.
• Omitting RETURNS then ignoring subprogram failure.
• PERFORM when external module required.
• CICS non-conversational subprogram ending task.
• Wrong static/dynamic assumption at runtime.

Explain It Like I'm Five

CALL is asking another expert to do a specialized job. You hand them the papers they need USING your folder. They hand back a note saying done or oops RETURNS return code. PERFORM is asking your teammate in the same room—same language, same notebook. CALL walks to another office where they speak COBOL or Assembler instead of Easytrieve.

Exercises

1. Write CALL with USING two fields and RETURNS RC.
2. Document parameter list matching mock COBOL linkage.
3. Explain dynamic versus static binding on your LPAR.
4. Add IF RC NE 0 error DISPLAY after CALL.
5. Contrast when PERFORM PROC beats CALL external module.