JeodeRuntime™ documentation

• Introduction
• Installation
• Demonstrations supplied
• Running Java applets
• Running Java applications
• Command-line options
• FAQ
• Notes on internationalization
• Further information
• Disclaimer

Introduction

JeodeRuntime is a fully-certified implementation of Sun's PersonalJava 1.2 specification.

JeodeRuntime can be used:

• As a plug-in to your iPAQ's Pocket Internet Explorer, to run Java applets from a web page.
• As a stand-alone Java VM (Virtual Machine), to run Java applications on your iPAQ.

Note: Some Java applets on web pages are not designed for the memory constraints of your iPAQ. Please see the FAQ section for guidelines on what types of applets you can expect to run.

Installation

By default, JeodeRuntime files are installed in \Windows and subdirectories of \Windows on your iPAQ.

Notes:

• You must have a working ActiveSync connection between your Windows PC and your iPAQ (for ActiveSync trouble-shooting information, please see the Microsoft web site).
• For Windows 2000 PCs, you must have administrator privileges set.

Uninstallation

Note: if uninstallation fails, please reset your iPAQ, then re-try.

Demonstrations supplied

• Quasar: a Java applet, invoked by opening a HTML file.
• PrimTest: a Java application which uses the AWT graphics library to demonstrate some Java graphics capabilities.

To run the demonstration applications or applet, select Start > Programs > Jeode > Examples, then select the demonstration application or applet to run. For example, to run the Quasar demonstration applet, select Start > Programs > Jeode > Examples > Quasar.

Running Java applets

When your browser next opens a web page which contains a Java applet, the plug-in runs the applet. This all happens automatically - no user intervention is needed.

For more information about running applets (including limitations), please refer to the FAQ section.

Running Java applications

You can then launch JeodeRuntime in two ways:

• Tap on the EVM icon (Start > Programs > Jeode), then enter options at the Enter args: prompt as follows:
  [command-line options] class-name [class-arguments]
  where:
  [command-line options] are command-line options to pass to the EVM (for example, -cp).
  class-name is the class name for your Java application (for example, PrimTest).
  [class-arguments] are any optional arguments for the Java application to run.

  For example:
  -cp \Windows\lib\jeodedemos.jar PrimTest

• Run JeodeRuntime as a shortcut.
  Create then tap on a shortcut (a .lnk file) to evm.exe in the Start menu. This allows you to store EVM arguments (class name and command-line options) in the Properties of the shortcut, avoiding the need to re-type them every time you launch JeodeRuntime.

  See the Creating a shortcut section below for more information.

Creating a shortcut

This creates a file Shortcut to evm.exe.lnk on your iPAQ. Copy this file to a directory on your PC, and open it with a text editor such as Notepad. The contents of the file will look like:

18#"\Windows\evm.exe"

You can now edit this file to add command-line parameters. For example, to run the supplied PrimTest example, you could edit the file to be:

18#"\Windows\evm.exe" -cp \Windows\lib\jeodedemos.jar PrimTest

You can add other command-line options to the shortcut as required, up to 255 characters.

You can now copy the shortcut back to the iPAQ, then tap on it to run the Primitives Test application.

You can use JeodeRuntime shortcuts (in \Windows\Start Menu\Programs\Jeode) as examples.

Command-line options

• -?
• -classpath or -cp
• -D
• -v or -verbose
• -version
• -Xnowinceconsole

-?, -h or -help
Displays help for all JeodeRuntime command-line options.
Best viewed using the -Djeode.evm.console.local.paging=TRUE option.

-classpath <pathnames> or -cp <pathnames>
Specify the path(s) used for loading application classes. The pathnames are separated by semi-colons.
For example, to include classes contained in jeodedemos.jar, you could use the command:
-cp \Windows\lib\jeodedemos.jar

-D<propertyName>=<value>
Supplies the value for a JeodeRuntime or standard Java system property.
For example, to keep the display console open, use the command:
-Djeode.evm.console.local.keep=TRUE

-v, -verbose
Causes messages to be displayed on the JeodeRuntime console when:

• A class file or dynamic library is successfully loaded.
• A garbage collection cycle is performed.

-version
Displays JeodeRuntime version information on the EVM console.

-Xnowinceconsole
Use the -Xnowinceconsole option to disable the EVM console if you do not want to see it - for example, when running graphical applications.

FAQ

• Why does my applet not work?
• Why do I get a "Failed to run applet" message?
• Does JeodeRuntime work with JavaScript?
• Can I discard some JeodeRuntime files to save memory?
• How do I define classpath settings?
• Is Swing supported?
• How do I prevent the console from closing when the EVM terminates?
• Why can't my program find a data file?
• Why do I get a 'NoClassDefFoundError' message?

Why does my applet not work?

• Applets in CAB files
  JeodeRuntime does not currently support loading applets from Microsoft CAB files, as CAB files are not part of standard Java technology. So if the web site makes assumptions (based on the type of browser) about the behavior of the VM being used, this may result in problems loading the applet.

