®
IBM Software Group
© 2006 IBM Corporation
EGL Calling Java
This Learning Module shows how to use EGL to call Java classes, methods and
access class variables.
2
EGL externalType Part
 An externalType part provides the EGL mapping to a Java Class. This is similar to the mapping that an EGL Interface provides for Web Service functions, but extends to map Java class
variables and constructors.
 Invoking ExternalType functions

If the class or function is marked static,

Simply invoke it using the name of its
externalType
externalType part and use dot syntax to reference the methods
typeName
typeName
.
.
methodName();
methodName();
 If the class or function is non-static (more typical)

Create a variable based on its
externalType
externalType part – initialize it with a
new
new keyword


Use it in much the same way you would a library name (use dot syntax for the methods)
externalTypeVariable.methodName();
externalTypeVariable.methodName();


externalType Declaration
externalType Declaration


Two class variables
Two class variables


One custom method
One custom method


class “constructor method”
class “constructor method”


Variable of externalType(TaxModule)
Variable of externalType(TaxModule)


Create new (non-static) instance
Create new (non-static) instance


Initialize class variable values

Initialize class variable values


Call calculateTax routine
Call calculateTax routine
3
EGL Calling Java Calling EGL – 1 of 2

The following types of transfer of control are possible in EGL:
1. EGL-generated Java™ program to EGL-generated Java program
2. Non-EGL (native or hand-coded) Java program to EGL program
3. EGL-generated Java program to non-EGL Java program
4. EGL-generated Java program to DLL
5. EGL-generated Java program to .EXE or .BAT file
1. EGL-generated Java
program
program to EGL-generated Java program

Calling one EGL-generated program from another is as simple as invoking the Java class for the target
program using a call statement. Be aware, however, of package dependencies. You must invoke a class
that is one of the following:

Within the same package as the calling program.

Qualified with a package name using dot syntax.

Identified with a linkage option part.
2. Non-EGL Java program to EGL program

To invoke an EGL-generated program from a non-EGL Java program, you must do one of the following:


Define the EGL program as a service – as we’ve seen in a prior unit.

Create Java wrapper classes for the EGL program. See workshop, further back in this section.
3. EGL-generated Java program to non-EGL Java program

To invoke non-EGL Java code from Java code generated by EGL, you must create an EGL ExternalType
– and a variable for the ExternalType. This EGL part contains function descriptions for the Java methods
you wish to call. ExternalTypes are considered a Best Practice.

Invoke the Java method as follows:

Create a variable based on the ExternalType part and use it in much the same way you would a library, appending the
ExternalType part variable name to the name of the method using dot syntax:
–
ExternalTypeVar.method();
ExternalTypeVar.method();
4
EGL Calling Java Calling EGL – 2 of 2

EGL-generated Java program to .DLL

You can call functions in a single, non-EGL dynamic link library (DLL) (written in, for
example, C or COBOL) from an EGL Java program. The file extension for the DLL depends
on your environment (examples include .dll, .so, and .sl).

You create a Library part of type nativeLibrary to act as an interface between your EGL
program and the DLL. The Library part lists function names and parameters, and can use
the alias property of the functions where function names do not match EGL conventions.


Access the functions by using dot syntax (library.function()) or by creating a use
declaration for the library to make its functions global to your program.

EGL-generated Java program to .EXE or .BAT file

EGL provides two functions that allow you to call a system command (such as a .bat or a
.exe executable file). These were covered as optional exercises in a previous section:

sysLib.callCmd();
–
This function transfers control to a specified executable; when the executable terminates, control returns to the
calling EGL program.

sysLib.startCmd();
–
This function transfers control to a specified executable, then keeps running; both the EGL program and the
executable run at the same time.

Related concepts – See product help

Transfer of control across programs

Linkage options part

Related tasks – See product help

Generating EGL and Web services

Generating Java wrappers
5

EGL externalType for the HelloEGLworld Class
 The externalType we will use to interface with the HelloEGLworld Java class


EGL variable declaration for the externalType. Notes:
EGL variable declaration for the externalType. Notes:
- Creates a
- Creates a
new
new
instance of the Java class (in memory)
instance of the Java class (in memory)
- Passes two values into the class variables
- Passes two values into the class variables
6
Workshop – Create a Java Class and Call it From an EGL Program

To see how all this works together, you will complete a workshop as follows (from 10,000 feet)

You will:

Create a new Java Class

Create a new EGL program that contains:

An EGL externalType of the Java Class

Calls to the Java functions – through the externalType

Access of the Java class variables - through the externalType


After finishing that, we’ll do two additional things:

Learn how to call Java API’s through the EGL JavaLib (built-in system) functions

Pass string arrays back and forth between EGL and Java

Important Note:
Important Note: Java is a case-sensitive language (okay we said that already). As such, be careful naming your classes and all the other files you
create in this workshop, as the copy/paste code will pre-determine your part names.
7
Create a new Java Package and Class

From Project Explorer:
From Project Explorer:

Right-click over \Java Resources: src\ and
create a
package
package named:
egljava
egljava

Right-click over
Right-click over
egljava
egljava and create a new
Java class named:
HelloEGLworld
HelloEGLworld

 Using the copy/paste code in the Notes, create
your first Java class…
Press Ctrl/S
Press Ctrl/S – to save
and compile your .java
source to a .class file
8

 Workshop continued – Create a new EGL Program
 From Project Explorer, right-click over the
