The CALLJ command allows BASIC to call a Java method. CALLJ is useful when using third party applications offering a Java API (for example, publish and subscribe, messaging, etc.)


    CALLJ packageAndClassName, [$]methodName, param SETTING ret  \
          [ON ERROR] errStatment

In order to use CALLJ, you need:

  • A Java virtual machine
  • CLASSPATH environment variable set to point on the class you want to
  • invoke


The Java virtual machine is loaded dynamically at runtime, so a compiled basic application has no dependencies on any Java virtual machine. By default, the program will search for:

jvm.dll on Windows platforms on HP UNIX for other platforms

Although it is not usually necessary, it is possible to specify a Java library by setting the JBCJVMLIB environment variable:

Windows: set JBCJVMLIB=jvm.dll AIX: export


The first call to CALLJ carries the overhead of loading the Java Virtual Machine into memory. Subsequent calls do not have this overhead. Many additional threads will be created and used by the JVM.

In addition, calls to non static methods carry the overhead of calling the constructor for the class. Wherever possible, static methods should be used.


packageAndClassName The "full" class name (e.g., com.jbase.util.utilClass)

methodName The name of the Java method in this class (e.g., "myMethod")

NOTE: If the method is static, you must append a dollay symbol ( $ ) before the name. It will be removed from the method name before calling it.

Param Any parameter (eg DynArray)


