<!doctype HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML><HEAD>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<TITLE>Development Environment for the IBM OS/2 Warp Developer Kit, Java(TM) Edition</TITLE>
</HEAD><BODY BGCOLOR="FFFFFF">
<A NAME=Top_Of_Page> </A>

<center><H3>Development Environment for the</H3>
<H4>IBM(R) OS/2(R) Warp Developer Kit, Java(TM) Technology Edition, Version 1.1.8</H4>
</center>

<P>
The <B>IBM OS/2 Warp Developer Kit, Java(TM) Technology Edition, Version 1.1.8 (Developer Kit)</B> 
is based on is based on Sun Microsystems' Java 1.1.8 maintenance level. This file describes 
the Toolkit component of the Developer Kit.
<HR>
<MENU>
<LI><A NAME=ToC_1  HREF="#Header_1 " >Installation</A>
<LI><A NAME=ToC_2  HREF="#Header_2 " >The APPLET Tag</A>
<LI><A NAME=ToC_16  HREF="#Header_16 " >Java Tools</A>
<UL>
<LI><A NAME=ToC_3  HREF="#Header_3 " > Compiler</A>
<LI><A NAME=ToC_4  HREF="#Header_4 " >Debugging Tools</A>
<UL>
<LI><A NAME=ToC_4A HREF="#Header_4A " >ICAT Debugger</A>
<LI><A NAME=ToC_4B HREF="#Header_4B " >JDB debugger</A>
</UL>
<LI><A NAME=ToC_5  HREF="#Header_5 " >JAVAP</A>
<LI><A NAME=ToC_6  HREF="#Header_6 " >JAVADOC</A>
<LI><A NAME=ToC_7  HREF="#Header_7"  >JAVAH</A>
</UL>
<LI><A NAME=ToC_8  HREF="#Header_8 " >Accessing Java Objects from a C Program</A>
<UL>
<LI><A NAME=ToC_9  HREF="#Header_9 " >The Java Native Interface (JNI)</A>
<LI><A NAME=ToC_9A HREF="#Header_9A" >The JAVAH Header and Source Files</A>
</UL>
<LI><A NAME=ToC_10 HREF="#Header_10 " >Files Written Through a PrintStream</A>
<LI><A NAME=ToC_11 HREF="#Header_11 " >Behavior of Java.lang.Class.forName()</A>
<LI><A NAME=ToC_12 HREF="#Header_12 " >Backslash and Tilde Characters in DBCS Countries</A>
<LI><A NAME=ToC_13 HREF="#Header_13 " >Conversion Between ShiftJIS and Unicode on
OS/2 Warp 4 Japanese Version</A>
<LI><A NAME=ToC_14 HREF="#Header_14" >Known Limitations</A>
<LI><A NAME=ToC_15 HREF="#Header_15" >Notices</A>
</MENU>

<HR><P>
<H2><A NAME="Header_1" HREF="#ToC_1">Installation</A></H2>
<P>
See the
README 
file in the <B>\JAVA11</B> directory for the latest
information regarding installation. After installation, this 
file is located in the directory where you unpacked the Developer 
Kit files.</p>
<P>
The Java Toolkit component requires that the Java Runtime component
be installed first. The Toolkit must reside on an HPFS or JFS partition. 
The links in this document work only if the Runtime, Toolkit, and ICAT 
Debugger components are installed on the same drive in the same directory.
</P>
<HR>
<H2><A NAME="Header_2" HREF="#ToC_2">The APPLET Tag</A></H2>
<P>
The APPLET tag is used to imbed a Java applet in an HTML page. When
the HTML page is loaded in a Java-enabled Web browser, the applet runs.
If the Web browser recognizes the APPLET tag but cannot run Java applets, the
text specified by the ALT attribute is shown. The Applet Viewer, included
as part of the Java Runtime component, can also be used to run an applet.
</P>
<H3>APPLET Tag Syntax</H3>
<P>
The syntax for the APPLET tag is:
<PRE>
    <B>&lt;APPLET</B>
    <B>      CODE    =  appletFile</B>   or   <B>OBJECT=serializedApplet</B>
          CODEBASE  =  codebaseURL
          ARCHIVE   =  archiveList
          ALT       =  alternateText
          NAME      =  appletInstanceName
    <B>      WIDTH   =  pixels</B>
    <B>      HEIGHT  =  pixels</B>
          ALIGN     =  alignment
          VSPACE    =  pixels
          HSPACE    =  pixels
    <B>&gt;</B>

     &lt; PARAM NAME = appletAttribute1  VALUE = appletValue1 &gt;
     &lt; PARAM NAME = appletAttribute2  VALUE = appletValue2 &gt;
      .
      .
      .
    <B>&lt;/APPLET&gt;</B>
