Rational Developer for System z
COBOL for Windows, Version 7.5, 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.

Format
Read syntax diagramSkip visual syntax diagram>>-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:

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.

Method arguments are always passed as native data types. If you specify compiler option FLOAT(HEX) or compiler option BINARY(390), you must specify the NATIVE phrase in the description of method arguments that are affected by those compiler options.

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:

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

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:

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. The value returned from a method is always a native data type. If you specify compiler option FLOAT(HEX) or compiler option BINARY(390), you must specify the NATIVE phrase in the description of returning items that are affected by those compiler options.

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 COBOL for Windows Programming Guide for discussion of local and global object references as defined in Java. These attributes affect the life-time of object references.

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:

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:

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:

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 42. 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'. 
byte2 Single-byte alphanumeric, PIC X or PIC A
short3 USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE clause of the form S9(n), where 1 <= n <= 4
int3 USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE clause of the form S9(n), where 5 <= n <= 9
long3 USAGE BINARY, COMP, COMP-4, or COMP-5, with a PICTURE clause of the form S9(n), where 10 <= n <= 18
float3 USAGE COMP-1
double3 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. COBOL for Windows 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. Both the NATIVE character format and the EBCDIC character format are interoperable with the Java byte type.
  3. Only the NATIVE binary formats are interoperable with the Java short and int types.
  4. Only the NATIVE floating point formats are interoperable with the Java long, float, and double types.

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 43. 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 COBOL for Windows Programming Guide.

For details on repository entries for class definitions, see REPOSITORY paragraph. For examples, see the COBOL for Windows 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 44. COBOL miscellaneous argument types and corresponding Java types
COBOL argument Corresponding Java data type
Reference-modified item of usage display with length one (NATIVE or EBCDIC) 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 45. 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

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)