In Java:

     package mypackage;
     public class mytestclass {
         static int i = 0;
         private mytestclass() {
         public String mymethod(String s) {
 	        return ( "Java Received : " + s ) ;
         public static String mystaticmethod(String s) {
   		    return s + " "  + i;

To call these methods from jBC:

    CALLJ 'mypackage.mytestclass', 'mymethod', p SETTING ret
    CRT ret
    CALLJ 'mypackage/mytestclass', '$mystaticmethod', p SETTING ret
    CRT ret


Use the SYSTEM(0) variable to manage any errors at the BASIC level, which occur during the call.

This variable can have the following values:

1Fatal error creating thread
2Cannot create JVM
3Cannot find class
4Unicode conversion error
5Cannot find method
6Cannot find object constructor
7Cannot instantiate object


jBC code using the ON ERROR will look like this:

    PROGRAM testcallj
         className = ''
         methodName = ''
         param = ''
         CRT "Please enter a Class Name " :  ;   INPUT className
         CRT "Please enter a Method Name " :  ;  INPUT methodName
         CRT "Please enter a Parameter : "  ; INPUT param
         CALLJ className,methodName, param SETTING ret ON ERROR GOTO errHandler
         CRT "Received batch from Java : " : ret
         err = SYSTEM(0)
         IF err = 2 THEN
              CRT "Cannot find the JVM.dll !"
         IF err = 3 THEN
              CRT "Class " : className : "doesn't exist !"
         IF err = 5 THEN
      	      CRT "Method " : methodName : "doesn't exist !"

The CALLJ function provides access to a JavaVM from within the BASIC environment. For it to be able to start a JavaVM (JVM) the environment needs to know where the JVM is located. Specifically it needs to know where certain libraries are located.


Windows: looking for 'jvm.dll'

Add "c:\jdk1.6.0_33\jre\bin\server" to the PATH environment variable.

A generic format might be %JDKDIR%\jre\bin\server.


For UNIX it is possible to configure generic symbolic links to make profiles portable.

Location of JDK export JDKDIR=/opt/java6

Symbolic link for JRE libs /opt/java6/jrelib

Symbolic link for JVM library /opt/java6/jvmlib


/opt/java6/jrelib -> /opt/java6/jre/lib/amd64

/opt/java6/jvmlib -> /opt/java6/jre/lib/amd64/server


Add "/opt/java6/jrelib:/opt/java6/jvmlib" to the LD_LIBRARY_PATH


/opt/java6/jrelib -> /opt/java6/jre/lib/IA64W

/opt/java6/jvmlib -> /opt/java6/jre/lib/IA64W/server


Add "/opt/java6/jrelib:/opt/java6/jvmlib" to the SHLIB_PATH


/opt/java6/jrelib -> /opt/java6/jre/bin

/opt/java6/jvmlib -> /opt/java6/jre/bin/classic


Add "/opt/java6/jrelib:/opt/java6/jvmlib" to the LIBPATH

Solaris SPARC

/opt/java6/jrelib -> /opt/java6/jre/lib/sparc

/opt/java6/jvmlib -> /opt/java6/jre/lib/sparc/server


Add "opt/java6/jrelib:/opt/java6/jvmlib" to the LD_LIBRARY_PATH

Solaris AMD64

/opt/java6/jrelib -> /opt/java6/jre/lib/amd64

/opt/java6/jvmlib -> /opt/java6/jre/lib/amd64/server


Add "opt/java6/jrelib:/opt/java6/jvmlib" to the LD_LIBRARY_PATH

EXAMPLES using JVM WITHOUT symbolic links as above:

Linux: looking for ''

     Add 2 directories to LD_LIBRARY_PATH.

Solaris: looking for ''

     Add 2 directories to LD_LIBRARY_PATH.

HP-UX 11: looking for ''

     Add 2 directories to SHLIB_PATH.



If the search for the library appears incorrect for your platform, then you can override it by setting the JBCJVMLIB environment variable.

e.g. `export JBCJVMLIB=jvm.shared_lib`

and then CALLJ will try to locate the library 'jvm.shared_lib' at runtime.


You can specify a policy file for the JMV. The policy for a Java application environment (specifying which permissions are available for code from various sources) is represented by a Policy object. More specifically, it is represented by a Policy subclass providing an implementation of the abstract methods in the Policy class (which is in the package). You can override it by setting the JBCJVMPOLICYFILE environment variable.

The source location for the default policy information is:





e.g. "export JBCJVMPOLICYFILE=/usr/jbase/mypolicy.all"


Internally, the Java virtual machine always operates with data in Unicode. However, as data transfers to or from the Java virtual machine, the Java virtual machine converts the data to other encodings. If the you want to change the default encoding of the JVM on your platform, then you can override it by setting the JBCJVMENCODING environment variable.

e.g. "export JBCJVMENCODING=Cp1257"


Internally, CALLJ is optimized to start the JVM with options (see the table below). If you do not want to pass these options for the JVM, then you can override it by setting the JBCJVMNOOPTS environment variable. In this case no more options will be passed to the JVM.


On Linux we assumed that the Sun Java JDK would be used and the JVM options reflect this. But as they are not compatible with the IBM JDK you can set the JBCIBMJDK option to allow the running of the IBM JDK for Linux.


Linux:-Xrs -XX:+AllowUserSignalHandlers
AIX 64 bits:-Xrs -d64
HPUX 64 bits:-Xrs -XX:+AllowUserSignalHandlers


If the you want to pass some options for the JVM, then set the JBCJVMOPT[1..5] environment variable

e.g. "export JBCJVMOPT1=-Xrs"


Allows many options to be set within one variable. e.g. export JBCJVMOPTS="-Xrs -Xms256M -Xmx512M"



There is a problem with HP-UX due to its dynamic loader. See man dlopen(3C) for detail of the TLS limitation.

This means that the JVM library must be linked against the calling program, there are no known problems caused by this.

'ldd progname' lists current external library references and we need to add libjvm.

The symptom looks like this:

     JVM: dl_error [Can't dlopen a library containing Thread Local Storage:]

If the program is built with the required link as below then it works.

     jbc -Jo callj.b -ljvm -L/opt/java6/jre/lib/IA64W/server

If the CALLJ statement is inside a subroutine, then the program that calls the subroutine must be built as above.

Last update: Fri, 01 Feb 2013 08:29 CET