</PRE>
<DL>
<P><DT><B>CODE = appletFile
</B><DD>This attribute gives the name of the file that contains
    the applet's compiled Applet subclass. This file is relative to
    the base URL of the applet and cannot be absolute. This is a
    required attribute if OBJECT is not specified.
<P><DT><B>OBJECT = serializedApplet
</B><DD>This attribute gives the name of the file that contains
    a serialized representation of an applet. The applet is
    deserialized, the <b>init()</b> method is not invoked, but the
    <b>start()</b> method is run. Any attributes passed to this applet
    are made available to it. You should be careful in
    using this feature because an applet should be stopped before it is serialized.
    This is a required attribute if CODE is not specified.
<P><DT><B>CODEBASE = codebaseURL</B>
<DD>This optional attribute specifies the directory that contains
    the code for the applet. If this attribute is not specified, the
    document URL is used.
<P><DT><B>ARCHIVE = archiveList</B>
<DD>This optional attribute specifies one or more archives containing
    classes and other resources that are to be preloaded. The classes
    are loaded using an instance of an AppletClassLoader with the
    given CODEBASE. The archives in archiveList are separated by
    commas (<B>,</B>). Multiple APPLET tags with the same CODEBASE share the
    same instance of the AppletClassLoader.
<P><DT><B>ALT = alternateText
</B><DD>This optional attribute specifies any text that should be
    displayed if the browser recognizes the APPLET tag but cannot
    run Java applets.
<P><DT><B>NAME = appletInstanceName
</B><DD>This optional attribute specifies a name for the applet instance,
    which makes it possible for applets on the same page to find and
    communicate with each other.
<P><DT><B>WIDTH = pixels
</B><DD>This required attribute specifies the initial width, in pixels,
    of the applet display area, not counting any windows or
    dialogs that the applet brings up.
<P><DT><B>HEIGHT = pixels
</B><DD>This required attribute specifies the initial height, in pixels,
    of the applet display area, not counting any windows or
    dialogs that the applet brings up.
<P><DT><B>ALIGN = alignment
</B><DD>This attribute specifies the alignment of the applet.
    The possible values of this attribute are the same as those for
    the HTML IMG tag:  left, right, top, texttop, middle, absmiddle,
    baseline, bottom, absbottom.
<P><DT><B>VSPACE = pixels
</B><DD>This attribute specifies the number of pixels above and
    below the applet. It is treated the same way as
    the VSPACE attribute on the HTML IMG tag.
<P><DT><B>HSPACE = pixels
</B><DD>This attribute specifies the number of pixels on
    each side of the applet. It is treated the same way as
    the HSPACE attribute on the HTML IMG tag.
<P><DT><B>&lt; PARAM NAME = appletAttribute1 VALUE = appletValue1 &gt; ...
</B><DD>This tag is the only way to specify an applet-specific attribute.
    Applets access their attributes with the <B>getParameter( )</B> method.
</DL>
<H3>APPLET Tag Example</H3>
<P>
This example shows how to code the APPLET tag to run an applet in
class MyApplet in a window 320 pixels wide and 120 pixels high. Two
parameters are passed to the applet, <B>mynumber</B> and
<B>mytext</B>, and if the HTML page is displayed by a browser
unable to run Java applets, the text specified by the ALT attribute is displayed:
<PRE>
   &lt;applet code="MyApplet.class" width=320 height=120
   alt="You would see a nifty applet here in a Java-capable browser."&gt;
   &lt;param name=mynumber value="42"&gt;
   &lt;param name=mytext   value="Fido 3"&gt;
   &lt;/applet&gt;
</PRE>
<p>
The parameters <B>mynumber</B> and <B>mytext</B> are accessed from the
MyApplet class with calls to the <B>getParameter()</B> method. The
<B>mynumber</B> parameter could be handled as follows:
<PRE>
   String  parm;
   int     answer;

   parm  = getParameter("mynumber");
   if (parm == null) {
     answer = 12;
   } else {
     answer = Integer.parseInt(parm);
   }
</PRE>
<HR>
<H2><A NAME="Header_16" HREF="#ToC_16">Java Tools</A></H2>
<p>The following sections describe the Java tools available to help you
write and debug Java programs.</p>

