EGL Reference Guide for iSeries

Java access functions

The Java access functions are EGL system functions that allow your generated Java code to access native Java objects and classes; specifically, to access the public methods, constructors, and fields of the native code.

This EGL feature is made possible at run time by the presence of the EGL Java namespace, which is a set of names and the objects to which those names refer. A single namespace is available to your generated program and to all generated Java code that your program calls locally, whether the calls are direct or by way of another local generated Java program, to any level of call. The namespace is not available in any native Java code.

To store and retrieve objects in the namespace, you invoke the Java access functions. Your invocations include use of identifiers, each of which is a string that is used to store an object or to match a name that already exists in the namespace. When an identifier matches a name, your code can access the object associated with the name.

Note:
EGL code that includes a Java access function cannot be generated as a COBOL program.


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

Java access (system words)

This page includes the following sections:

Before reviewing this page, see Java access functions.

List of functions

The Java access functions are listed in the next table.


Function Description
sysLib.java Invokes a method on a Java object or class and may return a value
sysLib.javaGetField Returns the value of a specified field of a specified object or class
sysLib.javaIsNull Returns a value (1 for true, 0 for false) to indicate whether a specified identifier refers to a null object
sysLib.javaIsObjID Returns a value (1 for true, 0 for false) to indicate whether a specified identifier is in the namespace
sysLib.javaRemove Removes the specified identifier from the namespace and, if no other identifiers refer to the object, removes the object
sysLib.javaRemoveAll Removes all identifiers and objects from the namespace
sysLib.javaSetField Sets the value of a field in a Java object or class
sysLib.javaStore Invokes a method and places the returned object (or null) into the namespace, along with a specified identifier
sysLib.javaStoreCopy Creates a new identifier based on another in the namespace, so that both refer to the same object
sysLib.javaStoreField Places the value of a class field or object field into the namespace
sysLib.javaStoreNew Invokes the constructor of a class and places the new object into the namespace
sysLib.javaType Returns the fully qualified name of the class of an object in the namespace

Mappings of EGL and Java types

Each of the arguments you pass to a method (and each value that you assign to a field) is mapped to a Java object or primitive type. Items of EGL primitive type CHAR, for example, are passed as objects of the Java String class. A cast operator is provided for situations in which the mapping of EGL types to Java types is not sufficient.

When you specify a Java name, EGL strips single- and double-byte blanks from the beginning and end of the value, which is case sensitive. The truncation precedes any cast. This rule applies to string literals and to items of type CHAR, DBCHAR, MBCHAR, or UNICODE. No such truncation occurs when you specify either a method argument or field value (for example, the string " my data " is passed to a method as is), unless you cast the value to objID or null.

The next table describes all the valid mappings.


Category of Argument Examples Java Type
A string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE No cast
"myString"
String
Cast with objId, which indicates an identifier
(objId)"myId"
 
x = "myId";
(objId)X
The class of the object to which the identifier refers

Cast with null, as may be appropriate to provide a null reference to a fully qualified class
(null)"java.
lang.thread"
 
x = "java.util.
HashMap";
(null)x
The specified class
Note:
You can't pass in a null-casted array such as (null)"int[]"

Cast with char, which means that the first character of the value is passed (each example in the next column passes an "a")
(char)"abc"
 
X = "abc";
(char)X
char
An item of type HEX
myHexValue
byte array
Numeric item or literal not containg decimals, with leading zeros included in the number of digits for a literal No cast, 1-4 digits
0100
short
No cast, 5-9 digits
00100
int
No cast, > 9 digits
1234567890
long
Numeric item or literal containing decimals, with leading and trailing zeros included in the number of digits for a literal No cast, 1-6 digits
3.14159
float
No cast, >6 digits
3.14159265
double
Numeric item or literal, with or without decimals Cast with byte, short, int, long, float, or double
X = 42;
 
(byte)X
 
(long)X
The specified primitive type; but if the value is out of range for that type, loss of precision occurs and the sign may change

