Rational Developer for System z
Enterprise PL/I for z/OS, Version 3.8, Programming Guide

Writing Java Sample Program #1

The first sample program is yet another variation of the "Hello World!" program.

The "Hello World!" program has one Java class, callingPLI.java. The native method, written in PL/I, is contained in hiFromPLI.pli. Here is a brief overview of the steps for creating this sample program:

  1. Write a Java program that defines a class containing a native method, loads the native load library, and calls the native method.
  2. Compile the Java program to create a Java class.
  3. Write a PL/I program that implements the native method and displays the "Hello!" text.
  4. Compile and link the PL/I program.
  5. Run the Java program which calls the native method in the PL/I program.

Step 1: Writing the Java Program

Declare the Native Method

All methods, whether Java methods or native methods, must be declared within a Java class. The only difference in the declaration of a Java method and a native method is the keyword native. The native keyword tells Java that the implementation of this method will be found in a native library that will be loaded during the execution of the program. The declaration of the native method looks like this:

public native void callToPLI();

In the above statement, the void means that there is no return value expected from this native method call. The empty parentheses in the method name callToPLI( ), means that there are no parameters being passed on the call to the native method.

Load the Native Library

A step that loads the native library must be included so the native library will be loaded at execution time. The Java statement that loads the native library looks like this:

 static {
   System.loadLibrary("hiFromPLI");
 }

In the above statement, the Java System method System.loadLibrary(...) is called to find and load the native library. The PL/I shared library, libhiFromPLI.so, will created during the step that compiles and links the PL/I program.

Write the Java Main Method

The callingPLI class also includes a main method to instantiate the class and call the native method. The main method instantiates callingPLI and calls the callToPLI() native method.

The complete definition of the callingPLI class, including all the points addressed above in this section, looks like this:

 public class callingPLI {
   public native void callToPLI();
   static {
      System.loadLibrary("hiFromPLI");
   }
   public static void main(String[] argv) {
      callingPLI callPLI = new callingPLI();
      callPLI.callToPLI();
      System.out.println("And Hello from Java, too!");
   }
 }

Step 2: Compiling the Java Program

Use the Java compiler to compile the callingPLI class into an executable form. The command would look like this:

javac callingPLI.java

Step 3: Writing the PL/I Program

The PL/I implementation of the native method looks much like any other PL/I subroutine.

Useful PL/I Compiler Options

The sample program contains a series of *PROCESS statements that define the important compiler options.

 *Process Limits( Extname( 100 ) ) Margins( 1, 100 ) ;
 *Process Display(Std) Dllinit Extrn(Short);
 *Process Rent Default( ASCII IEEE );

Here is a brief description of them and why they are useful:

Extname(100)
Allows for longer, Java style, external names.
Margins(1,100)
Extending the margins gives you more room for Java style names and identifiers.
Display(Std)
Writes the "Hello World" text to stdout, not via WTOs. In the z/OS UNIX environment WTOs would not be seen by the user.
Dllinit
Includes the initialization coded needed for creating a DLL.
Extrn(Short)
EXTRNs are emitted only for those constants that are referenced. This option is necessary for Enterprise PL/I V3R3 and later.
Default( ASCII IEEE );
ASCII specifies that CHARACTER and PICTURE data is held in ASCII - the form in which it is held by JAVA

IEEE specifies that FLOAT data is held in IEEE format - the form in which it is held by JAVA

RENT
The RENT option insures that code is reentrant even if it writes on static variables.
Correct Form of PL/I Procedure Name and Procedure Statement

The PL/I procedure name must conform to the Java naming convention in order to be located by the Java Class Loader at execution time. The Java naming scheme consists of three parts. The first part identifies the routine to the Java environment, the second part is the name of the Java class that defines the native method, and the third part is the name of the native method itself.

Here is a breakdown of PL/I procedure name Java_callingPLI_callToPLI in the sample program:

Java
All native methods resident in dynamic libraries must begin with Java
_callingPLI
The name of the Java class that declares the native method
_callToPLI
The name of the native method itself.
Note:
There is an important difference between coding a native method in PL/I and in C. The javah tool, which is shipped with the JDK, generates the form of the external references required for C programs. When you write your native methods in PL/I and follow the rules above for naming your PL/I external references, performing the javah step is not necessary for PL/I native methods.

In addition, the following options need to be specified in the OPTIONS option on the PROCEDURE statement:

The complete procedure statement for the sample program looks like this:

  Java_callingPLI_callToPLI:
  Proc( JNIEnv , MyJObject )
    External( "Java_callingPLI_callToPLI" )
    Options( FromAlien NoDescriptor ByValue );
JNI Include File

The two PL/I include files which contain the PL/I definitions of the Java Native interface are ibmzjni.inc which in turn includes ibmzjnim.inc. These include files are included with this statement:

   %include ibmzjni;

The ibmzjni and ibmzjnim include files are provided in the PL/I SIBMZSAM data set.

The Complete PL/I Procedure

For completeness, here is the entire PL/I program that defines the native method:

 *Process Limits( Extname( 100 ) ) Margins( 1, 100 ) ;
 *Process Display(Std) Dllinit Extrn(Short);
 *Process Rent Default( ASCII IEEE );
 PliJava_Demo: Package Exports(*);

  Java_callingPLI_callToPLI:
  Proc( JNIEnv , MyJObject )
    External( "Java_callingPLI_callToPLI" )
    Options( FromAlien NoDescriptor ByValue );

   %include ibmzjni;
   Dcl myJObject        Type jObject;

   Display('Hello from Enterprise PL/I!');

 End;

Step 4: Compiling and Linking the PL/I Program

Compiling the PL/I Program

Compile the PL/I sample program with the following command:

   pli -c hiFromPLI.pli
Linking the Shared Library

Link the resulting PL/I object deck into a shared library with this command:

   c89 -o libhiFromPLI.so hiFromPLI.o

Be sure to include the lib prefix on the name of the PL/I shared library or the Java class loader will not find it.


Terms of use | Feedback

This information center is powered by Eclipse technology. (http://www.eclipse.org)