<HR>
<H3><A NAME="Header_3" HREF="#ToC_3"> Compiler</A></H3>
<P>
The <B></B> compiler converts Java source code into Java byte codes,
which are later read and executed by the Java interpreter. Source code is
contained in files ending with an extension of <B>.java</B>. The compiler
stores its byte code output in a file with the same name as the source file,
but with an extension of <B>.class</B>.

<P>
The compiler starts with an initial Java interpreter heap size of 8 MB 
and has a maximum heap allocation of 16 MB. If this heap size is insufficient,
you can specify a larger size with the <B>-mx</B> option of the Java
interpreter. The <B>-J</B> option on <B></B> is used to pass the
option to the Java interpreter. For example, to compile LargeClass.java with 
a heap size of 100 MB:
<PRE>
        javac -J-mx100m LargeClass.java
</PRE>
<HR>
<H3><A NAME="Header_4" HREF="#ToC_4">Debugging Tools</A></H3>
<P>
The Developer Kit provides two Java debugging tools:
<UL>
<LI><A HREF="#Header_4A " >ICAT Debugger</A>
is a source-level debugger that runs on OS/2 Warp. It provides local
or remote debugging of Java applications.
<LI><A HREF="#Header_4B " >Java Debugger (JDB)</A>,
provided on 100% Pure Java platforms, is a command-line debugger for Java classes.
</UL>
<H3>Debugging Compiler Options</H3>
<P>
When compiling your Java application, specify the <B>-g</B> option to
enable the generation of debugging tables. These tables contain essential 
information about line numbers and local variables for the debuggers.
<P>
You can obtain additional debugging information for JDB by specifying
the <B>-O</B> option, which places static, final, and private methods inline.
You should not use this option with the ICAT Debugger for the Developer Kit because
the inline code distorts the display of source line numbers.
<P>
A class compiled with debugging information is larger than one compiled
without it.
<H3>TCP/IP Loopback Interface</H3>
<P>
To debug a Java application that is running on the same machine as the
debugger, the Transfer Control Protocol/Internet Protocol (TCP/IP) 
loopback interface must be active. To verify
that the interface is active, enter the following at an OS/2 command
prompt:
<PRE>
        ifconfig lo
</PRE>
If the interface is active, you will see something similar to this:
<PRE>
lo: flags=809&lt;UP,LOOPBACK&gt;
         inet 127.0.0.1 netmask xff000000
</PRE>
Otherwise, you will see something similar to this:
<PRE>
lo: flags=808&lt;LOOPBACK&gt;
</PRE>
If the TCP/IP loopback interface is inactive, you can start it by entering the
following at an OS/2 command prompt:
<PRE>
        ifconfig lo 127.0.0.1 up
</PRE>
<P>
To enable this interface automatically, open the TCP/IP folder, and then open the
TCP/IP Configuration object. Depending on the version of TCP/IP you have, 
you can also open the TCP/IP Configuration object by entering the following at an OS/2 command 
prompt:
<UL>
<LI><B>TCPCFG</B> for version 4.0 or earlier</LI>
<LI><B>TCPCFG2</B> for version 4.1 or higher</LI>
</UL>
After you have opened the TCP/IP Configuration object, click on the <B>Network</B> tab. 
Select the <B>loopback interface</B> as the interface to configure, and select
<B>Enable interface</B>.  At the OS/2 command prompt, specify <B>127.0.0.1</B> 
for the IP Address. Close the TCP/IP Configuration object, and save your changes
when prompted.
</P>

<HR>
<H3><A NAME="Header_4A" HREF="#ToC_4A">ICAT Debugger</A></H3>
<P>
The IBM Interactive Code Analysis Tool (ICAT) for OS/2 Java provides
debugging of OS/2 Java applications and their (potential) native-method
calls [C or C++ code collected in an OS/2 dynamic load library (DLL)
file]. The ICAT Debugger is a source-level debugger that uses OS/2
Presentation Manager (PM) for its presentation space and runs its
debug engine outside of a JVM.
<P>
Detailed information on the debugger can be found in the
<A HREF=icatjava\help\icatjava.htm>ICAT Debugger for the Developer Kit documentation</A>.
<HR>
<H3><A NAME="Header_4B" HREF="#ToC_4B">Java Debugger (JDB) Debugger</A></H3>
<P>
The <B>JDB</B> is a command-line debugger for Java
classes. The Java Debugger is started in place of the Java interpreter.
A list of the commands available and a brief description of each can be found by
specifying <B>help</B> or <B>?</B> at the OS/2 command prompt after the debugger is active.
<HR>
<H3><A NAME="Header_5" HREF="#ToC_5">JAVAP</A></H3>
<P>
<B>JAVAP</B> disassembles a Java class file and, depending on the options
specified, displays a variety of information about the file, including:
<ul>
<li>Local variable tables and line numbers
<li>Disassembled code
<li>Public variables and methods
<li>Private variables and methods
</ul>
</p>
<p>
If you type <B>JAVAP</B> without any options on an OS/2 command line, a list of options is displayed.
</p>
<HR>
<H3><A NAME="Header_6" HREF="#ToC_6">JAVADOC</A></H3>
<P>
<B>JAVADOC</B> generates a set of HTML pages based on declarations and
comments in the Java source files. JAVADOC displays all public and
protected declarations for classes, interfaces, methods, and variables.
You can pass either a package name or a list of Java source files as
an argument to JAVADOC.</P>

