Teraspace storage model native methods for Java

The IBM® i Java™ virtual machine (JVM) supports the use of teraspace storage model native methods. The teraspace storage model provides a large, process-local address environment for ILE programs. Using the teraspace storage model allows you to port native method code from other operating systems to IBM i with little or no source code changes.

Note: Teraspace storage model provides an environment in which static storage, local variables, and heap allocations are automatically located in teraspace storage. If all you need to do is enable access to teraspace storage, then you do not need to use teraspace storage model. It is enough to teraspace enable your native method code. To teraspace enable your native method, use the TERASPACE(*YES) parameter on the Create C Module (CRTCMOD), Create C++ Module (CRTCPPMOD), or other module creation command.

For details about programming with the teraspace storage model, see the following information:

Chapter 4 of ILE Concepts
Chapter 17 of WebSphere® Development Studio ILE C/C++ Programmer's Guide

The concept for Java native methods created for the teraspace storage model is very similar to that of native methods that use single-level storage. The JVM passes the teraspace storage model native methods a pointer to the Java Native Interface (JNI) environment that the methods can use to call JNI functions.

For teraspace storage model native methods, the JVM provides JNI function implementations that utilize teraspace storage model and 8-byte pointers.

Creating teraspace storage model native methods

To successfully create a teraspace storage model native method, your teraspace storage model module creation command needs to use the following options:

     TERASPACE(*YES) STGMDL(*TERASPACE) DTAMDL(*LLP64)

The following option (*TSIFC), to use teraspace storage functions, is optional:

     TERASPACE(*YES *TSIFC)

Note: If you do not use DTAMDL(*LLP64) when using teraspace storage model Java native methods, calling a native method throws a runtime exception.

Creating teraspace storage model service programs that implement native methods

In order to create a teraspace storage model service program, use the following option on the Create Service Program (CRTSRVPGM) control language (CL) command:

     CRTSRVPGM STGMDL(*TERASPACE)

In addition, you should use the ACTGRP(*CALLER) option, which allows the JVM to activate all teraspace storage model native method service programs into the same teraspace activation group. Using a teraspace activation group this way can be important for native methods to efficiently handle exceptions.

For additional details on program activation and activation groups, see Chapter 3 of ILE Concepts.

Using Java Invocation APIs with teraspace storage model native methods

Use the Invocation API GetEnv function when the JNI environment pointer does not match the storage model of the service program. The Invocation API GetEnv function always returns the correct JNI environment pointer.

The JVM supports both single-level and teraspace storage model native methods, but the two storage models use different JNI environments. Because the two storage models use different JNI environments, do not pass the JNI environment pointer as a parameter between native methods in the two storage models.