Cast with boolean, which means that non-zero is true, zero is false
X = 1;
(boolean)X
boolean

Note:
When EGL passes a float or double to Java, rounding may occur because of the way that Java approximates a real number.

For details on the internal format of items in EGL, see the help pages on Primitive types.

Examples

This section gives examples on how to use Java access functions.

Printing a date string

The following example prints a date string:

  // call the constructor of the Java Date class and
  // assign the new object to the identifier "date".
  sysLib.javaStoreNew( (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.
  charItem = sysLib.java( (objId)"date", "toString" );
 
  // assign the standard output stream of the 
  // Java System class to the identifier "systemOut".
  sysLib.javaStoreField( (objId)"systemOut", 
    "java.lang.System", "out" );
 
  // call the println method of the output 
  // stream and print today's date.
  sysLib.java( (objID)"systemOut","println",charItem );
 
  // 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 namespace or a class
  // name. The argument cannot refer to a static field.

Testing a system property

The following example retrieves a system property and tests for the absence of a value:

  // assign the name of an identifier to an item of type CHAR
  valueID = "osNameProperty"
 
  // place the value of property os.name into the 
  // namespace, and relate that value (a Java String) 
  // to the identifier osNameProperty
  sysLib.javaStore((objId)valueId, "java.lang.System",
    "getProperty", "os.name");
 
  // test whether the property value is non-existent
  // and process accordingly
  myNullFlag = sysLib.javaIsNull( (objId)valueId );
 
  if( myNullFlag = 1 )
    error = 27;
  end 

Working with arrays

When you work with Java arrays in EGL, use the Java class java.lang.reflect.Array, as shown in later examples and as described in the Java API documentation. You cannot use sysLib.javaStoreNew to create a Java array because Java arrays have no constructors.

You use the static method newInstance of java.lang.reflect.Array to create the array in the namespace. After you create the array, you use other methods in that class to access the elements.

The method newInstance expects two arguments:

The code that identifies the Class object varies according to whether you are creating an array of objects or an array of primitives. The subsequent code that interacts with the array also varies on the same basis.

Working with an array of objects  The following example shows how to create a 5-element object array that is accessible by use of the identifier "myArray":

  // Get a reference to the class, for use with newInstance
  sysLib.javaStore( (objId)"objectClass", "java.lang.Class",
    "forName", "java.lang.Object" );
 
  // Create the array in the namespace
  sysLib.javaStore( (objId)"myArray", "java.lang.reflect.Array",
    "newInstance", (objId)"objectClass", 5 );

If you want to create an array that holds a different type of object, change the class name that is passed to the first invocation of sysLib.javaStore. To create an array of String objects, for example, pass "java.lang.String" instead of "java.lang.Object".

To access an element of an object array, use the get and set methods of java.lang.reflect.Array. In the following example, i and length are numeric items:

  length = sysLib.java( "java.lang.reflect.Array", 
    "getLength", (objId)"myArray" );
  i = 0; 
 
  while ( i < length ) 
    sysLib.javaStore( (objId)"element", "java.lang.reflect.Array",
      "get", (objId)"myArray", i );
 
    // Here, process the element as appropriate
    sysLib.java( "java.lang.reflect.Array", "set", 
      (objId)"myArray", i, (objId)"element" ); 
    i = i + 1; 
  end 

The previous example is equivalent to the following Java code:

  int length = myArray.length; 
 
  for ( int i = 0; i < length; i++ ) 
  { 
    Object element = myArray[i]; 
 
    // Here, process the element as appropriate
 
    myArray[i] = element; 
  } 

Working with an array of Java primitives  To create an array that stores a Java primitive rather than an object, use a different mechanism in the steps that precede the use of java.lang.reflect.Array. In particular, obtain the Class argument to newInstance by accessing the static field TYPE of a primitive type class.

The following example creates myArray2, which is a 30-element array of integers:

  // Get a reference to the class, for use with newInstance
  sysLib.javaStoreField( (objId)"intClass", 
    "java.lang.Integer", "TYPE");
 
  // Create the array in the namespace
  sysLib.javaStore( (objId)"myArray2", "java.lang.reflect.Array",
    "newInstance", (objId)"intClass", 30 ); 

If you want to create an array that holds a different type of primitive, change the Class name that is passed to the invocation of sysLib.javaStoreField. To create an array of characters, for example, pass "java.lang.Character" instead of "java.lang.Integer".

To access an element of an array of primitives, use the java.lang.reflect.Array methods that are specific to a primitive type. Such methods include getInt, setInt, getFloat, setFloat, and so forth. In the following example, length, element, and i are numeric items:

  length = sysLib.java( "java.lang.reflect.Array", 
    "getLength", (objId)"myArray2" ); 
  i = 0; 
 
  while ( i < length )
    element = sysLib.java( "java.lang.reflect.Array", 
      "getDouble", (objId)"myArray2", i ); 
 
    // Here, process an element as appropriate
 
    sysLib.java( "java.lang.reflect.Array", "setDouble",
      (objId)"myArray2", i, element );
    i = i + 1; 
  end

The previous example is equivalent to the following Java code:

  int length = myArray2.length;
 
  for ( int i = 0; i < length; i++ )
  { 
    double element = myArray2[i];
 
    // Here, process an element as appropriate
 
    myArray2[i] = element;
  } 

Working with collections

To iterate over a collection that is referenced by a variable called list, a Java program does as follows:

  Iterator contents = list.iterator(); 
 
  while( contents.hasNext() ) 
  { 
    Object myObject = contents.next();
    // Process myObject
  }

Assume that hasNext is a numeric data and that your program related a collection to an identifier called list. The following EGL code is then equivalent to the Java code described earlier:

  sysLib.javaStore( (objId)"contents", (objId)"list", "iterator" );
  hasNext = sysLib.java( (objId)"contents", "hasNext" ); 
 
  while ( hasNext = 1 ) 
    sysLib.javaStore( (objId)"myObject", (objId)"contents", "next");
 
    // Process myObject
    hasNext = sysLib.java( (objId)"contents", "hasNext" );
  end

Converting an array to a collection

To create a collection from an array of objects, use the asList method of java.util.Arrays, as shown in the following example:

  // Create a collection from array myArray 
  // and relate that collection to the identifier "list 
  sysLib.javaStore( (objId)"list", "java.util.Arrays",
    "asList", (objId)"myArray" );

Next, iterate over list, as shown in the preceding section.

The transfer of an array to a collection works only with an array of objects, not with an array of Java primitives. Be careful not to confuse java.util.Arrays with java.lang.reflect.Array.

Error handling

Many of the Java access functions are associated with error codes, as described in the function-specific help pages. If the value of the system variable sysVar.handleSysLibErrors is 1 when one of the listed errors occurs, EGL sets the system variable sysVar.errorCode to a non-zero value. If the value of sysVar.handleSysLibErrors is 0 when one of the errors occurs, the program ends.

Of particular interest is the sysVar.errorCode value "00001000", which indicates that an exception was thrown by an invoked method or as a result of a class initialization.

When an exception is thrown, EGL stores it in the namespace. If another exception occurs, the second exception takes the place of the first. You can use the identifier caughtException to access the last exception that occurred.

In an unusual situation, an invoked method throws not an exception but an error such as OutOfMemoryError or StackOverflowError. In such a case, the program ends regardless of the value of system variable sysVar.handleSysLibErrors.

The following Java code shows how a Java program can have multiple catch blocks to handle different kinds of exceptions. This code tries to create a FileOutputStream object. A failure causes the code to set an errorType variable and to store the exception that was thrown.

  int errorType = 0;
  Exception ex = null;
 
  try
  {
    java.io.FileOutputStream fOut = 
      new java.io.FileOutputStream( "out.txt" );
  }
  catch ( java.io.IOException iox )
  {
    errorType = 1;
    ex = iox;
  }
  catch ( java.lang.SecurityException sx )
  {
    errorType = 2;
    ex = sx;
  } 

The following EGL code is equivalent to the previous Java code:

  handleSysLibErrors = 1;
  errorType = 0;
 
  sysLib.javaStoreNew( (objId)"fOut",
    "java.io.FileOutputStream", "out.txt" );
 
  if ( sysVar.errorCode = "00001000" )
    exType = sysLib.javaType( (objId)"caughtException" );
 
    if ( exType = "java.io.IOException" )
      errorType = 1;
      sysLib.javaStoreCopy( (objId)"caughtException", (objId)"ex" );
    else
      if ( exType = "java.lang.SecurityException" )
        errorType = 2;
        sysLib.javaStoreCopy( (objId)"caughtException", (objId)"ex" );
      end
    end
  end


Related concepts
Java access functions


Related reference
Exception handling
Primitive types
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.java

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



sysLib.Java syntax diagram

returnItem
The return item, if present, receives a value from the native Java method.

If the native Java method returns a value, the return item is optional.

The following cases apply:

identifierOrClass

This argument is one of the following entities:

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, 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 item of type CHAR, DBCHAR, MBCHAR, 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.

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".
  sysLib.JavaStoreNew( (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 = sysLib.Java( (objId)"date", "toString" );
 
  // assign the standard output stream of the 
  // Java System class to the identifier "systemOut".
  sysLib.JavaStoreField( (objId)"systemOut", "java.lang.System", "out" );
 
  // call the println method of the output 
  // stream and print today's date.
  sysLib.Java( (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 namespace or a class
  // name. The argument cannot refer to a static field.

An error during processing of sysLib.java 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 namespace
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 item
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
Java access functions


Related tasks
Syntax diagram


Related reference
Assignments
BIN and the integer types
Exception handling
Java access (system words)
Primitive types
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType
sysVar.handleOverflow
sysVar.overflowIndicator

sysLib.javaGetField

The system function sysLib.javaGetField returns the value of a specified field of a specified object or class. sysLib.javaGetField is one of several Java access functions.



sysLib.javaGetField syntax diagram

returnItem
The return item is required and receives the value of the field specified in the second argument. The following cases apply:
identifierOrClass

This argument is one of the following entities:

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. If you are specifying an identifier of an object, the identifier must be cast to objID, as in a later example. If you intend to specify a static field in the next argument, it is recommended that you specify a class in this argument.

EGL strips single- and double-byte blanks from the beginning and end of the argument value, which is case sensitive.

field
The name of the field to read.

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

An example is as follows:

  myItem = sysLib.javaGetField( (objId)"myID", "myField" );

An error during processing of sysLib.javaGetField 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 namespace
00001002 A public method, field, or class with the specified name does not exist or cannot be loaded
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 item
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
Java access functions


Related tasks
Syntax diagram


Related reference
Assignments
BIN and the integer types
Exception handling
Java access (system words)
sysLib.java
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaIsNull

The system function sysLib.javaIsNull returns a value (1 for true, 0 for false) to indicate whether a specified identifier refers to a null object. sysLib.javaIsNull is one of several Java access functions.



sysLib.javaIsNull syntax diagram

returnItem
A numeric item that receives one of two values: 1 for true, 0 for false. Use of a non-numeric item causes an error at validation time.
identifier

An identifier that refers to an object in the namespace.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. The identifier must be cast to objID. EGL strips single- and double-byte blanks from the beginning and end of the argument value, which is case sensitive.

An example is as follows:

  // test whether an object is null
  // and process accordingly
  isNull = sysLib.javaIsNull( (objId)valueId );
 
  if( isNull = 1 )
    error = 12;
  end 

An error during processing of sysLib.javaIsNull can set sysVar.errorCode to a value listed in the next table.


Value in sysVar.errorCode Description
00001001 The specified identifier was not in the namespace


Related concepts
Java access functions


Related tasks
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaIsObjID

The system function sysLib.javaIsObjID returns a value (1 for true, 0 for false) to indicate whether a specified identifier is in the namespace. sysLib.javaIsObjID is one of several Java access functions.



sysLib.javaIsObjID syntax diagram

returnItem
A numeric item that receives one of two values: 1 for true, 0 for false. Use of a non-numeric item causes an error at validation time.
identifier

An identifier that refers to an object in the namespace.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. The identifier must be cast to objID. EGL strips single- and double-byte blanks from the beginning and end of the argument value, which is case sensitive.

An example is as follows:

  // test whether an object is non-existent
  // and process accordingly
  isPresent = sysLib.javaIsObjID( (objId)valueId );
 
  if( isPresent = 0 )
    error = 27;
  end 

No run-time errors are associated with sysLib.javaIsObjID.


Related concepts
Java access functions


Related tasks
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaRemove

The system function sysLib.javaRemove removes the specified identifier from the EGL Java namespace. The object related to the identifier is also removed, but only if the identifier is the only one that refers to the object. If another identifier refers to the object, the object remains in the namespace and is accessible by way of that other identifier.

sysLib.javaRemove is one of several Java access functions.



sysLib.javaRemove syntax diagram

identifier
The identifier that refers to an object. No error occurs if the identifier is not found.

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

An example is as follows:

  sysLib.javaRemove( (objId)myStoredObject );

No run-time errors are associated with sysLib.javaRemove.

Note:
By invoking the system functions sysLib.javaRemove and sysLib.javaRemoveAll, your code allows the Java Virtual Machine to handle garbage collection in the EGL Java namespace. If you do not invoke an system function to remove an object from the namespace, the memory is not recovered during the run time of any program that has access to the namespace.


Related concepts
Java access functions


Related tasks
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaRemoveAll

The system function sysLib.javaRemoveAll removes all identifiers and objects from the EGL Java namespace. sysLib.javaRemoveAll is one of several Java access functions.



sysLib.javaRemoveAll syntax diagram

No run-time errors are associated with sysLib.javaRemoveAll.

Note:
By invoking the system functions sysLib.javaRemove and sysLib.javaRemoveAll, your code allows the Java Virtual Machine to handle garbage collection in the EGL Java namespace. If you do not invoke a system function to remove an object from the namespace, the memory is not recovered during the run time of any program that has access to the namespace.


Related concepts
Java access functions


Related tasks
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaSetField

The system function sysLib.javaSetField sets the value of a field in a native Java object or class. sysLib.javaSetField is one of several Java access functions.



sysLib.javaSetField syntax diagram

identifierOrClass

This argument is one of the following entities:

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, 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.

field
The name of the field to change.

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

value
The value itself.

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 assign a short to a field that is declared as an int.

An example is as follows:

  sysLib.javaSetField( (objID)"myId", "myField", 
    (short)myNumItem );

An error during processing of sysLib.javaSetField 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 namespace
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
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
Java access functions
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaStore

The system function sysLib.javaStore invokes a method and places the returned object (or null) into the EGL Java namespace, along with a specified identifier. If the identifier is already in the namespace, the action is equivalent to the following steps:

If the method returns a Java primitive instead of an object, EGL stores an object that represents the primitive; for example, if the method returns an int, EGL stores an object of type java.lang.Integer.

sysLib.javaStore is one of several Java access functions.



sysLib.javaStore syntax diagram

storeId
The identifier to store with the returned object.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. 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.

identifierOrClass

This argument is one of the following entities:

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, 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.

method
The method to invoke.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, 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.

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.

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

An example is as follows:

  sysLib.javaStore( (objId)"storeId", (objId)"myId", 
    "myMethod", 36 );

An error during processing of sysLib.javaStore 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 namespace
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
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
Java access functions


Related tasks
Java access (system words)


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaStoreCopy

The system function sysLib.javaStoreCopy creates a new identifier based on another in the namespace, so that both refer to the same object. If the source identifier is not in the namespace, a null is stored for the target identifier and no error occurs. If the target identifier is already in the namespace, the action is equivalent to the following steps:

sysLib.javaStoreCopy is one of several Java access functions.



sysLib.javaStoreCopy syntax diagram

sourceId
An identifier that refers to an object in the namespace or to null.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. 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.

targetId
The new identifier, which refers to the same object.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. 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.

An example is as follows:

  sysLib.javaStoreCopy( (objId)"sourceId", (objId)"targetId" );

No run-time errors are associated with sysLib.javaStoreCopy.


Related concepts
Java access functions
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaStoreField

The system function sysLib.javaStoreField places the value of a class field or object field into the EGL Java namespace. If the identifier used to store the object is already in the namespace, the action is equivalent to the following steps:

If the class or object field contains a Java primitive instead of an object, EGL stores an object that represents the primitive; for example, if the field contains an int, EGL stores an object of type java.lang.Integer.



sysLib.javaStoreField syntax diagram

storeId
The identifier to store with the object.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. 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.

identifierOrClass

This argument is one of the following entities:

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. If you are specifying an identifier of an object, the identifier must be cast to objID, as in a later example. If you intend to specify a static field in the next argument, it is recommended that you specify a class in this argument.

EGL strips single- and double-byte blanks from the beginning and end of the argument value, which is case sensitive.

field
The name of the field that refers to an object.

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

An example is as follows:

  sysLib.javaStoreField( (objId)"myStoreId", 
    (objId)"myId", "myField");

An error during processing of sysLib.javaStoreField 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 namespace
00001002 A public method, field, or class with the specified name does not exist or cannot 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
Java access functions


Related tasks
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreNew
sysLib.javaType

sysLib.javaStoreNew

The system function sysLib.javaStoreNew invokes the constructor of a class and places the new object into the EGL Java namespace. If the identifier is already in the namespace, the action is equivalent to the following steps:

sysLib.javaStoreNew is one of several Java access functions.



sysLib.javaRemove syntax diagram

storeId
The identifier to store with the new object.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. 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.

class

The fully qualified name of a Java class.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. EGL strips single- and double-byte blanks from the beginning and end of the argument value, which is case sensitive.

argument
A value passed to the constructor.

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 constructor parameter that is declared as an int.

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

An example is as follows:

  sysLib.javaStoreNew( (objId)"storeId", "myClass", 36 );

An error during processing of sysLib.javaStoreNew 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 namespace
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
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
00001008 The constructor cannot be called; the class name refers to an interface or abstract class


Related concepts
Java access functions


Related tasks
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaType

sysLib.javaType

The system function sysLib.javaType returns the fully qualified name of the class of an object in the EGL Java namespace. sysLib.javaType is one of several Java access functions.



sysLib.javaType syntax diagram

returnItem
The return item is required and must be of type CHAR, DBCHAR, MBCHAR, or UNICODE--

For details on mismatched lengths, see Assignments.

identifier
An identifier that refers to an object in the namespace.

This argument is either a string literal or an item of type CHAR, DBCHAR, MBCHAR, or UNICODE. 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.

An example is as follows:

  myItem = sysLib.javaType( (objId)"myId" );

An error during processing of sysLib.javaType can set sysVar.errorCode to a value listed in the next table.


Value in sysVar.errorCode Description
00001001 The object was null, or the specified identifier was not in the namespace


Related concepts
Java access functions


Related tasks
Syntax diagram


Related reference
Java access (system words)
sysLib.java
sysLib.javaGetField
sysLib.javaIsNull
sysLib.javaIsObjID
sysLib.javaRemove
sysLib.javaRemoveAll
sysLib.javaSetField
sysLib.javaStore
sysLib.javaStoreCopy
sysLib.javaStoreField
sysLib.javaStoreNew
sysLib.javaType


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]