<p><b>Note:</b> Source files (.java) are used; class files (.class) are not used.
</p>

<p>
If you type <B>JAVADOC</B> without any options on an OS/2 command line, a list of options is displayed.
</p>
<HR>
<H3><A NAME="Header_7" HREF="#ToC_7">JAVAH</A></H3>
<P>
<B>JAVAH</B> produces C header files and C source files from a Java class.
These files are used for
<A HREF="#Header_9A">accessing Java objects from a C program</A>.
</p>
<HR>
<H2><A NAME="Header_8" HREF="#ToC_8">Accessing Java Objects from a C Program</A></H2>
<P>
Java objects can be accessed from a native C or C++ program in one of two ways:
<UL>
<LI><A HREF="#Header_9 " >The Java Native Interface (JNI)</A>
<LI><A HREF="#Header_9A" >The JAVAH Header and Source Files</A>
</UL>
<P>
JNI, which was new in Java 1.1.1, provides a more stable interface to native
methods than the previous method of using JAVAH generated header and
source files.

<P>
<H3>General Programming Considerations</H3>
<UL>
<LI>The JVM modifies the floating point unit
control word to suppress some floating point exceptions. Native methods
that modify the floating point control word should save the
control word content on entry and restore it on exit from the native
method.

<P><LI>On OS/2 Warp Server, Version 4 prior to FixPak 31 and 
OS/2 Warp Server SMP prior to FixPak 31, the DosQueryThreadContext 
API call is not supported. 
This means that the JVM must use a voluntary suspend mechanism for 
garbage collection. This mechanism requires that all
Java threads periodically check for a suspend request. This mechanism
fails and garbage collection is not possible if a native method enters
a hard suspend of any duration.
<P>On  OS/2 Warp 4, this mechanism is replaced with
a more robust and less intrusive mechanism, but to ensure compatibility
when running applications on all supported versions of OS/2, native methods
should not wait for more than one or two seconds.
<P>
Callers can participate in the voluntary suspend process by arranging
for hard waits outside of the Java environment to be broken into a
series of short (&lt; 0.5 second) waits with a call to
<b>ThreadCheckForSuspend() </b>issued between each wait. For example you
might replace the following code:

<PRE>
      rc = DosRequestMutexSem( mutex, SEM_INDEFINITE_WAIT );
</PRE>with:<PRE>
      do
      {
        rc = DosRequestMutexSem( mutex, 250L );
        if (rc == ERROR_TIMEOUT) ThreadCheckForSuspend();
      } while (rc == ERROR_TIMEOUT);
</PRE>
<P>
The prototype definition for the ThreadCheckForSuspend call is:
<PRE>
       void ThreadCheckForSuspend (void);
</PRE>
<LI>To avoid possible DLL name conflicts in the future, use
DLL names that do not begin with the string <B>JAVA</B>.

</UL>
<HR>
<H2><A NAME="Header_9" HREF="#ToC_9">The Java Native Interface (JNI)</A></H2>
<P>
Java objects can be accessed from a C program using the Java Native
Interface (JNI), which was new with Java 1.1.1. Using the JNI provides
a more stable interface than
<A HREF="#Header_9A">The JAVAH Header and Source Files</A>.
<P>
To produce platform-specific native methods in C or C++ using JNI on OS/2:

<OL>
<LI>Create a Java class source file to wrap the native methods:
<PRE>
    class MyNativeClass
       {
         String x;
         ...
         public native void demo(String x);
         ...
         static { System.loadLibrary("MyLib"); }
       }
</PRE>
<P><B>Note: </B>  The <b>System.loadLibrary</b> method executes the first
time the class is called and loads a DLL called MyLib that must
contain the native methods.

<P><LI>Generate a .h file for your class file by using <B>JAVAH</B>:
<PRE>
     javah -jni MyNativeClass
