invoke()

The system function JavaLib.invoke invokes a method on a native Java™ object or class and may return a value. JavaLib.invoke is one of several Java access functions.

  JavaLib.invoke(
    identifierOrClass javaObjIdOrClass in,
    method STRING in
    {, argument anyEglPrimitive in})
  returns (result anyJavaPrimitive)
result
The result field, if present, receives a value from the native Java method.

If the native Java method returns a value, the result field is optional.

The following cases apply:

  • If the returned value is a BigDecimal, BigInteger, byte, short, int, long, float, or double, the result field must be a numeric data type. The characteristics do not need to match the value; for example, a float may be stored in a result field that is declared with no decimal digits. For details on handling overflow, see VGVar.handleOverflow and SysVar.overflowIndicator.
  • If the returned value is a boolean, the result field must be of a numeric primitive type. The value is 1 for true, 0 for false.
  • If the returned value is a byte array, the result field must be of type HEX. For details on mismatched lengths, see Assignments.
  • If the returned value is a String or char, the result field must be of type CHAR, DBCHAR, MBCHAR, STRING, or UNICODE--
    • If the result field is of type MBCHAR, STRING, or UNICODE, the returned value is always appropriate
    • If the result field is of type CHAR, problems can arise if the returned value includes characters that correspond to DBCHAR characters
    • If the result field is of type DBCHAR, problems can arise if the returned value includes Unicode characters that correspond to single-byte characters

    For details on mismatched lengths, see Assignments.

  • If the native Java method does not return a value or returns a null, the following cases apply:
    • No error occurs in the absence of a result field
    • An error occurs at run time if a result field is present; the error is 00001004, as listed later
identifierOrClass
This argument is one of the following entities:
  • An identifier that refers to an object in the object space; or
  • The fully qualified name of a Java class.

This argument is either a string literal or an variable of type CHAR, DBCHAR, MBCHAR, STRING, or UNICODE. If you are specifying an identifier of an object, the identifier must be cast to objID, as in a later example. EGL strips single- and double-byte blanks from the beginning and end of the argument value, which is case sensitive.

Your code cannot invoke a method on an object until you have created an identifier for the object. A later example illustrates this point with java.lang.System.out, which refers to a PrintStream object.

method
The name of the method to call.

This argument is either a string literal or an variable of type CHAR, DBCHAR, MBCHAR, STRING, or UNICODE. Single- and double-byte blanks are stripped from the beginning and end of the string, which is case sensitive.

argument
A value passed to the method.

A cast may be required, as specified in Java access (system words).

The Java type-conversion rules are in effect. No error occurs, for example, if you pass a short to a method parameter that is declared as an int.

To avoid losing precision, use an EGL float variable for a Java double, and an EGL smallfloat variable for a Java float. Using one of the other EGL types will probably result in a value being rounded.

The memory area in the invoking program does not change regardless of what the method does.

In the following example, the cast (objId) is required except as noted:
  // call the constructor of the Java Date class and
  // assign the new object to the identifier "date".
  JavaLib.storeNew( (objId)"date", "java.util.Date");

  // call the toString method of the new Date object
  // and assign the output (today's date) to the chaItem.
  // In the absence of the cast (objId), "date" 
  // refers to a class rather than an object.
  chaItem = JavaLib.invoke( (objId)"date", "toString" );

  // assign the standard output stream of the 
  // Java System class to the identifier "systemOut".
  JavaLib.storeField( (objId)"systemOut", "java.lang.System", "out" );

  // call the println method of the output 
  // stream and print today's date.
  JavaLib.invoke( (objID)"systemOut", "println", chaItem );

  // The use of "java.lang.System.out" as the first 
  // argument in the previous line would not have been
  // valid, as the argument must either be a 
  // an identifier already in the object space or a class
  // name. The argument cannot refer to a static field.

An error during processing of JavaLib.invoke can set SysVar.errorCode to a value listed in the next table.

Value in SysVar.errorCode Description
00001000 An exception was thrown by an invoked method or as a result of a class initialization
00001001 The object was null, or the specified identifier was not in the object space
00001002 A public method, field, or class with the specified name does not exist or cannot be loaded
00001003 The EGL primitive type does not match the type expected in Java
00001004 The method returned null, the method does not return a value, or the value of a field was null
00001005 The returned value does not match the type of the return variable
00001006 The class of an argument cast to null could not be loaded
00001007 A SecurityException or IllegalAccessException was thrown during an attempt to get information about a method or field; or an attempt was made to set the value of a field that was declared final
00001009 An identifier rather than a class name must be specified; the method or field is not static

Related concepts

Related tasks
Syntax diagram for EGL statements and commands

Related reference
Assignments
BIN and the integer types
EGL library JavaLib
Exception handling

getField()
isNull()
isObjID()
qualifiedTypeName()
remove()
removeAll()
setField()
store()
storeCopy()
storeField()
storeNew()
Primitive types
overflowIndicator
handleOverflow

Feedback
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.