Rational Developer for System z
Enterprise COBOL for z/OS, Version 4.1, Language Reference


INVOKE statement

The INVOKE statement can create object instances of a COBOL or Java class and can invoke a method defined in a COBOL or Java class.

Read syntax diagramSkip visual syntax diagram
Format

>>-INVOKE--+-identifier-1-+--+-literal-1----+------------------->
           +-class-name-1-+  +-identifier-2-+   
           +-SELF---------+  '-NEW----------'   
           '-SUPER--------'                     

>--+---------------------------------------------------------------+-->
   |        .----------------------------------------------------. |   
   |        |                .---------------------------------. | |   
   |        V                V                                 | | |   
   '-USING----+----+--VALUE----+-+-----------+--identifier-3-+-+-+-'   
              '-BY-'           | '-LENGTH OF-'               |         
                               '-literal-2-------------------'         

>--+-------------------------+---------------------------------->
   '-RETURNING--identifier-4-'   

>--+-------------------------------------------+---------------->
   '-+----+--EXCEPTION--imperative-statement-1-'   
     '-ON-'                                        

>--+------------------------------------------------+----------->
   '-NOT--+----+--EXCEPTION--imperative-statement-2-'   
          '-ON-'                                        

>--+------------+----------------------------------------------><
   '-END-INVOKE-'   

identifier-1
Must be defined as USAGE OBJECT REFERENCE. The contents of identifier-1 specify the object on which a method is invoked.

When identifier-1 is specified, either literal-1 or identifier-2 must be specified, identifying the name of the method to be invoked.

The results of the INVOKE statement are undefined if either:

  • identifier-1 does not contain a valid reference to an object.
  • identifier-1 contains NULL.
class-name-1
When class-name-1 is specified together with literal-1 or identifier-2, the INVOKE statement invokes a static or factory method of the class referenced by class-name-1. literal-1 or identifier-2 specifies the name of the method that is to be invoked. The method must be a static method if class-name-1 is a Java class; the method must be a factory method if class-name-1 is a COBOL class.

When class-name-1 is specified together with NEW, the INVOKE statement creates a new object that is an instance of class class-name-1.

You must specify class-name-1 in the REPOSITORY paragraph of the configuration section of the class or program that contains the INVOKE statement.

SELF
An implicit reference to the object used to invoke the currently executing method. When SELF is specified, the INVOKE statement must appear within the procedure division of a method.
SUPER
An implicit reference to the object that was used to invoke the currently executing method. The resolution of the method to be invoked will ignore any methods declared in the class definition of the currently executing method and methods defined in any class derived from that class; thus the method invoked will be one that is inherited from an ancestor class.
literal-1
The value of literal-1 is the name of the method to be invoked. The referenced object must support the method identified by literal-1.

literal-1 must be an alphanumeric literal or a national literal.

literal-1 is interpreted in a case-sensitive manner. The method name, the number of arguments, and the data types of the arguments in the USING phrase of the INVOKE statement are used to select the method with matching signature that is supported by the object. The method can be overloaded.

identifier-2
A data item of category alphabetic, alphanumeric, or national that at run time contains the name of the method to be invoked. The referenced object must support the method identified by identifier-2.

If identifier-2 is specified, identifier-1 must be defined as USAGE OBJECT REFERENCE without any optional phrases; that is, identifier-1 must be a universal object reference.

The content of identifier-2 is interpreted in a case-sensitive manner. The method name, the number of arguments, and the data types of the arguments in the USING phrase of the INVOKE statement are used to select the method with matching signature that is supported by the object. The method can be overloaded.

identifier-2 cannot be a windowed date field.

NEW
The NEW operand specifies that the INVOKE statement is to create a new object instance of the class class-name-1. class-name-1 must be specified.

When class-name-1 is implemented in Java, the USING phrase of the INVOKE statement can be specified. The number of arguments and the data types of the arguments in the USING phrase of the INVOKE statement are used to select the Java constructor with matching signature that is supported by the class. An object instance of class class-name-1 is allocated, the selected constructor (or the default constructor) is executed, and a reference to the created object is returned.

When class-name-1 is implemented in COBOL, the USING phrase of the INVOKE statement must not be specified. An object instance of class class-name-1 is allocated, instance data items are initialized to the values specified in associated VALUE clauses, and a reference to the created object is returned.

When NEW is specified, you must also specify a RETURNING phrase as described in RETURNING phrase.

USING phrase

The USING phrase specifies arguments that are passed to the target method. The argument data types and argument linkage conventions are restricted to those supported by Java. See BY VALUE phrase for details.

BY VALUE phrase

Arguments specified in an INVOKE statement must be passed BY VALUE.

The BY VALUE phrase specifies that the value of the argument is passed, not a reference to the sending data item. The invoked method can modify the formal parameter that corresponds to an argument passed by value, but changes do not affect the argument because the invoked method has access only to a temporary copy of the sending data item.

