invoke()

  javaLib.invoke(
    identifierOrClass javaObjIdOrClass in,
    method STRING in
    {, argument anyEglPrimitive in})
  returns (result anyJavaPrimitive)

identifierOrClass

Any of the following entities can serve as this argument:

• A Java™ objID, to call a method on an object in the Java™ object space.
• A string, to call a method on a class (a static method). 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 case-sensitive name of the method to invoke.

Input can be any variable or expression that is assignment compatible with the STRING type. Single- and double-byte blanks are stripped from the beginning and end of the string.

argument

A value passed to the method.

The Java™ type-conversion rules are in effect. A cast might be required; see "Mapping EGL primitives to Java™." 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 can result in a rounding error.

A value of an EGL external type is valid, as shown here:

SharedResourcePowerServer srps = JavaLib.getSharedResourcePowerServer();
JavaLib.invoke("anObject" as "objID:java", "aMethod", srps);

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

result

The result field, if present, receives a value from the local Java™ method.

If the local 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 can be stored in a result field that is declared with no decimal digits. For details on handling overflow, see "handleOverflow" and "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 local 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

If the v60ExceptionCompatibility program property is not set or set to NO, an exception causes EGL to throw a JavaObjectException. Other errors cause EGL to throw a RuntimeException.

If the v60ExceptionCompatibility program property is set to YES, an error during processing of javaLib.invoke() can set sysVar.errorCode to a value listed in the next table.