Frequently Asked Questions

<body topmargin=0 leftmargin=0 marginheight=0 marginwidth=0> <table cellpadding=0 cellspacing=0 border=0><tr> <td valign="top" colspan=2 height=50 BGCOLOR="#0099FF" TEXT="#F7F7FF" bgproperties="fixed" background="04100610egcecm.png"> <div> <FONT SIZE="5" COLOR="#FFFFFF" FACE="Verdana" ><B>Java for OS/390 and z/OS Tips and FAQs</B></FONT><B>     |     </B><A HREF="index.htm" TARGET="_top" TITLE="Java for OS/390 and z/OS Tips and FAQs"><U><B>Home</B></U></A><B>   </B><A HREF="id34.htm" TARGET="_top" TITLE="Privacy Policy"><U><B>Privacy Policy</B></U></A></div> <bR> <div> </div> </td> </tr><tr> <td valign="top" width=190 BGCOLOR="#CCCCFF" TEXT="#080000"> <div> <A HREF="id25.htm" TARGET="_top" TITLE="Introduction"><U>Introduction</U></A></div> <div> <A HREF="id2.htm" TARGET="_top" TITLE="The Basics"><U>The Basics</U></A></div> <div> <A HREF="id3.htm" TARGET="_top" TITLE="Development Tools"><U>Development Tools</U></A></div> <div> <B>Frequently Asked Questions</B></div> <div> <A HREF="id4.htm" TARGET="_top" TITLE="Links"><U>Links</U></A></div> <div> <A HREF="id15.htm" TARGET="_top" TITLE="IBM Manuals"><U>IBM Manuals</U></A></div> <div> <A HREF="id34.htm" TARGET="_top" TITLE="Privacy Policy"><U>Privacy Policy</U></A></div> <bR> <div> <A HREF="mailto:garyp@firstech.com" TARGET="_top" TITLE="mailto:garyp@firstech.com"><U>Contact me</U></A></div> </td> <td valign="top" height=430 BGCOLOR="#FFFFFF" TEXT="#080000"> <div> Frequently Asked Questions</div> <div> Please <A HREF="mailto:garyp@firstech.com" TARGET="_top" TITLE="mailto:garyp@firstech.com"><U>let me know</U></A> if you have additional questions and I'll add them here. </div> <bR> <div> <A HREF="#jos390" TITLE="Frequently Asked Questions"><U><B><IMG BORDER="0" SRC="Symb075c00b7011800000000.png" HEIGHT="19" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">Java on OS/390</B></U></A></div> <div> <A HREF="#jos390001" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">How can I tell if Java is installed on my OS/390?</U></A></div> <div> <A HREF="#jos390002" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">How do I get a copy of Java for OS/390?</U></A></div> <div> <A HREF="#jos390003" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">Can I create executable code with Java for OS/390?</U></A></div> <div> <A HREF="#jos390006" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">How do I compile a Java program in batch?</U></A></div> <div> <A HREF="#jos390007" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">How do I execute a Java program in batch?</U></A></div> <div> <A HREF="#jos390004" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">How do I debug my Java for OS/390 programs?</U></A></div> <div> <A HREF="#jos390008" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">What environment variables are used by the JVM?</U></A></div> <bR> <bR> <div> <A HREF="#javaasm" TITLE="Frequently Asked Questions"><U><B><IMG BORDER="0" SRC="Symb075c00b7011800000000.png" HEIGHT="19" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">Interfacing between </B></U></A><A HREF="#javaasm" TITLE="Frequently Asked Questions"><U><B>Assembler</B></U></A><A HREF="#javaasm" TITLE="Frequently Asked Questions"><U><B>-</B></U></A><A HREF="#javaasm" TITLE="Frequently Asked Questions"><U><B>COBOL-PL/I</B></U></A><A HREF="#javaasm" TITLE="Frequently Asked Questions"><U><B> Programs and Java</B></U></A></div> <div> <A HREF="#javaasm001" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">How do I communicate between Java programs and non-Java programs?</U></A></div> <div> <A HREF="#javaasm002" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">How do I call from Java to an Assembler program?</U></A></div> <div> <A HREF="#javaasm005" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">Can I call an AMODE 24 Assembler program from C?</U></A></div> <div> <A HREF="#javaasm003" TITLE="Frequently Asked Questions"><U><IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">How do I use packed decimal values in a Java program?</U></A></div> <bR> <div>  <A NAME="jos390"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></div> <div> <B>Java on OS/390</B></div> <div> <B> <A NAME="jos390001"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>How can I tell if Java is installed on my OS/390?</B></div> <div> The easiest way is to just ask your systems programmer! If that doesn't suit you, have a look in the <A HREF="id2_hfs.htm" TARGET="_top" TITLE="The Basics"><U>HFS</U></A>. You can navigate the HFS most easily by typing <B>ishell</B> at TSO or in PDF option 6. Java is usually installed in the /usr/lpp/java/J1.x directory. Assuming that this where java is installed, make sure that the <B>bin</B> subdirectory is in your PATH environment variable.  You can check this by typing</div> <div> <B>     echo $PATH</B></div> <div> or</div> <div>      <B>printenv PATH</B></div> <div> while in the OMVS shell. If the bin subdirectory to the J1.x directory is <I>not</I> in your path, enter the following command in the OMVS shell:</div> <div>      <B>export PATH=/usr/lpp/java/J1.x/bin:$PATH</B></div> <div> Then, to actually verify the version of Java which is installed, type the following into the OMVS shell:</div> <div>      <B>java -fullversion</B></div> <div> A string like the following should appear:</div> <div>   java full version "J2RE 1.3.1 IBM OS/390 Persistent Reusable VM build hm131s-20020723"</div> <div> Or, you can type</div> <div> <B>     java -version</B></div> <div> and you'll receive something like:</div> <div>   java version "1.3.1"</div> <div>   Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1)</div> <div>   Classic VM (build 1.3.1, J2RE 1.3.1 IBM OS/390 Persistent Reusable VM build hm131s-20020723 JIT enabled: jitc))</div> <div> <B> <A NAME="jos390002"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>How do I get a copy of Java for OS/390?</B></div> <div> You can order the code on a tape from IBM or you can download the code.  For more details, visit the <A HREF="http://www.s390.ibm.com/java/" TARGET="_top" TITLE="http://www.s390.ibm.com/java/"><U>IBM web page</U></A> for Java for OS/390.</div> <div> <B> <A NAME="jos390003"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>Can I create executable code with Java for OS/390?</B></div> <div> Java for OS/390 creates java bytecodes which are <I>not </I>directly executable OS/390 instructions. They are a bytecode for a virtual machine which must be "executed" or interpreted by that virtual machine. IBM used to have an offering that allowed you to take that bytecode file and turn it into actual executable object code. This was called "Visual Age for Java, Enterprise Edition for OS/390." It was product 5655-JAV. This is<B> not to be confused</B> with "Visual Age for Java, Enterprise Edition for Windows" which was an IDE that ran on a Windows desktop. This is also not to be confused with Java for OS/390 which is IBM's port of Sun's JDK. The similarity of the names makes this very confusing but they are, in fact, three distinct products. The native compiler available for Visual Age for Java, Enterprise Edition for OS/390 was also called HPJ (High Performance Java) sometimes.  The native compiler is no longer available.  Major advances in the JIT compiler have obviated the need for a static native compiler.</div> <div> <B> <A NAME="jos390006"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>How do I compile a Java program in batch?</B></div> <div> <A HREF="id26.htm" TARGET="_top" TITLE="Compiling a Java Program in Batch"><U>Here</U></A> is some JCL for doing this.</div> <div> <B> <A NAME="jos390007"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>How do I execute a Java program in batch?</B></div> <div> <A HREF="id27.htm" TARGET="_top" TITLE="Executing a Java Program in Batch"><U>Here</U></A> is some JCL for doing this.</div> <div> <B> <A NAME="jos390004"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>How do I debug my Java for OS/390 programs?</B></div> <div> There are two ways to use debuggers for your Java programs on OS/390. The first way, the jdb debugger, allows you to debug OS/390 java bytecode from OS/390 USS. Using this option, you only need Java for OS/390. You do not need any other software. The other way, discussed in greater detail below, makes use of a standard called JPDA or the <A HREF="http://java.sun.com/j2se/1.3/docs/guide/jpda/architecture.html" TARGET="_top" TITLE="http://java.sun.com/j2se/1.3/docs/guide/"><U>Java Platform Debugging Architecture</U></A>.</div> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">Under the USS itself, you can use the <B>jdb</B> command which comes with the Java Development Kit as part of Java for OS/390. Although documention for the jdb debugger can be found <A HREF="http://java.sun.com/j2se/1.3/docs/tooldocs/win32/jdb.html" TARGET="_top" TITLE="http://java.sun.com/j2se/1.3/docs/tooldo"><U>here</U></A>, the Sun documentation lists only a few of the commands. Type <FONT SIZE="2" COLOR="#000000" FACE="Courier New" >jdb </FONT>under the shell to start the debugger and then type <FONT SIZE="2" COLOR="#000000" FACE="Courier New" >help </FONT>for the full list of commands. The jdb command is a command-line debugging tool, analogous to dbx, though not nearly as powerful. If you're compiling from the command line using the javac command, be sure to specify the -g option to generate the debugging information need for jdb and the other debuggers. When compiling from an IDE, check to make sure if there is an option to include debugging information in the .class files. When exporting a class file to OS/390, be sure select the option to include debug information in the class file, if appropriate.</div> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0"> The OS/390 JVMs are JPDA-compliant JVMs so you can use any JPDA compliant debugger. An excellent visual debugger is built into <A HREF="http://www.eclipse.org" TARGET="_top" TITLE="http://www.eclipse.org"><U>Eclipse</U></A>. Before I used Eclipse, I used <A HREF="http://www.karmira.com/products/bugseeker2/index.html" TARGET="_top" TITLE="http://www.karmira.com/products/bugseeke"><U>BugSeeker </U></A>from Karmira, which is also excellect and very reasonably priced.  Most IDEs today include a JPDA-compliant debugger as part of the IDE.</div> <div>  <A NAME="jos390008"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></div> <div> <B>What environment variables are used by the JVM?</B></div> <div> I've pieced some of this information together so be sure to test anything before you rely on it. Not all of these environment variables are available in all releases. Also, IBM service has a number of environment variables that produce traces used for debugging the JVM and the JIT compiler.  They will advise you when to set these environment variables. I've discovered the following:</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">JAVA_HOME</div> <div> This is the base directory for your Java for OS/390 installation. It is the directory where the java command is located. Our value for JAVA_HOME is /usr/lpp/java/IBM/J1.3. You don't need to set this environment variable up yourself. If you don't have it set up, the java command will set it up for you.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">JAVA_COMPILER</div> <div> Turns off the JIT (just-in-time) compiler or allows you to substitute an alternate JIT compiler. The JIT must be turned off when debugging with the Remote Debugger.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">CLASSPATH</div> <div> This is the regular Java CLASSPATH variable used by all versions of the JVM. It is used as a search path for Java classes. It consists of a list of directories and/or jar files and/or zip files separated by colons.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">LIBPATH</div> <div> This isn't really a JVM environment variable but rather a USS environment variable. It contains a list of directories separated by colons that is used as a search path when loading DLLs under from the HFS. This is important when you have native code compiled as DLLs loaded with System.loadLibrary(). See the <A HREF="id15_cmanuals.htm" TARGET="_top" TITLE="IBM Manuals"><U>C/C++ Programming Guide</U></A> for more information.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">LD_LIBRARY_PATH</div> <div> This also contains a search path for DLLs under from the HFS. I'm not really sure how it's different from LIBPATH yet but for some things it needs to be set.  LD_LIBRARY_PATH is used on some versions of Unix in place of LIBPATH but I'm not sure how much it's needed on the mainframe.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">_CEE_RUNOPTS</div> <div> Contains Language Environment runtime options separated by a space. If this variable is set before java is invoked from the shell, these options will override those compiled into java by IBM as well as any installation or IBM defaults that would apply. Use this cautiously.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">_BPXK_MDUMP</div> <div> Also not part of the JVM but part of USS itself. This was first introduced in OS/390 v2r7. It can specify the name of an MVS or HFS file. If the filename starts with a /, it is assumed to be an HFS file. This indicates the location to which a SYSMDUMP should be written when running under USS. If the value is "OFF", the SYSMDUMP will be in the current working directory with a filename of coredump.<I>pid</I> where <I>pid</I> is the process id.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">IBM_JAVA_ZOS_TDUMP</div> <div> Modern versions of the JVM take a TDUMP when the JVM detects a problem. Setting this environment variable to NO prevents that from happening. For more complete information, see information APAR II13292.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">IBM_JAVA_ZOS_TDUMP_PATTERN</div> <div> This environment variable is set to a string which is a pattern for the dump dataset name in case the default name of the TDUMP dataset does not conform with your shop standards.</div> <bR> <div> <IMG BORDER="0" SRC="Symb075c00b700c800000000.png" HEIGHT="13" WIDTH="24" ALIGN="bottom" HSPACE="0" VSPACE="0">IBM_JAVA_ZOS_TDUMP_COUNT</div> <div> This limits the number of TDUMPs that are requested. For example, if an error occurs during CEEDUMP processing, it could result in two dumps.  The default for this value is 2.</div> <div>  <A NAME="javaasm"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></div> <div> <B>Interfacing between Assembler-COBOL-PL/I Programs and Java</B></div> <div> <B> <A NAME="javaasm001"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>How do I communicate between Java programs and non-Java programs?</B></div> <div> Java defines a standard feature for the Java platform called the <B>Java Native Interface</B> (<B>JNI</B>). This is a series of APIs and rules which allow communication between Java programs and non-Java programs. Remember that the JVM is free to internally represent data and methods (a String, for example) in any way that it feels like, as long as the results of defined operations work out correctly. Therefore, JNI makes no assumptions about how Java fields or methods are stored internally. JNI allows access to Java fields and methods in a standard way so that you can use the values in native programs. IBM has <A HREF="http://www.s390.ibm.com/java/os390jni.html" TARGET="_top" TITLE="http://www.s390.ibm.com/java/os390jni.ht"><U>an example of how to write a simple JNI program for OS/390</U></A>. The <A HREF="http://java.sun.com/products/jdk/1.3/docs/guide/jni/index.html" TARGET="_top" TITLE="http://java.sun.com/products/jdk/1.3/doc"><U>Sun Java website</U></A> has valuable information on the JNI in general. If you really want to get into this, as I have, I strongly recommend that you get yourself a copy of <A HREF="id4_jni.htm" TARGET="_top" TITLE="Links"><U>Sheng Liang's excellent book</U></A>.</div> <bR> <div> Although all JVMs are required to support the JNI, a particular JVM is also permitted to implement its own, possibly more efficient, non-portable techniques for accessing Java objects. As far as I know, the IBM JVM for OS/390 does not yet implement any native access other than the JNI. Using the JNI will allow your native programs to operate properly with any JVM which runs under OS/390.</div> <div> <B> <A NAME="javaasm002"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>How do I call from Java to an Assembler program?</B></div> <div> While Java native methods can be directly implemented by C or C++ programs, there is no supported way to implement a native method directly in Assembler, COBOL, PL/I, or Fortran. Since the JVM is written in C and C++, it uses C and C++ calling conventions when calling external programs. Therefore, you will need some C "glue" code which connects the Java native method to the Assembler program.</div> <bR> <div> The C code is included in a program object created with the DLL binder option so that the Java_<I>xxx</I> entrypoints can be located dynamically by the JVM when it goes to call the native method. Note that although the C code is defined as a DLL to the binder, it doesn't need to be compiled with the DLL compiler option unless it, in turn, calls DLLs. That is, the DLL compiler option tells the compiler to generate calls which can be resolved by a DLL. It doesn't have anything to do with callers of the C program.</div> <bR> <div> So far, I have called Assembler programs from C programs using static linking. <A HREF="id35.htm" TARGET="_top" TITLE="Calling from a Java Program to an Assemb"><U>Here</U></A> is an example of such a combination. </div> <div>  <A NAME="javaasm005"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></div> <div> <B>Can I call an AMODE 24 Assembler program from C?</B></div> <div> Yes, absolutely. I use a small assembler program that is called from C. That program takes a pointer to the real program to call and a pointer to a save area that is "below the line", in addition to the arguments to be passed on to the target assembler program.Then, it saves the original mode, switches modes and calls the target program. On return, it switches modes back to the original mode. Things look a little funny in the CEEDUMP but I can usually find what I need.</div> <div> <B> <A NAME="javaasm003"><IMG BORDER="0" SRC="1x1.gif" HEIGHT="1" ALIGN="bottom" WIDTH="1" HSPACE="0" VSPACE="0" ></A></B></div> <div> <B>How do I use packed decimal values in a Java program?</B></div> <div> In Java, the best way to represent decimal numbers is by using the <A HREF="http://www2.hursley.ibm.com/decimalj/" TARGET="_top" TITLE="http://www2.hursley.ibm.com/decimalj/"><U>com.ibm.math.BigDecimal </U></A>class. It is included with all IBM JVMs (including the one for OS/390 and z/OS) and provides a superior decimal implementation over java.math.BigDecimal. <A HREF="http://jcp.org/en/jsr/detail?id=13" TARGET="_top" TITLE="http://jcp.org/en/jsr/detail?id=13"><U>JSR13 </U></A>proposes to make this a part of Java itself. To convert numbers to BigDecimal from a byte array containing a packed decimal number, I use a routine that travels down the byte array and builds a StringBuffer to pass to the BigDecimal constructor. I'm going to experiment with some other techniques that may be more efficient but that is what I'm using for now.</div> </td> </tr></table></body>