identifier-3
Must be an elementary data item in the data division. The data type of identifier-3 must be one of the types supported for Java interoperation, as listed in Interoperable data types for COBOL and Java. Miscellaneous cases that are also supported as identifier-3 are listed in Miscellaneous argument types for COBOL and Java, with their corresponding Java type.

See Conformance requirements for arguments for additional requirements that apply to identifier-3.

literal-2
Must be of a type suitable for Java interoperation and must exactly match the type of the corresponding parameter in the target method. Supported literal forms are listed in Miscellaneous argument types for COBOL and Java, with their corresponding Java type.

literal-2 must not be a DBCS literal.

LENGTH OF identifier-3
Specifies that the length of identifier-3 is passed as an argument in the LENGTH OF special register. A LENGTH OF special register passed BY VALUE is treated as a PIC 9(9) binary value. For information about the LENGTH OF special register, see LENGTH OF.

Conformance requirements for arguments

When identifier-3 is an object reference, the following rules apply:

  • A class-name must be specified in the data description entry for that object reference. That is, identifier-3 must not be a universal object reference.
  • The specified class-name must reference a class that is exactly the class of the corresponding parameter in the invoked method. That is, the class of identifier-3 must not be a subclass or a superclass of the corresponding parameter's class.

When identifier-3 is not an object reference, the following rules apply:

  • If the target method is implemented in COBOL, the description of identifier-3 must exactly match the description of the corresponding formal parameter in the target method.
  • If the target method is implemented in Java, the description of identifier-3 must correspond to the Java type of the formal parameter in the target method, as specified in Interoperable data types for COBOL and Java.

Usage note: Adherence to conformance requirements for arguments is the responsibility of the programmer. Conformance requirements are not verified by the compiler.

RETURNING phrase

The RETURNING phrase specifies a data item that will contain the value returned from the invoked method. You can specify the RETURNING phrase on the INVOKE statement when invoking methods that are written in COBOL or Java.

identifier-4
The RETURNING data item. identifier-4:
  • Must be defined in the data division
  • Must not be reference-modified
  • Is not changed if an EXCEPTION occurs

The data type of identifier-4 must be one of the types supported for Java interoperation, as listed in Interoperable data types for COBOL and Java.

See Conformance requirements for the RETURNING item for additional requirements that apply to identifier-4.

If identifier-4 is specified and the target method is written in COBOL, the target method must have a RETURNING phrase in its procedure division header. When the target method returns, its return value is assigned to identifier-4 using the rules for the SET statement if identifier-4 is described with USAGE OBJECT REFERENCE; otherwise, the rules for the MOVE statement are used.

The RETURNING data item is an output-only parameter. On entry to the called method, the initial state of the PROCEDURE DIVISION RETURNING data item has an undefined and unpredictable value. You must initialize the PROCEDURE DIVISION RETURNING data item in the invoked method before you reference its value. The value that is passed back to the invoker is the final value of the PROCEDURE DIVISION RETURNING data item when the invoked method returns.

See the Enterprise COBOL Programming Guide for discussion of local and global object references as defined in Java. These attributes affect the life-time of object references.

Usage note: The RETURN-CODE special register is not set by execution of INVOKE statements.

Conformance requirements for the RETURNING item

For INVOKE statements that specify class-name-1 NEW, the RETURNING phrase is required. The returning item must be one of the following:

  • A universal object reference
  • An object reference specifying class-name-1
  • An object reference specifying a superclass of class-name-1

For INVOKE statements without the NEW phrase, the RETURNING item specified in the method invocation and in the corresponding target method must satisfy the following requirements:

  • The presence or absence of a return value must be the same on the INVOKE statement and in the target method.
  • If the RETURNING item is not an object reference, the following rules apply:
    • If the target method is implemented in COBOL, the returning item in the INVOKE statement and the RETURNING item in the target method must have an identical data description entry.
    • If the target method is implemented in Java, the returning item in the INVOKE statement must correspond to the Java type of the method result, as described in Interoperable data types for COBOL and Java.
  • If the RETURNING item is an object reference, the RETURNING item specified in the INVOKE statement must be an object reference typed exactly to the class of the returning item specified in the target method. That is, the class of identifier-4 must not be a subclass or a superclass of the class of the returning item in the target method.

Usage note: Adherence to conformance requirements for returning items is the responsibility of the programmer. Conformance requirements are not verified by the compiler.

ON EXCEPTION phrase

An exception condition occurs when the identified object or class does not support a method with a signature that matches the signature of the method specified in the INVOKE statement. When an exception condition occurs, one of the following actions occurs:

  • If the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1.
  • If the ON EXCEPTION phrase is not specified, a severity-3 Language Environment® condition is raised at run time.

NOT ON EXCEPTION phrase

If an exception condition does not occur (that is, the identified method is supported by the specified object), control is transferred to the invoked method. After control is returned from the invoked method, control is then transferred:

  1. To imperative-statement-2, if the NOT ON EXCEPTION phrase is specified.
  2. To the end of the INVOKE statement if the NOT ON EXCEPTION phrase is not specified.

END-INVOKE phrase