\EGLSource\programs\
\EGLSource\programs\ directory, and
create a new, EGL
program
program

Name the program:
callJava
callJava
 From within the code, copy/delete and replace the boilerplate code, with the complete program
solution shown below, in the
Notes
Notes area of this slide
Top section of callJava program
Functions
externalType Definition
With your mouse cursor
inside the source,
press:
•


Ctrl/S
Ctrl/S (why)?
•

Ctrl/G
Ctrl/G (why)?
9

 Workshop continued – Debug the EGL Program and Java Calls

Add a Breakpoint to the
callJava.egl
callJava.egl

program

From Project Explorer, right-click over the \EGLSource\programs\callJava.egl select
Debug EGL Program…
Debug EGL Program…
Step through the code
 Note the variable
values before and
after the calls
to the Java Class!
10
Additional Info on External Types

When creating external types, you may
run into a Java

”final”
”final” type variable
within the Java class you’re calling.

If you need to access this variable from
EGL, it will need to be defined in your
externalType.

The syntax is the same as with any
other variable. Note, you do not need to
include a “final” indicator.

Additionally, a cross-language conflict
can occur when creating external types
that have conflicting method/variable
names.

i.e. If the name of a Java method is the
same as an EGL reserved word, your
externalType will not compile.

To fix this you must add the “JavaName”
property to the function declaration.
Invalid
Valid
11
Topic

EGL Calls to Remote Programs (Overview)


Java (terms and concepts)

Calling Java using the externalType Part


Calling Java using
Calling Java using
JavaLib
JavaLib

Calling COBOL Programs

Calling RPG Programs
Sub-Topics:
EGL and Remote Programs
EGL and Remote Programs
12
EGL’s JavaLib Built-in System Function

If you are not calling a custom Java Class, but only calling a
static Java API
static Java API (think of these as
Java library “built-in-functions”) – you can dispense with having to define a new externalType,
and call the API using the
JavaLib
JavaLib Built-in Function.
Here are the JavaLib
function calls
We are interested in:


invoke()
invoke()

store()
store()
***Notes
***Notes
13
EGL’s JavaLib invoke() and store() Functions
 With JavaLib you can:

invoke() – call a static Java API (i.e. call a class that does NOT need to be created as a new instance)

Format:
JavaLib.invoke(“package.class”,”method”,<Optional parameter>);
JavaLib.invoke(“package.class”,”method”,<Optional parameter>);

store() – call a non-Static Java API and return an Object (instead of a Java primitive)

Format:
JavaLib.store(“objVariable”
JavaLib.store(“objVariable”
as "objID:java", “package.class", “method“);
as "objID:java", “package.class", “method“);
Notes on store()
 You tell Java to create a new Class instance (i.e. an object) and store it, in a temporary variable identified as the first parameter to
store()
store()
 You add the boilerplate: as "objID:java",


You specify which package.sub-package.class, etc.

And the method that returns the Java object into the temporary variable
14

 Workshop - EGL’s JavaLib invoke() and store() Functions
 From Project Explorer, edit the \EGLSource\programs\callJava.egl

Towards the end of the program (as shown here in the screen capture) insert the following two functions (found in the Notes
section of this slide)
 Un-comment the calls to these functions in the
main()
main() function
With your mouse cursor
inside the source,
press:
•

Ctrl/S
Ctrl/S
•

Ctrl/G
Ctrl/G
15

 Workshop continued – Debug the EGL Program and Java Calls

From Project Explorer, right-click over the \EGLSource\programs\callJava.egl
select Debug EGL Program and once again, step through the code

16

 OPTIONAL Workshop – Passing a String Array Between Java and EGL

There are some situations in your projects where you may need to send an array of strings from EGL to Java. You would use an externalType to
do this (and – it’s pretty easy). Follow these steps to see how (easy )

From
\JavaResources :src\egljava\HelloEGLworld.java
\JavaResources :src\egljava\HelloEGLworld.java – add the following new method to the existing Java class (source code is in the Notes
section of the slides):

Press
Ctrl/S
Ctrl/S – and you will get syntax errors in the code. Add the following
import
import statement to the top of the file:
New
Method
17

 OPTIONAL Workshop – Passing a String Array – Modify the externalType

From
\Programs\callJava.egl
\Programs\callJava.egl – modify the EGL externalType definition we’ve been using.
Add a new function for the new Java Class method at the bottom of the externalType
Press:
Press:


Ctrl/S
Ctrl/S

Ctrl/G
Ctrl/G
18

 OPTIONAL Workshop – Passing a String Array – Create a new JSP Page

From
\WebContent\
\WebContent\ – As you’ve done before, create a new JSP page, named:
callJavaPage
callJavaPage
 For the page’s JSFHandler, add the following code (which you can copy from the Notes section below)
Notes:
Notes:

Import
Import statement
– provides reference-ability to the externalType definition
– provides reference-ability to the externalType definition

Two fixed-length string arrays
Two fixed-length string arrays
– one initialized with values (to be passed into the Java Class), one empty that will contain data returned from the Java Class call
– one initialized with values (to be passed into the Java Class), one empty that will contain data returned from the Java Class call

Variable for the externalType
Variable for the externalType

to the Java Class – used in the previous workshop
to the Java Class – used in the previous workshop