The INVOKE Statement

General Rules

1. The instance of the program, function or method that executes the INVOKE statement is the activating run-time system element.
2. Object-identifier-1

    or identifier-1

   identifies an object instance. If object-identifier-1 is specified as a class-name, object-identifier-1 identifies the factory object of that class-name. Literal-1 or the content of the data item referenced by identifier-2 identifies a method of that object that will act upon that object instance:

   1. If the method to be invoked is a COBOL method, literal-1 or the content of the data item referenced by identifier-2 is the name of the method to be invoked as specified in its Method-ID paragraph.

      If the object instance is identified by a universal object reference, neither a formal parameter nor the returning item in the invoked method may be described with the ANY LENGTH clause

   2. If the method to be invoked is not a COBOL method, the rules for the formation of the method-name are dependent upon the domain involved.
3.  The AS phrase enables you to invoke methods on a COBOL data item. If template-1 is specified, it is used as a class template. Creation of templates is a function provided by objects in the supplied Class Library. (See your COBOL system documentation for details.)
4. When an INVOKE statement is executed, the method specified is made available for execution and control is transferred to the invoked method. If the invoked method is a COBOL method, its execution is as described in the topic General Rules in the topic The PROCEDURE DIVISION Header; otherwise, the execution is defined by the implementor of the language in which the method is written. After control is returned from the method, control is transferred to the end of the INVOKE statement.
5. The run unit is not aware of whether an invoked method is a COBOL method or a non-COBOL method until the invoked method has been located, prior to being made available for execution. The form of the method-name cannot be used to determine whether the method is a COBOL method or not.
6. The process of invoking a method or exiting from an invoked method does not alter the status or positioning of a file associated with any external file connector.
7. This implementation does not maintain any synchronization between the arguments and the Linkage Section data items. That is your responsibility.
   Note: The COBOL language places no restrictions on the alignment of the addresses of data items, whereas non-COBOL languages typically do make assumptions about addresses and will fail in some way if a misaligned data item is referenced. Alignment can be achieved by one or more of the following actions:

   • Modifying group items to include additional filler items
   • Ensuring operands in the USING phrase are level 01 or level 77 data items in conjunction with the ALIGN Compiler directive or
   • Use of the SYNCHRONIZED clause in conjunction with the IBMCOMP Compiler directive

   If a RETURNING phrase is specified on the INVOKE statement, a non-COBOL method must return a result in the appropriate format.

8. The sequence of arguments in the USING phrase of the INVOKE statement and the corresponding formal parameters in the USING phrase of the invoked method's PROCEDURE DIVISION header determines the correspondence between arguments and formal parameters. This correspondence is positional and not by name equivalence; the first argument corresponds to the first formal parameter, the second to the second, etc.

   If a parameter is an index-name, no such correspondence is established. Index-names in the invoked method and the invoking run-time system element always refer to separate indices.

   The effect of the USING phrase on the activated run-time system element is described in as described in the topic General Rules in the topic The PROCEDURE DIVISION Header

9. An argument that consists merely of a single identifier or literal is regarded as an identifier or literal rather than an arithmetic expression.
10. The values of the parameters referenced in the USING phrase of the INVOKE statement are made available to the invoked method at the time the INVOKE statement is executed.
11. The BY CONTENT, BY REFERENCE and BY VALUE phrases are transitive across the parameters that follow them until another BY CONTENT, BY REFERENCE or BY VALUE phrase is encountered.

    If no BY CONTENT, BY REFERENCE or BY VALUE phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed.

12. If the BY REFERENCE ADDRESS OF phrase is specified or implied then the method operates as if a data item had been declared with USAGE POINTER and that data item passed BY REFERENCE with a value acquired by a SET data item TO ADDRESS OF identifier-4 statement.
13. If the BY CONTENT phrase is specified or implied for a parameter, the invoked method cannot change the value of this parameter as referenced in the INVOKE statement's USING phrase, although the invoked method can change the value of the data item referenced by the corresponding data-name in the invoked method's PROCEDURE DIVISION header. The data description of each parameter in the BY CONTENT phrase of the INVOKE statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the PROCEDURE DIVISION header.

    If the BY CONTENT phrase is specified or implied for a parameter, the object program operates as if an additional data item had been declared and this additional data item used as the parameter in a BY REFERENCE phrase. If identifier-5 is specified then both the implied data description of the additional data item and its contents are identical to that of identifier-5. If literal-3 is specified then the implied data description of the additional item is equivalent to an alphanumeric data item with the same size as literal-3 and with its contents set to the value of literal-3. If LENGTH OF identifier-6 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-6.

