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.
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-'
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:
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.
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.
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.
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.
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.
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.
See Conformance requirements for arguments for additional requirements that apply to identifier-3.
literal-2 must not be a DBCS literal.
When identifier-3 is an object reference, the following rules apply:
When identifier-3 is not an object reference, the following rules apply:
Usage note: Adherence to conformance requirements for arguments is the responsibility of the programmer. Conformance requirements are not verified by the compiler.
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.
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.
For INVOKE statements that specify class-name-1 NEW, the RETURNING phrase is required. The returning item must be one of the following:
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:
Usage note: Adherence to conformance requirements for returning items is the responsibility of the programmer. Conformance requirements are not verified by the compiler.
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 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:
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.
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.
| 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 |
class types |
USAGE OBJECT REFERENCE class-name |
|
|
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.
| 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 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.
| 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.
| 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 |