</PRE>
<P>
This creates a <B>MyNativeClass.h</B> file.
<P>
<LI>Create a .c file to implement the functions declared in the
MyNativeClass.h file, and add a line to include the generated header.

<PRE>
#include "MyNativeClass.h"
</PRE>
<LI>Write your native methods in C using entry points of the form
Java_<B>&lt;class name&gt;_&lt;method name&gt;</B>:
<PRE>
/*
 * Class:     hello
 * Method:    demo
 * Signature: (java/lang/String;)
 */
JNIEXPORT void JNICALL Java_hello_demo
   (JNIEnv *ee, jobject o, jstring s)
{
}
</PRE>
<LI>
Generate a module definition file, <B>javadef.def</B>, as follows:
<PRE>
LIBRARY INITINSTANCE
DATA MULTIPLE NONSHARED
CODE SHARED
</PRE>
<LI>Compile and link the program as follows:
<PRE>
icc /Ge- /FeMyLib.dll MyNativeClass.c javadef.def javai.lib
</PRE>
<P>Your INCLUDE search path should include:
<PRE>
    x:\JAVA11\include;x:\JAVA11\include\os2;
</PRE>
<P>and the LIB search path should include:
<PRE>
    x:\JAVA11\lib;
</PRE>
where <B>x:\JAVA11</B> is the drive and directory where you installed
the Java Toolkit component.
</OL>

<HR>
<H2><A NAME="Header_9A" HREF="#ToC_9A">The JAVAH Header and Source Files</A></H2>
<P>
Java objects can be accessed from a C program using the C header and
source files produced by
<A HREF="#Header_7">JAVAH</A>.  These files allow access
to an object's instance variables.
<P>
<B>Note: Java 1.0.2 native method DLLs are not compatible with
the Developer Kit and must be recompiled and relinked.
</B>
<P>
<B>Any Java 1.0.2 native method DLLs must be recompiled and relinked
before they can be used with the Developer Kit.</B>  This is necessary
because of changes in the Java heap model that resulted in a change
to the <B>unhand()</B> macro. The name of the Java run-time interpreter
DLL has also changed, but this should be transparent to developers of native methods,
provided they relink with the new version of <B>JAVAI.LIB</B>.

<P>
With the new Java heap model, handles, as well as objects, can now move
during garbage collection. The garbage collector changes handles that
it knows about. However, if a native method stores a Java object handle in
static storage or on the C heap, the garbage collector does not know
about it and cannot fix it. In this case, the garbage collector could
move the handle and invalidate the reference held by the native method.
<P>
To prevent the garbage collector from moving a specific handle, call the
<B>pin_handle()</B> method and pass in the handle that is not to be moved.
Use the <B>unpin_handle()</B> method when finished with the handle; this
permits the handle to be moved during garbage collection.

<P>
To use platform-specific native methods in C or C++ on OS/2:
<OL>
<LI>Create a Java class source file to wrap the native methods:
<PRE>
    class MyNativeClass
       {
         String x;
         ...
         public native void demo(String x);
         ...
         static { System.loadLibrary("MyLib"); }
       }
</PRE>
<P><B>Note: </B>  The System.loadLibrary method executes the first
time the class is called and loads a DLL called MyLib, which must
contain the native methods.

<P><LI>Generate a .h file for your class file by using <B>JAVAH</B>:
<PRE>
     javah MyNativeClass
</PRE>
<LI>Generate a .c stub file for your class by using <B>JAVAH</B>:
<PRE>
     javah -stubs MyNativeClass
</PRE>
<LI>Write your native methods in C using entry points of the form
<B>&lt;class name&gt;_&lt;method name&gt;</B>:
<PRE>
   void MyNativeClass_demo(struct Hjava_lang_String * x)
</PRE>
<LI>Compile your C files. Your INCLUDE search path should include the
following:
<PRE>
    x:\JAVA11\include;x:\JAVA11\include\os2;
</PRE>
where <B>x</B> is the drive where you installed Java.<P>
<LI>Link your C files containing the native methods with the C stub file to
create a DLL with the name specified in the System.loadLibrary
statement. You need to link with the Java library
<B>x:\JAVA11\LIB\JAVAI.LIB </B> (or the debug version of the library,
<B>JAVAI_G.LIB</B>) if you have used any Java Runtime helper functions.

</OL>
<P>
The Java Runtime uses the IBM VisualAge C _Optlink calling convention
to call native methods in DLLs.