14. If the BY VALUE phrase is specified or implied for a parameter, the invoked method cannot change the value of this parameter as referenced in the INVOKE statement's USING phrase, though the invoked method can change the value of the data item referenced by the corresponding data-name in the invoked method's PROCEDURE DIVISION header. The method operates, conceptually, as if an additional data item had been declared in a system area (typically the stack), available to non-COBOL languages for passing parameters and this additional data item occupies the same storage area as the data item in the invoked method.

    If identifier-7 is specified and is BINARY, COMP-4, COMP-5 or COMP-X, then the data description of the additional data item is identical to that of identifier-7, except its usage is COMP-5. The contents of the additional data item are identical to the COMP-5 representation of the contents of identifier-7. This conversion and representation facilitates calling non-COBOL programs.

    Otherwise, if identifier-7 is specified then the implied data description of the additional data item and its contents are identical to that of identifier-7.

    If integer-1 is specified, then the data description of the additional item is equivalent to a signed numeric item USAGE COMP-5 that occupies the number of bytes of storage indicated by the value of integer-2, if specified, or the size of the system area otherwise (typically the size of a POINTER on the system).

    If LENGTH OF identifier-8 is specified, then the data description of the additional item is equivalent to PIC S9(n) USAGE COMP-5, where the value of n is at least 9 and defines a data item that is large enough to hold the maximum length of a data item in the COBOL system. The contents of the additional data item are set to the number of bytes of storage allocated to identifier-8.

    If the method being invoked is a COBOL method, each parameter in the BY VALUE phrase of the INVOKE statement must have a corresponding parameter declared in the USING phrase of the PROCEDURE DIVISION header that also has the BY VALUE phrase specified or implied.

    The additional data item generated as a result of the INVOKE statement, described above, is related to this corresponding parameter in the invoked method, as follows.

    • If the additional data item was subject to conversion from BINARY, COMP-4, COMP-5 or COMP-X to COMP-5, then the data description of the corresponding parameter in the invoked method must be identical to that of the data description of the additional data item with the exception that the corresponding parameter's usage can be any of BINARY, COMP-4, COMP-5 or COMP-X. On entry to the invoked COBOL method, a conversion from the USAGE COMP-5 of the additional data item to the USAGE of the corresponding parameter in the invoked method is performed.
    • If the additional data item was not subject to conversion to COMP-5, the data description of each parameter in the invoked method must be the same as the corresponding additional data item. This means there is no conversion or extension or truncation, of the additional data item to match the corresponding parameter in the invoked method.

    If the method being invoked is non-COBOL, the details of when you need to use the BY VALUE phrase are dependent on the domain involved.

15.  If identifier-4 is in the Linkage Section and has a level number other than 01 or 77 or is in the Working-Storage Section, the item is passed as if BY CONTENT had been specified and the address of identifier-4 cannot be modified by the invoked method.
16.  If the BY REFERENCE literal-2 phrase is specified or implied then the method processes literal-2 as described for literal-3.
17.  If LENGTH OF identifier-6 is specified then the data description of the argument is PIC S9(9) USAGE BINARY and its content is set to the number of bytes of storage allocated to identifier-6.
18.  If integer-1 is specified then the implied data description of the argument is a signed numeric item USAGE COMP-5 that occupies the number of bytes of storage specified by the value of integer-2, if specified, or 4 bytes otherwise.
19.  If LENGTH OF identifier-8 is specified then the data description of the argument is PIC S9(9) USAGE BINARY and its content is set to the number of bytes of storage allocated to identifier-8.
20.  If identifier-10 is specified, the invoked method must return a value with explicit or implicit USAGE POINTER. The result of the method is assigned to identifier-10 using the rules for the SET statement.
21. Invoked methods may contain INVOKE statements. An invoked method may execute an INVOKE statement that directly or indirectly invokes the invoking method.
22. If an OMITTED phrase is specified or a trailing argument is omitted, the omitted-argument condition for that parameter is true in the invoked method.
23. If a parameter for which the omitted-argument condition is true is referenced in an invoked method, except as an argument or in the omitted-argument condition, you will get RTS error message 203.