COBOL INVOKE – Quick Reference

INVOKE is the object-oriented COBOL statement for calling a method on an object or on a class. You specify what to call (an object reference or a class name), the method name, optional parameters (USING), an optional return value (RETURNING), and optional exception handling (ON EXCEPTION / NOT ON EXCEPTION). The block is terminated with END-INVOKE. INVOKE is used in OO COBOL; for calling traditional subprograms use the CALL statement instead.

Explain Like I'm Five: What Is INVOKE?

Imagine you have a robot (an object) that can do tasks (methods). When you say "robot, get name" or "robot, add these numbers," you are invoking a method. INVOKE is the COBOL way to say "object, run this method (with these inputs, and put the answer here)." If the robot reports a problem, you can do something special (ON EXCEPTION). INVOKE SELF means "this same robot, do another task;" INVOKE SUPER means "ask the parent robot to do it."

Syntax

1
2
3
4
5
6
INVOKE object-reference "method-name"
    [USING param-1 param-2 ...]
    [RETURNING return-value]
    [ON EXCEPTION imperative-statement ...]
    [NOT ON EXCEPTION imperative-statement ...]
END-INVOKE.

The object-reference is an object handle (data item that holds a reference to an object). For class (static) methods you use the class name instead. The method name is often a literal in quotes (e.g. "getName", "NEW"). USING lists the arguments; RETURNING is the receiving field for the method result. ON EXCEPTION and NOT ON EXCEPTION are optional and run depending on whether the method raised an exception.

Syntax Parts Explained

Instance Method vs Class Method

When you call a method on an object reference (e.g. INVOKE WS-CUSTOMER "getName" RETURNING WS-NAME), you are calling an instance method: it runs in the context of that object and can use that object's data. When you call a method on a class name (e.g. INVOKE Customer "NEW" RETURNING WS-CUSTOMER), you are calling a class (factory) method: there is no instance yet; such methods often create and return a new object. "NEW" is a common factory method name.

1
2
3
4
5
6
7
8
*> Factory method: create a new Customer object
INVOKE Customer "NEW" RETURNING WS-CUSTOMER.
 
*> Instance method: get name from the object
INVOKE WS-CUSTOMER "getName" RETURNING WS-NAME.
 
*> Instance method with parameters
INVOKE WS-CUSTOMER "setBalance" USING BY VALUE WS-AMOUNT.

USING and Parameter Passing

The USING phrase passes arguments to the method. The number and order must match the method's definition. You can specify BY REFERENCE (default in many implementations), BY VALUE, or BY CONTENT for each parameter when the method is defined; the caller must pass a compatible argument. BY REFERENCE passes the address so the method can modify the data. BY VALUE passes a copy (the method cannot change the caller's data). BY CONTENT passes a copy of the value. The exact syntax (e.g. BY VALUE identifier) depends on your COBOL dialect.

RETURNING

If the method returns a value, you specify RETURNING followed by a data item that receives that value. The item must have a type compatible with the method's return type (e.g. numeric, alphanumeric, object reference). After END-INVOKE, the returned value is in that item (provided no exception occurred).

SELF and SUPER

Inside a method, INVOKE SELF "otherMethod" calls another method on the same object (the current instance). Use it when one method delegates to another on the same object. INVOKE SUPER "methodName" calls the version of the method defined in the parent class. Use it when you override a method but still want to run the parent's logic (e.g. do the parent action first, then add your own).

1
2
3
4
5
*> In a method: call another method on same object
INVOKE SELF "validateInput" USING WS-INPUT.
 
*> In an overriding method: call parent implementation
INVOKE SUPER "process" USING WS-DATA.

ON EXCEPTION and NOT ON EXCEPTION

If the invoked method raises an exception or fails, control can go to the ON EXCEPTION clause. There you might set a flag, display an error, or take a different path. NOT ON EXCEPTION runs when the method completes normally. Only one of the two runs for a given invocation. END-INVOKE ends the block. If you do not specify ON EXCEPTION, an unhandled exception may propagate to the caller or the runtime.

1
2
3
4
5
6
7
INVOKE WS-SERVICE "process" USING WS-REQUEST RETURNING WS-RESULT
    ON EXCEPTION
        SET WS-ERROR TO TRUE
        DISPLAY "Method failed"
    NOT ON EXCEPTION
        DISPLAY "Success: " WS-RESULT
END-INVOKE.

INVOKE vs CALL

INVOKE is for object-oriented COBOL: you call a method on an object or class. CALL is for procedural COBOL: you call another program (subprogram) by name and pass parameters. CALL does not have a concept of "object" or "method"; it transfers control to a program. Use INVOKE in OO programs when you have classes and objects; use CALL when you are linking traditional programs in a run unit.

Step-by-Step: Calling an Instance Method

1. Ensure you have a valid object reference in a data item (e.g. from a factory method like INVOKE MyClass "NEW" RETURNING my-obj).
2. Prepare any arguments the method needs (USING parameters).
3. Write INVOKE object-ref "methodName" USING ... RETURNING ... as needed. Use the exact method name and parameter order defined for the method.
4. Add ON EXCEPTION (and optionally NOT ON EXCEPTION) if you need to handle success and failure differently.
5. Close with END-INVOKE. After END-INVOKE, check the RETURNING value or exception path.

Best Practices

• Always use END-INVOKE to close the INVOKE block so exception scope is clear.
• Check for null or invalid object references before INVOKE if the reference might not be set.
• Use ON EXCEPTION when the method can fail so the program can recover or report the error.
• Match USING and RETURNING types to the method definition to avoid runtime errors.
• Use SELF and SUPER only inside method code; the context is the current object and its class hierarchy.

Test Your Knowledge