This explicit scope terminator serves to delimit the scope of the INVOKE statement. An INVOKE statement that is terminated by END-INVOKE, along with its contained statements, becomes a unit that is treated as though it were an imperative statement. It can be specified as an imperative statement in a conditional statement; for example, in the exception phrase of another statement.

Interoperable data types for COBOL and Java

A subset of COBOL data types can be used for interoperation between COBOL and Java.

You can specify the interoperable data types as arguments in COBOL INVOKE statements and as the RETURNING item in COBOL INVOKE statements. Similarly, you can pass these types as arguments from a Java method invocation expression and receive them as parameters in the USING phrase or as the RETURNING item in the procedure division header of a COBOL method.

The following table lists the primitive Java types and the COBOL data types that are supported for interoperation and the correspondence between them.

Table 1. Interoperable Java and COBOL data types
Java data type COBOL data type
boolean1 Conditional variable and two condition-names of the form:
level-number  data-name        PIC X.
88            data-name-false  VALUE X'00'.
88            data-name-true   VALUE X'01' THROUGH X'FF'. 
byte Single-byte alphanumeric, PIC X or PIC A
short USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE clause of the form S9(n), where 1 <= n <= 4
int USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE clause of the form S9(n), where 5 <= n <= 9
long USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE clause of the form S9(n), where 10 <= n <= 18
float2 USAGE COMP-1
double2 USAGE COMP-2
char

Single-character national: PIC N USAGE NATIONAL
(an elementary data item of category national)

class types
(object references)

USAGE OBJECT REFERENCE class-name
  1. Enterprise COBOL interprets a PIC X argument or parameter as the Java boolean type only when the PIC X data item is followed by exactly two condition-names of the form shown. In all other cases, a PIC X argument or parameter is interpreted as the Java byte type.
  2. Java floating-point data is represented in IEEE floating-point, while Enterprise COBOL uses the IBM hexadecimal floating-point representation. The representations are automatically converted as necessary when Java methods are invoked from COBOL and when COBOL methods are invoked from Java.

In addition to the primitive types, Java Strings and arrays of Java primitive types can interoperate with COBOL. This requires specialized mechanisms provided by the COBOL runtime system and the Java Native Interface (JNI).

In a Java program, to pass array data to COBOL or to receive array data from COBOL, you declare the array types using the usual Java syntax. In the COBOL program, you declare the array as an object reference that contains an instance of one of the special classes provided for array support. Conversion between the Java and COBOL types is automatic at the time of method invocation.

In a Java program, to pass String data to COBOL or to receive String data from COBOL, you declare the array types using the usual Java syntax. In the COBOL program, you declare the String as an object reference that contains an instance of the special jstring class. Conversion between the Java and COBOL types is automatic at the time of method invocation. The following table lists the Java array and String data types and the corresponding special COBOL data types.

Table 2. Interoperable COBOL and Java array and String data types
Java data type COBOL data type
boolean[ ] object reference jboooleanArray
byte[ ] object reference jbyteArray
short[ ] object reference jshortArray
int[ ] object reference jintArray
long[ ] object reference jlongArray
char[ ] object reference jcharArray
Object[ ] object reference jobjectArray
String object reference jstring

The following java array types are not currently supported:

Java data type COBOL data type
float[ ] object reference jfloatArray
double[ ] object reference jdoubleArray

You must code an entry in the repository paragraph for each special class that you want to use, just as you do for other classes. For example, to use jstring, code the following entry:

Configuration Section.
Repository.
    Class jstring is "jstring".

Alternatively, for the String type, the COBOL repository entry can specify an external class name of java.lang.String:

Repository.
    Class jstring is "java.lang.String".

Callable services are provided by the Java Native Interface (JNI) for manipulating the COBOL objects of these types in COBOL. For example, callable services can be used to set COBOL alphanumeric or national data into a jstring object or to extract data from a jstring object. For details on use of JNI callable services for these and other purposes, see the Enterprise COBOL Programming Guide.

For details on repository entries for class definitions, see REPOSITORY paragraph. For examples, see the Enterprise COBOL Programming Guide.

Miscellaneous argument types for COBOL and Java

Miscellaneous cases of COBOL items that can be used as arguments in an INVOKE statement are listed in the following table along with the corresponding Java type.

Table 3. COBOL miscellaneous argument types and corresponding Java types
COBOL argument Corresponding Java data type
Reference-modified item of usage display with length one byte
Reference-modified item of usage national with length one (either an elementary data item of usage national or a national group item) char
SHIFT-IN and SHIFT-OUT special registers byte
LINAGE-COUNTER special register when its usage is binary int
LENGTH OF special register int

The following table lists COBOL literal types that can be used as arguments in an INVOKE statement, with the corresponding Java type.

Table 4. COBOL literal argument types and corresponding Java types
COBOL literal argument Corresponding Java data type
Fixed-point numeric literal with no decimal positions and with nine digits or less int
Floating-point numeric literal double
Figurative constant ZERO int
One-character alphanumeric literal byte
One-character national literal char
Symbolic character byte
Figurative constants SPACE, QUOTE, HIGH-VALUE, or LOW-VALUE byte

Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)