<HR>
<H2><A NAME="Header_10" HREF="#ToC_10">Files Written Through a PrintStream</A></H2>
<P>
Records written to a file using the <B>println()</B> method in the PrintStream
class are terminated using the <b>newLine()</b> method of the underlying
OutputStreamWriter. The <b>newLine()</b> method uses the appropriate <B>line.separator</B>
system property for the platform, which on OS/2 is the characters (x'0d0a').
<P>
This is a change from JDK 1.0.2. In JDK 1.0.2, when writing to a file through a PrintStream,
a single newline character (x'0a') was used as a line separator.
This was consistent with standard UNIX conventions, but differed from the OS/2
convention where records are terminated with the characters (x'0d0a').
<P>Java appropriately reads records terminated in either fashion.
<HR>
<H2><A NAME="Header_11" HREF="#ToC_11">Behavior of Java.lang.Class.forName()</A></H2>
<P>
<a href="http://java.sun.com:80/docs/books/jls/clarify.html">Clarifications and Amendments to
<I>The Java Language Specification</I></a> describes a change in the behavior of <b>Java.lang.Class.forName()</b>.
This document states:
<P>
<I>JLS 20.3.8 should state that a call to java.lang.Class.forName("X") causes the class named "X"
to be initialized.</I>

<P>
For the Developer Kit, the behavior of <b>Class.forName()</b> matches
the modified Sun specification and the Sun reference implementation. A call to java.lang.Class.forName("X")
now causes the class named "X" to be initialized.
<P>
This behavior is implicitly assumed in the Java Database Connectivity (JDBC) examples that
use <b>Class.forName()</b> to load JDBC drivers and expect the JDBC driver to be immediately usable.
The examples assume that the static initializers in the JDBC driver are run by the <b>Class.forName()</b>,
so that the static initializer code in the driver can register itself with the JDBC driver manager.

<HR>
<H2><A NAME="Header_12" HREF="#ToC_12">Backslash and Tilde Characters in DBCS Countries</A></H2>
<p>Certain DBCS code pages (for example, 932, 942, 943, 949) do not have a backslash
or tilde character at the same code point as other ASCII code pages. Examples of this are as follows:
<UL>
<LI>In most ASCII code pages, code point 0x5c is a backslash and code point 0x7e is a tilde.
<LI>In code pages 932, 942, and 943, code point 0x5c is a Japanese Yen mark and code point 0x7e
is an overline.
<LI> In code page 949, code point 0x5c is a Korean Won sign.
</UL>

<H3>Placement of the Characters</H3>
<p>The Java compiler, javac, first converts the Java source program from the local code page
to Unicode. It then processes the character escape sequences, such as \n, by reading the
backslash character, then the 'n' character, and then combining them as a character escape
to generate a Unicode newline, U+000A, before compiling the program.</p>

<p>In some instances, the backslash character (character 0x5C in code page 850)
in certain DBCS code pages is not in the same position. For example, in code page 943,
character 0x5C is a Yen character. If the javac compiler converted code point 0x5c in the
local code page (a Yen mark) in the Java source program to a Unicode Yen mark (U+00A5),
then  no backslash characters would be present, so no character escape sequence processing
would be performed.</p>

<p>Furthermore, in code pages 932, 943, and 949, there is no backslash anywhere in the local
code page, so there is no way for a programmer to generate a Unicode backslash (for use in
generating other Unicode characters using Unicode escape sequences) after code page conversion
in the javac compiler.</p>

<H3>Conversion Tables</H3>

<p>To allow programmers to write programs containing a backslash, the JVM
uses modified code page conversion tables for code pages 932, 943, and 949. These modified
tables pass through characters 0x00 to 0x7F in the local code page to U+0000 to U+007F in Unicode.
This means that a programmer can use a Yen mark (0x5c) in code page 932 and 943 and a Won sign
(0x5c) in code page 949 to represent a backslash character (U+005C) in Unicode. An overline
(0x7e) in code pages 932 and 943 can be used to represent a tilde (U+007E) in Unicode.</p>

<p>These modified codepage conversion tables are also used as the default for the JVM when running
in OS/2 code pages 932, 943, and 949. These are used for PrintStream, PrintWriter, OutputWriter
and InputReader classes when no explicit character encoding is specified.</p>

<p>Although using 0x5C in the local code page may be printed as a Yen mark in the local code page,
if an application programmer really wants a Yen mark, then a Unicode escape should be used to generate
a Unicode character U+00A5. This is needed to make the application portable to other code pages,
and also to cause Abstract Window Toolkit (AWT) to display the correct character glyph. Similar considerations apply if the
programmer wants a real overline: Unicode character U+203E should be used within the Java program.</p>