• Applets in JAR or ZIP files
  JeodeRuntime does support use of applets contained in JAR or ZIP files.

  However, because Pocket Internet Explorer is compatible with the HTML 3.2 Specification, Pocket Internet Explorer does not support using the ARCHIVE attribute of the APPLET tag in the HTML page calling the applet, and so Pocket Internet Explorer will not support loading applets from JAR or ZIP files under these circumstances.

  If you are able to rewrite the HTML in the web page calling the applet, you can use JAR and ZIP files, by specifying the archive as a parameter name as well as an ARCHIVE attribute (using <param name=archive>). For example:
  <param name=archive value=myclasses.jar>

  (An example of this technique is shown in \Windows\lib\Quasar.html, the HTML file calling the Quasar demonstration applet)

Why do I get a "Failed to run applet" message?

This means that the plug-in has detected a condition that prevents the applet from being run. There are various possibilities - one common problem is lack of memory on an iPAQ, as some applets are written assuming unlimited amounts of memory to be available.

The Jeode plug-in has no control over the memory requirements of the applet. If there is insufficient memory remaining for the plug-in to continue running, it will issue a message to the user and close down.

Does JeodeRuntime work with JavaScript?

Also, the Jeode plug-in does not currently support communications between JavaScript and Java applets. This means that applets which require this interaction will not work with JeodeRuntime.

Is Swing supported?

How do I define classpath settings?

Can I discard some JeodeRuntime files to save memory?

If your applet or application does not require internationalized locale support, you can discard the i18n_a.jar file. Also, if your application does not use graphics (AWT), you can discard the evmawt.dll and awt.jar files.

Both .jar files are stored in the lib subdirectory of your installed JeodeRuntime directory - for example, \Windows\lib. The evmawt.dll file is stored in the top-level JeodeRuntime directory - for example, \Windows.

Note: if you then try to run an applet or application that requires either of these pieces of functionality, the applet or application will not run correctly, and may generate an appropriate error message. To replace these files once deleted, you must re-install JeodeRuntime.

How do I prevent the console from closing when the EVM terminates?

You can also use the -Djeode.evm.console.local.paging=TRUE command-line option in a similar manner, to enable console paging - this is useful if your application sends more than one screen of information to the console; for example, when showing the JeodeRuntime help with the -? option.

Why can't my program find a data file?

Why do I get a 'NoClassDefFoundError' message?

However, if you get a message of the form:
Exception in thread "main", java.lang.NoClassDefFoundError: LocalizedError at ConvertEncoding.main (bytecode 146)

you may need to install extra internationalization support (the file i18n_b.jar) - see the Notes on internationalization section for details.

Notes on internationalization

• i18n_a.jar
  This file is installed onto your iPAQ device by default (but can be removed to save space if required). This file contains the most commonly-used parts of internationalization support, including:
  • International time and date format.
  • Time zone.
  • International currency symbols.
  • Character sorting information.

• i18n_b.jar
  This file is not installed onto your iPAQ device, but is stored on the JeodeRuntime directory on your PC - for example, in: C:\Program Files\Insignia Solutions Plc\JeodeForIPAQInstaller\i18n_b.jar. This file contains the least-commonly used parts of internationalization support, consisting of character encoding and conversion tables.

As i18n_b.jar is not commonly-used, we have not installed it on your iPAQ, to minimize the JeodeRuntime memory footprint - this will allow you to allocate more of your iPAQ's memory to run applications and applets.

If you need the extra support provided by i18n_b.jar, simply copy the file from your PC to the lib subdirectory of your installed Jeode product (for example, \Windows\lib) on your iPAQ. This support will then be available the next time you launch JeodeRuntime.

Note: typically, you will only need i18n_b.jar to run an application that needs to convert files from one character set to another (for example, to convert Shift-JIS to Unicode).

Further information

• JeodeRuntime on other platforms
• Jeode development environment

JeodeRuntime on other platforms

JeodeRuntime is also available on a number of other platforms - for more information, please contact Insignia Solutions.

Jeode development environment

Insignia Solutions also offers a version of the Jeode product suitable for a development environment, which includes extra tools, enhanced documentation, premier technical support, and other variants of JeodeRuntime. If you are interested in purchasing development seats of the Jeode platform for your development project, please contact Insignia Solutions.

Disclaimer

Reasonable efforts have been made to ensure the information in this documentation is accurate and up to date. However, Insignia will not be responsible for any errors or omissions.

Copyright

Insignia Solutions specifically retains title to and interest in all Insignia software.

The JeodeRuntime software is furnished under a license agreement and may only be installed, used, or copied in accordance with the terms of that agreement. Some or all of this work is covered by patent.

All use of this product is strictly limited by the terms of the associated license agreement. Some of the functions described here may not be applicable to your system, depending on how your system is configured.

Trademarks and acknowledgements

Insignia and Insignia Solutions are registered trademarks and Jeode, EVM, Embedded Virtual Machine, and JeodeRuntime trademarks of Insignia Solutions, Inc.

Sun and Java are registered trademarks of Sun Microsystems.

Windows is a registered trademark of Microsoft Corporation.

iPAQ is a registered trademark of Compaq Computer Corporation.