Java Invocation API

The Invocation API, which is part of the Java™ Native Interface (JNI), allows non-Java code to create a Java virtual machine, and load and use Java classes. This function lets a multithreaded program make use of Java classes that are running in a single Java virtual machine in multiple threads.

The IBM® Developer Kit for Java supports the Java Invocation API for the following types of callers:

An ILE program or service program that is enabled to work with teraspace storage. The storage model can either be single-level storage or teraspace storage. For more information about JNI and teraspace storage, see Teraspace storage model native methods for Java.
An PASE for i executable created for either 32-bit or 64-bit AIX®.
Note: The LIBPATH and LDR_CNTRL environment variables may need to be set appropriately when running PASE for i executables.

The application controls the Java virtual machine. The application can create the Java virtual machine, call Java methods (similar to the way in which an application calls subroutines), and destroy the Java virtual machine. Once you create the Java virtual machine, it remains ready to run within the process until the application explicitly destroys it. While being destroyed, the Java virtual machine performs clean-up, such as running finalizers, ending Java virtual machine threads, and releasing Java virtual machine resources.

With a Java virtual machine that is ready to run, an application written in ILE languages, such as C and RPG, can call into the Java virtual machine to perform any function. It also can return from the Java virtual machine to the C application, call into the Java virtual machine again, and so on. The Java virtual machine is created once and does not have to be recreated before calling into the Java virtual machine to run a little or a lot of Java code.

When using the Invocation API to run Java programs, the destination for STDOUT and STDERR is controlled by the use of an environment variable called QIBM_USE_DESCRIPTOR_STDIO. If this environment variable is set to Y or I (for example, QIBM_USE_DESCRIPTOR_STDIO=Y), the Java virtual machine uses file descriptors for STDIN (fd 0), STDOUT (fd 1), and STDERR (fd 2). In this case, the program must set these file descriptors to valid values by opening them as the first three files or pipes in this job. The first file opened in the job is given fd of 0, the second fd of 1, and third is fd of 2. For jobs initiated with the spawn API, these descriptors can be preassigned using a file descriptor map (see documentation on Spawn API). If the environment variable QIBM_USE_DESCRIPTOR_STDIO is not set or is set to any other value, file descriptors are not used for STDIN, STDOUT, or STDERR. Instead, STDOUT and STDERR are routed to a spooled file that is owned by the current job, and use of STDIN results in an IO exception.

Note: Message CPFB9C8 (File descriptors 0, 1, and 2 must be open to run the PASE for i program.) will be issued if it is determined that the file descriptors for STDIN, STDOUT, and STDERR are not set but are required to be set.