<H3>Code Page 942</H3>

<p>Code page 942 has both tilde and backslashes present, though at different code points from other
code pages. Because this code page does have backslashes and tildes present, even though they are in
different positions from other ASCII code pages, the modified code page converters are not used by default.</p>

<p>Programs written in this code page can be written using real backslashes and tilde symbols in
the local code page. If programs are written in another ASCII code page where backslash is code point
0x5C and they need to be compiled, then in most cases, the proper behavior can be achieved by using
one of the following methods:</p>

       <ul>
       <li>Replace the 0x5c character in the Java source program with
             the backslash character in the local code page (code point
             0xfe).

        <li>When compiling the Java application or applet, indicate that
             the file is written in a code page different from the local
             code page. For example, if the source code was written in
             code page 850, use the following command to compile it:

                <pre>javac  -encoding 850  myprogram.java</pre>
       </ul></p>

<p>If the file is written with DBCS characters in code page 942, using 0x5C to represent the backslash,
then the -encoding option of javac can be used to force the use of character encoding Cp942c',
which passes through characters 0x00 to 0x7F in the local code page to U+0000 to U+007F in Unicode.
For example:</p>

                <pre>javac  -encoding Cp942c myprogram.java</pre>

<p>If the source program is written in code page 942 using a real backslash (code point 0xfe) and
must be compiled on another system, then use the native2ascii program to convert the Java source program
from the local code page to a basic ASCII code page. For example:</p>

           <pre>native2ascii myprogram.java d:\mydest\myprogram.java</pre>

<p>To convert from a specific code page to a basic ASCII code page:</p>

           <pre>native2ascii -encoding 942 myprogram.java d:\mydest\myprogram.java</pre>

<H3>The File Separator Character</H3>
<p>The file separator character in most ASCII code pages on OS/2 is a backslash.
The file separator character is accessible in a Java program using the system property 'file.separator'
or the static constant, 'java.io.File.separator'.</p>

<p>In code pages 932 and 943, the local file separator character is still code point 0x5C, but this is
displayed at the command prompt as a Yen mark. Similarly, in code page 949, the separator character is
displayed as a Won sign. The default character converter for these code pages converts the file.separator
character to a backslash in Unicode, so a Java application sees the file separator as a Unicode
backslash (U+005C).</p>

<p>In code page 942, the local file separator is also a Yen mark, but this is converted by the Java character
converter to a Yen mark in Unicode, so the Java application sees the file separator character as a
Unicode Yen mark (U+00A5).</p>

<p>To make sure that your Java applications will work on all operating systems, always use the file.separator
system property. Application programmers should be sure not to embed path separators in their programs.</p>

       <p>For example, do not use:</p>

       <pre>FileInputStream x = new FileInputStream("mydir\myfile.ext");</pre>

       <p>Instead, use:</p>

            <pre>FileInputStream x = new FileInputStream("mydir" + File.separator+ "myfile.ext");</pre>

<HR>
<H2><A NAME="Header_13" HREF="#ToC_13">Conversion Between ShiftJIS and Unicode on OS/2 Warp 4 Japanese
Version</A></H2>

<p>In the Japanese environment, the following conversion tables for ShiftJIS code (PC code) and Unicode
are available:</p>

       <UL>
       <LI>SJIS
       <LI>Cp943C
       <LI>Cp943 = IBM-943
       <LI>Cp942 = IBM-942
       <LI>Cp942C
       </UL>

       <p>The system default conversion tables are:</p>

         <UL>
         <li>Cp943C for code pages 943 and 932
         <li>Cp942 for code page 942
         </UL>

       <p>To use the Cp942 table, set the table name explicitly in a method
       or as a parameter. These tables do the following conversions:</p>


<H3>For SBCS Characters</H3>
<TABLE BORDER=2 CELLSPACING=2 CELLPADDING=2 COLS=5>
<TR ALIGN=CENTER>
     <TD>&nbsp;
     <TD COLSPAN=2><b>PC Code</b>
     <TD COLSPAN=2><b>Unicode</b>
</TR>
<TR>
     <TD><b>Code Page</b>
     <TD><b>Code Point</b>
     <TD><b>Character</b>
     <TD><b>Code Point</b>
     <TD><b>Character</b>
</TR>
<TR>
     <TD>SJIS
     <TD>0x00-0x7F
     <TD>Correspond with Unicode
     <TD>U0000-U007F
     <TD>Correspond with PC Code
</TR>
<TR>
     <TD>Cp942C
     <TD COLSPAN=2>Corresponds with Unicode
     <TD COLSPAN=2>Corresponds with PC Code

</TR>
<TR>
     <TD>Cp943C
     <TD COLSPAN=2>Corresponds with Unicode
     <TD COLSPAN=2>Corresponds with PC Code

</TR>
<TR>
     <TD>Cp942
     <TD>0x00-0x5B
     <TD>Correspond with Unicode
     <TD>U0000-U005B
     <TD>Correspond with PC Code
</TR>
<TR>
     <TD>Cp943
     <TD>0x5c
     <TD>Yen Sign
     <TD>U00A5
     <TD>Yen Sign
</TR>
<TR>
     <TD>
     <TD>0x5D-0x7D
     <TD>Correspond with Unicode
     <TD>U005D-U007D
     <TD>Correspond with PC Code
</TR>
<TR>
     <TD>
     <TD>0x7e
     <TD>Overline
     <TD>U203E
     <TD>Overline
</TR>
<TR>
     <TD>
     <TD>0x7F
     <TD>Corresponds with Unicode
     <TD>U007F
     <TD>Corresponds with PC Code
</TR>
<TR>
     <TD>
     <TD>0x80
     <TD>Cent Sign
     <TD>U00A2
     <TD>Cent Sign
</TR>
<TR>
     <TD>
     <TD>0xA0
     <TD>Pound Sign
     <TD>U00A3
     <TD>Pound Sterling Sign
</TR>
<TR>
     <TD>
     <TD>0xFD
     <TD>Not Sign
     <TD>U00A7
     <TD>Not Sign
</TR>
<TR>
     <TD>
     <TD>0xFE
     <TD>Backslash
     <TD>U005C
     <TD>Backslash
</TR>
<TR>
     <TD>
     <TD>0xFF
     <TD>Tilde
     <TD>U007E
     <TD>Tilde
</TR>
</table>
</p>
       <p>For example, in the Cp943C table, the PC code for the range
       range 0x00 - 0x7F is converted to Unicode for the range U0000 - U007F
       straight. In the Cp942 table, the PC code Yen sign (0x5c) is
       converted to the Unicode Yen sign (U00A5).</p>


       <p>For DBCS characters:</p>

        <UL>
       <LI>In the Cp943, Cp943C and SJIS table, the PC code is regarded as the
       new JIS order.

       <LI>In the Cp942 and Cp942C table, the PC code is regarded as the old
       JIS order.
</ul>

<p>For User-Defined Characters and IBM Extended Characters:</p>
<UL>
<LI>In the Cp943 and Cp943C tables, these PC code characters are converted
to Unicode.

       <LI>In the SJIS table, these PC code characters are NOT converted
       to Unicode.

       <LI>In the Cp942 and Cp942C tables, these PC code characters are converted
       to Unicode.
</UL>

<HR>
<H2><A NAME="Header_14" HREF="#ToC_14">Known Limitations</A></H2>
<UL>
<LI>
The just-in-time (JIT) compiler optimizes out method tracing (<B>-tm</B> option)
and profiling. To obtain full method tracing and profiling you must disable the JIT. See
<A HREF=runtime.htm#JIT>Disabling the JIT Compiler</A>
in the
<A HREF=runtime.htm>Runtime documentation</A>
for details.
<P><LI>When the JIT compiler is enabled, an uncaught exception generates a
trace back without source line numbers. You must
<A HREF=runtime.htm#JIT>disable the JIT</A>
and run the failing application again to obtain a trace back with line numbers.

</UL>
<HR>
<H2><A NAME="Header_15" HREF="#ToC_15">Notices</A></H2>
<P>Trademarks
<P>The following are trademarks of International Business Machines
Corporation in the United States, or other countries, or both:
<UL>
<LI>IBM</LI>
<LI>OS/2</LI>
</UL>
<p>The following are trademarks of other companies:
<UL>
<LI>Java and 100% Pure Java are trademarks of Sun Microsystems, Inc.
<LI> The Java(TM) technology is owned and exclusively licensed by 
Sun Microsystems, Inc. Java is a trademark of Sun Microsystems, Inc. in
the U.S. and other countries. 
</UL>
<P>Copyrights
<UL>
<LI> (c) Copyright Sun Microsystems, Inc. 1992-1998. All rights reserved.
<LI> (c) Copyright IBM Corporation, 1996-1998. All rights reserved.
<LI> This product is based in part on the work of the Independent JPEG Group.
<LI> US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
</UL>

</BODY></HTML>
