AS/400 Developer Kit for Java




AS/400 Developer Kit for Java

© Copyright International Business Machines Corporation 1998, 1999. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Chapter 1. AS/400 Developer Kit for Java 1 Java file authorities in the integrated file system . . 41
Print this topic. . . . . . . . . . . . . . 2 Java character encodings . . . . . . . . . . 41
What’s new in V4R5 for AS/400 Developer Kit for File.encoding values and AS/400 CCSID . . . 42
Java . . . . . . . . . . . . . . . . . 3 Java Naming and Directory Interface . . . . . . 47
How to see what’s new or changed: . . . . . 3 Java Virtual Machine Debug Interface . . . . . 48
What’s new in V4R5 for Java Development Kit Limitations, restrictions, and unique behaviors . . 48
(JDK) 1.1.8 . . . . . . . . . . . . . . 3 The Java platform . . . . . . . . . . . . 49
What’s new in V4R5 for Java 2 Software Java applications and applets . . . . . . . 50
Development Kit (J2SDK), Standard Edition, Java virtual machine . . . . . . . . . . 50
version 1.2 . . . . . . . . . . . . . . 4 Java class files . . . . . . . . . . . . 51
Java ZIP files . . . . . . . . . . . . . 51
Chapter 2. Getting started with the Java JAR files. . . . . . . . . . . . . 51
Java interpreter . . . . . . . . . . . . 52
AS/400 Developer Kit for Java . . . . . 7 Java threads . . . . . . . . . . . . . 52
Installing the AS/400 Developer Kit for Java. . . . 7 Sun Microsystems, Inc. Java Development Kit . . . 53
Support for multiple Java Development Kits Java packages . . . . . . . . . . . . 54
(JDKs) . . . . . . . . . . . . . . . 8 Java tools . . . . . . . . . . . . . . 55
Configuring AS/400 for the AS/400 Developer Kit Native methods and the Java Native Interface . . 55
for Java . . . . . . . . . . . . . . . . 9
Running your first Hello World Java program . . . 10
Creating, compiling, and running a Hello World
Chapter 4. Commands and tools for the
Java program . . . . . . . . . . . . . . 10 AS/400 Developer Kit for Java. . . . . 57
Creating and running Java programs with the Java tools that are supported by the AS/400
AS/400 Developer Kit for Java . . . . . . . . 11 Developer Kit for Java . . . . . . . . . . . 57
Java classpath . . . . . . . . . . . . 12 Java ajar tool . . . . . . . . . . . . . 58
Selecting which mode to use when running a Java appletviewer tool . . . . . . . . . . 58
Java program . . . . . . . . . . . . . 15 Running the Java appletviewer tool with Remote
Creating and editing Java source files. . . . . . 16 Abstract Window Toolkit . . . . . . . . . 59
Downloading and installing Java packages on Java extcheck tool . . . . . . . . . . . 59
AS/400 . . . . . . . . . . . . . . . . 17 Java jar tool . . . . . . . . . . . . . 59
Release to release compatibility . . . . . . . . 19 Java jarsigner tool . . . . . . . . . . . 60
Java javac tool . . . . . . . . . . . . 60
Chapter 3. AS/400 Developer Kit for Java javadoc tool . . . . . . . . . . . 60
Java javah tool . . . . . . . . . . . . 61
Java concepts . . . . . . . . . . . 21 Java javakey tool . . . . . . . . . . . 61
Java transformer. . . . . . . . . . . . . 23 Java javap tool . . . . . . . . . . . . 62
AS/400 Developer Kit for Java advanced garbage Java keytool . . . . . . . . . . . . . 62
collection . . . . . . . . . . . . . . . 24 Java native2ascii tool . . . . . . . . . . 63
Java garbage collection . . . . . . . . . 24 Java policytool . . . . . . . . . . . . 63
AS/400 Java runtime environment. . . . . . 25 Java rmic tool . . . . . . . . . . . . 63
AS/400 Developer Kit for Java Remote Abstract Java rmid tool . . . . . . . . . . . . 64
Window Toolkit . . . . . . . . . . . . . 26 Java rmiregistry tool . . . . . . . . . . 64
AS/400 Developer Kit for Java Class Broker for Java 26 Java serialver tool . . . . . . . . . . . 64
Just-In-Time compiler . . . . . . . . . . . 27 Java tnameserv tool. . . . . . . . . . . 64
Comparison of Just-In-Time compiler and direct Java command in Qshell . . . . . . . . . 65
execution . . . . . . . . . . . . . . 27 CL commands that are supported by Java . . . . 66
Comparison of Integrated Language Environment Create Java Program (CRTJVAPGM) command 66
and Java . . . . . . . . . . . . . . . 27 Change Java Program (CHGJVAPGM) command 75
Running Java in a batch job . . . . . . . . . 28 JAVA command . . . . . . . . . . . . 79
Java classes, packages, and directories . . . . . 29 Run Java (RUNJVA) command . . . . . . . 79
Java system properties. . . . . . . . . . . 30 Delete Java Program (DLTJVAPGM) command . 85
Java system properties for Java Development Kit Dump Java Virtual Machine (DMPJVM)
(JDK) 1.1.8. . . . . . . . . . . . . . 30 command . . . . . . . . . . . . . . 86
Java system properties for Java 2 Software Display Java Program (DSPJVAPGM) command 89
Development Kit (J2SDK), Standard Edition, Operations Navigator commands that are supported
version 1.2. . . . . . . . . . . . . . 34 by Java . . . . . . . . . . . . . . . . 93
Files in the integrated file system . . . . . . . 40

© Copyright IBM Corp. 1998, 1999 iii

Chapter 5. Using Java with other Chapter 7. Accessing databases using
programming languages . . . . . . . 95 AS/400 Developer Kit for Java DB2
Using the Java Native Interface for native methods 96 SQLJ support . . . . . . . . . . . 133
Java native methods and threads considerations 98 SQLJ tools . . . . . . . . . . . . . . 133
Strings in native methods. . . . . . . . . 99 DB2 SQLJ restrictions. . . . . . . . . . . 133
Examples: Using the Java Native Interface for Embedding SQL statements in your Java
native methods . . . . . . . . . . . . 101 application . . . . . . . . . . . . . . 134
Using java.lang.Runtime.exec() . . . . . . . 105 Compiling and running SQLJ programs . . . . 135
Example: Calling another Java program with Host variables in Structured Query Language
java.lang.Runtime.exec() . . . . . . . . . 106 for Java . . . . . . . . . . . . . . 136
Example: Calling a CL program with Structured Query Language for Java profiles 136
java.lang.Runtime.exec() . . . . . . . . . 107 The structured query language for Java (SQLJ)
Example: Calling a CL command with translator (sqlj) . . . . . . . . . . . . . 139
java.lang.Runtime.exec() . . . . . . . . . 107 Precompiling SQL statements in a profile using the
Interprocess communication examples . . . . . 108 DB2 SQLJ profile customizer, db2profc . . . . . 139
Using sockets for interprocess communication 108 Printing the contents of DB2 SQLJ profiles
Using input and output streams for interprocess (db2profp and profp) . . . . . . . . . . . 143
communication . . . . . . . . . . . . 111 The SQLJ profile auditor installer (profdb). . . . 143
Calling Java from other languages . . . . . 113 Converting a serialized profile instance to Java
Java Invocation API . . . . . . . . . . . 114 class format using the SQLJ profile conversion tool
Invocation API functions . . . . . . . . 115 (profconv) . . . . . . . . . . . . . . 144
Support for multiple Java virtual machines . . 117
Example: Java Invocation API . . . . . . . 117 Chapter 8. Running your Java
application on a host that does not
Chapter 6. Accessing your AS/400
have a graphical user interface. . . . 145
database with the AS/400 Developer Setting up the Remote Abstract Window Toolkit for
Kit for Java JDBC driver . . . . . . 121 Java on a remote display . . . . . . . . . 145
Registering the AS/400 Developer Kit for Java Example: Setting up the Remote Abstract
JDBC driver before using JDBC . . . . . . . 122 Window Toolkit for Java on a Windows remote
Connecting to an AS/400 database using the display . . . . . . . . . . . . . . 146
AS/400 Developer Kit for Java JDBC driver . . . 123 Making the Remote Abstract Window Toolkit
Examples: Connecting to an AS/400 database for Java class files accessible to the remote
using the AS/400 Developer Kit for Java JDBC display . . . . . . . . . . . . . . 147
driver . . . . . . . . . . . . . . . 123 Adding RAWTGui.zip or RAWTGui.jar to the
Creating a JDBC application . . . . . . . . 124 CLASSPATH of the remote display . . . . . 147
Example: Creating a JDBC application . . . . 124 Starting the Remote Abstract Window Toolkit
Statement interface for AS/400 Developer Kit for for Java on a remote display . . . . . . . 148
Java . . . . . . . . . . . . . . . . 126 Running a Java program using Remote Abstract
Example: Statement interface for AS/400 Window Toolkit . . . . . . . . . . . 149
Developer Kit for Java . . . . . . . . . 126 Printing with the Remote Abstract Window
PreparedStatement interface for AS/400 Developer Toolkit. . . . . . . . . . . . . . . 151
Kit for Java . . . . . . . . . . . . . . 127 Remote Abstract Window Toolkit properties . . 151
Example: PreparedStatement interface for Remote Abstract Window Toolkit
AS/400 Developer Kit for Java . . . . . . 127 SecurityManager restrictions . . . . . . . 152
CallableStatement interface for AS/400 Developer Setting up the Class Broker for Java on a remote
Kit for Java . . . . . . . . . . . . . . 128 display . . . . . . . . . . . . . . . 152
Example: CallableStatement interface for AS/400 Installing Class Broker for Java on AS/400 . . 153
Developer Kit for Java . . . . . . . . . 128 Installing Class Broker for Java on Windows or
ResultSet interface for AS/400 Developer Kit for UNIX . . . . . . . . . . . . . . . 153
Java . . . . . . . . . . . . . . . . 128 Package content of cbj_1.1.jar . . . . . . . 154
Example: ResultSet interface for AS/400
Developer Kit for Java . . . . . . . . . 129 Chapter 9. Java security. . . . . . . 157
DatabaseMetaData interface for AS/400 Developer
Java security model . . . . . . . . . . . 157
Kit for Java . . . . . . . . . . . . . . 129
Making a Java application secure with secure
Example: DatabaseMetaData interface for
sockets layer . . . . . . . . . . . . . 158
AS/400 Developer Kit for Java . . . . . . 130
Preparing AS/400 for secure sockets layer
Blob interface for the AS/400 Developer Kit for
support . . . . . . . . . . . . . . 158
Java . . . . . . . . . . . . . . . . 130
Choosing a digital certificate to use . . . . . 160
Clob interface for the AS/400 Developer Kit for
Using the digital certificate when you run your
Java . . . . . . . . . . . . . . . . 131
Java application . . . . . . . . . . . 160

iv AS/400 Developer Kit for Java

 Modifying your Java code to use socket Performance Data Collector tool . . . . . . . 180
factories . . . . . . . . . . . . . . 162 Java Performance Data Converter tool . . . . 181
Modifying your Java code to use secure sockets Running the Java Performance Data Converter 181
layer . . . . . . . . . . . . . . . 165
Chapter 12. Debugging programs
Chapter 10. Creating an using the AS/400 Developer Kit for
internationalized Java program. . . . 169 Java . . . . . . . . . . . . . . . 183
Java locales . . . . . . . . . . . . . . 169 Debugging a Java program . . . . . . . . . 183
Example: Internationalization of dates using the Debugging Java programs by using the *DEBUG
java.util.DateFormat class . . . . . . . . . 171 option . . . . . . . . . . . . . . . 184
Example: Internationalization of numeric display Initial debugging displays for Java programs 184
using the java.util.NumberFormat class. . . . . 171 Setting breakpoints . . . . . . . . . . 185
Example: Internationalization of locale-specific data Stepping through Java programs to debug. . . 186
using the java.util.ResourceBundle class . . . . 172 Debugging Java and native method programs . . 188
Debugging a Java program from another display 188
Chapter 11. Tuning Java program QIBM_CHILD_JOB_SNDINQMSG environment
performance with the AS/400 variable . . . . . . . . . . . . . . 189
Developer Kit for Java . . . . . . . 175 Debugging servlets . . . . . . . . . . . 190
Java runtime performance considerations . . . . 176
Java transformation performance considerations 176 Chapter 13. Troubleshooting the
Java garbage collection performance considerations 177 AS/400 Developer Kit for Java . . . . 191
Java Native Method Invocation performance Finding job logs for Java problem analysis. . . . 191
considerations . . . . . . . . . . . . . 177 Collecting data for Java problem analysis . . . . 192
Java method inlining performance considerations 177 Getting support for the AS/400 Developer Kit for
Java exception performance considerations . . . 178 Java . . . . . . . . . . . . . . . . 193
Java event trace performance tools . . . . . . 178
Java call trace performance tools . . . . . . . 178 Chapter 14. Code examples for the
Java profiling performance tools . . . . . . . 179 AS/400 Developer Kit for Java . . . . 195
Collecting Java performance data . . . . . . 179

Contents v
vi AS/400 Developer Kit for Java
Chapter 1. AS/400 Developer Kit for Java

What it is:

The AS/400 Developer Kit for Java is optimized for use in an AS/400 server
environment. It utilizes the compatibility of Java programming and user interfaces,
so you can develop your own applications for the AS/400 system.

The AS/400 Developer Kit for Java allows you to create and run Java programs on
AS/400. The AS/400 Developer Kit for Java is a compatible implementation of the
Sun Microsystems, Inc. Java Technology, so we assume that you are familiar with
their Java Development Kit (JDK) documentation. To make it easier for you to
work with their information and ours, we provide links to Sun Microsystems,
Inc.’s information.

If for any reason our links to Sun Microsystems, Inc. Java Development Kit
documentation do not work, refer to their HTML reference documentation for the
information that you need. You can find this information on the World Wide Web

at The Source for Java Technology java.sun.com.

How to use these pages:

Select any of these topics for more details on how to use the AS/400 Developer Kit
for Java:
v Print this topic provides details on how to download a printable PDF file or a
zipped package of AS/400 Developer Kit for Java HTML files.
v What’s new in V4R5 highlights the latest product and information updates.
v Getting started gives information about installation, configuration, how to create
and run simple Hello World Java programs, downloading and installing, and
release to release compatibility.
v Concepts introduces the specific concepts that you should be familiar with when
using the AS/400 Developer Kit for Java. Also provides very basic Java
definitions for those who are looking for general details.
v Commands and tools provides details on how to use the Java commands and
Java tools.
v Other programming languages shows you how to call code that was written in
languages other than Java by using Java Native Interface (JNI),
java.lang.Runtime.exec(), interprocess communication, and the Java Invocation
API.
v JDBC driver explains how the AS/400 Developer Kit for Java JDBC driver
allows Java programs to access AS/400 database files.
v SQLJ support explains how the AS/400 Developer Kit for Java allows you to use
SQL statements that are embedded in your Java application.

© Copyright IBM Corp. 1998, 1999 1

 v Running on a host without a GUI contains information about how to set up and
run Java programs with the Remote Abstract Window Toolkit (AWT) or Class
Broker for Java.
v Security provides details on adopted authority and explains how you can use
SSL to make socket streams secure in your Java application.
v Internationalization gives instructions on how to customize a Java program for a
specific region of the world.
v Performance provides information about how to tune your Java performance.
v Debugging explains how to debug Java programs.
v Troubleshooting shows you how to find job logs and collect data for Java
program analysis. This topic also provides information about program
temporary fixes (PTFs) and getting support for the AS/400 Developer Kit for
Java.
v Code examples links directly to all of the code examples in this information.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Print this topic

You can view or download a PDF version of this document for viewing or
printing. You must have Adobe(R) Acrobat(R) Reader installed to view PDF files.

You can download a copy from Adobe .

To view or download the PDF version, select AS/400 Developer Kit for Java (about
943 KB or 176 pages).

To save a PDF on your workstation for viewing or printing:

1. Open the PDF in your browser (click the link above).
2. In the menu of your browser, click File.
3. Click Save As...
4. Navigate to the directory in which you would like to save the PDF.
5. Click Save.
Download a zipped package of this document

To download a zipped package of the AS/400 Developer Kit for Java HTML files
to your workstation:
1. Ensure your hard drive has at least 5.0 MB of storage space:
2. Create a new directory on your hard drive.
3. Download the package. The package size is about 412 KB.
a. Select the Save to disk option.
b. Select a temporary directory as the destination for the download.
c. Click OK.
4. Unzip the package into the directory you created in step 2.
5. Open devkit.htm with your browser to view the reference.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

2 AS/400 Developer Kit for Java

What’s new in V4R5 for AS/400 Developer Kit for Java
This topic highlights changes to the AS/400 Developer Kit for Java in V4R5.
We highlight Java Development Kit (JDK) 1.1.8 and Java 2 Software Development
Kit (J2SDK), Standard Edition, version 1.2 changes. If you are already familiar
with this information, you can link to the version of your choice for new updates:
v Java Development Kit (JDK) 1.1.8
v Java 2 Software Development Kit (J2SDK), Standard Edition, version 1.2
How to see where you are in our information:

The small links at the top of each page show you where you are in our
information. These links are displayed in a directory structure format. To see where
you are, read through the links. For example, if you look at the top of this page,
you see:

AS/400 Developer Kit for Java \ What’s new

These links tell you that you are in the “What’s new” information under the
“AS/400 Developer Kit for Java” topic.

How to see what’s new or changed:

To help you see where technical changes have been made, this information uses:

v The image to mark where new or changed information begins.

v The image to mark where new or changed information ends.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

What’s new in V4R5 for Java Development Kit (JDK) 1.1.8

This topic highlights changes to the AS/400 Developer Kit for Java in V4R5 for the
Java Development Kit (JDK) 1.1.8.

Getting started:
v See multiple JDK support for information on each JDK that IBM supports.
v See Java classpath for details on how to properly set your classpath for JDK 1.1.x
or J2SDK.
Tools and commands:
v The Java ajar tool was added to the list of Java tools that are supported by the
AS/400 Developer Kit for Java.
v See the Java appletviewer tool for new details about how to run the
appletviewer tool with Remote Abstract Window Toolkit.
v The new Dump Java Virtual Machine (DMPJVM) command was added to dump
information about the Java virtual machine for a job that you specify.
v The TGTRLS parameter was added to the Create Java Program (CRTJVAPGM)
command.
v The SUBTREE parameter was added to the Change Java Program
(CHGJVAPGM) command.

Chapter 1. AS/400 Developer Kit for Java 3

 v The JIT option was added to the OPTIMIZE parameter and the INTERPRET
parameter of the Run Java (RUNJVA) command.
v A display example with descriptions of each field was added to the Display Java
Program (DSPJVAPGM) command.
Running on a host without a GUI:
v
See the setting up the Remote Abstract Window Toolkit topic for updates.
v
If you want to run your Java application on a host that does not have a
graphical user interface (GUI), such as an AS/400 system, you can use either the
Remote Abstract Window Toolkit (AWT) or the Class Broker for Java (CBJ). You
can use the CBJ for high performance GUI services. Since Remote AWT is not
recommended for complex graphics or highly-interactive operations, you can use
the CBJ instead, which was designed for these environments. To use CBJ, see
setting up Class Broker for Java.
Debugging:
v Added details about how to debug servlets.
Code examples:
v More code examples were added.
Print this topic:
v See print this topic for a PDF of the AS/400 Developer Kit for Java information.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

What’s new in V4R5 for Java 2 Software Development Kit

(J2SDK), Standard Edition, version 1.2
This topic highlights changes to the AS/400 Developer Kit for Java in V4R5 for the
Java 2 Software Development Kit (J2SDK), Standard Edition, version 1.2.

Note: In this section, we only discuss changes that are unique or interesting in the
J2SDK, version 1.2. The general information on updates from the What’s new for
Java Development Kit (JDK) 1.1.8 topic also apply to J2SDK, version 1.2.

Getting started:
v See multiple JDK support for information on each JDK that IBM supports.
v See Java classpath for details on how to properly set your classpath for JDK 1.1.x
or J2SDK.
v The selecting which mode to use when running a Java program topic was added
to explain the difference between running a Java program with interpreted,
direct execution, or Just-In-Time compile.
v For information about the Java extensions framework, see downloading and
installing Java packages on AS/400 and installing extensions for the AS/400
Developer Kit for Java.
Concepts:
v See Class Broker for Java for overview information on how to run Java
applications on a host that does not have a graphical user interface (GUI).
v Support for a Just-In-Time compiler that improves performance by compiling
code as you need it was added.

4 AS/400 Developer Kit for Java

v New system properties for J2SDK were added.
v Support for the Java Virtual Machine Debug Interface was added.
Commands and tools:
v See the Java appletviewer tool for new details about how to run the
appletviewer tool with Remote Abstract Window Toolkit.
v The Java extcheck tool, Java jarsigner tool, Java keytool, Java policytool, Java
rmid tool, and the Java tnameserv tool were added to the list of Java tools that
are supported by the AS/400 Developer Kit for Java.
v The Java javakey tool is now obsolete in J2SDK, version 1.2.
Accessing databases using AS/400 Developer Kit for Java DB2 SQLJ support
v The accessing databases using AS/400 Developer Kit for Java DB2 SQLJ support
information has been revised.
v The SQLJ translator tool allows you to generate SQLJ profiles from your Java
source code.
v The DB2 SQLJ profile customizer allows you to customize SQLJ profiles.
v The DB2 SQLJ profile printer tool allows you to print SQLJ profiles.
v The SQLJ profile auditor installer tool allows you to install SQLJ profile autitors
over your SQLJ profiles.
v The SQLJ profile conversion tool allows you to convert a serialized profile
instance to Java class format.
v Embedding SQL Statements in your Java application shows you how you can
embed SQL statements into your Java source code.
v Compiling and running SQLJ Programs shows you how to compile and run
your SQLJ programs.
Running on a host without a GUI:
v
See the setting up the Remote Abstract Window Toolkit topic for updates.
v
If you want to run your Java application on a host that does not have a
graphical user interface (GUI), such as an AS/400 system, you can use either the
Remote Abstract Window Toolkit (AWT) or the Class Broker for Java (CBJ). You
can use the CBJ for high performance GUI services. Since Remote AWT is not
recommended for complex graphics or highly-interactive operations, you can use
the CBJ instead, which was designed for these environments. To use CBJ, see
setting up Class Broker for Java.
Debugging:
v Added details about how to debug servlets.
Code examples:
v More code examples were added.
Print this topic:
v See print this topic for a PDF of the AS/400 Developer Kit for Java information.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 1. AS/400 Developer Kit for Java 5

6 AS/400 Developer Kit for Java
Chapter 2. Getting started with the AS/400 Developer Kit for
Java
If you have not yet used the AS/400 Developer Kit for Java, follow these steps to
install it, configure it, and practice running a simple Hello World Java program.
1. If you are already familiar with the AS/400 Developer Kit for Java information,
see what’s new for links to the latest product updates and information.
2. Install the AS/400 Developer Kit for Java.
3. Configure your system.
4. If you are new to this information and have not yet used the AS/400 Developer
Kit for Java, see Running your first Hello World Java program. This topic
illustrates two methods of running a simple Hello World Java program with the
AS/400 Developer Kit for Java. It is a convenient way to see if you have
correctly installed the AS/400 Developer Kit for Java.
5. Now you are ready to create, compile and run your own Hello World Java
program. For how-to steps, see creating, compiling, and running a Hello World
Java program.
6. If you are interested in creating more of your own Java applications, read these
topics:
v Creating and running programs provides step-by-step instructions on how to
create and run your own Java programs.
v Creating and editing Java source files shows three different ways that you
can create and edit your Java source files.
v Downloading and installing Java packages on AS/400 helps you use Java
packages more effectively. It provides details about packages with graphical
user interface (GUI), integrated file system and case sensitivity, as well as ZIP
file handling and JAR file handling.
v Release to release compatibility provides information on compatibility from
one release to another.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Installing the AS/400 Developer Kit for Java

Installing the AS/400 Developer Kit for Java allows you to create and run Java
programs on AS/400.

To install the AS/400 Developer Kit for Java:

1. Enter the Go Licensed Program (GO LICPGM) command on the command line.
2. Select option 11 (Install licensed program).
3. Choose option 1 (Install) for licensed program (LP) 5769-JV1 *BASE, and select
the option that matches the Java Development Kit (JDK) that you want to
install. If the option that you wish to install is not displayed in the list, you can
add it to the list by entering option 1 (Install) in the option field. Enter 5769JV1
in the licensed program field and your option number in the product option
field. IBM supports multiple JDKs.
Note: You can install more than one option at once.

© Copyright IBM Corp. 1998, 1999 7

 The AS/400 Developer Kit is licensed program (LP) number 5769-JV1.

Once you have installed the AS/400 Developer Kit for Java on your AS/400, you
may choose to configure your system.

See running your first Hello World Java program for information on getting started
with the AS/400 Developer Kit for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Support for multiple Java Development Kits (JDKs)

AS/400 supports multiple Java Development Kits (JDKs) and Java 2 SDK (J2SDK),
Standard Edition, version 1.2. AS/400 supports the use of multiple JDKs
simultaneously, but only through multiple Java virtual machines. A single Java
virtual machine runs one specified JDK.

Find the JDK that you are using or want to use, and select the coordinating option
to install. You can install more than one JDK at one time. The java.version system
property determines which JDK to run. However, when you change the
java.version system property it has no effect once a Java virtual machine is up and
running.

Option JDK java.home java.version

1 1.1.6 /QIBM/ProdData/Java400/jdk116/
1.1.6
2 1.1.7 /QIBM/ProdData/Java400/jdk117/
1.1.7
3 1.2* /QIBM/ProdData/Java400/jdk12/
1.2

4 1.1.8 1.1.8
/QIBM/ProdData/Java400/jdk118/

* Version 1.2 is the same as Java 2 SDK (J2SDK), Standard Edition, version 1.2.

For example, these are the results of which options you install and the command
you enter.

Install Enter Result

Option 1 (1.1.6) java Hello JDK 1.1.6 runs, because only
one JDK is installed and that
is your default.
Option 1 (1.1.6) java -Djava.version=1.1.7 Error stating that Option 2 is
Hello not installed.
Option 1 (1.1.6) and Option 2 java Hello JDK 1.1.8 runs, because the
(1.1.7) and Option 4 (1.1.8) most recent JDK 1.1.x is the
default.
Option 1 (1.1.6) and Option 2 java -Djava.version=1.1.7 JDK 1.1.7 runs.
(1.1.7) and Option 4 (1.1.8) Hello

8 AS/400 Developer Kit for Java

 Option 1 (1.1.6), Option 2 java -Djava.version=1.2 J2SDK, Standard Edition,
(1.1.7), and Option 3 (1.2) Hello version 1.2 runs. If you did
not specify java.version, the
latest 1.1.x (for example, JDK
1.1.7) is the default. For more
details on the java.version
property, see Java system
properties.
Option 3 (1.2) java Hello J2SDK, Standard Edition,
version 1.2 runs.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Configuring AS/400 for the AS/400 Developer Kit for Java

Once you have installed the AS/400 Developer Kit for Java on your AS/400, you
may choose to configure your system.

Time zone configuration

If your Java programs are sensitive to time of day, then time zone configuration
may be required.

If the Coordinated Universal Time Offset (QUTCOFFSET) system value is set to its
default (+00:00), then Java uses the AS/400 time as the current time. The default
value of the user.timezone Java system property setting is UTC.

A QUTCOFFSET system value and an updated locale are required for any of these:
v If QUTCOFFSET is not set to its default value, thus sensitive to time zone.
v If your Java code expects the user.timezone system property to default to a value
other than UTC.
v If you specify the user.timezone Java system property when running the java
command.
The LC_TOD category of the locale contains the tname field, which must be set to
the same value that matches your time zone. For details on how to create a locale
and format the tname field, see the AS/400 International Application Development,

SC41-5603 book.

System property configuration

Java system properties determine the environment in which the Java programs run.
They are similar to system values or environment variables in OS/400. A number
of properties are set when the Java virtual machine starts. You can choose to use
the system property default values or you can specify your own set of default
property values by doing either of these steps:
1. Provide a file in /QIBM/UserData/Java400, named SystemDefault.properties.
The property values that you specify in this file override the system defaults
that IBM provides. This file sets the default system properties for all Java
virtual machines that run on your AS/400 system.
2. Or, place a SystemDefault.properties file in your own user.home path. This file
and the properties that it contains override those in

Chapter 2. Getting started with the AS/400 Developer Kit for Java 9
 /QIBM/UserData/Java400/SystemDefault.properties. This file sets the default
system properties for all Java virtual machines that run for you.
See running your first Hello World Java program for information on getting started
with the AS/400 Developer Kit for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Running your first Hello World Java program

You can get your Hello World Java program up and running in either of these
ways:
1. You can simply run the Hello World Java program that was shipped with the
AS/400 Developer Kit for Java in the com.ibm.as400.system package.
To run the program that is included:
a. Check that the AS/400 Developer Kit for Java is installed by entering the
Go Licensed Program (GO LICPGM) command. Then, select option 10
(Displayed installed licensed programs). Verify that licensed program
5769-JV1 *BASE and at least one of the options are listed as installed.
b. Enter java com.ibm.as400.system.Hello on the AS/400 Main Menu
command line. Press Enter to run the Hello World Java program.
c. If the AS/400 Developer Kit for Java was installed correctly, Hello World
appears in the Java Shell Display. Press F3 (Exit) or F12 (Exit) to return to
the command entry display.
d. If the Hello World class does not run, check to see that the installation was
completed successfully, or see getting support for the AS/400 Developer Kit
for Java for service information.
2. You can also run your own Hello Java program. For more information about
how to create your own Hello Java program, see creating, compiling, and
running a Hello World Java program.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Creating, compiling, and running a Hello World Java program

Creating the simple, Hello World Java program is a great place to start when
becoming familiar with the AS/400 Developer Kit for Java.

To create, compile, and run your own Hello World Java program:
1. Create the source file as an American National Standard Code for Information
Interchange (ASCII) text file in the integrated file system.
a. Name your text file Hello.java. For more information about how you can
create and edit your file, see creating and editing Java source files.
b. Make sure that your file contains this source code:
class Hello {
public static void main (String args[]) {
System.out.println(“Hello World”);
}
}
2. Compile the source file.

10 AS/400 Developer Kit for Java

 a. Enter the Work with Environment Variable (WRKENVVAR) command to
check the CLASSPATH environment variable. If the CLASSPATH variable
does not exist, add it and set it to ’.’ (the current directory). If the
CLASSPATH variable does exist, make sure that the ’.’ is at the beginning of
the path name list. For details about the CLASSPATH environment variable,
see Java classpath.
b. Enter the Start Qshell (STRQSH) command to start the Qshell Interpreter.
c. Use the change directory (cd) command to change the current directory to
the integrated file system directory that contains the Hello.java file.
d. Enter javac followed by the name of the file as you have it saved on your
disk. For example, enter javac Hello.java.
3. Run the class file.
a. Enter java followed by Hello to run your Hello.class with the Java virtual
machine. For example, enter java Hello.
b. “Hello World” prints to your screen if everything was entered correctly.
c. Press F3 (Exit) or F12 (Disconnect) to return to the command entry display.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Creating and running Java programs with the AS/400 Developer Kit for
Java
You can create Java application and applet programs by using the AS/400
Developer Kit for Java. You can also use Sun Microsystems, Inc. Java Development
Kit (JDK) that is available on a workstation.

To create a Java program:

1. Create a source code file by using an editor that supports American National
Standard Code for Information Interchange (ASCII) text files.
2. Compile the source file into a class file by using the Java compiler tool, which
is javac.
Note: Java class files are portable across platforms, so the Java source file can
compile on a workstation that also has a javac. After the source files are
compiled, the class files are transferred to the integrated file system.
3. Set the file authorities on the class file in the integrated file system.
4. Optimize the Java program by using the Create Java Program (CRTJVAPGM)
command.
Note: This step is optional.
To run a Java program:
1. Ensure that your Java classpath is set up correctly.
2. Use the Run Java (RUNJVA) command or JAVA command on AS/400, or the
java command in Qshell to run the Java program. Then, select which mode
you want to use to run your Java program. You can either set the mode by
setting a system property with the Java command, or by setting the
environment variable before you run the Java command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 2. Getting started with the AS/400 Developer Kit for Java 11
 Java classpath
The Java virtual machine uses the Java classpath to find classes during runtime.
Java commands and tools also use the classpath to locate classes. The default
system classpath, the CLASSPATH environment variable, and the classpath
command parameter all determine what directories are searched when looking for
a particular class.

Note: In In Java 2 Software Development Kit (J2SDK), Standard Edition,

version 1.2, the java.ext.dirs property determines the classpath for the extensions
that will be loaded. See Installing extensions for the AS/400 Developer Kit for Java
for more information.

The default system classpath is system-defined and you cannot change it. On
AS/400, the default classpath specifies where to find the classes that are part of the
AS/400 Developer Kit, the Remote Abstract Window Toolkit (AWT), and other
system classes.

To find any other classes on the system, you must specify the classpath to search
by using the CLASSPATH environment variable or the classpath parameter. The
classpath parameter that is used on a tool or command overrides the value that is
specified in the CLASSPATH environment variable.

You can work with the CLASSPATH environment variable using the Work with
Environment Variable (WRKENVVAR) command. From the WRKENVVAR display,
you can add or change the CLASSPATH environment variable. The Add
Environment Variable (ADDENVVAR) command and Change Environment
Variable (CHGENVVAR) command either add or change the CLASSPATH
environment variable.

The value of the CLASSPATH environment variable is a list of path names,

separated by colons(:), which are searched to find a particular class. A path name is
a sequence of zero or more directory names. These directory names are followed
by the name of the directory, the ZIP file, or the JAR file that is to be searched in
the integrated file system. The components of the path name are separated by the
slash (/) character. Use a period (.) to indicate the current working directory.

You can set the CLASSPATH variable in the Qshell environment by using the
export utility that is available using the Qshell Interpreter.

These commands add the CLASSPATH variable to your environment and set it to
the value “ .:/myclasses.zip:/Product/classes.”
v This command sets the CLASSPATH variable in the Qshell environment:
export -s CLASSPATH=.:/myclasses.zip:/Product/classes
v This command sets the CLASSPATH variable from the command line:
ADDENVVAR ENVVAR(CLASSPATH) VALUE(“.:/myclasses.zip:/Product/classes”)
J2SDK searches for classes differently than JDK 1.1.x. JDK 1.1.x searches the system
classpath first, then any user-specified classpaths. J2SDK searches the bootstrap
classpath first, then the extension directories, then the classpath.

So, the search order for JDK 1.1.x, using the example code above, is:
1. The default system classpath,
2. The current working directory,

12 AS/400 Developer Kit for Java

3. The myclasses.zip file that is located in the “root” (/) file system,
4. The classes directory in the Product directory in the “root” (/) file system.
The search order for J2SDK, using the example code above, is:
1. The bootstrap classpath, which is in the sun.boot.class.path property,
2. The extension directories, which is in the java.ext.dirs property,
3. The default system classpath,
4. The current working directory,
5. The myclasses.zip file that is located in the “root” (/) file system,

6. The classes directory in the Product directory in the “root” (/) file system.
When entering the Qshell environment, the CLASSPATH variable is set to the
environment variable. The classpath parameter specifies a list of path names. It has
the same syntax as the CLASSPATH environment variable. A classpath parameter
is available on these tools and commands:
v java command in Qshell
v javac tool
v javah tool
v javap tool
v javadoc tool
v rmic tool
v Run Java (RUNJVA) command
For more information about the above commands, see commands and tools. If you
use the classpath parameter with any of these command or tools, it ignores the
CLASSPATH environment variable.

You can override the CLASSPATH environment variable by using the

java.class.path property. You can change the java.class.path property, as well as
other properties, by using the SystemDefault.properties file. The values in the
SystemDefault.properties files override the CLASSPATH environment variable. For
information on the SystemDefault.properties file, see The SystemDefault.properties
file.

In JDK 1.1.x, the os400.class.path.system property also affects what is searched

when looking for classes. This property can contain one of three values: PRE,
POST, or NONE. By default, this property is set to PRE, which causes the default
system classpath to be searched before the path. The CLASSPATH environment
variable or the classpath parameter specify this path. If you set the
os400.class.path.system property to POST, the default system classpath is searched
after any user-specified classpath. If the value NONE is used, the default classpath
is not searched at all and only the user-specified classpath is searched.

Note: Use caution when specifying NONE or POST because unpredictable results
occur if a system class cannot be found or is incorrectly replaced by a user-defined
class. Therefore, you should allow the system default classpath to be searched
before any user-specified classpath.

See Java system properties for information about how to determine the
environment in which Java programs run.

Chapter 2. Getting started with the AS/400 Developer Kit for Java 13
 For more information, see the OS/400 Program and CL Command APIs, SC41-5870

book or the OS/400 Integrated File System Introduction.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

SystemDefault.properties file
The SystemDefault.properties file is a standard Java properties file. You can
specify default properties in a SystemDefault.properties file. The
SystemDefault.properties file that is in your home directory takes priority over the
SystemDefault.properties file that is in the /QIBM/UserData/Java400 directory.

You can specify the values of properties in the SystemDefault.properties file just
like you do in any Java properties file.

Example: SystemDefault.properties file

#Comments start with pound sign
#this means always run with JDK 1.2
java.version=1.2
#set my special property
myown.propname=6

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Installing extensions for the AS/400 Developer Kit for Java

Extensions are packages of Java classes that you can use to extend the
functionality of the core platform. Extensions are packaged in one or more ZIP files
or JAR files, and are loaded into the Java virtual machine by an extension class
loader.

The extension mechanism allows the Java virtual machine to use the extension
classes in the same way that the virtual machine uses the system classes. The
extension mechanism also provides a way for you to retreive extensions from
specified uniform resource locators (URLs) when they are not already installed in
the Java Development Kit (JDK) or Java 2 Runtime Environment, Standard Edition,
version 1.2.

The JAR files of an installed extension are located in the

QIBM/ProdData/Java400/ext directory. If you would like to install an extension,
enter this command:
ADDLNKOBJ('/QIBM/ProdData/Java400/ext/extensionToInstall.jar')
NEWLNK('/QIBM/UserData/Java400/ext/extensionToInstall.jar')
LNKTYPE(*SYMBOLIC)

Where extensionToInstall.jar is the name of the zip or JAR file that contains the
extension that you wish to install.

When you create a link to an extension by using the Add Link Object
(ADDLNKOBJ) command, the list of files that the extension class loader searches
changes for every Java virtual machine that is running on AS/400. If you do not want

14 AS/400 Developer Kit for Java

 to impact the extension class loaders for other Java virtual machines on AS/400,
but you still wish to create a link to an extension, follow these steps:
1. Create a directory to install the extensions.
Use either the Make Directory (MKDIR) command from the AS/400 command
line or the mkdir command from the Qshell Interpreter.
2. Install the extensions to the new directory using the ADDLNKOBJ command.
3. Add the new directory to the java.ext.dirs property.
You can add the new directory to the java.ext.dirs property by using the PROP
field of the JAVA command from the AS/400 command line.
If the name of your new directory is “/home/username/ext,” and the name of
your Java program is “Hello,” then the commands that you enter should look like
this:
MKDIR DIR('/home/username/ext')
ADDLNKOBJ('/QIBM/ProdData/Java400/ext/extensionToInstall.jar')
NEWLNK('/home/username/ext/extensionToInstall.jar')
LNKTYPE(*SYMBOLIC)
JAVA Hello PROP((java.ext.dirs '/home/username/ext'))

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Selecting which mode to use when running a Java program

When you run a Java program, you can select which mode you would like to
use. You can choose either interpreted, direct execution, or Just-In-Time (JIT)
compile.

Interpreted:

If you choose to run your Java program in the interpreted mode, the code is
verified and a Java program object is created to hold the pre-verified form of the
program. Each bytecode is interpreted at runtime.

For information on running your Java program in the interpreted mode, see the
Run Java (RUNJVA) command.

Direct Execution:

If you choose to run your Java program using direct execution, the code is verified
and a Java program object is created to hold the pre-verified form of the program.
Machine instructions for a method are generated during the first call to that
method, and saved for use the next time that the program runs. One copy is also
shared for the entire system.

For information on running your Java program using direct execution, see the Run
Java (RUNJVA) command.

Just-In-Time (JIT) compile:

If you choose to run your Java program using the Just-In-Time compiler, the code
is verified and an associated Java program is created to hold the pre-verified form

Chapter 2. Getting started with the AS/400 Developer Kit for Java 15
 of the program. Machine instructions for a method are generated during the first
call to that method, and saved for the duration of the Java virtual machine run.

To use the JIT compiler, you need to set the compiler value to jitc. You can set the
value by adding an environment variable or setting the java.compiler system
property. Select one method from the list below to set the compiler value:
v Add the environment variable by entering the Add Environment Variable
(ADDENVVAR) command on the AS/400 command line. Then, run your Java
program using the Run Java (RUNJVA) command or JAVA command. For
example, enter
ADDENVVAR ENVVAR (JAVA_COMPILER) VALUE(jitc)
JAVA CLASS(Test)
v Set the java.compiler system property on the AS/400 command line. For
example, enter JAVA CLASS(Test) PROP((java.compiler jitc))
v Set the java.compiler system property on the Qshell Interpreter command line.
For example, enter java -Djava.compiler=jitc Test
Once you set this value, the JIT compiler optimizes all of the Java code before
running it.

Just-In-Time (JIT) compile and Direct Execution:

The most common way to use the Just-In-Time (JIT) compiler, is with the jit_de
option. When running with this option, programs that have already been
optimized with direct execution, run in direct execution mode. Programs that have
not been optimized for direct optimization, run in JIT mode.

To use JIT and direct execution together, you need to set the compiler value to
jitc-de. You can set the value by adding an environment variable or setting the
java.compiler system property. Select one method from the list below to set the
compiler value:
v Add the environment variable by entering the Add Environment Variable
(ADDENVVAR) command on the AS/400 command line. Then, run your Java
program using the Run Java (RUNJVA) command or JAVA command. For
example, enter
ADDENVVAR ENVVAR (JAVA_COMPILER) VALUE(jitc_de)
JAVA CLASS(Test)
v Set the java.compiler system property on the AS/400 command line. For
example, enter JAVA CLASS(Test) PROP((java.compiler jitc_de))
v Set the java.compiler system property on the Qshell Interpreter command line.
For example, enter java -Djava.compiler=jitc_de Test
Once this value is set, the Java program for the class file that was created as direct
execution is used. If the Java program was not created as direct execution, the class
file is optimized by the JIT prior to running. For more information, see the
comparison of Just-In-Time compiler and direct execution.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Creating and editing Java source files

With Client Access:

16 AS/400 Developer Kit for Java

 Java source files are American National Standard Code for Information Interchange
(ASCII) text files in the integrated file system on AS/400.

You can create and edit a Java source file with Client Access and a
workstation-based editor.

On a workstation:

You can create a Java source file on a workstation. Then, transfer the file to the
integrated file system by using file transfer protocol (FTP).

To create and edit Java source files on a workstation:

1. Create the ASCII file on the workstation by using the editor of your choice.
2. Connect to AS/400 with FTP.
3. Transfer the source file to your directory in the integrated file system as a
binary file, so that the file remains in ASCII format.
With Source Entry Utility:

You can create a Java source file as a text file by using source entry utility (SEU).

To create a Java source file as a text file by using SEU:

1. Create a source file member by using SEU.
2. Use the Copy To Stream File (CPYTOSTMF) command to copy the source file
member to an integrated file system stream file, while converting the data to
ASCII.
If you need to make changes to the source code, change the database member by
using SEU and copy the file again.

For information on storing files, see files in the integrated file system.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Downloading and installing Java packages on AS/400

To download, install, and use Java packages more effectively on AS/400, see the
following:
v Packages with graphical user interfaces (page 17)
v Case sensitivity and integrated file system (page 17)
v ZIP file handling and JAR file handling (page 18)
v Java extensions framework (page 19)

Packages with graphical user interfaces:

Java programs used with graphical user interface (GUI) require the use of a
presentation device with graphical display capabilities. For example, you can use a
personal computer, technical workstation, or network computer. AS/400 provides a
Remote Abstract Window Toolkit (AWT) capability. This capability runs
applications on AS/400 by using a full range of graphical capabilities on the
appropriate Transmission Control Protocol/Internet Protocol (TCP/IP) attached
display device. For more specific installation, setup, and overall use information,
see setting up the Remote Abstract Window Toolkit.

Chapter 2. Getting started with the AS/400 Developer Kit for Java 17
 Case sensitivity and integrated file system:

Integrated file system provides file systems, which are both case-sensitive and
those that are not with regard to file names. QOpenSys is an example of a
case-sensitive file system within the integrated file system. Root, ’/’, is an example
of a case-insensitive file system. For more information about the integrated file
system, see the “File Systems” information in the OS/400 Integrated File System
Introduction.

ZIP file handling and JAR file handling:

ZIP files and JAR files contain a set of Java classes. When you use the Create Java
Program (CRTJVAPGM) command on one of these files, the classes are verified,
converted to an internal machine form, and if specified, transformed to AS/400
machine code. You can treat ZIP files and JAR files like any other individual class
file. When an internal machine form is associated with one of these files, it remains
associated with the file. The internal machine form is used on future runs in place
of the class file to improve performance. If you are unsure whether a current Java
program is associated your class file or JAR file, use the Display Java Program
(DSPJVAPGM) command to display information about your Java program on
AS/400.

In previous releases of the AS/400 Developer Kit for Java, you had to recreate a
Java program if you changed the JAR file or ZIP file in any way, because the
attached Java program would become unusable. This is no longer true. In many
cases, if you change a JAR file or ZIP file, the Java program is still valid and you
do not have to recreate it. If partial changes are made, such as when a single class
file is updated within a JAR file, you only need to recreate the affected class files
that are within the JAR file.

Java programs remain attached to the JAR file after most typical changes to the
JAR file. For example, these Java programs remain attached to the JAR file when:
v Changing or recreating a JAR file by using the ajar tool.
v Changing or recreating a JAR file by using the jar tool.
v Replacing a JAR file by using the 0S/400 COPY command or the Qshell cp
utility.
Note: Java programs do not remain intact with the COPY command, however,
Java programs do remain intact with the move object (MOV) command.
Anytime you copy a JAR file, you need to run the CRTJVAPGM command
against the resulting JAR file for performance and space. Or, let the Java
programs be created automatically, as needed, when the application runs.
If you access a JAR file in the integrated file system through Client Access or from
a mapped drive on a personal computer (PC), these Java programs remain
attached to the JAR file when:
v Dragging and dropping another JAR file onto the existing integrated file system
JAR file.
v Changing or recreating the integrated file system JAR file by using the jar tool.
v Replacing the integrated file system JAR file by using the PC copy command.
When a jar file is changed or replaced, the Java program that is attached to it is no
longer current.

18 AS/400 Developer Kit for Java

 There is one exception in which Java programs do not remain attached to the JAR
file. The attached Java programs are destroyed if you use file transfer protocol
(FTP) to replace the JAR file. For example, this occurs if you use the FTP put
command to replace the JAR file.

See runtime performance for more detailed information about the performance
characteristics of JAR files.

Java extensions framework:

In Java 2 SDK, Standard Edition, version 1.2, extensions are packages of Java
classes that you can use to extend the functionality of the core platform. An
extension or application is packaged in one or more JAR files. The extension
mechanism allows the Java virtual machine to use the extension classes in the
same way that the virtual machine uses the system classes. The extension
mechanism also provides a way for you to retreive extensions from specified URLs
when they are not already installed in the Java Development Kit (JDK) or Java 2
Runtime Environment, Standard Edition, version 1.2.

See Installing extensions for the AS/400 Developer Kit for Java for information on
installing extensions.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Release to release compatibility

As with all Java programs, your class files are portable to previous and future
releases of AS/400 or other compatible Java machines, subject to any limitations
that Sun Microsystems, Inc. introduces. However, the Java programs are currently
not portable between releases of AS/400, so you should run the Create Java
Program (CRTJVAPGM) command to optimize the class file, ZIP file, or JAR file
when you move the program to another AS/400 from a different release.

The Java programs that may be attached to the class file, ZIP file, or JAR file are
not upward compatible from releases prior to V4R4. You should run the
CRTJVAPGM command on V4R4 for the best optimization when using a class file,
ZIP file, or JAR file with an attached Java program from a release prior to V4R4.
Use the Display Java Program (DSPJVAPGM) command to determine if you have
an attached Java program. Regardless, you should still run the CRTJVAPGM
command even if there is not an attached Java program from a previous release. In
either case, implicit creation occurs if you do not explicitly run the CRTJVAPGM
command, but an an explicit creation by using the CRTJVAPGM command
produces better code and uses less disk space.

If you have Java programs that were created at optimization level 40, prior to the
installation of Java 2 Software Development Kit (J2SDK), Standard Edition, version
1.2, you should recreate them by using the CRTJVAPGM command. You need to
recreate them because of changes made in the base J2SDK classes.

Note: If you create Java programs that use unique J2SDK, version 1.2 features, they
are not portable to versions prior to J2SDK, version 1.2. If your Java programs do
not use unique features, they are portable to prior versions.

See runtime performance for more detailed performance information.

Chapter 2. Getting started with the AS/400 Developer Kit for Java 19
 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

20 AS/400 Developer Kit for Java

Chapter 3. AS/400 Developer Kit for Java concepts
The AS/400 Developer Kit for Java concepts introduce what you should be
familiar with when using the AS/400 Developer Kit for Java. This information is
specific to AS/400.

The basic Java concepts provide Java definitions for those of you who are looking
for basic details. This is general Java information, and is not specific to the AS/400.
It is only provided here as a quick reference. Reference information is also
available for Sun Microsystems Inc. Java Development Kit (JDK).

AS/400 Developer Kit for Java concepts:

The AS/400 Developer Kit for Java is optimized for use in an AS/400 server
environment. It utilizes the compatibility of Java programming and user interfaces,
so you can develop your own applications for AS/400.

The AS/400 Developer Kit for Java allows you to create and run Java programs on
AS/400. The AS/400 Developer Kit for Java is a compatible implementation of the
Sun Microsystems, Inc. Java Technology, so we assume that you are familiar with
their Java Development Kit (JDK) documentation, and often provide links to this
information.

Unique aspects of the AS/400 Developer Kit for Java design include:
v The integration of critical Java virtual machine components below the
Technology Independent Machine Interface (TIMI).
v A Java transformer for conversion of Java bytecodes to RISC machine
instructions.
v Advanced, scalable implementations of garbage collection, object allocation, and
synchronization.
v The Remote Abstract Window Toolkit implementation that supports the java.awt
APIs.
v The Class Broker for Java that you can use for high performance graphical user
interface (GUI) services.
v A Just-In-Time compiler that improves performance by compiling code as you
need it.
The AS/400 Developer Kit for Java is not an integrated language environment
(ILE) language. It introduces a new language environment on AS/400 that is built
on Java, American National Standard Code for Information Interchange (ASCII),
integrated file system, and other industry standards.

The AS/400 Developer Kit for Java supports the common JDK tools, such as javac,
javadoc, and jar. There are also CL commands and Operations Navigator interfaces
to the AS/400 Developer Kit for Java.

For definitions of specific AS/400 Developer Kit for Java concepts and details, click
on any of these links:
v Running Java in a batch job explains how Java programs run in a batch job by
using the Submit Job (SBMJOB) command.

© Copyright IBM Corp. 1998, 1999 21

 v Java classes, packages, and directories provides definitions of each and how they
relate to one another.
v Java system properties shows the system properties along with their descriptions
and system default values.
v Files in the integrated file system lists where you can store source files in
integrated file systems.
v Java file authorities in the integrated file system shows you how to set Java file
authorities.
v Java character encodings explains how the Java virtual machine converts data to
other encodings.
v Java Naming and Directory Interface tells you how to run JNDI.
v Java Virtual Machine Debug Interface explains what JVMDI is and why you
would use it.
v Limitations, restrictions, and unique behaviors lists any known limitations.
Basic Java concepts:

Java is a full-function, object-oriented programming language that you can use to

develop applications and applets. Object-oriented programming uses objects and
classes in a program to represent entities and classifications of entities in the real
world. The class defines the attributes and behavior common to all objects of that
class. An object is an instance of a class—the specific example of the more general
conceptual model. Object-oriented programming enables programmers to design
applications that use classes and objects that parallel those that are found in the
real world.

Not only can you use Java technology for programming applets or writing
applications, but you can use servlets to bring Java to your servers. Servlets are
protocol and platform-independent server side components that are written in Java
to dynamically extend Java enabled servers. See the IBM WebSphere Application

Server homepage for more specific servlet information.

Syntactically, the Java language is similar to C++. But it was designed to be

simpler to learn and simpler to use. One of the simplifications in Java was the
elimination of pointers in the language. In a language like C++, pointers are often
the source of errors in a program, because of incorrect memory references. Java
allows references to objects, but the programmer cannot manipulate or directly
change references.

Java is simpler than C++ in other ways. There are no multiple inheritance of
implementation, templates, operator overloading, or header files. These
simplifications add to the versatility of the language by making it easier for
programmers to use and by reducing the risk of programming errors.

Java also relieves the programmer of having to manage memory. A component of

the Java virtual machine, called the garbage collector, frees up memory that is
allocated to an object once that object is no longer in use. The garbage collector
keeps track of which objects are active in a program. When the program no longer
refers to the object, the garbage collector automatically frees up the object’s
memory for reuse within the program.

The garbage collector runs in parallel with the user-written program. Java
incorporates multithreading into its runtime and provides the language constructs
that allow a programmer to write multithreaded code. Threads allow parallel,

22 AS/400 Developer Kit for Java

 concurrent running of code within a program. The ability to create and run threads
is not inherent in other programming languages. Java provides the power of
threads as part of the base language.

Java is an ideal language for network computing. You can develop both applets
and applications that run in a distributed environment. Java programs are portable
between platforms and do not require any modification or recompilation to run on
different hardware or operating system configurations.

For more detailed information about the basic Java platform or Sun Microsystems,
Inc. Java Development Kit, see these topics for background information:
v The Java platform compares how the Java environment differs from traditional
programming languages.
v Sun Microsystems, Inc. Java Development Kit provides information and details
about the Java Development Kit.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java transformer
The Java transformer is an IBM Operating System/400 (OS/400) component that
preprocesses class files to prepare them to run using the AS/400 Java virtual
machine. The Java transformer creates an optimized program object that is
persistent and is associated with the class file. In the default case, the program
object contains a compiled, 64-bit RISC machine instruction version of the class.
The Java interpreter does not interpret the optimized program object at runtime.
Instead, it directly runs when the class file is loaded.

You do not need to do anything to start the Java transformer. It runs automatically
the first time that the class file runs on the system, unless you explicitly request
that the class file run in interpreted mode.

You can use the Create Java Program (CRTJVAPGM) command to explicitly start
the Java transformer. The CRTJVAPGM command optimizes the class file or JAR
file while the command runs, so nothing needs to be done while the program is
running. This improves the speed of the program the first time that it runs. Using
the CRTJVAPGM command, instead of relying on default optimization, ensures the
best optimization possible and also better utilizes space for the Java programs that
are associated with the class file or JAR file.

Using the CRTJVAPGM command on a class file, JAR file, or ZIP file causes all the
classes in the file to be optimized, and the resulting Java program object will be
persistent. This results in better runtime performance. You can also change the
optimization level or select an optimization level other than the default of 10 by
using the CRTJVAPGM command or the Change Java Program (CHGJVAPGM)
command. At optimization level 40, interclass binding is performed between the
classes within a JAR file, and in some cases, the classes are inlined. Interclass
binding improves the call speed. Inlining removes the call entirely. In some cases,
you can inline methods between classes within the JAR file or ZIP file. Specifying
OPTIMIZE(*INTERPRET) on the CRTJVAPGM command causes any classes that are
specified on the command to be verified and prepared to run in interpreted mode.

The Run Java (RUNJVA) command can also specify OPTIMIZE(*INTERPRET). This
parameter specifies that any classes running under the Java virtual machine are

Chapter 3. AS/400 Developer Kit for Java concepts 23

 interpreted, regardless of the optimization level of the associated program object.
This is useful when debugging a class that was transformed with an optimization
level of 40. To force interpretation, use INTERPRET(*YES).

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

AS/400 Developer Kit for Java advanced garbage collection

The AS/400 Developer Kit for Java implements an advanced garbage collector
algorithm. This algorithm allows the discovery and collection of unreachable
objects without significant pauses in the operation of the Java program. A
concurrent collector cooperatively discovers the references to objects under the
running threads, instead of a single thread.

Many garbage collectors are “stop-the-world”. This means that at the point where
a collection cycle occurs, all threads, except the thread that does garbage collection,
stop while the garbage collector does its work. When this happens, Java programs
experience a pause, and any multiple processor capability of the platform is
wasted relative to Java, while the collector does its work. The AS/400 algorithm
never stops the program threads. It allows those threads to continue operation
while the garbage collector completes its task. This prevents the pauses, and allows
all processors to be used during garbage collection.

Garbage collection occurs automatically based on parameters that you specify

when you start the Java virtual machine. Garbage collection can also be started
explicitly under the control of the Java program by using the
java.lang.Runtime.gc() method.

For a basic concept definition, see Java garbage collection.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java garbage collection

Garbage collection is the process of freeing storage that is used by objects that are
no longer referred to by a program. With garbage collection, programmers no
longer have to write error prone code to explicitly “free” or “delete” their objects.
This code frequently results in “memory leak” program errors. The garbage
collector automatically detects an object or group of objects that the user program
can no longer reach. It does this because there are no references to that object in
any program structure. Once the object has been collected, you can allocate the
space for other uses.

The Java runtime environment includes a garbage collector that frees memory that
is no longer in use. The garbage collector runs automatically, as needed.

The garbage collector can also be started explicitly under the control of the Java
program using the java.lang.Runtime.gc() method.

See AS/400 Developer Kit for Java advanced garbage collection for AS/400
Developer Kit for Java specifics.

24 AS/400 Developer Kit for Java

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

AS/400 Java runtime environment

The Java runtime environment starts whenever you enter the Run Java (RUNJVA)
command or JAVA command on the AS/400 command line. Because the Java
environment is multithreaded, it is necessary to run the Java virtual machine in a
job that supports threads, such as a batch immediate (BCI) job. Once the Java
virtual machine starts, additional threads may start in which the garbage collector
runs. The typical Java environment looks like this:

It is also possible to start the Java runtime environment by using the java
command in Qshell from the Qshell Interpreter. In this environment, the Qshell
Interpreter is running in a BCI job that is associated with an interactive job. The
Java runtime environment starts in the job that is running the Qshell Interpreter.

When the Java runtime environment starts from an interactive job, the Java Shell
Display is shown. This display provides an input line for entering data into the
System.in stream, as well as displaying data that is written to the System.out
stream and System.err stream.

Chapter 3. AS/400 Developer Kit for Java concepts 25

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

AS/400 Developer Kit for Java Remote Abstract Window Toolkit

The Remote Abstract Window Toolkit is an implementation of the Abstract
Window Toolkit (AWT). It allows Java applications to run, without any changes, on
a host that does not have a graphical user interface (GUI). AS/400 does not
support locally-attached graphic terminals; therefore Remote AWT is necessary to
allow graphical Java applications to run on AS/400.

You use Remote AWT with install and administration interfaces of server
applications. These interfaces typically have a minimum of complex graphics and
highly-interactive content. Remote AWT distributes AWT processing between
AS/400 and a workstation. Responsiveness of graphic-intensive and
highly-interactive operations might not be as fast as AWT implementations on
platforms with locally-attached graphic terminals.

Since AS/400 Developer Kit for Java Remote AWT is not recommended for
complex graphics or highly-interactive operations, you can use the Class Broker for
Java instead, which was designed for these environments.

For information on how to set up Remote AWT, see Setting up the Remote
Abstract Window Toolkit for Java on a remote display.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

AS/400 Developer Kit for Java Class Broker for Java

Class Broker for Java (CBJ) is a general-purpose framework for writing
client/server applications in Java. Typically, a client/server application consists of
both a client object and a server object. The server and client are responsible for all
communication between the two objects. This communication is often
accomplished by Remote Method Invocation (RMI) or by a socket connection. RMI
is not very easy or flexible to use and there is a considerable learning curve when
trying to use sockets effectively.

CBJ is easy to use, flexible, and hides the complexity of socket connections. Except
for a few calls to the CBJ classes to initialize the application, a brokered
client/server application appears to be a local application. CBJ handles all
communication and resource loading between the client and server. The fact that
some of the objects of the program are running on the client and some are running
on the server is almost transparent. CBJ creates client and server proxies using the
CBJ runtime. Once the broker creates the proxy objects, the client communicates
with the remote server by calling methods on the proxy of the server. Likewise, the
server object communicates with the client by calling methods on the proxy of the
client. Thus, both the client and server sides of the application appear as if they are
calling methods of local objects.

For information about using Class Broker for Java, see setting up Class Broker for
Java .

26 AS/400 Developer Kit for Java

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Just-In-Time compiler
A Just-In-Time (JIT) compiler is a platform-specific compiler that generates
machine instructions for each method upon the first call to that method. To
improve performance, the JIT compiler compiles code as you need it.

To understand the difference between the JIT compiler and direct execution, see
comparison of the JIT compiler and direct execution.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Comparison of Just-In-Time compiler and direct execution

If you are trying to decide whether to use the Just-In-Time compiler or direct
execution mode to run your Java program, this table provides additional
information to help you make the best choice for your situation.

Just-In-Time compiler Direct execution

Provides an automatic compile of any You compile an entire class or JAR file using
method when needed. This method is much the Create Java Program (CRTJVAPGM)
faster than direct execution. command or the files are compiled
automatically at runtime.
Used for development of small or low usage Used for relatively large applications. Direct
applications, and highly dynamic execution code, at optimization level 40, is
applications in which the code is generated typically faster than JIT. Most ready to
or loaded at runtime. JIT may be your only deploy server applications use direct
choice for optimized code, other than execution at optimization level 40, because
interpretation, which is often much slower. they are likely to be in use by multiple users
at any given time, and the cost of using JIT
over and over is too much overhead.
Optimizations are limited to those that can More complex optimizations are possible,
be performed rapidly at runtime. since optimization is not performed at
runtime.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Comparison of Integrated Language Environment and Java

The Java environment on AS/400 is separate from the integrated language
environment (ILE). Java is not an ILE language, and it cannot bind to ILE object
modules to create programs or service programs on AS/400.

ILE Java
Members that are part of the library or file Stream files in the integrated file system
structure on AS/400 store source codes. contain source code.

Chapter 3. AS/400 Developer Kit for Java concepts 27

 ILE Java
Source entry utility (SEU) edits extended American National Standard Code for
binary-coded decimal interchange code Information Interchange (ASCII) source files
(EBCDIC) source files. are usually edited using a workstation editor.
Source files compile into object code Source code compiles into class files, which
modules, which are stored in libraries on the integrated file system stores.
AS/400.
Object modules are statically bound together Classes are dynamically loaded, as needed, at
in programs or service programs. runtime.
You can directly call to functions that are Java Native Interface must be used to call
written in other ILE programming languages. other languages from Java.
ILE languages are always compiled and run Java programs can be interpreted or
as machine instructions. compiled.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Running Java in a batch job

Java programs run in a batch job by using the Submit Job (SBMJOB) command. In
this mode, the Java Qshell Command Entry display is not available to handle the
System.in, System.out, nor System.err streams.

You may redirect these streams to other files. Default handling sends the
System.out and System.err streams to a spooled file. The batch job, which results in
an input and output exception for read requests from System.in, owns the spooled
file. You can redirect System.in, System.out, and System.err within your Java
program. You can also use the os400.stdin, os400.stdout, and os400.stderr system
properties to redirect System.in, System.out, and System.err.

Note: SBMJOB sets the Current Working Directory (CWD) to the HOME directory
that is specified in the user profile.

Example: Running Java in a Batch Job

SBMJOB CMD(JAVA Hello OPTION(*VERBOSE)) CPYENVVAR(*YES)

Running the JAVA command in the above example will spawn a second job.
Therefore, the subsystem that the batch job runs in must be capable of running
more than one job.

You can verify that your batch job is capable of running more than one job by
following these steps:
1. On the CL command line, enter DSPSBSD(MYSBSD), where MYSBSD is the
subsystem description of your batch job.
2. Choose option 6, Job queue entries.
3. Look at the Max Active field for your job queue.
If the Max Active field is less than or equal to 1, and it is not *NOMAX,
enter the following on the CL command line:
CHGJOBQE SBSD(MYSBSD) JOBQ(MYJOBQ) MAXACT(*NOMAX)
Where:
v MYSBSD is your subsystem description, and
v MYJOBQ is your job queue.

28 AS/400 Developer Kit for Java

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Java classes, packages, and directories

Each Java class is part of a package. The first statement in a Java source file
indicates which class is in what package. If the source file does not contain a
package statement, the class is part of an unnamed default package.

The package name relates to the directory structure in which the class resides. The
integrated file system supports Java classes in a hierarchical file structure that is
similar to what you find on most PC and UNIX systems. You must store a Java
class in a directory with a relative directory path that matches the package name
for that class. For example, consider these Java class:
package classes.geometry;
import java.awt.Dimension;
public class Shape {
Dimension metrics;
// The implementation for the Shape class would be coded here ...
}

The package statement in the code above indicates that the Shape class is part of
the “classes.geometry” package. For the Java runtime to find the Shape class, store
the Shape class in the relative directory structure “classes/geometry”.

Note: The package name corresponds to the relative directory name in which the
class is stored. The Java virtual machine class loader finds the class by appending
the relative path name to each directory that is specified in the classpath. The Java
virtual machine class loader can also find the class by searching the ZIP files or
JAR files that are specified in the classpath.

For example, if the Shape class was stored in the /Product/classes/geometry

directory in the “root” (/) file system, /Product would need to be specified in the
classpath.

Chapter 3. AS/400 Developer Kit for Java concepts 29

 Note: Multiple versions of the Shape class can exist in the directory structure. To
use the “beta” version of the Shape class, place /Beta/myclasses in the
CLASSPATH before any other directories or ZIP files that contain the Shape class.

The Java compiler uses the Java classpath, package name, and directory structure
to find packages and classes when compiling Java source code.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java system properties

Java system properties determine the environment in which the Java programs run.
They are similar to system values or environment variables in OS/400. A number
of properties are set when the Java virtual machine starts.

To view the system properties that this release supports, link to the version of your
choice for detailed information:
v Java Development Kit (JDK) 1.1.8
v Java 2 Software Development Kit (J2SDK), Standard Edition, version 1.2

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java system properties for Java Development Kit (JDK) 1.1.8

Java system properties determine the environment in which the Java programs run.
They are similar to system values or environment variables in OS/400. A number
of properties are set when the Java virtual machine starts.

30 AS/400 Developer Kit for Java

The system properties are set to these system default values in JDK 1.1.8.

System properties System default values

awt.toolkit com.ibm.rawt.client.CToolkit
file.encoding.pkg sun.io
file.separator / (forward slash)
java.class.version 45.3
java.home See Multiple JDK support for details.
java.vendor IBM Corporation
java.vendor.url http://www.ibm.com
line.separator \n
os.arch PowerPC
os.name OS/400
os400.class.path.rawt 0
os400.class.path.security.check

20
Valid values:
0—No security check
10—equivalent to RUNJVA
CHKPATH(*IGNORE)
20—equivalent to RUNJVA
CHKPATH(*WARN)
30—equivalent to RUNJVA
CHKPATH(*SECURE)
os400.class.path.tools 0
os400.create.type

direct
Valid values:
interpret—equivalent to RUNJVA
OPTIMIZE(*INTERPRET) and
INTERPRET(*OPTIMIZE), or
INTERPRET(*YES)
direct—Otherwise
os400.defineClass.optLevel 20
os400.enbpfrcol

0
Valid values:
0—equivalent to CRTJVAPGM
ENBPFRCOL(*NONE)
1—equivalent to CRTJVAPGM
ENBPFRCOL(*ENTRYEXIT)
7—equivalent to CRTJVAPGM
ENBPFRCOL(*FULL)
os400.interpret

0
Valid values:
0—equivalent to CRTJVAPGM
INTERPRET(*NO)
1—equivalent to CRTJVAPGM
INTERPRET(*YES)

Chapter 3. AS/400 Developer Kit for Java concepts 31

 System properties System default values
os400.optimization

10
Valid values:
0—equivalent to CRTJVAPGM
OPTIMIZE(*INTERPRET)
10—equivalent to CRTJVAPGM
OPTIMIZE(10)
20—equivalent to CRTJVAPGM
OPTIMIZE(20)
30—equivalent to CRTJVAPGM
OPTIMIZE(30)
40—equivalent to CRTJVAPGM
OPTIMIZE(40)
os400.run.mode

program_create_type
Valid values:
interpret—equivalent to RUNJVA
OPTIMIZE(*INTERPRET) and
INTERPRET(*OPTIMIZE), or
INTERPRET(*YES)
program_create_type—Otherwise
os400.stdin.allowed 0
os400.verify.checks.disable 65535 This system property value is a string
that represents the sum of one or more
numeric values. For a list of these values, see
os400.verify.checks.disable numeric values.
path.separator : (colon)

This set of system properties are set based on additional system information.

System properties Description

file.encoding Maps the OS/400 job CCSID to the
corresponding ISO ASCII CCSID. Also, sets
the file.encoding value to the Java value that
represents the ISO ASCII coded character set
identifier (CCSID). See file.encoding values
and AS/400 CCSID for a table that shows the
relationship between possible file.encoding
values and the closest matching AS/400
coded character set identifier (CCSID).
java.class.path Path used to locate classes. Defaults to the
default system classpath followed by the
user-specified classpath. You can change the
contruction of the java.class.path system
property by using the os400.class.path.system
system property.
java.version Determines which Java Development Kit
(JDK) to run.

If you specify a JDK that is not installed, an

error message results. If you do not specify a
JDK, the most recent JDK is the default. If
only one JDK is installed, that is your
default. See Multiple JDK support for version
details.

32 AS/400 Developer Kit for Java

System properties Description
os.version Obtains the OS/400 release level from the
Retrieve Product Information application
program interface (API).
os400.CertificateContainer Directs Java secure sockets layer (SSL)
support to use the specified certificate
container for the Java program that was
started and the property that was specified.
If you specify the os400.secureApplication
system property, this system property is
ignored. For example, enter
-Dos400.certificateContainer=/home/username/mykeyfile.k
or any other keyfile in the integrated file
system.
os400.CertificateLabel You can specify this system property in
conjunction with the
os400.CertificateContainer system property.
This property lets you select which certificate
in the specified container you want secure
sockets layer (SSL) to use. For example,
enter-Dos400.certificateLabel=myCert,
where myCert is the label name that you
assign to the certificate through the Digital
Certificate Manager (DCM) when you create
or import the certificate.
os400.child.stdio.convert Allows control of the data conversion for
stdin, stdout, and stderr in Java. Data
conversion occurs by default in the Java
virtual machine to convert ASCII data to or
from EBCDIC. You can turn these
conversions on or off with this property,
which effects any child processes that were
started by this process by using the
runtime.exec() method. See default values.
os400.class.path.system PRE (this causes the os400 default system
classpath to be prepended onto the
user-specified portion of the classpath when
constructing the java.class.path system
property). Other values are POST (the system
default class is appended to the
user-specified portion of the classpath) and
NONE (only the user-specified classpath is
used). The default is PRE. The property is
not case sensitive. For example, you can
specify NONE, none, noNe. However, the
property name is case sensitive. For example,
you cannot specify
OS400.CLASS.PATH.SYSTEM. To avoid
potential problems, you should not change
this system property.
os400.file.io.mode Converts the CCSID of the file if it if
different than the file.encoding value when
you specify TEXT, rather than the default,
which is BINARY.
os400.secureApplication Associates the Java program that starts when
use use this system property
(os400.secureApplication) with the registered
secure application name. You can view
registered secure application names by using
the Digital Certificate Manager (DCM).

Chapter 3. AS/400 Developer Kit for Java concepts 33

 System properties Description
os400.stderr Allows mapping stderr to a file or socket.
See default values.
os400.stdin Allows mapping stdin to a file or socket. See
default values.
os400.stdio.convert Allows control of the data conversion for
stdin, stdout, and stderr in Java. Data
conversion occurs by default in the Java
virtual machine to convert ASCII data to or
from EBCDIC. You can turn these
conversions on or off with this property,
which effects the current Java program. See
default values.
os400.stdout Allows mapping stdout to a file or socket.
See default values.
user.dir Current working directory using the getcwd
API.
user.home Retrieves the initial working directory by
using the Get API (getpwnam). You can place
a SystemDefault.properties file in your
user.home path to override the default
properites in
/QIBM/UserData/Java400/SystemDefault.properties.
See configuring AS/400 for details on how to
specify your own set of default property
values.
user.language The Java virtual machine uses this system
property to read the job LANGID value and
uses this value to find the corresponding
language.
user.name The Java virtual machine uses this system
property to retrieve the effective user profile
name from the Security section
(Security.UserName) of the Trusted
Computing Base (TCB).
user.region The Java virtual machine uses this system
property to read the job CNTRYID value and
uses this value to determine the user region.
user.timezone The Java virtual machine uses this system
property to obtain the time zone name by
using the QlgRetrieveLocalInformation API.
If no time zone information is available,
user.timezone is set to Univeral Time
Coordinate (UTC).

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java system properties for Java 2 Software Development Kit

(J2SDK), Standard Edition, version 1.2
Java system properties determine the environment in which the Java programs run.
They are similar to system values or environment variables in OS/400. A number
of properties are set when the Java virtual machine starts.

The system properties are set to these system default values in Java 2 Software
Development Kit (J2SDK), Standard Edition, version 1.2.

34 AS/400 Developer Kit for Java

System properties System default values
awt.toolkit com.ibm.rawt.client.CToolkit
file.encoding.pkg sun.io
file.separator / (forward slash)
java.class.version 46.0
java.ext.dirs
/QIBM/ProdData/Java400/jdk12/lib/ext:/QIBM/ProdData/
java.home See Multiple JDK support for details.
java.library.path OS/400 library list
java.policy
/QIBM/ProdData/Java400/jdk12/lib/security/java.policy
java.specification.name Java Language Specification
java.specification.vendor Sun Microsystems, Inc.
java.specification.version 1.2
java.sys.class.path Class_Path_Sys
java.use.policy true
java.vendor IBM Corporation
java.vendor.url http://www.ibm.com
java.vm.name AS/400 Developer Kit for Java
java.vm.specification.name Java Virtual Machine Specification
java.vm.specification.vendor Sun Microsystems, Inc.
java.vm.specification.version 1.2
java.vm.vendor IBM Corporation
java.vm.version OS400_JVM_12
line.separator \n
os.arch PowerPC
os.name OS/400
os400.class.path.rawt 0
os400.class.path.security.check

20
Valid values:
0—No security check
10—equivalent to RUNJVA
CHKPATH(*IGNORE)
20—equivalent to RUNJVA
CHKPATH(*WARN)
30—equivalent to RUNJVA
CHKPATH(*SECURE)
os400.class.path.tools 0
os400.create.type

direct
Valid values:
interpret—equivalent to RUNJVA
OPTIMIZE(*INTERPRET) and
INTERPRET(*OPTIMIZE), or
INTERPRET(*YES)
direct—Otherwise
os400.defineClass.optLevel 20

Chapter 3. AS/400 Developer Kit for Java concepts 35

 System properties System default values
os400.enbpfrcol

0
Valid values:
0—equivalent to CRTJVAPGM
ENBPFRCOL(*NONE)
1—equivalent to CRTJVAPGM
ENBPFRCOL(*ENTRYEXIT)
7—equivalent to CRTJVAPGM
ENBPFRCOL(*FULL)
os400.interpret

0
Valid values:
0—equivalent to CRTJVAPGM
INTERPRET(*NO)
1—equivalent to CRTJVAPGM
INTERPRET(*YES)
os400.optimization

10
Valid values:
0—equivalent to CRTJVAPGM
OPTIMIZE(*INTERPRET)
10—equivalent to CRTJVAPGM
OPTIMIZE(10)
20—equivalent to CRTJVAPGM
OPTIMIZE(20)
30—equivalent to CRTJVAPGM
OPTIMIZE(30)
40—equivalent to CRTJVAPGM
OPTIMIZE(40)
os400.run.mode

program_create_type
Valid values:
interpret—equivalent to RUNJVA
OPTIMIZE(*INTERPRET) and
INTERPRET(*OPTIMIZE), or
INTERPRET(*YES)
program_create_type—Otherwise
os400.stdin.allowed 0
os400.verify.checks.disable 65535 This system property value is a string
that represents the sum of one or more
numeric values. For a list of these values, see
os400.verify.checks.disable numeric values.
path.separator : (colon)

36 AS/400 Developer Kit for Java

This set of system properties are set based on additional system information.

System properties Description

file.encoding Maps the OS/400 job CCSID to the
corresponding ISO ASCII CCSID. Also, sets
the file.encoding value to the Java value that
represents the ISO ASCII coded character set
identifier (CCSID). See file.encoding values
and AS/400 CCSID for a table that shows the
relationship between possible file.encoding
values and the closest matching AS/400
coded character set identifier (CCSID).
java.class.path Path used to locate classes. Defaults to the
user-specified classpath.
java.compiler Specifies whether code is compiled with the
Just-In-Time (JIT) compiler (jitc) or with both
the JIT compiler and direct execution
(jitc_de).
java.version Determines which Java Development Kit
(JDK) to run.

If you specify a JDK that is not installed, an

error message results. If you do not specify a
JDK, the most recent JDK is the default. If
only one JDK is installed, that is your
default. See Multiple JDK support for version
details.
os.version Obtains the OS/400 release level from the
Retrieve Product Information application
program interface (API).
os400.CertificateContainer Directs Java secure sockets layer (SSL)
support to use the specified certificate
container for the Java program that was
started and the property that was specified.
If you specify the os400.secureApplication
system property, this system property is
ignored. For example, enter
-Dos400.certificateContainer=/home/username/mykeyfile.k
or any other keyfile in the integrated file
system.
os400.CertificateLabel You can specify this system property in
conjunction with the
os400.CertificateContainer system property.
This property lets you select which certificate
in the specified container you want secure
sockets layer (SSL) to use. For example,
enter-Dos400.certificateLabel=myCert,
where myCert is the label name that you
assign to the certificate through the Digital
Certificate Manager (DCM) when you create
or import the certificate.
os400.child.stdio.convert Allows control of the data conversion for
stdin, stdout, and stderr in Java. Data
conversion occurs by default in the Java
virtual machine to convert ASCII data to or
from EBCDIC. You can turn these
conversions on or off with this property,
which effects any child processes that were
started by this process by using the
runtime.exec() method. See default values.

Chapter 3. AS/400 Developer Kit for Java concepts 37

 System properties Description
os400.class.path.system This system property is ignored in version
1.2.
os400.file.io.mode Converts the CCSID of the file if it if
different than the file.encoding value when
you specify TEXT, rather than the default,
which is BINARY.
os400.secureApplication Associates the Java program that starts when
use use this system property
(os400.secureApplication) with the registered
secure application name. You can view
registered secure application names by using
the Digital Certificate Manager (DCM).
os400.stderr Allows mapping stderr to a file or socket.
See default values.
os400.stdin Allows mapping stdin to a file or socket. See
default values.
os400.stdin.allowed Specifies whether stdin is allowed (1) or not
allowed (0). If the caller is running a batch
job, stdin should not be allowed. The default
0.
os400.stdio.convert Allows control of the data conversion for
stdin, stdout, and stderr in Java. Data
conversion occurs by default in the Java
virtual machine to convert ASCII data to or
from EBCDIC. You can turn these
conversions on or off with this property,
which effects the current Java program. See
default values.
os400.stdout Allows mapping stdout to a file or socket.
See default values.
user.dir Current working directory using the getcwd
API.
user.home Retrieves the initial working directory by
using the Get API (getpwnam). You can place
a SystemDefault.properties file in your
user.home path to override the default
properites in
/QIBM/UserData/Java400/SystemDefault.properties.
See configuring AS/400 for details on how to
specify your own set of default property
values.
user.language The Java virtual machine uses this system
property to read the job LANGID value and
uses this value to find the corresponding
language.
user.name The Java virtual machine uses this system
property to retrieve the effective user profile
name from the Security section
(Security.UserName) of the Trusted
Computing Base (TCB).
user.region The Java virtual machine uses this system
property to read the job CNTRYID value and
uses this value to determine the user region.

38 AS/400 Developer Kit for Java

System properties Description
user.timezone The Java virtual machine uses this system
property to obtain the time zone name by
using the QlgRetrieveLocalInformation API.
If no time zone information is available,
user.timezone is set to Univeral Time
Coordinate (UTC).

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

os400.stdio.convert and os400.child.stdio.convert system

property values
This table shows the system values for both the os400.stdio.convert and
os400.child.stdio.convert system properties.

Value Description
N (default) No stdio conversion is performed during read or write.
Y All stdio converts to or from the file.encoding value to job CCSID
during read or write.
1 Only stdin data converts from job CCSID to file.encoding during read.
2 Only stdout data converts from file.encoding to job CCSID during
write.
3 Both stdin and stdout conversions are performed.
4 Only stderr data converts from file.encoding to job CCSID during
write.
5 Both stdin and stderr conversions are performed.
6 Both stdout and stderr conversions are performed.
7 All stdio conversions are performed.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

os400.stdin, os400.stdout, and os400.stderr system property

values
This table shows the system values for os400.stdin, os400.stdout, and os400.stderr
system properties.

Value Example name Description Example

File SomeFileName SomeFileName is an file:/QIBM/UserData/Java400/Output.file
absolute path or a path
relative to the current
directory.
Port HostName Port address port:myhost:2000
Port TCPAddress Port address port:1.1.11.111:2000

Chapter 3. AS/400 Developer Kit for Java concepts 39

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

os400.verify.checks.disable numeric values

The os400.verify.checks.disable system property value is a string that represents the
sum of one or more numeric values from this list:

Value Description
Bypass access checks for local classes:
Indicates that you want the Java virtual
1
machine to bypass access checks on private
and protected fields and methods for classes
that are loaded from the local file system. It
is helpful when transferring applications,
which contain inner classes that refer to
private and protected methods and fields of
their enclosing classes.
2 Suppress NoClassDefFoundError during
early load: Indicates that you want the Java
virtual machine to ignore
NoClassDefFoundErrors, which occur
during early verification checks for
typecasting and field or method access.
4 Allow LocalVariableTable checking to be
bypassed: Indicates that if you encounter an
error in the LocalVariableTable of a class, the
class operates as if the LocalVariableTable
does not exist. Otherwise errors in the
LocaleVariableTable result in a
ClassFormatError.
7 Value used at runtime.

You can indicate the value in decimal, hexadecimal, or octal format. It ignores
values that are less than zero. For example, to select the first two values from the
list, use this AS/400 command syntax:
JAVA CLASS(Hello) PROP((os400.verify.checks.disable 3))

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Files in the integrated file system

The integrated file system stores Java-related class files, source files, ZIP files, and
JAR files in a hierarchical file structure. You can also store source files in the
integrated file system. You may store the files in the these integrated file systems:
v “root” (/) file system
v open systems file system (QOpenSys)
v user-defined file system
v library file system (QSYS.LIB)
v OS/2 Warp Server for AS/400 file system (QLANSrv)
v optical file system (QOPT)

40 AS/400 Developer Kit for Java

 Note: Other integrated file systems are not supported, because they are not thread
safe.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java file authorities in the integrated file system

To run or debug a Java program, the class file, JAR file, or ZIP file needs to have
read authority (*R). Any directories need read and execute authorities (*RX).

To use the Create Java Program (CRTJVAPGM) command to optimize a program,

the class file, JAR file, or ZIP file must have read authority (*R), and the directory
must have execute authority (*X). If you use a pattern in the class file name, the
directory must have read and execute authority (*RX).

To delete a Java program by using the Delete Java Program (DLTJVAPGM)

command, you must have read and write authority (*RW) to the class file, and the
directory must have execute authority (*X). If you use a pattern in the class file
name, the directory must have read and execute authority (*RX).

To display a Java program by using the Display Java Program (DSPJVAPGM)

command, you need no special authority on the class file or directory.

Note: Files and directories that do not have execute authority (*X) always appear
to have execute authority (*X) to a user with QSECOFR authority. Different users
can get different results in certain situations, even though both users appear to
have the same access to the same files. This is important to know when running
shell scripts using the Qshell Interpreter or java.Runtime.exec().

For example, one user writes a Java program that uses java.Runtime.exec() to call a
shell script, then tests it using a userid with QSECOFR authority. If the file mode
of the shell script has read and write authority (*RW), the integrated file system
allows the userid with QSECOFR authority to run it. However, a non-QSECOFR
authority user could try to run the same Java program, and the integrated file
system would tell the java.Runtime.exec() code that the shell script is not
executable, because *X is missing. In this case, java.Runtime.exec() throws an input
and output exception.

For more information, see the OS/400 Program and CL Command APIs, SC41-5870

book or the OS/400 Integrated File System Introduction.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java character encodings

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.

You store Java program files in the integrated file system. You encode the character
or text program files in the integrated file system in the code page that is specified
by the Java system property “file.encoding.” This includes Java source code files

Chapter 3. AS/400 Developer Kit for Java concepts 41

 (.java), Java .property files, and any character data user program files. For more
information, see the file.encoding values and AS/400 CCSID table or the default
file.encoding values table.

Program data input or output that uses any stream class, other than these four:
java.io.InputStreamReader, java.io.FileReader, java.io.OutputStreamWriter, or
java.io.FileWriter, is considered binary data and performs no character code page
conversion. Program data input or output that uses the above four stream classes
is considered as character data, and performs an appropriate character code page
conversion. Character code page conversion depends on the source or target of the
data.

Character data that is written to a Transmission Control Protocol/Internet Protocol

(TCP/IP) socket that uses an OutputStreamReader converts to the code page that is
specified by the file.encoding system property. Character data that is read from a
TCP/IP socket that uses an InputStreamReader converts from the code page that is
specified by the file.encoding system property.

Character data that is written to the System.out and System.err streams is

converted to the code page that is specified by the AS/400 job CCSID. Data that is
read from the System.in stream is converted from the code page that is specified
by the AS/400 job coded character set identifier (CCSID).

If System.in has been redirected to another stream, the conversion is handled

differently. System.in can be redirected by using the java.lang.System.SetIn()
method if you want to supply the input to your program from the output of
another Java program. In this case, conversion from an AS/400 CCSID is not
appropriate, because both the source and target programs are Java. The data is
converted from the code page that is specified by the Java file.encoding system
property. Similarly, data to a redirected System.out or and System.err is converted
to the code page that is specified by the Java file.encoding system property.

Data to or from the DB2/400 database, through the JDBC APIs, converts to or from
the CCSID of the AS/400 database.

Data that is transferred to or from other programs through Java Native Interface
does not get converted.

For more information about internationalization, see the AS/400 National

Language Support, SC41-5101 book or the AS/400 International Application

Development, SC41-5603 book.

You can also see Internationalization by Sun Microsystems, Inc. for more
information.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

File.encoding values and AS/400 CCSID

This table shows the relation between possible file.encoding values and the closest
matching AS/400 coded character set identifier (CCSID).

42 AS/400 Developer Kit for Java

file.encoding CCSID Description
Big5 950 8-bit ASCII T-Chinese BIG-5
CNS11643 964 Chinese National Character
Set for traditional Chinese
Cp037 037 IBM EBCDIC US, Canada,
Netherlands,...
Cp273 273 IBM EBCDIC Germany,
Austria
Cp277 277 IBM EBCDIC Denmark,
Norway
Cp278 278 IBM EBCDIC Finland,
Sweden
Cp280 280 IBM EBCDIC Italy
Cp284 284 IBM EBCDIC Spanish, Latin
America
Cp285 285 IBM EBCDIC UK
Cp297 297 IBM EBCDIC France
Cp420 420 IBM EBCDIC Arabic
Cp424 424 IBM EBCDIC Hebrew
Cp437 437 8-bit ASCII US PC
Cp500 500 IBM EBCDIC International
Cp737 737 8-bit ASCII Greek MS-DOS
Cp775 775 8-bit ASCII Baltic MS-DOS
Cp838 838 IBM EBCDIC Thailand
Cp850 850 8-bit ASCII Latin-1
Multinational
Cp852 852 8-bit ASCII Latin-2
Cp855 855 8-bit ASCII Cyrillic
Cp856 856 8-bit ASCII Hebrew
Cp857 857 8-bit ASCII Latin-5
Cp860 860 8-bit ASCII Portugal
Cp861 861 8-bit ASCII Iceland
Cp862 862 8-bit ASCII Hebrew
Cp863 863 8-bit ASCII Canada
Cp864 864 8-bit ASCII Arabic
Cp865 865 8-bit ASCII Denmark,
Norway
Cp866 866 8-bit ASCII Cyrillic
Cp868 868 8-bit ASCII Urdu
Cp869 869 8-bit ASCII Greek
Cp870 870 IBM EBCDIC Latin-2
Cp871 871 IBM EBCDIC Iceland
Cp874 874 8-bit ASCII Thailand
Cp875 875 IBM EBCDIC Greek
Cp918 918 IBM EBCDIC Urdu
Cp921 921 8-bit ASCII Baltic
Cp922 922 8-bit ASCII Estonia
Cp930 930 IBM EBCDIC Japanese
Extended Katakana
Cp933 933 IBM EBCDIC Korean
Cp935 935 IBM EBCDIC Simplified
Chinese
Cp937 937 IBM EBCDIC Traditional
Chinese
Cp939 939 IBM EBCDIC Japanese
Extended Latin

Chapter 3. AS/400 Developer Kit for Java concepts 43

 file.encoding CCSID Description
Cp942 942 8-bit ASCII Japanese
Cp943 943 Japanese PC data mixed for
open env
Cp948 948 8-bit ASCII IBM Traditional
Chinese
Cp949 949 8-bit ASCII Korean KSC5601
Cp950 950 8-bit ASCII T-Chinese BIG-5
Cp964 964 EUC Traditional Chinese
Cp970 970 EUC Korean
Cp1006 1006 ISO 8-bit Urdu
Cp1025 1025 IBM EBCDIC Cyrillic
Cp1026 1026 IBM EBCDIC Turkey
Cp1046 1046 8-bit ASCII Arabic
Cp1097 1097 IBM EBCDIC Farsi
Cp1098 1098 8-bit ASCII Farsi
Cp1112 1112 IBM EBCDIC Baltic
Cp1122 1122 IBM EBCDIC Estonia
Cp1123 1123 IBM EBCDIC Ukraine
Cp1124 1124 ISO 8-bit Ukraine
Cp1250 1250 MS-Win Latin-2
Cp1251 1251 MS-Win Cyrillic
Cp1252 1252 MS-Win Latin-1
Cp1253 1253 MS-Win Greek
Cp1254 1254 MS-Win Turkish
Cp1255 1255 MS-Win Hebrew
Cp1256 1256 MS-Win Arabic
Cp1257 1257 MS-Win Baltic
Cp1258 1251 MS-Win Russian
Cp1381 1381 8-bit ASCII S-Chinese GB
Cp1383 1383 EUC Simplified Chinese
Cp33722 33722 EUC Japanese
EUC_CN 1383 EUC for Simplified Chinese
EUC_JP 33722 EUC for Japanese
EUC_KR 970 EUC for Korean
EUC_TW 964 EUC for Traditional Chinese
GB2312 1381 8-bit ASCII S-Chinese GB
GBK 1386 New simplified Chinese 8-bit
ASCII 9
ISO2022CN_CNS None Available 7-bit ASCII for Traditional
Chinese
ISO2022CN_GB None Available 7-bit ASCII for Simplified
Chinese
ISO2022JP 5054 7-bit ASCII for Japanese
ISO2022KR 25546 7-bit ASCII for Korean
ISO8859_1 819 ISO 8859-1 ISO Latin-1
ISO8859_2 912 ISO 8859-2 ISO Latin-2
ISO8859_3 913 ISO 8859-3 ISO Latin-3
ISO8859_4 914 ISO 8859-4 ISO Latin-4
ISO8859_5 915 ISO 8859-5 ISO Latin-5
ISO8859_6 1089 ISO 8859-6 ISO Latin-6
(Arabic)
ISO8859_7 813 ISO 8859-7 ISO Latin-7
(Greek/Latin)
ISO8859_8 916 ISO 8859-8 ISO Latin-8
(Hebrew)

44 AS/400 Developer Kit for Java

file.encoding CCSID Description
ISO8859_9 920 ISO 8859-9 ISO Latin-9
(ECMA-128, Turkey)
JIS0201 897 Japanese industry standard
X0201
JIS0208 952 Japanese industry standard
X0208
JIS0212 953 Japanese industry standard
X0212
Johab None Available Korean composition Hangul
encoding (full)
K018_R Cyrillic
KSC5601 949 8-bit ASCII Korean
MS874 874 MS-Win Thailand
SJIS 932 8-bit ASCII Japanese
TIS620 874 Thai industry standard 620
UTF8 1208 UTF-8 (IBM CCSID 1208,
which is not yet available on
AS/400)
Unicode 13488 UNICODE, UCS-2
UnicodeBig 13488 Same as Unicode
UnicodeBigUnmarked Unicode with no byte-order
mark
UnicodeLittle Unicode with little-endian
byte order
UnicodeLittleUnmarked UnicodeLittle with no
byte-order mark

For default values, see Default file.encoding values.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Default file.encoding values

This table shows how the file.encoding value is set based on the AS/400 coded
character set identifier (CCSID) when the Java virtual machine starts.

AS/400 CCSID Corresponding Default file.encoding Description

ASCII CCSID
37 ISO8859_1 English for USA,
Canada, New
Zealand, and
Australia; Portuguese
for Portugal and
Brazil; and Dutch for
Netherlands
256 ISO8859_1 International #1
273 ISO8859_1 German/Germany,
German/Austria
277 ISO8859_1 Danish/Denmark,
Norwegian/Norway,
Norwegian/Norway,
NY
278 ISO8859_1 Finnish/Finland
280 ISO8859_1 Italian/Italy

Chapter 3. AS/400 Developer Kit for Java concepts 45

 AS/400 CCSID Corresponding Default file.encoding Description
ASCII CCSID
284 ISO8859_1 Catalan/Spain,
Spanish/Spain
285 ISO8859_1 English/Great Britain,
English/Ireland
290 Cp942 SBCS portion of
Japanese EBCDIC
mixed (CCSID 5026)
297 ISO8859_1 French/France
420 ISO8859_6 Arabic/Egypt
423 ISO8859_7 Greece
424 ISO8859_8 Hebrew/Israel
500 ISO8859_1 German/Switzerland,
French/Belgium,
French/Canada,
French/Switzerland
833 Cp949 SBCS portion of
Korean EBCDIC
mixed (CCSID 933)
836 Cp1381 SBCS portion of
S-Chinese EBCDIC
mixed (CCSID 935).
838 Cp874 Thai
870 ISO8859_2 Czech/Czech
Republic,
Croatian/Croatia,
Hungarian/Hungary,
Polish/Poland
871 ISO8859_1 Icelandic/Iceland
875 ISO8859_7 Greek/Greece
880 ISO8859_5 Bulgaria (ISO 8859_5)
905 ISO8859_9 Turkey extended
918 Cp868 Urdu
930 Cp942 Japanese EBCDIC
mixed (very close to
CCSID 5026)
933 Cp970 Korean/Korea
935 Cp1381 Simplified
Chinese/China
937 Cp950 Traditional
Chinese/Taiwan
939 Cp942 Japanese EBCDIC
Mixed (very close to
CCSID 5035)
1025 ISO8859_5 Belorussian/Belarus,
Bulgarian/Bulgaria,
Macedonian/Macedonia,
Russian/Russia
1026 ISO8859_9 Turkish/Turkey
1027 Cp942 SBCS portion of
Japanese EBCDIC
mixed (CCSID 5035)
1097 Cp1098 Farsi
1112 Cp921 Lithuanian/Lithuania,
Latvian/Latvia, Baltic
1122 Cp922 Estonian/Estonia
1123 Cp1123 Ukrainian/Ukraine

46 AS/400 Developer Kit for Java

 AS/400 CCSID Corresponding Default file.encoding Description
ASCII CCSID
1130 ISO8859_1 Vietnamese. There is
no Vietnamese
language support in
JDK 1.1.4, so
file.encoding is set to
8859_1.
1132 ISO8859_1 Lao. There is no Lao
language support in
JDK 1.1.4, so
file.encoding is set to
8859_1.
1388 Cp1381 Simplified Chinese
EBCDIC mixed (GBK
is included)
5026 Cp942 Japanese EBCDIC
mixed CCSID
(Extended Katakana)
5035 Cp942 Japanese EBCDIC
mixed CCSID
(Extended Latin)
8612 Cp864 Arabic (base shapes
only) (or ASCII 420
and 8859_6)
9030 Cp874 Thai (host extended
SBCS)
13124 Cp1381 SBCS portion of
Simplified Chinese
EBCDIC mixed (GBK
is included)
28709 Cp948 SBCS portion of
Traditional Chinese
EBCDIC mixed
(CCSID 937)

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java Naming and Directory Interface

The Java Naming and Directory Interface (JNDI) is part of JavaSoft’s platform
application program interfaces (API). With JNDI you can connect seamlessly to
multiple naming and directory services. You can build powerful and portable
directory-enabled Java applications by using this interface.

JavaSoft developed the JNDI specification with leading industry partners,

including IBM, SunSoft, Novell, Netscape, and Hewlett-Packard Co.

If you would like to run JNDI, add this to your classpath:

/QIBM/ProdData/Java400/ext/ibmjndi.jar:/QIBM/ProdData/Java400/ext/jndi.jar

For more information about JNDI, see Java Naming and Directory interface by Sun

Microsystems, Inc. For IBM-specific information, see the DSSeries LDAP V3

Client for Java Programming Guide.

Chapter 3. AS/400 Developer Kit for Java concepts 47

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Java Virtual Machine Debug Interface

In Java 2 SDK (J2SDK), Standard Edition, version 1.2, the Java Virtual Machine
Debug Interface (JVMDI) is part of Sun Microsystems, Inc. platform application
program interfaces (APIs). JVMDI allows anyone to write a Java debugger for
AS/400 in AS/400 C code. The debugger does not need to know the internal
structure of the Java virtual machine, and cannot harm the Java virtual machine
since it uses JVMDI interfaces.

The debugger runs in the same multi-thread capable job as the Java virtual
machine. The debugger uses Java Native Interface (JNI) Invocation APIs to create a
Java virtual machine. It then places a hook at the beginning of a user class main
method and calls the main method. When the main method begins, the hook is hit
and debugging begins. Typical debug facilities are available, such as setting
breakpoints, stepping, displaying variables, and changing variables.

The debugger handles communication between the job where the Java virtual
machine is running and a job handling the user interface. This user interface is
either on your AS/400 or another system.

A service program, called QJVAJVMDI that resides in the QSYS library, supports
the JVMDI functions.

For more information about JVMDI, see Java Virtual Machine Debugger Interface
by Sun Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Limitations, restrictions, and unique behaviors

When using the AS/400 Developer Kit for Java, you may notice that there are
some limitations in how it is used. This list identifies any known limitations,
restrictions, or unique behaviors.
v When a class is loaded and its superclasses are not found, the error indicates
that the original class was not found. For example, if class B extends class A,
and class A is not found when loading class B, the error indicates that class B
was not found, even though it is actually class A that was not found. When you
see an error that indicates that a class was not found, check to make sure that
the class and all of its superclasses are in the CLASSPATH. This also applies to
interfaces that are implemented by the class being loaded.

v The garbage collection heap is limited to 132,800 MB.

v The number of constructed objects is limited to 256 million.

v The java.net backlog parameter on AS/400 may behave differently than on other
platforms. For example:
– Listen backlogs 0, 1
- Listen(0) means to allow one pending connection; it does not disable a
socket.

48 AS/400 Developer Kit for Java

 - Listen(1) means to allow one pending comment, and means the same as
Listen(0).
– Listen backlogs > 1
- This allows many pending requests to remain on the listen queue. If a new
connection request arrives and the queue is at the limit, then it deletes one
of the pending requests.
v On other platforms that support JDK 1.1.6, the DecimalFormat class may
incorrectly format numeric input. This was fixed in the version of JDK 1.1.6 that
is used on AS/400.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

The Java platform

The Java platform is the environment for developing and managing Java applets
and applications. It consists of three primary components: the Java language, the
Java packages, and the Java virtual machine. The Java language and packages are
similar to C++ and its class libraries. The Java packages contain classes, which are
available in any compliant Java implementation. The application program interface
(API) should be the same on any system that supports Java.

Java differs from a traditional language, like C++, in how it compiles and runs. In
a traditional programming environment, you write and compile source code of a
program into object code for a specific hardware and operating system. The object
code binds to other object code modules to create a running program. The
executable code is specific for a particular set of computer hardware and does not
run on other systems without modification. This graphic illustrates the traditional
language deployment environment.

The Java environment differs from other programming environments in that the
Java compiler does not generate machine code for a hardware-specific instruction
set. Instead, the Java compiler converts Java source code into Java virtual machine
instructions, which Java class files store. You can use either ZIP files or JAR files to
store class files. The class file does not target a specific hardware platform, but
instead targets the Java virtual machine architecture.

This graphic shows the Java environment, as explained above.

Chapter 3. AS/400 Developer Kit for Java concepts 49

 You can embed the Java virtual machine within a web browser or an operating
system such as IBM Operating System/400 (OS/400). The Java virtual machine
consists of the Java interpreter and runtime. The interpreter performs the task of
interpreting the class file and running the Java instructions on a particular
hardware platform. The Java virtual machine is what allows Java code to be
written and compiled once, and run on any platform.

Java is a “multithreaded” programming language, thus more than one thread may
be running within the Java virtual machine at one time. Java threads provide a
way for a Java program to perform multiple tasks at the same time.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java applications and applets

You can write Java programs in two forms: applications and applets.

Applications are stand-alone programs that do not require the use of a browser.
Java applications run by starting the Java interpreter from the command line and
by specifying the file that contains the compiled application. Applications usually
reside on the system on which they are deployed. Applications access resources on
the system, and the Java “sandbox” security model does not restrict applications.

A Java applet is a small computer program that you write in Java and run inside
of a Java-compatible browser or appletviewer. A Hypertext Markup Language
(HTML) web document can include a reference to the system on which the applet
resides. At runtime, the server downloads the applet from the server onto the
target system. On the target system, the applet is restricted from accessing local
system resources unless authorization has been explicitly granted.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java virtual machine

The Java virtual machine is a runtime environment that you can add into a web
browser or any operating system, such as IBM Operating System/400 (OS/400).
The Java virtual machine runs instructions that a Java compiler generates. It
consists of a bytecode interpreter and runtime that allow Java class files to run on
any platform, regardless of the platform on which they were originally developed.

50 AS/400 Developer Kit for Java

 The class loader and security manager, which is part of the Java runtime, insulate
code that comes from another platform. They also can restrict which system
resources each class that is loaded accesses.

Note: Java applications are not restricted; only applets are restricted. Applications
can freely access system resources and use native methods. Most AS/400
Developer Kit for Java programs are applications.

You can use the Create Java Program (CRTJVAPGM) command to ensure that the
code meets the safety requirements that the Java runtime imposes to verify the
bytecodes. This includes enforcing type restrictions, checking data conversions,
ensuring that parameter stack overflows or underflows will not occur, and
checking for access violations. However, you do not need to explicitly verify the
bytecodes. If you do not use the CRTJVAPGM command in advance, then the
checks occur during the first use of a class. Once the bytecodes are verified, the
interpreter decodes the bytecodes and runs the machine instructions that are
needed to carry out the desired operations.

Note: The Java interpreter is only used if you specify OPTIMIZE(*INTERPRET) or

INTERPRET(*YES).

In addition to loading and running the bytecodes, the Java virtual machine
includes a garbage collector that manages memory. Garbage collection runs at the
same time as the loading and interpretation of the bytecodes.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java class files

Java class files are stream files that are produced when a source file is compiled by
the Java compiler. The class file contains tables that describe each field and method
of the class. The file also contains the bytecodes for each method, static data, and
descriptions that are used to represent Java objects.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java ZIP files

A ZIP file is a single file that contains many class files, which may be individually
extracted. The contents of a ZIP file may be either compressed or not compressed.
ZIP files are an especially useful way to store classes on systems that do not
support long file names.

To combine many files into one, see Java JAR files.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java JAR files

A Java ARchive (JAR) file is a file format, that is based on the ZIP file format,
which combines many files into one. You can use JAR as a general archiving tool,
but its main purpose is to download Java applets and their components (.class
files, images, and sounds). Java applets download into a browser in a single

Chapter 3. AS/400 Developer Kit for Java concepts 51

 Hypertext Transfer Protocol (HTTP) transaction rather than by opening a new
connection for each piece. This method of downloading improves the speed at
which an applet loads on a web page and begins functioning.

JAR is the only archive format that is cross-platform. JAR is also the only format
that handles audio files and image files, as well as class files. JAR is an open
standard, fully extendable format that is written in Java.

The JAR format also supports compression, which reduces the size of the file and
decreases download time. Additionally, an applet author may digitally sign
individual entries in a JAR file to authenticate their origin.

To update classes in JAR files, see the Java ajar tool.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java interpreter
The Java interpreter is the part of the Java virtual machine that interprets Java class
files for a particular hardware platform. The Java interpreter decodes each
bytecode and runs a series of machine instructions for that bytecode.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java threads
A thread is a single independent stream that runs within a program. Java is a
multithreaded programming language, so more than one thread may be running
within the Java virtual machine at one time. Java threads provide a way for a Java
program to perform multiple tasks at the same time. A thread is essentially a flow
of control in a program.

Threads are a modern programming construct that are used to support concurrent
programs and to improve the performance and scalability of applications. Most
programming languages support threads through the use of add-in programming
libraries. Java supports threads as built-in application program interfaces (API).

Note: The use of threads provides the support to increase the interactivity,
meaning a shorter wait at the keyboard because more things are running in
parallel. But, the program is not necessarily more interactive just because it has
threads.

Threads are the mechanism for waiting on long running interactions, while still
allowing the program to handle other work. Threads are the ability to support
multiple flows through the same code stream. They are sometimes called
“lightweight processes”. The Java language includes direct support for threads.
But, by design, it does not support asynchronous non-blocking input and output
with interrupts or multiple wait.

Threads allow the development of parallel programs that scale well in an

environment where a machine has multiple processors. If properly constructed,
they also provide a model for handling multiple transactions and users.

52 AS/400 Developer Kit for Java

 You can use threads in a Java program for a number of situations. Some programs
must be able to engage in multiple activities and still be able to respond to
additional input from the user. For example, a Web browser should be able to
respond to user input while playing a sound.

Threads can also use asynchronous methods. When you call a second method, you
do not have to wait for the first method to complete before the second method
continues with its own activity.

There are also many reasons not to use threads. If a program uses inherently
sequential logic, one thread can accomplish the entire sequence. Using multiple
threads in such a case results in a complex program with no benefits. There is
considerable work in creating and starting a thread. If an operation involves only a
few statements, it is faster to handle it in a single thread. This can be true even
when the operation is conceptually asynchronous. When multiple threads share
objects, the objects must synchronize to coordinate thread access and maintain
consistency. Synchronization adds complexity to a program, is difficult to tune for
optimal performance, and can be a source of programming errors.

For more threads information, see Developing multithreaded applications .

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Sun Microsystems, Inc. Java Development Kit

The Java Development Kit (JDK) is software that is distributed by Sun
Microsystems, Inc. for Java developers. It includes the Java interpreter, Java classes,
and Java development tools: compiler, debugger, disassembler, appletviewer, stub
file generator, and documentation generator.

The JDK enables programmers to write applications that are developed once and
run anywhere on any Java virtual machine. Java applications that are developed
with the JDK on one system can be used on another system without changing or
recompiling the code. The Java class files are portable to any standard Java virtual
machine.

To find more information about the current JDK, check the version of the AS/400
Developer Kit for Java on your AS/400.

You can check the version of the default AS/400 Developer Kit for Java Java
virtual machine on your AS/400 by entering either of the following:
v java -version on the Qshell command prompt.
v RUNJVA CLASS(*VERSION) on the CL command line.
Then, look for the same version of Sun Microsystems, Inc. JDK at The Source for

Java Technology java.sun.com for specific documentation. The AS/400

Developer Kit for Java is a compatible implementation of the Sun Microsystems,
Inc. Java Technology, so you should be familiar with their JDK documentation.

See Support for multiple Java Development Kits (JDKs) for more information about
using different Java virtual machines.

Chapter 3. AS/400 Developer Kit for Java concepts 53

 For more specific details on Sun Microsystems, Inc. Java Development Kit, see
these topics:
v Java packages lists the packages that are available as part of Sun Microsystems,
Inc. JDK.
v Java tools is a reference table that lists the tools that Sun Microsystems, Inc. JDK
supplies.
v Native methods and the Java Native Interface defines what a native method is
and what they do. This topic also briefly explains the Java Native Interface.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java packages
A Java package is a way of grouping related classes and interfaces in Java. Java
packages are similar to class libraries that are available in other languages.

The Java packages, which provide the Java APIs, are available as part of Sun
Microsystems, Inc. Java Development Kit (JDK).

Package Contents
java.applet Applet classes
java.awt Graphics, window, and graphical user
interface (GUI) classes
java.awt.datatransfer Data transfer classes
java.awt.event Event processing classes and interfaces
java.awt.image Image processing classes
java.awt.peer GUI interfaces for platform independence
java.beans JavaBeans component model API
java.io Input and output classes
java.lang Core language classes
java.lang.reflect Reflection API classes
java.math Arbitrary precision arithmetic
java.net Networking classes
java.rmi Remote Method Invocation classes
java.rmi.dgc RMI-related classes
java.rmi.registry RMI-related classes
java.rmi.server RMI-related classes
java.security Security classes
java.security.acl Security-related classes
java.security.interfaces Security-related classes
java.sql JDBC SQL API for database classes
java.text Internationalization classes
java.util Data types
java.util.zip Compression and decompression classes

For more information about the Java APIs by Sun Microsystems, Inc., see the Sun
Microsystems, Inc. API Users Guide.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

54 AS/400 Developer Kit for Java

Java tools
For a complete list of tools that Sun Microsystems, Inc. Java Development Kit
supplies, see Tools Reference by Sun Microsystems, Inc. For more information
about each individual tool that the AS/400 Developer Kit for Java supports, see
Java tools that are supported by the AS/400 Developer Kit for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Native methods and the Java Native Interface

Native methods are Java methods that start in a language other than Java. Native
methods can access system-specific functions and APIs that are not available
directly in Java.

The use of native methods limits the portability of an application, because it

involves system-specific code. Native method can either be new native code
statements or native code statements that call existing native code.

Once you decide that a native method is required, it may have to interoperate with
the Java virtual machine where it runs. The Java Native Interface (JNI) facilitates
this interoperability in a platform-neutral way.

The JNI is a set of interfaces that permit a native method to interoperate with the
Java virtual machine in numerous ways. For example, the JNI includes interfaces
that create new objects and call methods, get fields and set fields, process
exceptions, and manipulate strings and arrays.

For a complete description of the JNI, refer to the Java Native Interface by Sun

Microsystems, Inc. , or The Source for Java Technology java.sun.com .

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 3. AS/400 Developer Kit for Java concepts 55

56 AS/400 Developer Kit for Java
Chapter 4. Commands and tools for the AS/400 Developer Kit
for Java
When using the AS/400 Developer Kit for Java, you can either use Java tools with
the Qshell Interpreter or CL commands.

If you have prior Java programming experience, you may be more comfortable
using the Qshell Interpreter Java tools, because they are similar to the tools that
you would use with Sun Microsystems, Inc. Java Development Kit. See Qshell
Interpreter for information about using the Qshell environment.

If you are an AS/400 programmer, you may want to use the CL commands for
Java that are typical to the AS/400 server environment. Read on for more
information about using CL commands and Operations Navigator commands.

You can use any of these commands and tools with the AS/400 Developer Kit for
Java:
v The Qshell environment includes the Java development tools that are typically
required for program development.
v The CL environment contains the CL commands for optimizing and managing
Java programs.
v The Operations Navigator commands also create and run optimized Java
programs.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java tools that are supported by the AS/400 Developer Kit for Java
The AS/400 Developer Kit for Java supports these tools.
v Java ajar tool
v Java appletviewer tool
v Java extcheck tool
v Java jar tool
v Java jarsigner tool
v Java javac tool
v Java javadoc tool
v Java javah tool
v Java javakey tool
v Java javap tool
v Java keytool
v Java native2ascii tool
v Java policytool
v Java rmic tool
v Java rmid tool
v Java rmiregistry tool
v Java serialver tool

© Copyright IBM Corp. 1998, 1999 57

 v Java tnameserv tool
With a few exceptions, the Java tools, except the ajar tool, support the syntax and
options that are documented by Sun Microsystems, Inc. They must all run by using
the Qshell Interpreter.

You can start the Qshell Interpreter by using the Start Qshell (STRQSH or QSH)
command. When the Qshell Interpreter is running, a QSH Command Entry display
appears. All output and messages from Java tools and programs that run under
Qshell appear in this display. Any input to a Java program is also read from this
display. See Java command in Qshell for more details.

Note: Functions of AS/400 command entry are not available directly from within
the Qshell. To get a command entry, press F21 (CL command entry).

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java ajar tool

The ajar tool is an alternative interface to the jar tool that you use to create and
manipulate Java ARchive (JAR) files. You can use the ajar tool to manipulate both
JAR files and ZIP files.

If you need a ZIP interface or UNZIP interface, use the ajar tool instead of the jar
tool.

The ajar tool lists the contents of JAR files, extracts from JAR files, creates new
JAR files, and supports many of the ZIP formats just as the jar tool does.
Additionally, the ajar tool supports adding and deleting files in existing JAR files.

The ajar tool is available using the Qshell Interpreter. For more details, see ajar -
Alternative Java archive.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java appletviewer tool

The appletviewer tool allows you to run applets without a web browser. It is
compatible with the appletviewer tool that is supplied by Sun Microsystems, Inc.

The appletviewer tool is available using the Qshell Interpreter. You need to use
Remote Abstract Window Toolkit to run the appletviewer tool. See Running
the Java appletviewer tool with Remote AWT for information about how to set up
Remote AWT to use the appletviewer tool.

For more information about the appletviewer tool, see the appletviewer tool by
Sun Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

58 AS/400 Developer Kit for Java

Running the Java appletviewer tool with Remote Abstract
Window Toolkit
To use the Java appletviewer tool, you need to set up the Remote Abstract
Window Toolkit for Java on a Windows remote display, and use either the
sun.applet.AppletViewer class or run the appletviewer tool in the Qshell
Interpreter with Remote AWT properties.

For example, if you use the sun.applet.AppletViewer class and run example1.html
out of the TicTacToe directory, the command line should look like this:
JAVA CLASS(sun.applet.AppletViewer) PARM('example1.html') CLASSPATH('/TicTacToe')
PROP((RmtAwtServer '1.1.11.11') (os400.class.path.rawt 1)(java version 1.2))

If you use the appletviewer tool in the Qshell Interpreter and run example1.html
out of the TicTacToe directory, the commands should look like this:
qsh “enter”
cd TicTacToe “enter”
Appletviewer -J-DRmtAwtServer=1.1.11.11 -J-Dos400.class.path.rawt=1 -J-Djava.version=1.2 example1.

Note: -J are runtime flags for Appletviewer. -D are properties.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java extcheck tool

In Java 2 SDK (J2SDK), Standard Edition, version 1.2, the extcheck tool detects
version conflicts between a target JAR file and currently installed extension JAR
files. It is compatible with the keytool that is supplied by Sun Microsystems, Inc.

The extcheck tool is available using the Qshell Interpreter.

For more information about the extcheck tool, see the extcheck tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java jar tool

The jar tool combines multiple files into a single Java ARchive (JAR) file. It is
compatible with the jar tool that is supplied by Sun Microsystems, Inc.

The jar tool is available using the Qshell Interpreter.

For an alternative interface to the jar tool, see the ajar tool for creating and
manipulating JAR files.

For more information about AS/400 file systems, see the OS/400 Integrated File
System Introduction or files in the integrated file system.

For more information about the jar tool, see the jar tool by Sun Microsystems, Inc.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 59
 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Java jarsigner tool

In Java 2 SDK (J2SDK), Standard Edition, version 1.2, the jarsigner tool signs
JAR files and verifies signatures on signed JAR files. The jarsigner tool accesses
the keystore, which the keytool creates and manages, when it needs to find the
private key for signing a JAR file. In J2SDK, the jarsigner and keytool tools
replace the javakey tool. It is compatible with the jarsigner tool that is supplied
by Sun Microsystems, Inc.

The jarsigner tool is available using the Qshell Interpreter.

For more information about the jarsigner tool, see the jarsigner tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java javac tool

The javac tool compiles Java programs. It is compatible with the javac tool that is
supplied by Sun Microsystems, Inc. with one exception.
-classpath
Does not override the default classpath. Instead, it is appended to the
system default classpath. The -classpath option does override the
CLASSPATH environment variable.

The javac tool is available using the Qshell Interpreter.

If you have JDK 1.1.x installed on AS/400 as your default, but you need to run the
1.2 version of the java command, enter this command:
javac -djava.version=1.2 <my_dir> MyProgram.java

For more information about the javac tool, see the javac tool by Sun Microsystems,
Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java javadoc tool

The javadoc tool generates API documentation. It is compatible with the javadoc
tool that is supplied by Sun Microsystems, Inc.

The javadoc tool is available using the Qshell Interpreter.

For more information about the javadoc tool, see the javadoc tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

60 AS/400 Developer Kit for Java

Java javah tool
The javah tool facilitates the implementation of Java native methods. It is
compatible with the javah tool that is supplied by Sun Microsystems, Inc. with a
few exceptions.

Note: Writing native methods means that your application is not 100% pure Java.
It also means that your application is not directly portable across platforms. Native
methods are, by nature, platform or system specific. Using native methods may
increase your development and maintenance costs for your applications.

The javah tool is available using the Qshell Interpreter. It reads a Java class file
and creates a C-language header file in the current working directory. The header
file that is written is an AS/400 Stream File (STMF). It must be copied to a file
member before it can be included in a C program on AS/400.

The javah tool is compatible with the tool that is provided by Sun Microsystems,
Inc. If these options are specified; however, AS/400 ignores them.
-td The javah tool on AS/400 does not require a temporary directory.
-stubs Java on AS/400 only supports the Java Native Interface (JNI) form of
native methods. Stubs were only required for the pre-JNI form of native
methods.
-trace Relates to the .c stub file output, which Java on AS/400 does not support.
-v Not supported.

Note:The -jni option must always be specified. The AS/400 system does not
support native method implementations prior to JNI.

For more information about the javah tool, see the javah tool by Sun Microsystems,
Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java javakey tool

Use the javakey tool for encryption key, and certificate generation and
management, including generation of digital signatures for applets. It is compatible
with the javakey tool that is supplied by Sun Microsystems, Inc. in Java
Development Kit (JDK) versions 1.1.x.

In Java 2 Software Development Kit (J2SDK), Standard Edition, version 1.2, the
javakey tool is obsolete. Due to bugs in JDK versions 1.1.x, code that is signed
using the 1.1.x javakey tool is recognized as unsigned in the J2SDK, version 1.2. If
you sign code using J2SDK, version 1.2, it is recognized as unsigned on JDK 1.1.x
versions.

Note: The AS/400 secure sockets layer (SSL) support cannot access keys created by
this tool. Instead, you must use the certificate and key containers that are
integrated into the AS/400 and created or imported with the Digital Certificate
Manager. See making a Java application secure with the secure sockets layer for
more information.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 61
 Applet packaging and applet signing is dependent on your browser. Check your
browser documentation to ensure that your browser is compatible with the Java
JAR file format and javakey applet signing.

Note: The files that are created by the javakey tool contain sensitive information.
Appropriate integrated file system security measures protect the public and private
key files.

The javakey tool is available using the Qshell Interpreter.

For more information about AS/400 file systems, see the OS/400 Integrated File
System Introduction or files in the integrated file system.

For more information about the javakey tool, see the javakey tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java javap tool

The javap tool disassembles compiled Java files and prints out a representation of
the Java program. This may be helpful when the original source code is no longer
available on a system.

It is compatible with the javap tool that is supplied by Sun Microsystems, Inc. with
a few exceptions.
-b This option is ignored. Backward compatibility is not required, because
Java on AS/400 only supports Java Development Kit (JDK) 1.1.4 and later.
-p On AS/400, -p is not a valid option. You must spell out -private.
-verify
This option is ignored. The javap tool does not do verification on AS/400.

The javap tool is available using the Qshell Interpreter.

Note:The use of the javap tool to disassemble classes may violate the license
agreement for those classes. Consult the license agreement for the classes before
using the javap tool.

For more information about the javap tool, see the javap tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java keytool
In Java 2 SDK (J2SDK), Standard Edition, version 1.2, the keytool creates
public and private key pairs, self-signed certificates, and manage keystores. In
J2SDK, the jarsigner and keytool tools replace the javakey tool. It is compatible
with the keytool that is supplied by Sun Microsystems, Inc.

The keytool is available using the Qshell Interpreter.

62 AS/400 Developer Kit for Java

 For more information about the keytool, see the keytool by Sun Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java native2ascii tool

The native2ascii tool converts a file with native-encoded characters (characters
which are non-Latin 1 and non-Unicode) to one with Unicode-encoded characters.
It is compatible with the native2ascii tool that is supplied by Sun Microsystems,
Inc.

The native2ascii tool is available using the Qshell Interpreter.

For more information about the native2ascii tool, see the native2ascii tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java policytool
In Java 2 SDK, Standard Edition, version 1.2, the policytool creates and
changes the external policy configuration files that define the Java security policy
of your installation. It is compatible with the policytool that is supplied by Sun
Microsystems, Inc.

The policytool is a graphical user interface (GUI) tool available using the Qshell
Interpreter and the Remote Abstract Window Toolkit. See AS/400 Developer Kit
for Java Remote Abstract Window Toolkit for more information.

For more information about the policytool, see the policytool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java rmic tool

The rmic tool generates stub files and class files for Java objects. It is compatible
with the rmic tool that is supplied by Sun Microsystems, Inc.

The rmic tool is available using the Qshell Interpreter.

For more information about the rmic tool, see the rmic tool by Sun Microsystems,
Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 63
 Java rmid tool
In Java 2 SDK (J2SDK), Standard Edition, version 1.2, the rmid tool starts the
activation system daemon, so objects can be registered and activated in a Java
virtual machine. It is compatible with the rmid tool that is supplied by Sun
Microsystems, Inc.

The rmid tool is available using the Qshell Interpreter.

For more information about the rmid tool, see the rmid tool by Sun Microsystems,
Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java rmiregistry tool

The rmiregistry tool starts a remote object registry on a specified port. It is
compatible with the rmiregistry tool that is supplied by Sun Microsystems, Inc.

The rmiregistry tool is available using the Qshell Interpreter.

For more information about the rmiregistry tool, see the rmiregistry tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java serialver tool

The serialver tool returns the version number or serialization-unique identifier for
one or more classes. It is compatible with the serialver tool that is supplied by
Sun Microsystems, Inc.

The serialver tool is available using the Qshell Interpreter.

For more information about the serialver tool, see the serialver tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java tnameserv tool

In Java 2 SDK (J2SDK), Standard Edition, version 1.2, the tnameserv tool
provides access to the naming service. It is compatible with the tnameserv tool that
is supplied by Sun Microsystems, Inc.

The tnameserv tool is available using the Qshell Interpreter.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

64 AS/400 Developer Kit for Java

Java command in Qshell
The java command in Qshell runs Java programs. It is compatible with the java
tool that is supplied by Sun Microsystems, Inc. with a few exceptions.

The AS/400 Developer Kit for Java ignores these options of the java command in
Qshell.

Option Description
-cs Not supported.
-checksource Not supported.
-debug Supported by the AS/400 internal debugger.
-noasyncgc Garbage collection is always running with
the AS/400 Developer Kit for Java.
-noclassgc Garbage collection is always running with
the AS/400 Developer Kit for Java.
-prof AS/400 has its own performance tools.
-ss Not applicable on AS/400.
-oss Not applicable on AS/400.
-t AS/400 uses its own trace function.
-verify Always verify on AS/400.
-verifyremote Always verify on AS/400.
-noverify Always verify on AS/400.

On AS/400, the -classpath option does not override the default classpath. Instead,
it is appended to the system default classpath. The -classpath option does
override the CLASSPATH environment variable.

The java command in Qshell supports new options for AS/400. These are the new
options that are supported.

Option Description
-secure Checks for public write access to directories
in the CLASSPATH.
-gcfrq Specifies the garbage collection frequency.
-gcpty Specifies the garbage collection priority.
-opt Specifies the optimization level.
-verbosegc A message is displayed for each garbage
collection sweep.

The Run Java (RUNJVA) command in the CL command reference information

describes these new options in detail. The CL command reference information for
the Create Java Program (CRTJVAPGM) command, Delete Java Program
(DLTJVAPGM) command, and Display Java Program (DSPJVAPGM) command
contains information about managing Java programs.

The java command in Qshell is available using the Qshell Interpreter.

For more information about the java command in Qshell, see the java tool by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 65
CL commands that are supported by Java
The AS/400 Developer Kit for Java supports the these CL commands.
v Create Java Program (CRTJVAPGM) command creates a Java program on
AS/400 from a Java class file, ZIP file, or JAR file.
v Change Java Program (CHGJVAPGM) command changes the attributes of a Java
program.
v JAVA command and Run Java (RUNJVA) command run AS/400 Java programs.
v Delete Java Program (DLTJVAPGM) command deletes an AS/400 Java program
that is associated with a Java class file, ZIP file, or JAR file.

v Dump Java Virtual Machine (DMPJVM) command dumps information about

the Java virtual machine for a specified job to a spooled printer file.
v Display Java Program (DSPJVAPGM) command displays information about a
Java program on AS/400.
For more information see the OS/400 Program and CL Command APIs, SC41-5870

book.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Create Java Program (CRTJVAPGM) command

Purpose:

The Create Java Program (CRTJVAPGM) command creates a Java program on

AS/400 from a Java class file, or one or more Java programs from a JAR file. If the
file name ends with .jar or .zip, then it is a JAR file. The resulting Java program
object or objects become part of the class file or JAR file object, but cannot be
changed directly.The Java programs run when you start the Run Java (RUNJVA)
command. You can control the size and performance of the Java program by using
the OPTIMIZE parameter, or LICOPT parameter.

Syntax:
CRTJVAPGM Command
(P)
>>—CRTJVAPGM—CLSF(—.-class-file-name-.—)————————————————>
'-JAR-file-name—-'
>—.———————————————.—.———————————-.———————>
| .-10————-. | | .-*YES-. |
'-OPTIMIZE(—+-*INTERPRET-+—)-' '-REPLACE(—'-*NO—'—)-'
|-20————-|
|-30————-|
'-40————-'
>—.———————————————-.—.————————————.——————>
| .-*NONE———. | | .-*USER—. |
'-ENBPFRCOL(—+-*ENTRYEXIT-+—)-' '-USRPRF(—'-*OWNER-'—)-'
'-*FULL———'
>—.————————————-.—.————————————.—————————>
| .-*NO—. | | .-*NONE-. |
'-USEADPAUT(—'-*YES-'—)-' '-SUBTREE(—'-*ALL—'—)-'
>—.————————————————-.———————————————————>
| .-*OPTIMIZE———. |
'-LICOPT(—'-options-string-'—)—'

66 AS/400 Developer Kit for Java

>—.————————————————.———————————————————-><
| .-*CURRENT———-. |
'-TGTRLS(—'-target-release-'—)-'

Notes: (P) All parameters preceding this point can be specified positionally.

Required parameters:
CLSF
The CLSF parameter specifies the class file name or JAR file name from
which you create Java programs on AS/400. One or more directory names
may qualify the class file name.
For the class-file-name, specify the name of the class file or a pattern for
identifying the name of the class files that are used. Specify a pattern in
the last part of the name. An asterisk matches any number of characters,
and a question mark matches a single character. Enclose the name in
apostrophes if it is qualified or contains a pattern. An example of a
qualified class file name is:
'/directory1/directory2/myclassname.class'

An example of a pattern is:

'/directory1/directory2/myclass*.class'

For the JAR-file-name, specify the name of the JAR file or a pattern for
identifying the name of the JAR files that are used. A file is a JAR file if it
ends with .jar or .zip. Specify a pattern in the last part of the name. An
asterisk matches any number of characters, and a question mark matches a
single character. Enclose the name in apostrophes if it is qualified or
contains a pattern. An example of a qualified JAR file name is:
'/directory1/directory2/myappname.jar'

An example of a pattern is:

'/directory1/directory2/myapp*.zip'

Optional parameters:
OPTIMIZE
The OPTIMIZE parameter for the CRTJVAPGM command specifies the
optimization level of the AS/400 Java program that attaches to the class
file object or JAR file object. If you use the OPTIMIZE(*INTERPRET)
parameter, the resulting Java program is verified and converted to an
internal form. It is then interpreted when it runs. For the other
optimization levels, the internal form includes AS/400 machine
instructions. These AS/400 machine instructions are optimized based on
the specified optimization level. The AS/400 directly runs the machine
instructions when the program runs.
When you specify OPTIMIZE(*INTERPRET), Java programs are smaller,
but run slower than Java programs that are created with higher
optimization levels. As you increase the optimization level beyond 10, Java
program performance gradually improves, but the time that is required to
create the Java program increases. It also makes it more difficult to debug
the Java program as you increase the optimization level.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 67
 Typically, *INTERPRET is a good option during development and early
testing, because quick edit, compile turnaround, and quality debug
functions are important. As the program moves toward release, the level of
optimization often increases.
This list shows how the optimization levels differ and what they do:
10 The Java program contains a transformed version of the class file
bytecodes, but has only minimal additional compiler optimization.
You can display and change variables while debugging.
20 The Java program contains a compiled version of the class file
bytecodes and performs additional compiler optimization. You can
display, but not change variables while debugging.
30 The Java program contains a compiled version of the class file
bytecodes and performs more compiler optimization than
optimization level 20. Debugging at higher optimization levels is
more difficult, because optimization reduces the ability to stop at
precise points in the code and display program variables. You can
display, but not change variables while debugging. The values that
are presented may not be the current value of the variable.
40 The Java program contains a compiled version of the class file
bytecodes and performs more compiler optimization than
optimization level 30. In addition, it includes optimization that
disables call and instruction tracing. Optimization level 40 includes
cross-class optimizations. In a small number of cases, the order in
which static initializers are run for unrelated classes (not related by
inheritance nor containment) may be different than outlined in the
static initialization specification. In addition, it includes
optimization that disables call and instruction tracing.
Note: If your Java program fails to optimize or throws an
exception at optimization level 40, use optimization level 30.
*INTERPRET
The Java programs that you create are not optimized. When you
start the program, it interprets the class file bytecode. You can
display and change variables while debugging.

REPLACE
The REPLACE parameter specifies whether a new Java program replaces
an existing Java program that is associated with the class file.
*YES Forces all of the Java programs that are associated with the class
file or JAR file to be re-created for your selected optimization level.
For large JAR files, this could be time consuming, but it creates the
highest performing code generation and uses the minimum
amount of space on the disk.
*NO Recreates the minimum number of required Java programs that are
associated with the class file or JAR file. If classes have been
modified, no Java program is associated with one or more classes.
If the Java program is at a different optimization level than you
had specified with the OPTIMIZE parameter, new Java programs
are created.

68 AS/400 Developer Kit for Java

ENBPFRCOL
The ENBPFRCOL parameter specifies whether or not to enable the
collection of performance data.
*NONE
The collection of performance data is not enabled. No performance
data is collected.
*ENTRYEXIT
The performance data is collected for procedure entry and exit.
*FULL The performance data is collected for procedure entry and exit.
Performance data is also collected before and after calls to the
external procedures.

USRPRF
The USRPRF parameter specifies whether the authority checking that is
done while the program is running should include only the user who is
running the program (*USER) or both the user who is running the program
and the program owner (*OWNER). The user profiles of the program user,
or both the program user and the program owner control which objects the
program can use. This includes the authority that the program has for each
object. Only the program owner or program user with QSECOFR authority
can change the user profile attribute of an existing Java program.
Note: Integrated file system functions that the program might use, such as
File.delete(), do not recognize adopted authority. Integrated file system
functions only use the authority from the user who is running the
program.
*USER
The program runs under the user profile of the program user.
*OWNER
You use the user profiles of both the program owner and program
user when processing the program. You can use the collective sets
of object authority in both user profiles to find and access objects
during program processing. Authority from the group profile of
the owning user profile is not used.

USEADPAUT
The USEADPAUT parameter specifies whether or not you use program
adopted authority from previous programs in the call stack as a source of
authority when the program is running.
Note: Integrated file system functions that the program might use, such as
File.delete(), do not recognize adopted authority. Integrated file system
functions only use the authority from the user who is running the
program.
*NO Do not use program adopted authority from previous call levels
when the program is running. If an authorization list is specified
for the QUSEADPAUT system value and the user performing
CRTJVAPGM is not included in that authorization list, then the
value *NO is automatically supplied for this parameter.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 69
 *YES Use program adopted authority from previous call levels when the
program is running.

LICOPT
The LICOPT parameter specifies one or more licensed internal code
compile-time optimization options. Only advanced programmers, who
understand the potential benefits and drawbacks of each selected type of
optimization, should use this parameter. For a listing of recognized strings
for the LICOPT parameter, see LICOPT parameter strings.
Note:You should contact your service representative for more information
on how to use these optimizations.
*OPTIMIZE
The *OPTIMIZE option uses the set of compile-time optimizations,
which are implicitly associated with the optimization level that is
specified on the OPTIMIZE parameter. If you specify
OPTIMIZE(*INTERPRET), no compile-time optimizations are
performed.
’Licensed-Internal-Code-options-string’
Use the selected licensed internal code compile-time optimization
options when creating the Java program object. Certain
optimization options may reduce your ability to debug the Java
program that was created.

SUBTREE
The SUBTREE parameter specifies whether or not subdirectories are
processed when looking for files that match the CLSF keyword.
*NONE
Only the files that match the object name pattern are processed. No
subtrees are processed. If the directory has subdirectories, neither
the subdirectories nor the objects on the subdirectories are
processed.
*ALL The entire subtree of the path that is specified in CLSF is processed
to create Java programs for files that match the name that was
specified on the CLSF parameter.

TGTRLS
The TGTRLS parameter specifies the release of the operating system on
which you intend to use the object that is being created. When specifying
the target-release, you use the VxRxMx format to specify the release. Vx is
the version. Rx is the release, and Mx is the modification level. For
example, V4R5M0 is version 4, release 5, modification level 0. Valid values
depend on the current version, release, and modification level. These valid
values change with each new release.
*CURRENT
The object is used on the release of the operating system that is

70 AS/400 Developer Kit for Java

 currently running on your system. The object can also be used on a
system that has any subsequent release of the operating system
installed.
target-release
Specify the release in the format VxRxMx. You can use the object
on a system with a specified release, or with any subsequent
release of the operating system installed. Valid values depend on
the current version, release, and modification level. These valid
values change with each new release. To see a list of valid target
release levels, press the F4 key.

For more performance information, see tuning Java program performance with the
AS/400 Developer Kit for Java.

See Example: Create Java Program (CRTJVAPGM) command for an example that
uses the CRTJVAPGM command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Licensed Internal Code option parameter strings

This table shows the strings that are recognized by the Licensed Internal Code
option (LICOPT) parameter. These strings are not case sensitive, but they are
shown as mixed case for readability.

LICOPT parameter strings

String Description
AllFieldsVolatile If set, treats all fields as volatile.
NoAllFieldsVolatile Is not set; does not treat all fields as volatile.
AllowBindingToLoadedClasses Indicates that temporary class representations
that were created as a result of defineClass
calls within a running Java virtual machine
may be tightly bound to other class
representations within the same Java virtual
machine.
NoAllowBindingToLoadedClasses Indicates that temporary class representations
that were created as a result of defineClass
calls within a running Java virtual machine
may not be tightly bound to other class
representations within the same Java virtual
machine.
AllowBindingWithinJar Indicates that class representations within a
ZIP file or JAR file may be tightly bound to
other class representations within the same
ZIP file or JAR file.
NoAllowBindingWithinJar Indicates that class representations within a
ZIP file or JAR file may not be tightly bound
to other class representations within the same
ZIP file or JAR file.
AllowInlining Tells the translator that it is permitted to
inline local methods. This is the default for
optimization levels 30 and 40.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 71
 String Description
NoAllowInlining Does not tell the translator that it is
permitted to inline local methods.
AssumeUnknownFieldsNonvolatile When the attributes of a field in an external
class cannot be determined, this parameter
generates code by assuming that the field is
non-volatile.
NoAssumeUnknownFieldsNonvolatile When the attributes of a field in an external
class cannot be determined, this parameter
generates code by assuming that the field is
volatile.
BindErrorHandling Specifies what action should be taken if, as a
result of honoring the
AssumeUnknownFieldsNonvolatile,
PreresolveExtRef, or PreLoadExtRef Licensed
Internal Code option, the Java virtual
machine class loader detects that a class
representation contains method
representations, which cannot be used in the
current context.
BindInit Use bound call to local init methods.
NoBindInit Do not use bound call to local init methods.
BindSpecial Use bound call to local special methods.
NoBindSpecial Do not use bound call to local special
methods.
BindStatic Use bound call to local static methods.
NoBindStatic Do not use bound call to local static
methods.
BindTrivialFields Bind trivial field references during program
creation.
NoBindTrivialFields Resolve field references at first touch.
BindVirtual Use bound call to local final virtual methods.
NoBindVirtual Do not use bound call to local final virtual
methods.
DeferResolveOnClass Takes a string parameter that is presumed to
be the name of a class (for example,
java.lang.Integer). When you set
PreresolveExtRef to optimization level 40,
classes that are specified with
DeferResolveOnClass are not in the
preresolve operation. This is useful if some
classes in unused paths in the code are not in
the CLASSPATH. It allows you to use
optimization level 40 regardless of this by
specifying a
“DeferResolveOnClass=’somepath.someclass’”
for each missing class. Multiple
DeferResolveOnClass entries are allowed.
DevirtualizeFinalJDK Allows CRTJVAPGM to use knowledge of
the standard JDK to devirtualize calls to
those JDK methods that are known to be
final methods or members of final classes. It
is the default at optimization levels 30 and
40.
NoDevirtualizeFinalJDK Does not allow CRTJVAPGM to use
knowledge of the standard JDK to
devirtualize calls to those JDK methods that
are known to be final methods or members
of final classes.

72 AS/400 Developer Kit for Java

String Description
DevirtualizeRecursive Causes special code to be generated in the
case of some recursive methods and
eliminates much of the overhead of the
recursive method calls. However, additional
checking logic is generated on initial entry to
the recursive method, so performance may
not improve in cases of shallow recursion.
NoDevirtualizeRecursive Does not cause special code to be generated
in the case of some recursive methods.
DisableIntCse Causes certain common subexpression
optimizations to be disabled when generating
code for certain types of integer expressions.
This may improve overall optimization by
exposing other optimization oppportunities
to the Optimizing Translator.
NoDisableIntCse Causes certain common subexpression
optimizations to not be disabled when
generating code for certain types of integer
expressions. This generally results in better
performing code at lower optimization levels.
DoExtBlockCSE Perform extended basic block common
subexpression elimination.
NoDoExtBlockCSE Do not perform extended basic block
common subexpression elimination.
InlineArrayCopy Causes the inlining of the System.arraycopy
method in some cases of scalar arrays.
NoInlineArrayCopy Prevents the inlining of the System.arraycopy
method.
DoLocalCSE Perform local common subexpression
elimination.
NoDoLocalCSE Do not perform local common subexpression
elimination.
EnableCseForCastCheck If set, generates code for castcheck that can
be DAGed to an earlier instance of.
Is not set; does not generate code for
castcheck that can be DAGed to an earlier
NoEnableCseForCastCheck instance of.
ErrorReporting Runtime error reporting field**: Provides the
option to fail the compile when encountering
verification or class format errors. 0=Report
all errors immediately; 0=Report all errors
immediately; 1=Defer reporting of bytecode
verification errors; 2=Defer reporting of
bytecode verification errors and class format
errors to runtime.
InlineInit Inline init methods for java.lang classes.
NoInlineInit No inline init methods.
InlineMiscFloat Inline miscellaneous float/double methods
from java.lang.Math.
NoInlineMiscFloat No inline miscellaneous float/double
methods.
InlineMiscInt Inline miscellaneous int/long methods from
java.lang.Math.
NoInlineMiscInt No inline miscellaneous int/long methods.
InlineTransFloat Inline transcendental float/double methods
from java.lang.Math.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 73
 String Description
NoInlineTransFloat No inline transcendental float/double
methods.
PreloadExtRef Indicates that referenced classes may be
pre-loaded (without class initialization) upon
method entry.
NoPreloadExtRef Indicates that referenced classes may not be
pre-loaded upon method entry. However, the
PreresolveExtRef parameter overrides this
setting and causes referenced classes to be
pre-loaded and initialized. .
PreresolveExtRef Preresolve referenced methods at method
entry.
NoPreresolveExtRef Resolve method references at first touch. Use
to resolve “class not found” exceptions on
programs that run on other machines.
ShortCktAthrow If set, attempt to short-circuit athrows.
NoShortCktAthrow Is not set; does not attempt to short-circuit
athrows.
ShortCktExSubclasses If set, recognize some subclasses of Exception
and short-circuit them directly.
NoShortCktExSubclasses Is not set; does not recognize some
subclasses of Exception and short-circuit
them directly.

The double asterisk (**) signifies that these strings require a numerical value for
input in the syntax of stringname=number (with no spaces in between).

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Create Java Program (CRTJVAPGM) command

To create a Java program and associate it with the class file, myJavaClassFileName,
use the Create Java Program (CRTJVAPGM) command. When created with
OPTIMIZE(*INTERPRET), the Java program class file bytecodes are interpreted. To
start the program, use the Run Java (RUNJVA) command.

Example 1: Create an interpreted Java program

CRTJVAPGM CLSF('/projectA/team2/myJavaClassFileName.class')
OPTIMIZE(*INTERPRET)

This example is the same as Example 1; except that the program is optimized. It is
created with OPTIMIZE(40), so the program contains compiled machine
instructions that run when the Java program starts.

Example 2: Create an optimized Java program

CRTJVAPGM CLSF('/projectB/team2/myJavaclassfile.class')
OPTIMIZE(40)

See the Create Java Program (CRTJVAPGM) command for syntax diagram and
parameter details.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

74 AS/400 Developer Kit for Java

Change Java Program (CHGJVAPGM) command
Purpose:

The Change Java Program (CHGJVAPGM) command changes the attributes of a

Java program, which is attached to either a Java class file or a set of Java programs
that are attached to a JAR file. A file is a JAR file if the file name ends with .jar or
.zip.

You can recreate Java programs if the attributes that are specified differ from those
of the current programs or if you specify MERGE(*YES). The CHGJVAPGM
command does not create Java programs for class files, or classes within JAR files
that do not have attached Java programs. A Java program is created dynamically
when a class is loaded without a current Java program attached. There may be
classes in a JAR file from which no Java programs have been created. You can use
the Create Java Program (CRTJVAPGM) command to create Java programs from
these classes. The CHGJVAPGM command replaces existing Java programs only.

Syntax:
CHGJVAPGM Command
(P)
>>—CHGJVAPGM—CLSF(—.-class-file-name-.—)————————————————>
'-JAR-file-name—-'
>—.———————————————.—.———————————————-.———>
| .-SAME———-. | | .-*SAME———. |
'-OPTIMIZE(—+-*INTERPRET-+—)-' '-ENBPFRCOL(—+-*NONE———+—)-'
|-10————-| |-*ENTRYEXIT-|
|-20————-| '-*FULL———'
|-30————-|
'-40————-'
>—.——————————-.—.————————————.———————————>
| .-*RPL-. | | .-*NONE-. |
'-MERGE(—'-*YES-'—)-' '-SUBTREE(—'-*ALL—'—)-'
>—.————————————————.———————————————————->
| .-*SAME—————. |
'-LICOPT(—+-*OPTIMIZE———+—)-'
'-options-string-'

Notes: (P) All parameters preceding this point can be specified positionally.

Required parameter:
CLSF
The CLSF parameter specifies the class file name or JAR file name that are
attached to the Java programs to change. One or more directory names
may qualify the class file name.
For the class-file-name, specify the name of the class file or a pattern for
identifying the name of the class files that are used. Specify a pattern in
the last part of the name. An asterisk matches any number of characters,
and a question mark matches a single character. Enclose the name in
apostrophes if it is qualified or contains a pattern. An example of a
qualified class file name is:
'/directory1/directory2/myclassname.class'

An example of a pattern is:

'/directory1/directory2/myclass*.class'

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 75
 For the JAR-file-name, specify the name of the JAR file or a pattern for
identifying the name of the JAR files that are used. A file is a JAR file if it
ends with .jar or .zip. Specify a pattern in the last part of the name. An
asterisk matches any number of characters, and a question mark matches a
single character. Enclose the name in apostrophes if it is qualified or
contains a pattern. An example of a qualified JAR file name is:
'/directory1/directory2/myappname.jar'

An example of a pattern is:

'/directory1/directory2/myapp*.zip'

Optional parameters:
OPTIMIZE
The OPTIMIZE parameter for the CHGJVAPGM command specifies the
optimization level of each AS/400 Java program that is attached to the
class object or the JAR file object. If you use the OPTIMIZE(*INTERPRET)
parameter, the resulting Java program is verified and converted to an
internal form. It is then interpreted when it runs. For the other
optimization levels, the internal form includes AS/400 machine
instructions. These AS/400 machine instructions are optimized based on
the specified optimization level. The AS/400 directly runs the machine
instructions when the program runs.
OPTIMIZE(*INTERPRET) Java programs are smaller, but run slower than
Java programs that are created with higher optimization levels. As the
optimization level increases beyond 10, Java program performance
gradually improves, but the time that is required to create the Java
program increases. It also makes it more difficult to debug the Java
program as you increase the optimization level.
Typically, *INTERPRET is a good option during development and early
testing, because quick edit, compile turnaround, and quality debug
functions are important. As the program moves toward release, the level of
optimization often increases.
This list shows how the optimization levels differ and what they do:
*SAME
The value does not change.
10 The Java program contains a transformed version of the class file
bytecodes, but has only minimal additional compiler optimization.
You can display and change variables while debugging.
20 The Java program contains a compiled version of the class file
bytecodes and has additional compiler optimization. You can
display, but not change variables while debugging.
30 The Java program contains a compiled version of the class file
bytecodes and has more compiler optimization than optimization
level 20. Debugging at higher optimization levels is more difficult,
because optimization reduces the ability to stop at precise points in
the code and display program variables. You can display, but not
change variables while debugging. The values that are presented
may not be the current value of the variable.
40 The Java program contains a compiled version of the class file
bytecodes and has more compiler optimization than optimization
level 30. In addition, it includes optimization that disables call and

76 AS/400 Developer Kit for Java

 instruction tracing.
Note: If your Java program fails to optimize or throws an
exception at optimization level 40, use optimization level 30.
*INTERPRET
The Java program that is created does not contain machine specific
instructions. When the program starts, it interprets the class file
bytecodes. You can display and change variables while debugging.

ENBPFRCOL
The ENBPFRCOL parameter specifies whether or not to enable the
collection of performance data.
*SAME
The value does not change.
*NONE
The collection of performance data is not enabled. No performance
data is collected.
*ENTRYEXIT
The performance data is collected for procedure entry and exit.
*FULL The performance data is collected for procedure entry and exit.
Performance data is also collected before and after calls to the
external procedures.

MERGE
The MERGE parameter specifies whether or not you merge Java programs,
which are attached to a JAR file, into the minimum number of Java
programs possible. This parameter is ignored if you are processing a Java
class file.
*RPL Specifies that you merge Java programs, which are attached to a
JAR file, only if the Java programs need to be re-created and
replaced, because other Java program attributes are being changed.
If no attributes are changed and no Java programs need to be
re-created and replaced, then no merging of Java programs occurs.
*YES You merge all Java programs, which are attached to a JAR file, into
the minimum number of Java programs possible to save space or
improve class loader time.

SUBTREE
The SUBTREE parameter specifies whether or not subdirectories are
processed when looking for files that match the CLSF keyword.
*NONE
Only the files that match the object name pattern are processed. No
subtrees are processed. If the directory has subdirectories, neither
the subdirectories nor the objects on the subdirectories are
processed.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 77
 *ALL The entire subtree of the path that is specified in CLSF is processed
to create Java programs for files that match the name that was
specified on the CLSF parameter.

LICOPT
The LICOPT parameter specifies one or more licensed internal code
compile-time optimization options. Only advanced programmers, who
understand the potential benefits and drawbacks of each selected type of
optimization, should use this parameter.
Note: You should contact your service representative for more information
on how to use these optimizations.
*SAME
The value does not change.
*OPTIMIZE
The *OPTIMIZE option uses the set of compile-time optimizations,
which are implicitly associated with the optimization level that is
specified on the OPTIMIZE parameter. If you specify
OPTIMIZE(*INTERPRET), no compile-time optimizations are
performed.
’options-string’
See LICOPT parameter strings for a listing of recognized strings.

For more performance information, see tuning Java program performance with the
AS/400 Developer Kit for Java.

See Example: Change Java Program (CHGJVAPGM) command for an example that
uses the CHGJVAPGM command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Change Java Program (CHGJVAPGM) command

To change a Java program that is associated with the class file,
myJavaClassFileName, use the Change Java Program (CHGJVAPGM) command.
The Java program class file bytecodes are interpreted. To start the program, use the
Run Java (RUNJVA) command. The Java program is re-created only if the
attributes that are specified are different than those of the current program.

Example 1: Change an interpreted Java program

CHGJVAPGM CLSF('/projectA/team2/myJavaClassFileName.class')
OPTIMIZE(*INTERPRET)

This example is the same as Example 1, except that the program is optimized. It is
changed with OPTIMIZE(10), so the program contains compiled machine
instructions that run when the Java program starts.

Example 2: Change an optimized Java program in a JAR file

78 AS/400 Developer Kit for Java

 CHGJVAPGM CLSF('/projectB/myJavaappfile.jar')
OPTIMIZE(10)

See the Change Java Program (CHGJVAPGM) command for syntax diagram and
parameter details.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

JAVA command
The JAVA command functions exactly the same as the Run Java (RUNJVA)
command. You can use them interchangeably. See Run Java (RUNJVA) command
for information and parameters that you can use with the JAVA command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Run Java (RUNJVA) command

Purpose:

The Run Java (RUNJVA) command runs the AS/400 Java program, which is
associated with the Java class that is specified. If a Java program does not exist,
one is created and associated with the class file.

Syntax:
RUNJVA Command
>>—RUNJVA—CLASS(—.-class-name—.—)———————————————————>
| (1)|
'-*VERSION——'
(P)
>—.———————————————————————————————————->
| .-*NONE—————————. |
| | <————————-> (2)| |
'-PARM(—'—-parameter-value———'—)-'
>—.———————————————-.—.—————————————.—————>
| .-*ENVVAR——. | | .-*WARN—-. |
'-CLASSPATH(—'-class-path-'—)-' '-CHKPATH(—+-*SECURE-+—)-'
'-*IGNORE-'
>—.———————————————.—.———————————————.———->
| .-10————-. | | .-*OPTIMIZE-. |
'-OPTIMIZE(—+-*INTERPRET-+—)-' '-INTERPRET(—+-*NO———-+—)-'
+-*JIT———-+ |-*YES———|
+-20————-+ '-*JIT———'
+-30————-+
'-40————-'
>—.——————————————————————————-.—————————>
| .-*NONE————————————————-. |
| | <————————————————> (3)| |
'-PROP(—'—-property-name—property-value———-'—)-'
>—.———————————————————————————.—————————>
| .-*NOMAX———————————————-. |
'-GCHMAX(—'-garbage-collection-heap-maximum-size-'—)-'
>—.———————————————————————————.—————————>
| .-*2048————————————————. |
'-GCHINL(—'-garbage-collection-heap-initial-size-'—)-'
>—.—————————————————————————-.——————————->
| .-50————————————————-. |
'-GCFRQ(—'-garbage-collection-frequency-value-'—)-'
>—.——————————.—.———————————————————.————-><
| .-20-. | | .-*NONE————————. |

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 79
 '-GCPTY(—+-30-+—-)-' | | <———————-> (4)| |
'-10-' '-OPTION(—'—.-*DEBUG——-.———'—)-'
|-*VERBOSE—-|
|-*VERBOSEGC-|
'-*NOCLASSGC-'

Notes: (1) All other parameters are ignored if CLASS(*VERSION) is specified.

(2) A maximum of 200 repetitions.
(P) All parameters preceding this point can be specified positionally.
(3) A maximum of 100 repetitions.
(4) A maximum of 4 repetitions.

Required parameters:
CLASS
The CLASS parameter specifies the class name that is to be run. One or
more package names may qualify the class name. Follow each package
name with a period. For example, CLASS(’pkg1.pkg2.myclass’) identifies a
class that is qualified by two package names.
For class-name, specify the name of the class that runs.

The limit for the CLASS parameter is 5000 characters.

*VERSION
The build version for Sun Microsystems, Inc. Java Development Kit
(JDK), and the Java virtual machine displays. No Java program
runs.

Optional parameters:

PARM
The PARM parameter specifies one or more parameter values that are
passed to the Java program. You may specify a maximum of 200 parameter
values.
For parameter-value, specify the parameters to pass to the Java program.

The limit for the PARM parameter is 256 characters.

*NONE
There are no input parameters to the Java program.

CLASSPATH
The CLASSPATH parameter specifies the path that is used to locate classes.
Colons separate the directories.
The classpath locates classes. An example classpath:
'/directory1/directory2:/QIBM/ProdData/Java400'

The limit for the CLASSPATH parameter is 5000 characters.

*ENVVAR
The environment variable CLASSPATH determines the classpath.

80 AS/400 Developer Kit for Java

CHKPATH
The CHKPATH parameter specifies the level of warnings that are given for
directories in the CLASSPATH that have public write authority. A directory
in the CLASSPATH that has public write authority may cause a security
exposure. An exposure could occur, because an undesired class may be
inserted into the directory that is found before the official class.
*WARN
A warning message is sent to the QJVACMDSRV job log for each
directory in the CLASSPATH that has public write authority.
*SECURE
A warning message is sent for each directory in the CLASSPATH
that has public write authority. If one or more warning messages
are sent, an escape message is sent and the Java program does not
run.
*IGNORE
Ignore the fact that directories in the CLASSPATH may have public
write authority. No warning messages are sent.

OPTIMIZE
The OPTIMIZE parameter specifies the optimization level of the AS/400
Java program that is used if no Java program has ever been associated
with the Java class. Optimization is a time consuming operation, so
programs run slowly the first time that they are optimized if you use the
RUNJVA command instead of the CRTJVAPGM command. However,
subsequent runs use the optimized form, so optimization is a one-time
cost. This is true for class files, JAR files, and ZIP files.
The effect of the OPTIMIZE parameter depends on the current
optimization level of the program. The current optimization level results
from either the previous use of the RUNJVA command or the CRTJVAPGM
command.
If the program has never run on AS/400, and no previous CRTJVAPGM
command has run, then the optimization level that is selected is used
before the program runs. This optimization level is stored in the class file,
JAR file, or ZIP file.
If the RUNJVA command or CRTJVAPGM command has been run against
the program, then the OPTIMIZE parameter on the RUNJVA command has
no effect. One exception is the OPTIMIZE(*INTERPRET) parameter. This
parameter forces all of the loaded Java classes to run interpretively
regardless of the OPTIMIZE value of the associated Java program.
If you want to change the level of optimization of a program that has been
previously optimized, use the CRTJVAPGM command or CHGJVAPGM
command. Using the RUNJVA command does not create the desired
optimization level. Instead, it uses the saved value that is associated with
the class file, JAR file, or ZIP file.
Note:The *INTERPRET parameter behaves this way to debug code that has
been previously optimized. It does not require that you delete your
program, create the program again for low optimization, debug it, and
then optimize it again.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 81
 If the OPTIMIZE(*INTERPRET) parameter is used, the resulting Java
program is verified and converted to an internal form. Then, it is
interpreted when it runs. For the other optimization levels, the internal
form includes AS/400 machine instructions. These AS/400 machine
instructions are optimized based on the specified optimization level. The
AS/400 directly runs the machine instructions when the program runs.
OPTIMIZE(*INTERPRET) Java programs are smaller, but run slower than
Java programs that are created using higher optimization levels. As the
optimization level increases beyond 10, Java program performance
gradually improves, but the time that is required to create the Java
program increases. It is also more difficult to debug the Java program.
Typically, *INTERPRET is a good option during development and early
testing, because quick edit, compile turnaround, and quality debug
functions are important. As the program moves toward release, the level of
optimization often increases.
This list shows how the optimization levels differ and what they do:
10 The Java program contains a transformed version of the class file
bytecodes, but has only minimal additional compiler optimization.
While debugging, you can display and change variables.
*INTERPRET
The Java program that is created does not contain machine specific
instructions. When the program starts, it is interpreted. You can
display and change variables while debugging.
*JIT No Java program that contains machine instruction sequences is
created. The class runs by using the Just-In-Time (JIT) compiler.

20 The Java program contains a compiled version of the class file

bytecodes and has additional compiler optimization. You can
display and change variables while debugging.
30 The Java program contains a compiled version of the class file
bytecodes and has more compiler optimization than optimization
level 20. Debugging at higher optimization levels is more difficult,
because optimization reduces the ability to stop at precise points in
the code and display program variables.
40 The Java program contains a compiled version of the class file
bytecodes and has more compiler optimization than optimization
level 30. In addition, it includes optimization that disables call and
instruction tracing.
Note: If your Java program fails to optimize or throws an
exception at optimization level 40, use optimization level 30.

INTERPRET
The INTERPRET parameter specifies whether all Java class files should run
interpretively.
OPTIMIZE
Java class files run interpretively depending on the value that is
specified for the OPTIMIZE parameter. If OPTIMIZE(*INTERPRET)
is specified, all Java class files run interpretively. If another value is

82 AS/400 Developer Kit for Java

 specified for the OPTIMIZE parameter, Java class files with Java
programs, which were created by using the CRTJVAPGM
command and by specifying OPTIMIZE(*INTERPRET), run
interpretively.
*NO Only Java class files with Java programs, which were created by
using the CRTJVAPGM command and by specifying
OPTIMIZE(*INTERPRET), run interpretively. Java class files that
need to create a Java program are created with the optimization
level that is specified by using the OPTIMIZE parameter.
*YES All Java class files run interpretively regardless of which
OPTIMIZE value the associated Java program created. Java class
files that need to create a Java program are created with the
optimization level that is specified by using the OPTIMIZE
parameter.
*JIT All Java class files run by using the Just-In-Time (JIT) compiler,
regardless of what OPTIMIZE value was used when the associated
Java program was created.

PROP
The PROP parameter specifies a list of values to assign to Java system
properties. You can assign up to 100 properties.

The limit for the PROP parameter is 5000 characters each for name and
value.
*NONE
No properties are specified.

For property-name, specify the name of the property to change.

For property-value, specify the value that is assigned to the property.

GCHMAX
The GCHMAX parameter specifies the maximum amount of memory in
kilobytes that the Java virtual machine can allocate. Normally, you should
use the default or set this value as large as possible. However, if you are
concerned about a program that uses all available memory, you can set
GCHMAX to a smaller value. The default value is system dependent and
model dependent.
If Java virtual machine memory allocation reaches GCHMAX, all other
Java virtual machine threads are stopped while garbage collection takes
place. If garbage collection cannot reduce the memory allocation, the Java
virtual machine stops.
*NOMAX
The garbage collection heap grows until all system resources are
gone. Then, a synchronous garbage collection starts to reclaim the
resources that are no longer in use. With *NOMAX, synchronous
garbage collection occurs only if all available heap storage has been
used.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 83
 GCHINL
The GCHINL parameter provides a suggested threshold for initial garbage
collection. If this value is equal to GCHMAX, then garbage collection does
not run until the amount of memory that is allocated by the Java virtual
machine approaches GCHMAX. Setting the value to a smaller value
triggers an earlier garbage collection. The default value is system
dependent and model dependent.
GCFRQ
Note: This parameter is no longer supported. It exists solely for
compatibility with releases earlier than Version 4 Release 3 Modification 0
of the AS/400 system.
The GCFRQ parameter provides a suggested garbage collection frequency.
It may or may not be honored depending on the system release and model.
Values between 0 and 100 are allowed for GCFRQ. The default parameter
is 50. A lower value means less frequent garbage collection. A higher value
means more frequent garbage collection.
GCPTY
Note: This parameter is no longer supported. It exists solely for
compatibility with releases earlier than Version 4 Release 3 Modification 0
of the AS/400 system.
The GCPTY parameter provides a suggested garbage collection priority. It
may or may not be honored depending on the system release and model.
The GCPTY parameter specifies the relative priority of the threads that run
garbage collection. The priority is relative to the default user Java threads.
Higher values indicate higher priority. A low priority garbage collection
thread is less likely to run, because other higher priority tasks are running.
In most cases, GCPTY should be set to the default (equal) value or the
higher priority value. Setting GCPTY to the lower priority value can inhibit
garbage collection and cause in all Java threads to be held while the
garbage collector frees storage.
20 The default parameter value is 20. This indicates that the garbage
collection thread has the same priority as default user Java threads.
30 The 30 priority gives garbage collection higher priority than default
user Java threads. Garbage collection is more likely to run.
10 The 10 priority gives garbage collection lower priority than default
user Java threads. Garbage collection is less likely to run.

OPTION
The OPTION parameter specifies special options that are used when a Java
class runs.
*NONE
No special options are used when a Java class runs.
*DEBUG
Allows the use of the AS/400 system debugger for the Java
program.

84 AS/400 Developer Kit for Java

 *VERBOSE
A message is displayed each time a class file is loaded.
*VERBOSEGC
A message is displayed for each garbage collection sweep.
*NOCLASSGC
Unused classes are not reclaimed when garbage collection runs.

See Example: Using the Run Java (RUNJVA) command for an example that uses
the RUNJVA command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Using the Run Java (RUNJVA) command

The Run Java (RUNJVA) command runs the AS/400 Java program that is
associated with the class.

Example 1: Run a Java program

RUNJVA CLASS (’/projectA/myJavaclassname’)

See the Run Java (RUNJVA) command for syntax diagram and parameter details.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Delete Java Program (DLTJVAPGM) command

Syntax:
DLTJVAPGM Command
(1)
>>-DLTJVAPGM—-CLSF(—'class-file-name'—)———————————>
>——-+—————————————+——————————————-><
| .-NONE—-. |
'-SUBTREE(—+-*ALL—-+—-)-'

Note:All parameters preceding this point can be specified positionally.

Purpose:

The Delete Java Program (DLTJVAPGM) command deletes an AS/400 Java

program that is associated with a Java class file, ZIP file, or JAR file. If no Java
program is associated with the file that is specified, informational message
JVAB526 is sent, and command processing continues.

Parameters:
CLSF
The CLSF parameter specifies the class file, ZIP file, or JAR file name from
which to delete the associated Java program on AS/400. One or more
directory names may qualify the class file name.
For class-file-name, specify the name of the class file or a pattern to
identify file or files to be used. A pattern may be specified in the last part

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 85
 of the name. An asterisk matches any number of characters, and a question
mark matches a single character. Enclose the name in apostrophes if it is
qualified or contains a pattern. An example of a qualified class name is:
'/directory1/directory2/myclassname.class'
SUBTREE
The SUBTREE parameter specifies whether or not subdirectories are
processed when looking for files that match the CLSF keyword.
*NONE
Only the files that match the object name pattern are processed. No
subtrees are processed. If the directory has subdirectories, neither
the subdirectories nor the objects on the subdirectories are
processed.
*ALL The entire subtree of the path that is specified in CLSF is processed
to create Java programs for files that match the name that was
specified on the CLSF parameter.

See Example: Delete Java Program (DLTJVAPGM) command for an example that
uses the DLTJVAPGM command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Delete Java Program (DLTJVAPGM) command

The Delete Java Program (DLTJVAPGM) command deletes the Java program that is
associated with the specified class file that is named myJavaClassFileName.

Note: The DLTJVAPGM command does not delete the class file or ZIP file.

Example 1: Delete a Java program

DLTJVAPGM CLSF(’/projectA/team2/myJavaClassFileName.class’)

See the Delete Java Program (DLTJVAPGM) command for syntax diagram and
parameter details.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Dump Java Virtual Machine (DMPJVM) command

Purpose:

The Dump Java Virtual Machine (DMPJVM) command dumps information about
the Java virtual machine for a specified job. The dump includes formatted
information about the classpath, garbage collection, and threads that are associated
with the Java virtual machine.

Syntax:

86 AS/400 Developer Kit for Java

DMPJVM Command
(1)
>>—DMPJVM——-.——————————————————————————.—->
| .-*SRVJOB———————————————-. |
'-JOB(—'-.————————————-.—job-name-'—)-'
'-.—————-.—user-name/-'
'-job-number/-'
>—.——————————————.—.——————————————.————><
| .-10——-. | | .-*SELECT-. |
'-STACKFRAME(—+-*ALL—-+—)-' '-DUPJOBOPT(—'-*MSG——'—)-'
'-number-'

Notes: All parameters preceding this point can be specified positionally.

Restrictions:
v The DMPJVM command uses the Start Service Job (STRSRVJOB) command and
Start Debug (STRDBG) command. The user of this command must be authorized
to the STRSRVJOB command and STRDBG command.
v The DMPJVM command ships with public *EXECUTE authority, and the
QPGMR, QSYSOPR, QSRV, and QSRVBAS user profiles have private authorities
to use the DMPJVM command.
v The DMPJVM command must run under a user profile, which is the same as the
job user identity of the Java virtual machine job, or which has use (*USE)
authority to the job user identity of the Java virtual machine job.
v The DMPJVM command is not allowed if the remote service operation for
another job has started, and that job is not the same job that was specified on
this command.
v The DMPJVM command is not allowed if the Java virtual machine job is held,
suspended, or ending.
Optional parameters:
JOB The JOB parameter specifies the name of the job where the Java virtual
machine is running. If no job number is given, all of the jobs that are
currently in the system are searched for the simple job name. The job name
entered must be a job in which a Java virtual machine is currently running.
*SRVJOB
Information about the Java virtual machine in the job that is
currently being serviced is dumped. If no job is currently being
serviced, a job identifier is required.
A job identifier is a qualified name with up to three elements. For
example:
v job-name
v user-name/job-name
v job-number/user-name/job-name
job-name
Specifies the name of the Java virtual machine job.
user-name
Specifies the name of user of the Java virtual machine job.
job-name
Specifies the number of the Java virtual machine job.

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 87
 STACKFRAME
The STACKFRAME parameter specifies the maximum number of stack
frames for each thread to process. This value must be greater than zero,
and cannot be greater than 100. If there are more than the specified
number of frames on a thread stack, the more recent frames on the stack
are processed and ’...’ indicates that not all of the stack frames were
processed.
10 Each thread processes a maximum of ten stack frames.
*ALL Each thread processes all stack frames. If a thread has more than
100 stack frames, only the first 100 frames are processed.
number
The maximum number (1-100) of stack frames that the thread
processes.

DUPJOBOPT
Specifies the action to be taken when the DMPJVM command finds
duplicate jobs.
*SELECT
When the DMPJVM command finds duplicate jobs during an
interactive session, the selection display is shown. Otherwise, an
escape message is issued.
*MSG When the DMPJVM command finds duplicate jobs, an escape
message is issued.

See Example: Dump Java Virtual Machine (DMPJVM) command for an example
that uses the DMPJVM command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Dump Java Virtual Machine (DMPJVM) command

The Dump Java Virtual Machine (DMPJVM) command dumps information
about the Java virtual machine for a specified job.

Example 1: Dump a Java Virtual Machine

DMPJVM JOB(099246/FRED/QJVACMDSRV)

The DMPJVM command dumps the information for the Java virtual machine that
is running in the job that is named 099246/FRED/QJVACMDSRV.

Example output:
JAVA VIRTUAL MACHINE INFORMATION: 099246/FRED/QJVACMDSRV
......................................................................
. Classpath
......................................................................
/QIBM/ProdData/Java400/jdk117/lib/jdkptf117.zip:/QIBM/ProdData/Java400/jdk1
17/lib/classes.zip:/QIBM/ProdData/Java400/ext/IBMmisc.jar:/QIBM/ProdData/Ja
va400/ext/db2_classes.jar:/QIBM/ProdData/Java400/ext/jssl.jar:/QIBM/ProdDat
a/Java400/ext/ibmjssl.jar:/QIBM/ProdData/Java400/:/home/fred
......................................................................
. Garbage collection

88 AS/400 Developer Kit for Java

 ......................................................................
Garbage collector parameters
Initial size: 2048 K
Max size: *NOMAX
Current values
Heap size: 9476 K
Garbage collections: 0
......................................................................
. Thread information
......................................................................
Information for 3 thread(s) of 3 thread(s) processed
Thread: 00000001 Thread-0
TDE: B000200002941000
Thread priority: 5
Thread status: Destroy wait
Thread group: main
Runnable: java/lang/Thread
Stack:
None
Locks:
None
......................................................................
Thread: 00000003 t2
TDE: B000100005B37000
Thread priority: 5
Thread status: Timed wait
Thread group: main
Runnable: dbgtest2
Stack:
java/io/BufferedInputStream.read()I+11 (BufferedInputStream.java:154)
pressEnter.theFirstMethod(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Str
ava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lj
tring;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/S
0 (dbgtest2.java:15)
dbgtest2.run()V+69 (dbgtest2.java:44)
java/lang/Thread.run()V+11 (Thread.java:466)
Locks:
None
......................................................................
Thread: 00000002 t1
TDE: B000100005B33000
Thread priority: 5
Thread status: Java wait
Thread group: main
Runnable: dbgtest2
Stack:
pressEnter.theFirstMethod(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/Str
ava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Lj
tring;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/S
(dbgtest2.java:14)
dbgtest2.run()V+69 (dbgtest2.java:44)
java/lang/Thread.run()V+11 (Thread.java:466)
Locks:
None
......................................................................

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Display Java Program (DSPJVAPGM) command

Syntax:

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 89
 DSPJVAPGM Command
(1)
>>-DSPJVAPGM—-CLSF(—'class-file-name'—)———————————>
>——-+—————————————+——————————————-><
| .-*———. |
'-OUTPUT(—+-*PRINT-+—-)—'

Note:

All parameters preceding this point can be specified positionally.

Purpose:

The Display Java Program (DSPJVAPGM) command displays information about a

Java program on AS/400. This information includes creation and processing
attributes, such as the optimization level and the size.

Parameters:
CLSF The CLSF parameter specifies the class file, ZIP file, or JAR file name from
which to display the associated Java program on AS/400. One or more
directory names may qualify the class file name.
For class-file-name, specify the name of the class file, ZIP file, or JAR file.
An example of a qualified class name is:
'/directory1/directory2/myclassname.class'
OUTPUT
The OUTPUT parameter specifies where the output is to be sent.
* Display shows the output that was requested by an interactive job.
Output that was requested by a batch job prints with the spooled
output of the job.
*PRINT
The output prints with the spooled output of the job.

Display example:

This display example shows you what Display Java Program (DSPJVAPGM)
output looks like for a ZIP file.
+————————————————————————————————————————+
Display Java Program Information
File name . . . . . . . . . . . . . . . : /user/classes.zip1
Owner . . . . . . . . . . . . . . . . . : USER2
Java program creation information:
File change date/time . . . . . . . . . . . . . : 07/18/98 09:03:373
Java program creation date/time . . . . . . . . : 07/18/98 14:03:384
Java programs . . . . . . . . . . . . . . . . . : 15
Classes with current Java programs . . . . . . : 16
Classes without current Java programs . . . . . : 07
Optimization . . . . . . . . . . . . . . . . . : *INTERPRET8
Enable performance collection . . . . . . . . . : *NONE9
Use adopted authority . . . . . . . . . . . . . : *NO10
User profile . . . . . . . . . . . . . . . . . : *USER11
Licensed Internal Code options . . . . . . . . : ErrorReporting=012
Java program statistics:
Java program size . . . . . . . . . . . . . . . : 270745613
Release program created for . . . . . . . . . . : V4R5M014

90 AS/400 Developer Kit for Java

 Bottom
Press Enter to continue.
+————————————————————————————————————————+
1. File name: The name of the file that has an attached Java program.
Note: You must have *USE authority for the class file for the Java program
that is to be displayed.
2. Owner: The name of the user profile of the user who owns this Java program.
3. File change date/time: The date and time when the class file was last
changed.
4. Java program creation date/time: If this is a ZIP file, this is the date and time
when the first Java program was attached to the file. If this is a class file, this
is the date and time when the Java program was created.
5. Java programs: Indicates the number of Java programs that are associated
with the file.
Note: For the best performance, the number of Java programs should be low
(1 or 2). The number of Java programs is large if your Java programs were
created implicitly. This occurs when a Java program runs and classes in the
JAR file were loaded before the Create Java Program (CRTJVAPGM) command
was run on the JAR file. If the number of Java programs is high, you may
want to use the CHGJVAPGM MERGE(*YES) function to consolidate the
programs and improve class loader performance. If the number of classes is
low, and the number of Java programs is high, this may be caused by multiple
changes of classes in the JAR file. Again, you can use either the CRTJVAPGM
command or CHGJVAPGM command to consolidate the programs.
6. Classes with current Java programs: Indicates the number of classes in the
file that have current Java programs.
7. Classes without current Java programs: Indicates the number of classes in the
file that do not have current Java programs.
Note: For the best performance, the number of classes without current Java
programs should be low. If the number of classes without current Java
programs is high, you may want to use the CRTJVAPGM command to update
the program.
8. Optimization: Specifies the optimization level of the AS/400 Java program.
For OPTIMIZE(*INTERPRET), the resulting Java program interprets the class
file bytecodes when started. For other optimization levels, the Java program
contains machine instruction sequences that run when the Java program starts.
Java programs that use OPTIMIZE(*INTERPRET) are smaller, but run slower
than Java programs that you create with higher optimization levels. As you
increase the optimization level beyond 10, the performance of the Java
program generally improves. However, the time that is required to create the
Java program increases and debugging becomes more difficult.
This list shows how the optimization levels differ and what they do:
10 The Java program contains a compiled version of the class file
bytecodes, but has only minimal additional compiler optimization.
You can display and change variables while debugging.
20 The Java program contains a compiled version of the class file
bytecodes and has additional compiler optimization. You can display,
but not change variables while debugging.
30 The Java program contains a compiled version of the class file
bytecodes and has more compiler optimization than optimization level
20. Debugging at higher optimization levels is more difficult, because
optimization reduces the ability to stop at precise points in the code

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 91
 and display program variables. You can display, but not change
variables while debugging. The values that are presented may not be
the current value of the variable.
40 The Java program contains a compiled version of the class file
bytecodes and has more compiler optimization than optimization level
30. In addition, it includes optimization that disables call and
instruction tracing.
Note: If your Java program fails to optimize or throws an exception at
optimization level 40, use optimization level 30.
*INTERPRET
The Java program is not optimized. When the program starts, it
interprets the class file bytecodes. You can display and change
variables while debugging.
9. Enable performance collection: This is the level of performance data
collection that is allowed for this Java program. These values can be returned:
*NONE
No performance collection is enabled for this Java program.
*ENTRYEXIT
This gives the entry and exit information on all of the procedures of
the Java program, including those that were leaf procedures. This also
includes the PEP routine. *ENTRYEXIT is useful in capturing
information on all procedures.
*FULL This gives the entry and exit information on all of the procedures of
the Java program, including those that were leaf procedures. Also,
precall and postcall hooks around other calls to other procedures.
*FULL is useful in capturing information on all procedures.
10. Use adopted authority: Indicates if the Java programs use adopted authority
from previous call levels in the stack.
11. User profile: Indicates if the authority checking that was done while this
program is running should include only the user who is running the program
(*USER), or both the user who is running the program and the program owner
(*OWNER).

12. Licensed Internal Code options: The selected licensed internal code (LIC)
compile-time options that are used when the Java program was created.
13. Java program size: The size, in bytes, of the Java programs that are attached
to the file.

14. Release program create for: The release of the operating system for which
the object was created.
See Example: Display Java Program (DSPJVAPGM) command for an example that
uses the DSPJVAPGM command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Display Java Program (DSPJVAPGM) command

The DSPJVAPGM (Display Java Program) command displays the Java program
that is associated with the specified class file named myJavaClassFileName.

Example 1: Display a Java Program

92 AS/400 Developer Kit for Java

 DSPJVAPGM
CLSF('/projectA/team2/myJavaClassFileName.class')
OUTPUT(*)

See the Display Java Program (DSPJVAPGM) command for syntax diagram and
parameter details.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Operations Navigator commands that are supported by Java

AS/400 Operations Navigator is a graphical interface for your Windows desktop. It
is part of Client Access for Windows and covers many AS/400 functions that
administrators or users need to accomplish their daily work.

Operations Navigator supports Java as a third-party plug-in. To install the

third-party plug-in, you need to install the AS/400 Developer Kit for Java on your
AS/400. Then, install the AS/400 Developer Kit for Java on your personal
computer through Selective Setup in the Client Access folder.

Class files reside in the integrated file system. Operations Navigator allows you to
see these class files in the right pane. Right-click the class file that you want to use.
This brings up a context menu.

Selecting the New Java program from the context menu starts the Java transformer,
which creates an AS/400 Java program that is associated with your class file. A
dialog box allows you to specify details on how to create the program. You can
create the program for either Java transformation or Java interpretation.

Note:If you select transformation, the bytecodes in your class file transform into
RISC instructions that result in better performance than if you used interpretation.

Selecting Change Java program from the context menu changes attributes of Java
programs that are attached to Java class files, ZIP files, or JAR files.

Selecting Run Java program from the context menu runs your class file on AS/400.
A dialog appears to allow you to specify details on how to run the program. If you
have already selected New Java program, the AS/400 Java program that is
associated with your class file is used when running the program. If an AS/400
Java program is not already associated with your class file, then the AS/400 Java
program is created before the program runs.

Selecting Delete Java program from the context menu deletes the AS/400 Java
program that is associated with your class file.

See the online help information for the parameters and options of the New Java
program, Change Java program, Run Java program, and Delete Java program
Operations Navigator commands.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 4. Commands and tools for the AS/400 Developer Kit for Java 93
94 AS/400 Developer Kit for Java
Chapter 5. Using Java with other programming languages
With Java, you have multiple ways to call code that was written in languages other
than Java.

Java Native Interface:

One of the ways you can call code written in another language is to implement
selected Java methods as ’native methods.’ Native methods are procedures, written
in another language, that provide the actual implementation of a Java method.
Native methods can access the Java virtual machine using the Java Native Interface
(JNI). These native methods run under the Java thread, which is a kernel thread, so
they must be thread safe. A function is thread safe if you can start it
simultaneously in multiple threads within the same process. A function is thread
safe if and only if all the functions it calls are thread safe also.

Native methods are a “bridge” to access system functions that are not directly
supported in Java, or to interface to existing user code. Use caution when using
native methods, because the code that is being called may not be thread safe. See
using the Java Native Interface for native methods for more information about JNI
and native methods.

java.lang.Runtime.exec():

You can use java.lang.Runtime.exec() to call programs or commands from within a

Java program. The exec() method starts another process in which any AS/400
program or command can run. In this model, you can use standard in, standard
out, and standard err of the child process for interprocess communication.

Interprocess communication:

One option is to use sockets for interprocess communication between the parent
and child processes.

You can also use stream files for communication between programs. Or see
interprocess communication examples for an overview of your options when
communicating with programs that are running in another process.

To call Java from other languages, see calling Java from other languages.

You can also use the AS/400 Toolbox for Java to call existing programs and
commands on AS/400. Data queues and AS/400 messages are usually used for
interprocess communication with the AS/400 Toolbox for Java.

Note: By using Runtime.exec(), AS/400 Toolbox for Java, or JNI you may
compromise the portability of the Java program. You should avoid using these
methods in a “pure” Java environment.

Java Invocation API:

Using the Java Invocation API, which is also a part of the Java Native Interface
(JNI) specification, allows a non-Java application to use the Java virtual machine. It
also allows the use of Java code as an extension of the application.

© Copyright IBM Corp. 1998, 1999 95

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Using the Java Native Interface for native methods

You should only use native methods in cases where pure Java cannot meet your
programming needs. Limit the use of native methods by only using them under
these circumstances:
v To access system functions that are not available using pure Java.
v To implement extremely performance-sensitive methods that can benefit
significantly from a native implementation.
v To interface to existing application program interfaces (API) that allow Java to
call other APIs.
To use the Java Native Interface (JNI) for native methods, do these steps:
1. Design the class by specifying which methods will be native methods with the
standard Java language syntax.
2. Decide on a library and program name for the service program (*SRVPGM)
that contains native method implementations. When coding the
System.loadLibrary() method call in the static initializer for the class, specify
the name of the service program.
3. Use the javac tool to compile the Java source into a class file.
4. Use the javah tool to create the header file (.h). This header file contains the
exact prototypes for creating the native method implementations. The -d
option specifies the directory where you should create the header file.
5. Copy the header file from the integrated file system into a member in a source
file by using the Copy From Stream File (CPYFRMSTMF) command. You must
copy the header file into a source file member for the C compiler to use it.
Use the new stream file support for the Create Bound ILE C/400 Program
(CRTCMOD) command to leave your C source and C header files in the
integrated file system. For more information on the CRTCMOD command and
the use of stream files, see the ILE C Programmer’s Guide, SC09-2712 book.

6. Write the native method code. See Java native methods and threads
considerations for details about the languages and functions that are used for
native methods.
a. Include the header file that was created in the previous steps.
b. Match the prototypes in the header file exactly.
c. Convert strings to American National Standard Code for Information
Interchange (ASCII) if the strings are to pass to the Java virtual machine.
For more information, see Java character encodings.
7. If your native method must interact with the Java virtual machine, use the
functions that are provided with JNI.
8. Compile your C source code, using the CRTCMOD, into a module (*MOD)
object.
9. Bind one or more module objects into a service program (*SRVPGM) by using
the Create Service Program (CRTSRVPGM) command. The name of this service
program must match the name that you supplied in your Java code that is in
the System.load() or System.loadLibrary() function calls.

96 AS/400 Developer Kit for Java

10. If you used the ’System.loadLibrary()’ call in your Java code, do one of the
following.

If you are using a version that is older than J2SDK:

Add the AS/400 library that contains your new service program to the
AS/400 library list. To add the library, use the Add Library List Entry
(ADDLIBLE) command. This allows the Java program to find the service
program when it processes the System.loadLibrary() function.
If you are using J2SDK:
You do not need to modify your library list. Instead, you can either:
v Include the list of the libraries that you need in the LIBPATH environment
variable. You can modify the LIBPATH environment variable in QShell and
from the AS/400 command line.
– From the Qshell command prompt, type in:
export LIBPATH=/QSYS.LIB/MYLIB.LIB
java -Djava.version=1.2 myclass
– Or, from the command line:
ADDENVVAR LIBPATH ’/QSYS.LIB/MYLIB.LIB’
JAVA PROP((java.version 1.2)) myclass
v Or, supply the list in the java.library.path property. You can modify the
java.library.path property in QShell and from the AS/400 command line.
– From the Qshell command prompt, type in:
java -Deja.library.path=/QSYS.LIB/MYLIB.LIB -Djava.version=1.2
myclass
– Or, from the AS/400 command line, type in:
JAVA PROP((java.library.path ’/QSYS.LIB/MYLIB.LIB’) (java.version
’1.2’)) myclass

Where /QSYS.LIB/MYLIB.LIB is the library that you wish to load using the
’System.loadLibrary()’ call, and myclass is the name of your Java application.

11.
The patches syntax for System.load(String patches) can be any of these:
v “path” (integrated file system filename that specifies the library that the
service program provides), which is a symbolic link to a *SRVPGM, such as
“/qsys.lib/mylib.lib/myNMsp.srvpgm”
v /qsys.lib/sysNMsp.srvpgm
v /qsys.lib/mylib.lib/myNMsp.srvpgm

v If you have a version older than J2SDK:

/qsys.lib/%libl%.lib/myNMsp.srvpgm
Note: This is equivalent to using the System.loadLibrary(“myNMsp”)
method.

Note: If the “pathname” is used as a string literal, then you must enclose it in
quotation marks. For example,
System.load(“/qsys.lib/mylib.lib/myNMsp.srvpgm”).
12.
The “libya” syntax for System.loadLibrary(String libya) is mysp. The system
finds mysp by using *LIBL. For example, loadLibrary(“myNMsp”) is

Chapter 5. Using Java with other programming languages 97

 equivalent to System.load(“/qsys.lib/%libl%.lib/myNMsp.srvpgm”). If the
“pathname” is used as a string literal, then you must enclose the libname in
quotation marks.

Note: The %libl% syntax is not supported for J2SDK.

For a complete description of the JNI, refer to the Java Native Interface by Sun

Microsystems, Inc., and The Source for Java Technology java.sun.com.

See Examples: Using the Java Native Interface for native methods for an example
of how to use the JNI for native methods.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java native methods and threads considerations

You can use native methods to access functions that are not available in Java.

To better use Java with native methods you need to understand these concepts:
v A Java thread, whether created by Java or an attached native thread, has all
floating point exceptions disabled. If the thread runs a native method that
reenables floating point exceptions, Java does not turn them off a second time. If
the user application does not disable them before returning to run Java code,
then the Java code may not behave correctly if a floating point exception occurs.
When a native thread detaches from the Java virtual machine, its floating point
exception mask is restored to the value that was in effect when it was attached.
v When a native thread attaches to the Java virtual machine, the Java virtual
machine changes the threads priority, if necessary, to conform to the one to ten
priority schemes that Java defines. When the thread detaches, the priority is
restored. After attaching, the thread can change the thread priority by using a
native method interface (for example, a POSIX API). Java does not change the
thread priority on transitions back to the Java virtual machine.
v The Invocation API component of the Java Native Interface (JNI) permits a user
to embed a Java virtual machine within their application. If an application
creates a Java virtual machine and the Java virtual machine ends abnormally, the
MCH74A5 “Java Virtual Machine Terminated” AS/400 exception is signalled to
the initial thread of the process if that thread was attached to the Java virtual
machine when the Java virtual machine ended. The Java virtual machine could
end abnormally for any of these reasons:
– The user calls the java.lang.System.exit() method.
– A thread that the Java virtual machine requires ends.
– An internal error occurs in the Java virtual machine.
This behavior differs from most other Java platforms. On most other platforms,
the process that automatically creates the Java virtual machine ends abruptly as
soon as the Java virtual machine ends. If the application monitors and handles a
signalled MCH74A5 exception, it may continue to run. Otherwise, the process
ends when the exception goes unhandled. By adding the code that deals with
the AS/400-specific MCH74A5 exception you can make the application less
portable to other platforms.
Because native methods always run in a multithreaded process, the code that they
contain must be thread safe. This places these restrictions on the languages and
functions that are used for native methods:

98 AS/400 Developer Kit for Java

 v You should not use ILE CL for native methods, because this language is not
thread safe. To run thread safe CL commands, you can use the C language
system() function or the java.lang.Runtime.exec() method.
– Use the C language system() function to run thread safe CL commands from
within a C or C++ native method.
– Use the java.lang.Runtime.exec() method to run thread safe CL commands
directly from Java.
v You can use ILE C, ILE C++, ILE COBOL, and ILE RPG to write a native
method, but all of the functions that are called from within the native method
must be thread safe.
Note: Compile-time support for writing native methods is currently only
supplied for the C and C++ languages. While possible, writing native methods
in other languages may be much more complicated.
Caution:
Not all standard C, C++, COBOL, or RPG functions are thread safe.
v The C and C++ exit() and abort() functions should never be used within a native
method. These functions cause the entire process that runs the Java virtual
machine to stop. This includes all of the threads in the process, regardless of if
they were originated by Java or not.
Note: The exit() function referred to is the C and C++ function, and is not the
same as the java.lang.Runtime.exit() method.
For more information about threads on AS/400, see Developing multithreaded
applications.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Strings in native methods

Many Java Native Interface (JNI) functions accept C language-style strings as
parameters. For example, the FindClass() JNI function accepts a string parameter
that specifies the fully-qualified name of a classfile. If the classfile is found, it is
loaded by FindClass, and a reference to it is returned to the caller of FindClass.

All JNI functions expect their string parameters to be encoded in UTF-8. For details
on UTF-8, you can refer to the JNI Specification, but in most cases it is enough to
observe that 7-bit American National Standard Code for Information Interchange
(ASCII) characters are equivalent to their UTF-8 representation. 7-bit ASCII
characters are actually 8-bit characters but their first bit is always 0. So, most ASCII
C strings are actually already in UTF-8.

The C compiler on the AS/400 system operates in extended binary-coded decimal

interchange code (EBCDIC) by default, so you can provide strings to the JNI
functions in UTF-8. There are two ways to do this. You can use literal strings, or
you can use dynamic strings. Literal strings are strings whose value is known
when the source code is compiled. Dynamic strings are strings whose value is not
known at compile time, but rather is actually computed at run time.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Literal strings in native methods

It is easier to encode literal strings in UTF-8 if the string is composed of characters
with a 7-bit American National Standard Code for Information Interchange (ASCII)

Chapter 5. Using Java with other programming languages 99

 representation. If the string is representable in ASCII, as most are, then the string
can be bracketed by ’pragma’ statements that modify the current codepage of the
compiler. Then, the compiler stores the string internally in the UTF-8 form that is
required by the JNI. If the string is not representable in ASCII, it is easier to treat
the original extended binary-coded decimal interchange code (EBCDIC) string as a
dynamic string, and process it using iconv() before passing it to the JNI. For more
information on dynamic strings, see Dynamic strings.

For example, to find the class named “java/lang/String” the code looks like this:
#pragma convert(819)
myClass = (*env)->FindClass(env,“java/lang/String”);
#pragma convert(0)

The first pragma, with the number 819, informs the compiler to store all
subsequent double-quoted strings (literal strings) in ASCII. The second pragma,
with the number 0, tells the compiler to revert to the default code page of the
compiler for double-quoted strings, which is usually the EBCDIC code page 37. So,
by bracketing this call with these pragmas, we satisfy the JNI requirement that
string parameters are encoded in UTF-8.

Caution: Be careful with text substitutions. For example, if your code looks like
this:
#pragma convert(819)
#define MyString “java/lang/String”
#pragma convert(0)
myClass = (*env)->FindClass(env,MyString);

Then, the resulting string is EBCDIC, because the value of MyString is substituted
into the FindClass call during compilation. At the time of this substitution, the
pragma, number 819, is not in effect. Thus, literal strings are not stored in ASCII.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Converting dynamic strings to and from EBCDIC, Unicode, and

UTF-8
To manipulate string variables that are computed at run time, it may be necessary
to convert strings to and from extended binary-coded decimal interchange
(EBCDIC), Unicode, and UTF-8.

The system API that provides for code page conversion function is iconv(). To use
iconv(), follow these steps:
1. Create a conversion descriptor with QtqIconvOpen().
2. Call iconv() to use the descriptor to convert to a string.
3. Close the descriptor by using iconv_close.
In Example 3 of the using the Java Native Interface for native methods examples,
the routine creates, uses, and then destroys the iconv conversion descriptor within
the routine. This scheme avoids the problems with multithreaded use of an iconv_t
descriptor, but for performance sensitive code it is better to create a conversion
descriptor in static storage, and moderate multiple access to it using a mutual
exclusion (mutex) or other synchronization facility.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

100 AS/400 Developer Kit for Java

Examples: Using the Java Native Interface for native methods
This example program is a simple Java Native Interface (JNI) example in which a
C native method is used to display “Hello, World.” Use thejavah tool with the
NativeHello class file to generate the NativeHello.h file. This example assumes that
the NativeHello C implementation is part of a service program that is called
NATHELLO.
Note: The library where the NATHELLO service program is located must be in the
library list for this example to run.

Example 1:NativeHello class

public class NativeHello {
// Declare a field of type 'String' in the NativeHello object.
// This is an 'instance' field, so every NativeHello object
// contains one.
public String theString; // instance variable
// Declare the native method itself. This native method
// creates a new string object, and places a reference to it
// into 'theString'
public native void setTheString(); // native method to set string
// This 'static initializer' code is called before the class is
// first used.
static {
// Attempt to load the native method library. If you do not
// find it, write a message to 'out', and try a hardcoded path.
// If that fails, then exit.
try {
// System.loadLibrary uses the AS/400 library list in JDK1.1,
// and uses the java.library.path property or the LIBPATH environment
// variable in JDK1.2
System.loadLibrary(“NATHELLO”);
}
catch (UnsatisfiedLinkError e1) {
// Did not find the service program.
System.out.println
(“I did not find NATHELLO *SRVPGM.”);
System.out.println (“(I will try a hardcoded path)”);
try {
// System.load takes the full integrated file system form path.
System.load (“/qsys.lib/jniexample.lib/nathello.srvpgm”);
}
catch (UnsatisfiedLinkError e2) {
// If you get to this point, then you are done! Write the message
// and exit.
System.out.println
(“<sigh> I did not find NATHELLO *SRVPGM anywhere. Goodbye”);
System.exit(1);
}
}
}
// Here is the 'main' code of this class. This is what runs when you
// enter 'java NativeHello' on the command line.
public static void main(String argv[]){
// Allocate a new NativeHello object now.
NativeHello nh = new NativeHello();
// Echo location.
System.out.println(“(Java) Instantiated NativeHello object”);
System.out.println(“(Java) string field is '” + nh.theString + “'”);
System.out.println(“(Java) Calling native method to set the string”);
// Here is the call to the native method.
nh.setTheString();
// Now, print the value after the call to double check.
System.out.println(“(Java) Returned from the native method”);

Chapter 5. Using Java with other programming languages 101

 System.out.println(“(Java) string field is '” + nh.theString + “'”);
System.out.println(“(Java) All done...”);
}
}

Example 2:Generated NativeHello.h header file

/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class NativeHello */
#ifndef _Included_NativeHello
#define _Included_NativeHello
#ifdef __cplusplus
extern “C” {
#endif
/*
* Class: NativeHello
* Method: setTheString
* Signature: ()V
*/
JNIEXPORT void JNICALL Java_NativeHello_setTheString
(JNIEnv *, jobject);
#ifdef __cplusplus
}
#endif
#endif

This NativeHello.c example shows the implementation of the native method in C.

This example simply shows how to link Java to native methods. However, it points
out complications that arise from the fact that AS/400 is internally an extended
binary-coded decimal interchange code (EBCDIC) machine. It also shows
complications from the current lack of true internationalization elements in the JNI.

These reasons, although they are not new with the JNI, cause some unique,
AS/400-specific differences in the C code that you write. You must remember that
if you are writing to stdout or stderr or reading from stdin, your data is probably
encoded in EBCDIC form.

In C code, you can easily convert most literal strings, those that contain 7-bit
characters only, into the UTF-8 form that is required by the JNI. To do this, bracket
the literal strings with code-page conversion pragmas. However, because you may
write information directly to stdout or stderr from your C code, you might allow
some literals to remain in EBCDIC.

Note: The #pragma convert(0) statements convert character data to EBCDIC. The
#pragma convert(819) statements convert character data to American National
Standard Code for Information Interchange (ASCII). These statements convert
character data in the C program at compile time.

Example 3:NativeHello.c native method implementation of the NativeHello Java

class
#include <stdlib.h> /* malloc, free, and so forth */
#include <stdio.h> /* fprintf(), and so forth */
#include <qtqiconv.H> /* iconv() interface */
#include <string.h> /* memset(), and so forth */
#include “NativeHello.h” /* generated by 'javah-jni' */
/* All literal strings are ISO-8859-1 Latin 1 code page (and with 7-bit
characters, they are also automatically UTF-8). */
#pragma convert(819) /* handle all literal strings as ASCII */
/* Report and clear a JNI exception. */
static void HandleError(JNIEnv*);
/* Print an UTF-8 string to stderr in the coded character */

102 AS/400 Developer Kit for Java

set identifier (CCSID) of the current job. */
static void JobPrint(JNIEnv*, char*);
/* Constants describing which direction to covert: */
#define CONV_UTF2JOB 1
#define CONV_JOB2UTF 2
/* Convert a string from the CCSID of the job to UTF-8, or vice-versa. */
int StringConvert(int direction, char *sourceStr, char *targetStr);
/* Native method implementation of 'setTheString()'. */
JNIEXPORT void JNICALL Java_NativeHello_setTheString
(JNIEnv *env, jobject javaThis)
{
jclass thisClass; /* class for 'this' object */
jstring stringObject; /* new string, to be put in field in 'this' */
jfieldID fid; /* field ID required to update field in 'this' */
jthrowable exception; /* exception, retrieved using ExceptionOccurred */
/* Write status to console. */
JobPrint(env, “( C ) In the native method\n”);
/* Build the new string object. */
if (! (stringObject = (*env)->NewStringUTF(env, “Hello, native world!”)))
{
/* For nearly every function in the JNI, a null return value indicates
that there was an error, and that an exception had been placed where it
could be retrieved by 'ExceptionOccurred()'. In this case, the error
would typically be fatal, but for purposes of this example, go ahead
and catch the error, and continue. */
HandleError(env);
return;
}
/* get the class of the 'this' object, required to get the fieldID */
if (! (thisClass = (*env)->GetObjectClass(env,javaThis)))
{
/* A null class returned from GetObjectClass indicates that there
was a problem. Instead of handling this problem, simply return and
know that the return to Java automatically 'throws' the stored Java
exception. */
return;
}
/* Get the fieldID to update. */
if (! (fid = (*env)->GetFieldID(env,
thisClass,
“theString”,
“Ljava/lang/String;”)))
{
/* A null fieldID returned from GetFieldID indicates that there
was a problem. Report the problem from here and clear it.
Leave the string unchanged. */
HandleError(env);
return;
}
JobPrint(env, “( C ) Setting the field\n”);
/* Make the actual update.
Note: SetObjectField is an example of an interface that does
not return a return value that can be tested. In this case, it
is necessary to call ExceptionOccurred() to see if there
was a problem with storing the value */
(*env)->SetObjectField(env, javaThis, fid, stringObject);
/* Check to see if the update was successful. If not, report the error. */
if ((*env)->ExceptionOccurred(env)) {
/* A non-null exception object came back from ExceptionOccurred,
so there is a problem and you must report the error. */
HandleError(env);
}
JobPrint(env, “( C ) Returning from the native method\n”);
return;
}
static void HandleError(JNIEnv *env)
{

Chapter 5. Using Java with other programming languages 103

 /* A simple routine to report and handle an exception. */
JobPrint(env, “( C ) Error occurred on JNI call: ”);
(*env)->ExceptionDescribe(env); /* write exception data to the console */
(*env)->ExceptionClear(env); /* clear the exception that was pending */
}
static void JobPrint(JNIEnv *env, char *str)
{
char *jobStr;
char buf[512];
size_t len;
len = strlen(str);
/* Only print non-empty string. */
if (len) {
jobStr = (len >= 512) ? malloc(len+1) : &buf;
if (! StringConvert(CONV_UTF2JOB, str, jobStr))
(*env)->FatalError
(env,“ERROR in JobPrint: Unable to convert UTF2JOB”);
fprintf(stderr, jobStr);
if (len >= 512) free(jobStr);
}
}
int StringConvert(int direction, char *sourceStr, char *targetStr)
{
QtqCode_T source, target; /* parameters to instantiate iconv */
size_t sStrLen, tStrLen; /* local copies of string lengths */
iconv_t ourConverter; /* the actual conversion descriptor */
int iconvRC; /* return code from the conversion */
size_t originalLen; /* original length of the sourceStr */
/* Make local copies of the input and output sizes that are initialized
to the size of the input string. The iconv() requires the
length parameters to be passed by address (that is as int*). */
originalLen = sStrLen = tStrLen = strlen(sourceStr);
/* Initialize the parameters to the QtqIconvOpen() to zero. */
memset(&source,0x00,sizeof(source));
memset(&target,0x00,sizeof(target));
/* Depending on direction parameter, set either SOURCE
or TARGET CCSID to ISO 8859-1 Latin. */
if (CONV_UTF2JOB == direction ) {
source.CCSID = 819;
}
else {
target.CCSID = 819;
}
/* Create the iconv_t converter object. */
ourConverter = QtqIconvOpen(&target,&source);
/* Make sure that you have a valid converter, otherwise return 0. */
if (-1 == ourConverter.return_value) return 0;
/* Perform the conversion. */
iconvRC = iconv(ourConverter,
(char**) &sourceStr,
&sStrLen,
&targetStr,
&tStrLen);
/* If the conversion failed, return a zero. */
if (0 != iconvRC ) return 0;
/* Close the conversion descriptor. */
iconv_close(ourConverter);
/* The targetStr returns pointing to the character just
past the last converted character, so set the null
terminator there now. */
*targetStr = '\0';
/* Return the number of characters that were processed. */
return originalLen-tStrLen;
}
#pragma convert(0)

104 AS/400 Developer Kit for Java

 See Using the Java Native Interface for native methods for background
information.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Using java.lang.Runtime.exec()
The java.lang.Runtime.exec() method calls programs or commands from within a
Java program. The actual processing that occurs depends on exactly what
information is passed to the exec() method. In all cases, the Runtime.exec() method
creates another thread-enabled batch immediate (BCI) job. The BCI job processes
the command string that is passed in on the Runtime.exec() method.

To use the java.lang.Runtime.exec() method, you must install the Qshell Interpreter
on your AS/400. For more information about the Qshell Interpreter, see Qshell
Interpreter.

Note: The java.lang.Runtime.exec() method runs programs in a separate process.

This differs from the C system function, which runs a program in the same
process.

If the command being processed is a Qshell utility, it runs in the second BCI job,
and the third BCI job is not created. If the command being processed is a CL
command, the second BCI job is started to run the Qshell, and the third BCI job is
started to run the CL command. A Qshell utility is a built-in utility that QSH can
run directly. An example of a Qshell utility is the javac command, which compiles
Java programs. The processing in the second (or third) BCI job runs concurrently
with the Java virtual machine. Any exit or shutdown processing in those jobs does
not affect the original Java virtual machine.

When calling an AS/400 command or program, you must ensure that any
parameters being passed to the called program are in the code page that is
expected by that program.

See calling another Java program, calling a CL program, or calling a CL command

for java.lang.Runtime.exec() examples.

Chapter 5. Using Java with other programming languages 105

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Example: Calling another Java program with

java.lang.Runtime.exec()
This example shows how to call another Java program with
java.lang.Runtime.exec(). This class calls the Hello program that is shipped as part
of the AS/400 Developer Kit for Java. When the Hello class writes to System.out,
this program gets a handle to the stream and can read from it.

Note: You use the Qshell Interpreter to call the program.

Example 1: CallHelloPgm class

import java.io.*;
public class CallHelloPgm
{
public static void main(String args[])
{
Process theProcess = null;
BufferedReader inStream = null;
System.out.println(“CallHelloPgm.main() invoked”);
// call the Hello class
try
{
theProcess = Runtime.getRuntime().exec(“java com.ibm.as400.system.Hello”);
}
catch(IOException e)
{
System.err.println(“Error on exec() method”);
e.printStackTrace();
}
// read from the called program's standard output stream
try
{
inStream = new BufferedReader(
new InputStreamReader( theProcess.getInputStream() ));
System.out.println(inStream.readLine());
}
catch(IOException e)
{
System.err.println(“Error on inStream.readLine()”);
e.printStackTrace();
}
} // end method
} // end class

For background information, see Using java.lang.Runtime.exec().

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

106 AS/400 Developer Kit for Java

Example: Calling a CL program with java.lang.Runtime.exec()
This example shows how to run CL programs from within a Java program. See
calling a CL command for an example of how to call a CL command from within a
Java program. In this example, the Java class CallCLPgm runs a CL program. The
CL program uses the Display Java Program (DSPJVAPGM) command to display
the program that is associated with the Hello class file. This example assumes that
the CL program has been compiled and exists in a library that is called
JAVSAMPLIB. The output from the CL program is in the QSYSPRT spooled file.

Note: The JAVSAMPLIB is not created as part of the AS/400 Developer Kit
licensed program (LP) number 5769-JV1 installation process. You must explicitly
create the library.

Example 1: CallCLPgm class

import java.io.*;
public class CallCLPgm
{
public static void main(String[] args)
{
try
{
Process theProcess =
Runtime.getRuntime().exec(“/QSYS.LIB/JAVSAMPLIB.LIB/DSPJVA.PGM”);
}
catch(IOException e)
{
System.err.println(“Error on exec() method”);
e.printStackTrace();
}
} // end main() method
} // end class

Example 2: Display Java CL program

PGM
DSPJVAPGM CLSF('/QIBM/ProdData/Java400/com/ibm/as400/system/Hello.class') +
OUTPUT(*PRINT)
ENDPGM

For background information, see Using java.lang.Runtime.exec().

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Calling a CL command with java.lang.Runtime.exec()

This example shows how to run a CL command from within a Java program. In
this calling a CL command example, the Java class runs a CL command. The CL
command uses the Display Java Program (DSPJVAPGM) command to display the
program that is associated with the Hello class file. The output from the CL
command is in the QSYSPRT spooled file.

Note: Every command that is passed in to the Runtime.getRuntime().exec()

function needs to be in quotes and in Qshell format. In addition, in order to run a
CL command from Qshell, it is necessary to pass in the string:
“system \”CL COMMAND\“”
Where CL COMMAND is the CL command you wish to run. So the line to call the
command MYCLCOM should like this: Runtime.getRuntime().exec(“system
\”MYCLCOM\“”);

Chapter 5. Using Java with other programming languages 107

 Example 1: CallCLCom class
import java.io.*;
public class CallCLCom
{
public static void main(String[] args)
{
try
{
Process theProcess =
Runtime.getRuntime().exec(“system \”DSPJVAPGM CLSF('/com/ibm/as400/system/Hello.clas
}
catch(IOException e)
{
System.err.println(“Error on exec() method”);
e.printStackTrace();
}
} // end main() method
} // end class

For background information, see Using java.lang.Runtime.exec().

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Interprocess communication examples

When communicating with programs that are running in another process, there are
a number of options.

One option is to use sockets for interprocess communication. One program can act
as the server program, that listens on a socket connection for input from the client
program. The client program connects to the server with a socket. Once the socket
connection is established, either program can send or receive information.

Another option is to use stream files for communication between programs. To do

this, use the System.in, System.out, and System.err classes.

A third option is to use the AS/400 Toolbox for Java which provides data queues
and AS/400 message objects.

You can also calling Java from other languages.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Using sockets for interprocess communication

Sockets streams communicate between programs that are running in separate
processes. The programs can either start separately or start by using the
java.lang.Runtime.exec() method from within the main Java program. If a program
is written in a language other than Java, you must ensure that any American
National Standard Code for Information Interchange (ASCII) or extended
binary-coded decimal interchange code (EBCDIC) conversion takes place. See Java
character encodings for more details.

For an example that uses sockets, see Example: Using sockets for interprocess
communication.

108 AS/400 Developer Kit for Java

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Example: Using sockets for interprocess communication

This example uses sockets to communicate between a Java program and a C
program. You should start the C program first, which listens on a socket. Once the
Java program connects to the socket, the C program sends it a string by using that
socket connection. The string that is sent from the C program is an American
National Standard Code for Information Interchange (ASCII) string in codepage
819.

The Java program should be started using this command, java TalkToC xxxxx
nnnn on the Qshell Interpreter command line or on another Java platform. Or, enter
JAVA TALKTOC PARM(xxxxx nnnn) on the AS/400 command line to start the Java
program. xxxxx is the domain name or Internet Protocol (IP) address of the system
on which the C program is running. nnnn is the port number of the socket that the
C program is using. You should also use this port number as the first parameter on
the call to the C program.

Example 1: TalkToC client class

import java.net.*;
import java.io.*;
class TalkToC
{
private String host = null;
private int port = -999;
private Socket socket = null;
private BufferedReader inStream = null;
public static void main(String[] args)
{
TalkToC caller = new TalkToC();
caller.host = args[0];
caller.port = new Integer(args[1]).intValue();
caller.setUp();
caller.converse();
caller.cleanUp();
} // end main() method
public void setUp()
{
System.out.println(“TalkToC.setUp() invoked”);
try
{
socket = new Socket(host, port);
inStream = new BufferedReader(new InputStreamReader(
socket.getInputStream()));
}
catch(UnknownHostException e)
{
System.err.println(“Cannot find host called: ” + host);
e.printStackTrace();
System.exit(-1);
}
catch(IOException e)
{
System.err.println(“Could not establish connection for ” + host);
e.printStackTrace();
System.exit(-1);
}
} // end setUp() method
public void converse()
{
System.out.println(“TalkToC.converse() invoked”);

Chapter 5. Using Java with other programming languages 109

 if (socket != null && inStream != null)
{
try
{
System.out.println(inStream.readLine());
}
catch(IOException e)
{
System.err.println(“Conversation error with host ” + host);
e.printStackTrace();
}
} // end if
} // end converse() method
public void cleanUp()
{
try
{
if(inStream != null)
{
inStream.close();
}
if(socket != null)
{
socket.close();
}
} // end try
catch(IOException e)
{
System.err.println(“Error in cleanup”);
e.printStackTrace();
System.exit(-1);
}
} // end cleanUp() method
} // end TalkToC class

SockServ.C starts by passing in a parameter for the port number. For example, CALL
SockServ ’2001’.

Example 2: SockServ.C server program

#include <stdlib.h>
#include <stdio.h>
#include <errno.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <netinet/tcp.h>
#include <unistd.h>
#include <sys/time.h>
void main(int argc, char* argv[])
{
int portNum = atoi(argv[1]);
int server;
int client;
int address_len;
int sendrc;
int bndrc;
char* greeting;
struct sockaddr_in local_Address;
address_len = sizeof(local_Address);
memset(&local_Address,0x00,sizeof(local_Address));
local_Address.sin_family = AF_INET;
local_Address.sin_port = htons(portNum);
local_Address.sin_addr.s_addr = htonl(INADDR_ANY);
#pragma convert (819)
greeting = “This is a message from the C socket server.”;
#pragma convert (0)

110 AS/400 Developer Kit for Java

 /* allocate socket */
if((server = socket(AF_INET, SOCK_STREAM, 0))<0)
{
printf(“failure on socket allocation\n”);
perror(NULL);
exit(-1);
}
/* do bind */
if((bndrc=bind(server,(struct sockaddr*)&local_Address, address_len))<0)
{
printf(“Bind failed\n”);
perror(NULL);
exit(-1);
}
/* invoke listen */
listen(server, 1);
/* wait for client request */
if((client = accept(server,(struct sockaddr*)NULL, 0))<0)
{
printf(“accept failed\n”);
perror(NULL);
exit(-1);
}
/* send greeting to client */
if((sendrc = send(client, greeting, strlen(greeting),0))<0)
{
printf(“Send failed\n”);
perror(NULL);
exit(-1);
}
close(client);
close(server);
}

For more information, see Using sockets for interprocess communication.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Using input and output streams for interprocess

communication
Input and output streams communicate between programs that are running in
separate processes. The java.lang.Runtime.exec() method runs a program. The
parent program can get handles to the child process input and output streams and
can write to or read from those streams. If the child program is written in a
language other than Java, you must ensure that any American National Standard
Code for Information Interchange (ASCII) or extended binary-coded decimal
interchange code (EBCDIC) conversion takes place. See Java character encodings
for more details.

For an example that uses input and output streams, see Example: Using input and
output streams for interprocess communication.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Using input and output streams for interprocess

communication
This example shows how to call a C program from Java and use input and output
streams for interprocess communication. In this example, the C program writes a

Chapter 5. Using Java with other programming languages 111

 string to its standard output stream, and the Java program reads this string and
displays it. This example assumes that a library, which is named JAVSAMPLIB, has
been created and that the CSAMP1 program has been created in it.

Note: The JAVSAMPLIB is not created as part of the AS/400 Developer Kit
licensed program (LP) number 5769-JV1 installation process. You must explicitly
create it.

Example 1: CallPgm class

import java.io.*;
public class CallPgm
{
public static void main(String args[])
{
Process theProcess = null;
BufferedReader inStream = null;
System.out.println(“CallPgm.main() invoked”);
// call the CSAMP1 program
try
{
theProcess = Runtime.getRuntime().exec(
“/QSYS.LIB/JAVSAMPLIB.LIB/CSAMP1.PGM”);
}
catch(IOException e)
{
System.err.println(“Error on exec() method”);
e.printStackTrace();
}
// read from the called program's standard output stream
try
{
inStream = new BufferedReader(new InputStreamReader
(theProcess.getInputStream()));
System.out.println(inStream.readLine());
}
catch(IOException e)
{
System.err.println(“Error on inStream.readLine()”);
e.printStackTrace();
}
} // end method
} // end class

Example 2: CSAMP1 C Program

#include <stdio.h>
#include <stdlib.h>
void main(int argc, char* args[])
{
/* Convert the string to ASCII at compile time */
#pragma convert(819)
printf(“Program JAVSAMPLIB/CSAMP1 was invoked\n”);
#pragma convert(0)
/* Stdout may be buffered, so flush the buffer */
fflush(stdout);
}

For more information, see Using input and output streams for interprocess
communication.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

112 AS/400 Developer Kit for Java

Calling Java from other languages
To call Java programs from other languages, it is necessary to call a command to
run the Java virtual machine. The application program interface (API) to call a
command differs, and depends on the language that calls Java. For example, from
C, the system() function runs the Run Java (RUNJVA) command. From CL, you can
directly call the RUNJVA command. Other ILE languages can use the QCMDEXC
call.

Note: Any of these calls cause another process to be created in which the Java
virtual machine is run. To communicate between the processes, you must use some
form of interprocess communication. Some methods of interprocess communication
are sockets, data queues, and stream files. If data is passing between the programs,
it is necessary to ensure that the programs convert that data properly.

For examples of how to call the Java Hello program in C or RPG, see Example:
Calling Java from C or Example: Calling Java from RPG, respectively.

You can also use the Java Invocation API specification, which allows a non-Java
application, such as C, to use the Java virtual machine.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Calling Java from C

This is an example of a C program that uses the system() function to call the Java
Hello program.

Example 1: Calling Java from C

#include <stdlib.h>
int main(void)
{
int result;
/* The system function passes the given string to the CL command processor
for execution. */
result = system(“JAVA CLASS('com.ibm.as400.system.Hello')”);
}

For more information, see calling Java from other languages.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Calling Java from RPG

This is an example of an RPG program that uses the QCMDEXC API to call the
Java Hello program.

Example 1: Calling Java from RPG

D* DEFINE THE PARAMETERS FOR THE QCMDEXC API
D*
DCMDSTRING S 25 INZ('JAVA CLASS(''com.ibm.as400.system.Hello'')')
DCMDLENGTH S 15P 5 INZ(25)
D* NOW THE CALL TO QCMDEXC WITH THE 'JAVA' CL COMMAND
C CALL 'QCMDEXC'
C PARM CMDSTRING
C PARM CMDLENGTH
C* This next line will display 'DID IT' after you exit the
C* Java Shell via F3 or F12.

Chapter 5. Using Java with other programming languages 113

 C 'DID IT' DSPLY
C* Set On LR to exit the RPG program
C SETON LR
C

For more information, see calling Java from other languages.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

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 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 C 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
re-created 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.

For an example that uses the Invocation API, see Example: Java Invocation API.
See Invocation API functions for details about the Invocation API functions that are
supported by the AS/400 Developer Kit for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

114 AS/400 Developer Kit for Java

Invocation API functions
The AS/400 Developer Kit for Java supports the these Invocation API functions.
Note: Before using this API, you must ensure that you are in a multithread-capable
job. See Developing multithreaded applications for more information about
multithread-capable jobs.
v JNI_GetDefaultJavaVMInitArgs Note: This function is only supported for Java
Development Kit (JDK) 1.1.x.
Returns a JDK 1.1 structure that contains default values for arguments that need
to be passed to JNI_CreateJavaVM when you create a Java virtual machine.
Signature:
jint JNI_GetDefaultJavaVMInitArgs(void *args_);
v JNI_GetCreatedJavaVMs
Returns information about all Java virtual machines that were created.
Signature:
jint JNI_GetCreatedJavaVMs(JavaVM **vmBuf,
jsize bufLen,
jsize *nVMs);

vmBuf is an output area whose size is determined by bufLen, which is the

number of pointers. Each Java virtual machine has an associated JavaVM
structure that is defined in java.h. This API stores a pointer to the JavaVM
structure that is associated with each created Java virtual machine into vmBuf,
unless vmBuf is full. Pointers to JavaVM structures are stored in the order of the
corresponding Java virtual machines that are created. nVMs returns the number
of virtual machines that are currently created. AS/400 supports the creation of
more than one Java virtual machine, so you may expect a value higher than one.
This information, along with the size of the vmBuf, determines whether pointers
to JavaVM structures for each created Java virtual machine are returned.
v JNI_CreateJavaVM
Allows a user to create a Java virtual machine and subsequently use it in an
application.
Signature for Java Development Kit 1.1.x:
jint JNI_CreateJavaVM(JavaVM **p_vm,
JNIEnv **p_env,
void *vm_args);

Signature for Java 2 Software Development Kit (J2SDK):

jint JNI_CreateJavaVM(JavaVM **p_vm,
void **p_env,
void *vm_args);

p_vm is the address of a JavaVM pointer for the newly created Java virtual
machine. Several other JNI Invocation APIs use p_vm to identify the Java virtual
machine. p_env is the address of a JNI Environment pointer for the newly
created Java virtual machine. It points to a table of JNI functions that start those
functions. vm_args is a structure that contains Java virtual machine initialization
parameters. When using JDK 1.1.x, you can obtain a structure that contains
default values by calling JNI_GetDefaultJavaVMInitArgs. For details on how to

do this with J2SDK, see Java Native Interface .

If you start a Run Java (RUNJVA) command or JAVA command and specify a
property that has an equivalent command parameter, then the command

Chapter 5. Using Java with other programming languages 115

 parameter takes precedence. The property is ignored. For example, the
os400.optimization parameter is ignored in this command:
JAVA CLASS(Hello) PROP((os400.optimization 0))

For a list of 0S/400 unique properties that are supported by the

JNI_CreateJavaVM API, see Java system properties.

Note:With multiple Java virtual machines within one process, all Java virtual
machines share the same process static storage that is allocated for any native
methods. Java virtual machine internal implementation already partitions data
on a per-Java virtual machine basis, but you must consider that with native
method applications Java virtual machines share process static storage. For other
considerations, see support for multiple Java virtual machines.
v DestroyJavaVM
Destroys the Java virtual machine.
Signature:
jint DestroyJavaVM(JavaVM *vm)

When the Java virtual machine is created, vm is the JavaVM pointer that is
returned.
v AttachCurrentThread
Attaches a thread to a Java virtual machine, so it can use Java virtual machine
services.
Signature for Java Development Kit (JDK) 1.1.x:
jint AttachCurrentThread(JavaVM *vm,
JNIEnv **p_env,
void *thr_args);

Signature for Java 2 Software Development Kit (J2SDK):

jint AttachCurrentThread(JavaVM *vm,
void **p_env,
void *thr_args);

The JavaVM pointer, vm, identifies the Java virtual machine to which the thread
is being attached. p_env is the pointer to the location where the JNI Interface
pointer of the current thread is placed. thr_args contains VM specific thread
attachment arguments.
v DetachCurrentThread
Signature:
jint DetachCurrentThread(JavaVM *vm);

vm identifies the Java virtual machine from which the thread is being detached.
For a complete description of the Invocation API functions, refer to the Java Native
Interface Specification by Sun Microsystems, Inc., or The Source for Java

Technology java.sun.com.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

116 AS/400 Developer Kit for Java

Support for multiple Java virtual machines
Java on the AS/400 system, unlike the Sun Microsystems, Inc. reference
implementation, supports the creation of multiple Java virtual machines within a
single job or process. This means that you can successfully call JNI_CreateJavaVM()
more than once in a job, and JNI_GetCreatedJavaVMs() can return more than one
Java virtual machine in its list of results.

If you want to create multiple Java virtual machines for use within a single job or
process, you should carefully consider the following:

Native method static storage scoping:

v Service programs that contain native method implementations are only activated
once per job, regardless of the number of Java virtual machines that you create.
This implies that native method static storage is scoped to the job and not to any
specific Java virtual machine.
v Values that a native method places in static storage are independent of the Java
virtual machine that called the native method. These values are visible to any
Java virtual machine in the job.
v If you intentionally use native method static storage in a multiple Java virtual
machine scenario, you should carefully consider the possible requirements for
synchronization, above and beyond the use of synchronized methods and
monitors, which are Java virtual machine specific. The qualification of a native
method as synchronized only prevents simultaneous runs within a single Java
virtual machine and not simultaneous runs from multiple Java virtual machines.
Java virtual machine termination:
v If a Java virtual machine is abnormally terminated, either due to a user calling
java.lang.System.exit() or an internal Java virtual machine failure, the failing
Java virtual machine and all of its attached threads are terminated.
v If the process initial thread is among the threads that were attached to the failed
Java virtual machine, an exception is thrown to the initial thread. If the initial
thread handles this exception, the other Java virtual machines can continue to
run.
v If the process initial thread is terminated, either by an unhandled exception or
any other reason, all of the Java virtual machines in the process are terminated,
as well.
Abnormal termination from C

If you use the ILE/C exit() or abort() routines in any thread of a multithreaded
job you will immediately bring down the entire job, including all Java virtual
machines.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Java Invocation API

This example follows the standard Invocation API paradigm. For example, it does
the following:
v Creates a Java virtual machine by using JNI_CreateJavaVM.
v Uses the Java virtual machine to find the class file that you want to run.
v Finds the methodID for the main method of the class.

Chapter 5. Using Java with other programming languages 117

 v Calls the main method of the class.
v Reports errors if an exception occurs.
To compile this program, you must bind it with a service program that exports the
functions to start a new Java virtual machine. These are the entry points that you
need:
v JNI_GetDefaultJavaVMInitArgs, which initializes the parameters to create.
v JNI_CreateJavaVM, which creates the Java virtual machine.
When you compile the program, you do not need to do anything explicit with the
compile command. The service program that exports these entry points is in the
system binding directory. The name of the service program is QJVAJNI.

To run this program, use SBMJOB CMD(CALL PGM(YOURLIB/PGMNAME))

ALWMLTTHD(*YES). Any job that creates a Java virtual machine must be
multithread-capable. The only job on AS/400 that is multithread-capable is a batch
immediate (BCI) job. The output from the main program, as well as any output
from the program, ends up in QPRINT spooled files. These spooled files are visible
if you use the Work with Submitted Jobs (WRKSBMJOB) command and view the
job that you started with Submit Job (SBMJOB).

Note: The C runtime exit() routine used below is not recommended unless you
know that your program is the only thread in the process. When called from a
process that is capable of supporting multiple threads, exit() immediately ends all
threads in a process.

Example:Using the Java Invocation API

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <jni.h>
int main (int argc, char *argv[])
{
JDK1_1InitArgs initArgs; /* Virtual Machine (VM) initialization structure.
* This is the structure that is passed by reference to JNI_CreateJavaVM
*See jni.h for details.
*/
JavaVM* myJVM; /* The JavaVM and JNIEnv pointers that you get back. */
JNIEnv* myEnv; /* ...from the JNI_CreateJavaVM() call. */
char* myClasspath; /* You need to modify the classpath, so you have your own. */
jclass myClass; /* The class you are going to find, called 'NativeHello'. */
jmethodID mainID; /* The method ID of the class' “main” routine. */
jclass stringClass; /* Required to create a string array argument for 'main'. */
jobjectArray args; /* Because main expects an array of strings, you must pass one. */
/* Set the version field of the initialization arguments. */
initArgs.version = 0x00010001;
/* Get the default initialization arguments. */
JNI_GetDefaultJavaVMInitArgs(&initArgs);
/* Now, you want to add the directory onto the end of the classpath,
* so that the findClass finds it correctly. To do this, you have two options:
* You can append your classpath entries to the default classpath that is returned
* by the call to JNI_GetDefaultJavaVMInitArgs, or
* you can use OS/400 specific functions for the same result. This is a
* three-step solution:
* 1. Set the CLASSPATH environment variable to its requirements with 'putenv()'
* 2. Clear the initialization arguments classpath to NULL, which forces
* JNI_CreateJavaVM to look at the CLASSPATH value
* 3. Set the “os400.class.path.system=PRE” property, to force JNI_CreateJavaVM
* to prepend the system default classpath to the effective classpath.
*
* The first option is used in this example, because it is more platform independent
*

118 AS/400 Developer Kit for Java

 * NOTE: You must specify the directory name in UTF-8 format! So, you wrap
* blocks of code in #pragma convert statements.
*/
#pragma convert(819)
myClasspath = malloc( strlen(initArgs.classpath) + strlen(“:/CrtJvmExample”) + 1 );
strcpy( myClasspath, initArgs.classpath );
strcat( myClasspath, “:/CrtJvmExample” );
initArgs.classpath = myClasspath;
#pragma convert(0)
/* Create the JVM. */
if (JNI_CreateJavaVM(&myJVM, &myEnv, &initArgs)) {
fprintf(stderr, “Failed to create the JVM\n”);
exit(1);
}
/* Use the newly created JVM to find the example class.
* NOTE: Again, you are dealing with UTF-8 here, so you
* have to wrap the calls in #pragma convert.
*/
#pragma convert(819)
if (! (myClass = (*myEnv)->FindClass(myEnv, “NativeHello”))) {
#pragma convert(0)
/* Cannot find the class, so write an error message
* to C stderr and exit the program.
*/
fprintf(stderr, “Failed to find the class 'NativeHello'\n”);
exit(1); /* Exit terminates the entire process on AS/400. */
}
/* Now, get the method identifier for the 'main' entry point
* of the class. Note: The signature of 'main' is always
* the same for every class, “main” and “([Ljava/lang/String;)V”
* Again, you are dealing with UTF-8.
*/
#pragma convert(819)
if (! (mainID = (*myEnv)->GetStaticMethodID(myEnv, myClass,
“main”,
“([Ljava/lang/String;)V”))) {
/* The 'main' methodID is not found for some reason. */
if ( (*myEnv)->ExceptionOccurred(myEnv) ) {
/* a java exception occurred, so print it out */
(*myEnv)->ExceptionDescribe(myEnv);
/* The JVM ends. */
(*myEnv)->FatalError(myEnv, “Failed to find jmethodID of 'main()'”);
}
#pragma convert(0)
/* Cannot find the 'main' methodID, so write an error message
* to C stderr and exit the program.
*/
fprintf(stderr, “Failed to find the 'main()' method\n”);
exit(1); /* Exit terminates the entire process on AS/400. */
}
#pragma convert(819)
if (! (stringClass = (*myEnv)->FindClass(myEnv,“java/lang/String”))) {
#pragma convert(0)
/* Did not find java/lang/String, so write an error message
* to C stderr and exit the program.
*/
fprintf(stderr, “Failed to find the java/lang/String”);
exit(1); /* exit terminates the entire process on AS/400.*/
}
/* Now, you need to create an empty array of strings,
* because ([Ljava/lang/String) is a required part of the signature of
* every Java main routine.
*/
if (! (args = (*myEnv)->NewObjectArray(myEnv,0,stringClass,0))) {
/* Empty array was not created, so write an error message
* to C stderr and exit the program.
*/

Chapter 5. Using Java with other programming languages 119

 fprintf(stderr, “Failed to create empty array of strings”);
exit(1); /* Exit terminate the entire process on AS/400. */
}
/* Now, you have the methodID of main, and the class, so you can call the main method. */
(*myEnv)->CallStaticVoidMethod(myEnv,myClass,mainID,args);
/* Check for errors. */
if ( (*myEnv)->ExceptionOccurred(myEnv) ) {
fprintf(stderr,“An exception occurred while running 'main'”);
exit(1);
}
/* Finally, destroy the JavaVM that you created. */
if ( (*myJVM)->DestroyJavaVM(myJVM) ) {
fprintf(stderr, “Failed to destroy the JVM\n”);
exit(1);
}
/* All done. */
return 0;
}

For more information, see Java Invocation API.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

120 AS/400 Developer Kit for Java

Chapter 6. Accessing your AS/400 database with the AS/400
Developer Kit for Java JDBC driver

With the AS/400 Developer Kit for Java JDBC driver your Java programs can
access AS/400 database files, access JDBC database functions with embedded
Structured Query Language (SQL) for Java, and run SQL statements and process
results. JDBC is a standard part of Java and is included on AS/400. JDBC is a
Java API for running structured query language (SQL) statements. It allows the
user to issue SQL statements and process the results.

To utilize the JDBC driver:

1. Import the required classes:
v import java.sql.*;
v import com.ibm.db2.jdbc.app.*;
2. Set up the Uniform Resource Locator (URL).
3. Register the AS/400 Developer Kit for Java JDBC driver with the
DriverManager so that you can use JDBC to access data in an AS/400 database
file.
4. Connect to an AS/400 database by using the DriverManager.getConnection()
method.
5. Create the SQL statements that you want to use to update the data in your
table. SQL statements can be any of these interfaces:
v Statement is the standard SQL statement interface.
v PreparedStatement is a precompiled statement that can accept input
parameters.
v CallableStatement is a precompiled statement that can accept input and
output parameters.
6. Set the parameters for your PreparedStatement and CallableStatement SQL
statements.
7. Run the SQL statements.
8. Close each of the SQL statements using the Statement.close() method.
9. Close the connection to the AS/400 database.
JDBC defines these Java interfaces:
v The Driver interface creates the connection and returns information about the
driver version.
v The Connection interface represents a connection to a specific database.
v The Statement interface runs SQL statements and obtains the results.
v The PreparedStatement interface runs compiled SQL statements.
v The CallableStatement interface runs SQL stored procedures.
v The ResultSet interface provides access to a table of data that is generated by
running an SQL query or DatabaseMetaData catalog method.
v The ResultSetMetaData interface determines the types and properties of the
columns in a ResultSet.
v The DatabaseMetaData interface provides information about the database as a
whole.

© Copyright IBM Corp. 1998, 1999 121

 v JDBC 2.0 defines the Blob interface provides access to binary large objects
(BLOBs).
v JDBC 2.0 defines the Clob interface provides access to character large objects
(CLOBs).
See Example: Creating a JDBC application for an example of how to combine all of
the interfaces to build a JDBC application.

You can access AS/400 databases through two JDBC drivers: AS/400 Developer Kit
for Java driver or AS/400 Toolbox for Java JDBC driver. For specific information
about the AS/400 Toolbox for Java JDBC driver, see AS/400 Toolbox for Java.

For more information about JDBC, see the JDBC by Sun Microsystems, Inc.
documentation.

For more information about AS/400 Native JDBC Driver, see AS/400 Developer
Kit for Java JDBC Web Page.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Registering the AS/400 Developer Kit for Java JDBC driver before
using JDBC
You must register the AS/400 Developer Kit for Java JDBC driver with the
DriverManager before using JDBC to access data in an AS/400 database file.

You can either use a Java system property or have the Java program register the
drivers.
v Registration that uses a system property.
Each Java virtual machine has its own method of setting system properties. For
example, the java command in Qshell uses the -d option to set system
properties.
To set the driver using system properties, specify this command from the Qshell
Interpreter:
java -djdbc.drivers=com.ibm.db2.jdbc.app.DB2Driver MySQL

To set the driver using system properties, specify this from the CL command
line:
JAVA CLASS(MySQL)
PROP((jdbc.drivers com.ibm.db2.jdbc.app.DB2Driver))

For system property details, see Java system properties.

v Registration that uses the Java program.
To explicitly load the driver, add either of these commands to the Java program
before the first JDBC call:
–
java.sql.DriverManager.registerDriver (new com.ibm.db2.jdbc.app.DB2Driver ());
–
Class.forName(“DB2Driver”);

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

122 AS/400 Developer Kit for Java

Connecting to an AS/400 database using the AS/400 Developer Kit for
Java JDBC driver
To connect to the AS/400 database, use the DriverManager.getConnection()
method.

DriverManager.getConnection() takes a Uniform Resource Locator (URL) string as

an argument. The JDBC driver manager attempts to locate a driver that can
connect to the database that is represented by the URL. When using the AS/400
Developer Kit for Java driver, use this syntax for the URL:
“jdbc:db2:systemName”

The systemName contains an entry from the relational database directory. Enter the
Work with Relational Database Directory Entries (WRKRDBDIRE) command to
display or add the system name. Then, specify *LOCAL for the remote location in
the WRKRDBDIRE command. Typically, the name that is chosen is the same name
as the system name of the AS/400 that contains the database.

See Examples: Connecting to an AS/400 database using the AS/400 Developer Kit
for Java JDBC driver for an example of how to connect to an AS/400 database.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Examples: Connecting to an AS/400 database using the

AS/400 Developer Kit for Java JDBC driver
These are examples of how to use the JDBC driver to connect to an AS/400.

Example 1: Connecting to the AS/400 database; no default schema or properties

// Connect to system 'mySystem'. No default schema or properties are specified.
Connection c = DriverManager.getConnection(“jdbc:db2://mySystem”);

Example 2: Connecting to the AS/400 database; default schema is specified

// Connect to system 'mySys2'. The default schema 'mySchema' is specified.
// A schema is the default library if none is specified on a query.
Connection c2 = DriverManager.getConnection(“jdbc:db2://mySys2/mySchema”);

The Java program can specify a set of JDBC properties either by using the
java.util.Properties interface or by specifying the properties as part of the URL.
This example specifies properties by using the Properties interface.

Example 3: Connecting to the AS/400 database; properties are specified using

Java.util.Properties
// Create a properties object.
Properties p = new Properties();
// Set the properties for the connection.
p.put(“naming”, “sql”);
p.put(“user”, “JonDoe”);
p.put(“password”, “JD1”);
// Connect using the properties object.
Connection c = DriverManager.getConnection(“jdbc:db2://mySystem”,p);

Example 4: Disconnecting from the database

Chapter 6. Accessing your AS/400 database with the AS/400 Developer Kit for Java JDBC driver 123
 c.close();

For more information, see connecting to an AS/400 database using the AS/400
Developer Kit for Java JDBC driver.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Creating a JDBC application

JDBC is a Java API for running structured query language (SQL) statements. It
allows the user to issue SQL statements and process the results.

To utilize the JDBC driver:

1. Import the required classes.
2. Set up the Uniform Resource Locator (URL).
3. Register the driver.
4. Connect to the database.
5. Create a statement object.
6. Run SQL statements that create a table in the database and insert records.
7. Close the statement.
8. Create the PreparedStatement object.
9. Set the parameters and run the statement.
10. Close the PreparedStatement.
11. Create the CallableStatement object.
12. Set the input parameters, register the output parameters, and run the stored
procedures.
13. Close the CallableStatement.
14. Close the connection.
See Example: Creating a JDBC application for an example of how to combine all of
the interfaces to build a JDBC application.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Creating a JDBC application

These examples illustrate how to put all the interfaces together to build a JDBC
application.

Example 1: JDBC application

// Before running this example, some setup is required on the AS/400.
//
// 1. Find a *LOCAL Relational Database (e.g. AS400NAME) using CL Command WRKRDBDIRE,
// or add one if there is no such entry. Modify the source code for this Java
// program with this name and compile it.
//
// 2. Create stored procedure ADD on the AS/400 where this Java program will be run
// using the following CL commands:
//
// (Note: the example assumes library MYLIBRARY is empty, once created)
//
// > CRTLIB MYLIBRARY

124 AS/400 Developer Kit for Java

// > STRSQL
// > CREATE PROCEDURE MYLIBRARY/ADD
// (IN P1 INTEGER, IN P2 INTEGER, OUT P3 INTEGER)
// LANGUAGE SQL SPECIFIC MYLIBRARY/ADD
// JDCSPRSX: BEGIN
// SET P3 = P1 + P2;
// END JDCSPRSX
//
import java.lang.*;
import java.util.*;
import java.sql.*;
import com.ibm.db2.jdbc.app.*;
public class aJDBCApp
{
public static void main(String args[]) throws Exception
{
// Define a URL where AS400NAME is *LOCAL Relational Database
// defined on an AS/400 using CL command WRKRDBDIRE.
String url = “jdbc:db2://AS400NAME”;
// Register the driver.
Class.forName(“com.ibm.db2.jdbc.app.DB2Driver”);
// Connect to the database.
Connection c = DriverManager.getConnection(url, “” “”);
// Create a Statement object.
Statement s = c.createStatement();
// Run an SQL statement that creates a table in the database.
s.executeUpdate(“CREATE TABLE MYLIBRARY.MYTABLE (NAME VARCHAR(20), ID INTEGER)”);
// Run an SQL statement that inserts a record into the table.
s.executeUpdate(“INSERT INTO MYLIBRARY.MYTABLE (NAME, ID) VALUES ('DAVE', 123)”);
// Run an SQL statement that inserts a record into the table.
s.executeUpdate(“INSERT INTO MYLIBRARY.MYTABLE (NAME, ID) VALUES ('CINDY', 456)”);
// Create the PreparedStatement object.
// It precompiles the specified SQL statement.
// The question marks indicate where parameters must be set before the statement is run.
PreparedStatement ps = c.prepareStatement(“INSERT INTO MYLIBRARY.MYTABLE (NAME, ID) VALUES (?,
// Set parameters and run the statement.
ps.setString(1, “JOSH”);
ps.setInt(2, 789);
ps.executeUpdate();
// Set parameters and run the statement again.
ps.setString(1, “DAVE”);
ps.setInt(2, 456);
ps.executeUpdate();
// Close PreparedStatement.
ps.close();
// Create the CallableStatement object.
// It pre-compiles the specified call to a stored procedure.
// The question marks indicate where input parameters must be set
// and where output parameters can be retrieved.
// The first two parameters are input parameters,
// and the third parameter is an output parameter.
CallableStatement cs = c.prepareCall(“CALL MYLIBRARY.ADD (?, ?, ?)”);
// Set input parameters.
cs.setInt (1, 123);
cs.setInt (2, 234);
// Register the type of the output parameter.
cs.registerOutParameter (3, Types.INTEGER);
// Run the stored procedure.
cs.execute ();
// Get the value of the output parameter.
int sum = cs.getInt (3);
// Show the output parameter value returned by stored procedure ADD
System.out.println(“sum = ” + sum + “\n”);
// Close the CallableStatement.
cs.close();
// Define a complete SQL Statement.
String myQuery =

Chapter 6. Accessing your AS/400 database with the AS/400 Developer Kit for Java JDBC driver 125
 “select * from MYLIBRARY.MYTABLE”;
// Run an SQL query on the table.
ResultSet rs = s.executeQuery(myQuery);
System.out.println(
“Query result: \n”);
ResultSetMetaData rsmd = rs.getMetaData();
System.out.println(rsmd.getColumnName(1) + “” + rsmd.getColumnName(2));
System.out.println(“————”);
while (rs.next()) {
String value1 = rs.getString(1);
int value2 = rs.getInt(2);
System.out.println(value1 + “” + value2);
}
// Close the Statement.
s.close();
// Close the connection.
c.close();
}
}

For more information, see AS/400 Developer Kit for Java JDBC driver.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Statement interface for AS/400 Developer Kit for Java

A Statement object is an object that runs a structured query language (SQL)
statement and optionally obtains the ResultSet that is produced by it. Use
Connection.createStatement() to create new Statement objects.

CallableStatement inherits from PreparedStatement, and PreparedStatement inherits

from Statement. Statement runs a simple SQL statement that has no parameters.
PreparedStatement runs a precompiled SQL statement that may or may not have
IN parameters. CallableStatement runs a call to a database-stored procedure. A
CallableStatement may or may not have IN and OUT parameters.

See Example: Statement interface for AS/400 Developer Kit for Java for an example
of a Statement object.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Statement interface for AS/400 Developer Kit for

Java
This is an example of a Statement object.

Example 1: Statement object

// Connect to AS/400.
Connection c = DriverManager.getConnection(“jdbc:db2://mySystem”);
// Create a Statement object.
Statement s = c.createStatement();
// Run an SQL statement that creates a table in the database.
s.executeUpdate(“CREATE TABLE MYLIBRARY.MYTABLE (NAME VARCHAR(20), ID INTEGER)”);
// Run an SQL statement that inserts a record into the table.
s.executeUpdate(“INSERT INTO MYLIBRARY.MYTABLE (NAME, ID) VALUES ('DAVE', 123)”);
// Run an SQL statement that inserts a record into the table.
s.executeUpdate(“INSERT INTO MYLIBRARY.MYTABLE (NAME, ID) VALUES ('CINDY', 456)”);
// Run an SQL query on the table.

126 AS/400 Developer Kit for Java

 ResultSet rs = s.executeQuery(“SELECT * FROM MYLIBRARY.MYTABLE”);
// Close the Statement and the Connection.
s.close();
c.close();

For more information, see Statement interface for AS/400 Developer Kit for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

PreparedStatement interface for AS/400 Developer Kit for Java

A PreparedStatement object is an object that precompiles and stores structured
query language (SQL) statements. Having been precompiled is what makes the
statement “prepared.” This approach is more efficient than running the same
statement multiple times with a Statement object that compiles the statement each
time it runs. In addition, the SQL statement that is contained in a
PreparedStatement object may have one or more IN parameters.

Use Connection.prepareStatement() to create PreparedStatement objects.

See Example: PreparedStatement interface for AS/400 Developer Kit for Java for an
example of the Prepared Statement interface.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: PreparedStatement interface for AS/400 Developer

Kit for Java
This is an example of the PreparedStatement interface.

Example 1: PreparedStatement interface

// Connect to AS/400.
Connection c = DriverManager.getConnection(“db2:as400://mySystem”);
// Create the PreparedStatement object. It precompiles the specified SQL statement.
// The question marks indicate where parameters must be set before the statement is run.
PreparedStatement ps = c.prepareStatement(“INSERT INTO MYLIBRARY.MYTABLE (NAME, ID) VALUES (?, ?)”
// Set parameters and run the statement.
ps.setString(1, “JOSH”);
ps.setInt(2, 789);
ps.executeUpdate();
// Set parameters and run the statement again.
ps.setString(1, “DAVE”);
ps.setInt(2, 456);
ps.executeUpdate();
// Close PreparedStatement and the Connection.
ps.close();
c.close();

For more information, see PreparedStatement interface for AS/400 Developer Kit
for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 6. Accessing your AS/400 database with the AS/400 Developer Kit for Java JDBC driver 127
CallableStatement interface for AS/400 Developer Kit for Java
A CallableStatement object runs structured query language (SQL) stored
procedures. The stored procedure that is being called must already be stored in the
database. CallableStatement does not contain the stored procedure, only the call to
the stored procedure.

A stored procedure can return one or more ResultSet objects, and can use IN
parameters, OUT parameters, and INOUT parameters.

Use Connection.prepareCall() to create new CallableStatement objects.

See Example: CallableStatement interface for AS/400 Developer Kit for Java for an
example of how to use the CallableStatement interface.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: CallableStatement interface for AS/400 Developer Kit

for Java
This is an example of how to use the CallableStatement interface.

Example 1: CallableStatement interface

// Connect to AS/400.
Connection c = DriverManager.getConnection(“jdbc:db2://mySystem”);
// Create the CallableStatement object.
// It precompiles the specified call to a stored procedure.
// The question marks indicate where input parameters must be set and
// where output parameters can be retrieved.
// The first two parameters are input parameters, and the third parameter is an output parameter.
CallableStatement cs = c.prepareCall(“CALL MYLIBRARY.ADD (?, ?, ?)”);
// Set input parameters.
cs.setInt (1, 123);
cs.setInt (2, 234);
// Register the type of the output parameter.
cs.registerOutParameter (3, Types.INTEGER);
// Run the stored procedure.
cs.execute ();
// Get the value of the output parameter.
int sum = cs.getInt (3);
// Close the CallableStatement and the Connection.
cs.close();
c.close();

For more information, see CallableStatement interface for AS/400 Developer Kit for
Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

ResultSet interface for AS/400 Developer Kit for Java

The ResultSet object is an object that provides access to a table of data that is
generated by running a query. The table rows are retrieved in sequence. Within a
row, column values can be accessed in any order.

128 AS/400 Developer Kit for Java

 The data stored in ResultSet is retrieved by using the various get methods
depending on the type of data being retrieved. The next() method moves to the
next row.

See Example: ResultSet interface for AS/400 Developer Kit for Java for an example
of how to use the ResultSet interface.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: ResultSet interface for AS/400 Developer Kit for

Java
This is an example of how to use the ResultSet interface.

Example 1: ResultSet interface

// Connect to AS/400.
Connection c = DriverManager.getConnection(“db2:as400://mySystem”);
// Create a Statement object.
Statement s = c.createStatement();
// Run a query. The result is placed in a ResultSet object.
ResultSet rs = s.executeQuery (“SELECT NAME,ID FROM MYLIBRARY.MYTABLE”);
// Iterate through the rows of the ResultSet.
while (rs.next ())
{
// Get the values from the ResultSet.
// The first value is a string, and the second value is an integer.
String name = rs.getString(“NAME”);
int id = rs.getInt(“ID”);
System.out.println(“Name = ” + name);
System.out.println(“ID = ” + id);
}
// Close the Statement and the Connection.
s.close();
c.close();

For more information, see ResultSet interface for AS/400 Developer Kit for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

DatabaseMetaData interface for AS/400 Developer Kit for Java

The DatabaseMetaData object provides information about the database as a whole
as well as catalog information. DatabaseMetaData determines the specific support
that is provided by the database.

See Example: DatabaseMetaData interface for AS/400 Developer Kit for Java for an
example of how to use the DatabaseMetaData interface.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 6. Accessing your AS/400 database with the AS/400 Developer Kit for Java JDBC driver 129
 Example: DatabaseMetaData interface for AS/400 Developer
Kit for Java
This example shows how to return a list of tables.

Example 1: Returning a list of tables

// Connect to AS/400.
Connection c = DriverManager.getConnection(“jdbc:db2://mySystem”);
// Get the database meta data from the connection.
DatabaseMetaData dbMeta = c.getMetaData();
// Get a list of tables matching this criteria.
String catalog = “myCatalog”;
String schema = “mySchema”;
String table = “myTable%”; // % indicates search pattern
String types[] = {“TABLE”, “VIEW”, “SYSTEM TABLE”}:
ResultSet rs = dbMeta.getTables(catalog, schema, table, types);
// ... iterate through the ResultSet to get the values.
// Close the Connection.
c.close():

For more information, see DatabaseMetaData interface for AS/400 Developer Kit
for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Blob interface for the AS/400 Developer Kit for Java

You can use a Blob object to access binary large objects (BLOBs), such as sound
byte (.wav) files or image (.gif) files.

NOTE: Only use the Blob interface if you are also using Java 2 to develop your
application.

With the Blob class, the lob threshold property can be used. This property specifies
the maximum large object (LOB) size (in kilobytes) that can be retrieved as part of
a result set. LOBs that are larger than this threshold are retrieved in pieces using
extra communication to the server. Larger LOB thresholds reduce the frequency of
communication to the server, but they download more LOB data, even if it is not
used. Smaller lob thresholds may increase frequency of communication to the
server, but they only download LOB data as it is needed.

Using the Blob interface, you can do the following:

v Return the entire blob as a stream of uninterpreted bytes
v Return part of the contents of the blob
v Return the length of the blob
The following example shows how to use the DB2Blob interface:
Blob blob = resultSet.getBlob (1);
long length = blob.length ();
byte[] bytes = blob.getBytes (0, (int) length);

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

130 AS/400 Developer Kit for Java

Clob interface for the AS/400 Developer Kit for Java
If you have JDBC 2.0, you can use a Clob object to access character large
objects (CLOBs), such as large documents.

NOTE: Use the Clob interface only if you are using Java 2 to develop your
application.

With the Clob class, the lob threshold property can be used. This property specifies
the maximum large object (LOB) size (in kilobytes) that can be retrieved as part of
a result set. LOBs that are larger than this threshold are retrieved in pieces using
extra communication to the server. Larger LOB thresholds reduce the frequency of
communication to the server, but they download more LOB data, even if it is not
used. Smaller lob thresholds may increase frequency of communication to the
server, but they only download LOB data as it is needed.

Using the Clob interface, you can do the following:

v Return the entire clob as a stream of ASCII characters
v Return the contents of the clob as a character stream
v Return a part of the contents of the clob
v Return the length of the clob
The following example shows how to use the DB2Clob interface:
Clob clob = rs.getClob (1);
int length = clob.getLength ();
String s = clob.getSubString (0, (int) length);

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 6. Accessing your AS/400 database with the AS/400 Developer Kit for Java JDBC driver 131
132 AS/400 Developer Kit for Java
Chapter 7. Accessing databases using AS/400 Developer Kit
for Java DB2 SQLJ support

DB2 Structured Query Language for Java (SQLJ) support is based on the SQLJ
ANSI standard. The DB2 SQLJ support is contained in the AS/400 Developer Kit
for Java. DB2 SQLJ support allows you to create, build, and run embedded SQL for
Java applications.

The SQLJ support provided by the AS/400 Developer Kit for Java includes the
SQLJ run-time classes, and is available in
/QIBM/ProdData/Java400/ext/runtime.zip. For more information on the SQLJ
run-time classes, refer to the Runtime API documentation supplied in the

Implementation from www.sqlj.org.

SQLJ tools
The following tools are also included in the SQLJ support provided by the AS/400
Developer Kit for Java.
Note:These tools must be run in the Qshell Interpreter:
v The SQLJ translator, sqlj, replaces embedded SQL statements in the SQLJ
program with Java source statements and generates a serialized profile that
contains information about the SQLJ operations that are found in the SQLJ
program.
v The DB2 SQLJ Profile Customizer, db2profc, precompiles the SQL statements
stored in the generated profile and generates a package in the DB2 database.
v The DB2 SQLJ Profile Printer, db2profp, prints the contents of a DB2 customized
profile in plain text.
v The SQLJ profile auditor installer, profdb, installs and uninstalls debugging
class-auditors into an existing set of binary profiles.
v The SQLJ profile conversion tool, profconv, converts a serialized profile instance
to Java class format.

DB2 SQLJ restrictions

When you create DB2 applications with SQLJ, you should be aware of the
following restrictions:
v DB2 SQLJ support adheres to standard DB2 Universal Database restrictions on
issuing SQL statements.
v The DB2 SQLJ profile customizer should only be run on profiles associated with
connections to the local database.
v The SQLJ Reference Implementation requires JDK 1.1.x. See Support for multiple
Java Development Kits (JDKs) for more information on running multiple
versions of the Java Development Kit.
For information on using SQL in your Java applications, see Embedding SQL
Statements in your Java application and Compiling and running SQLJ Programs.

© Copyright IBM Corp. 1998, 1999 133

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Embedding SQL statements in your Java application

Static SQL statements in SQLJ are in SQLJ clauses. SQLJ clauses begin with
#sql and end with a semicolon (;) character.

Before you create any SQLJ clauses in your Java application, import the following
packages:
v import java.sql.*;
v import sqlj.runtime.*;
v import sqlj.runtime.ref.*;
The simplest SQLJ clauses are executable clauses and consist of the token #sql
followed by an SQL statement enclosed in braces. For example, the following SQLJ
clause may appear wherever a Java statement may legally appear:

#sql { DELETE FROM TAB };

The example above will delete all the rows in the table named TAB.

Note: For information on compiling and running SQLJ applications, see Compiling
and running SQLJ Programs.

In an SQLJ executable clause, the tokens that appear inside the braces are either
SQL tokens or host variables. All host variables are distinguished by the colon (:)
character. SQL tokens never occur outside the braces of an SQLJ executable clause.
For example, the following Java method inserts its arguments into an SQL table:
public void insertIntoTAB1 (int x, String y, float z) throws SQLException
{
#sql { INSERT INTO TAB1 VALUES (:x, :y, :z) };
}

The method body consists of an SQLJ executable clause containing the host
variables x, y, and z. For more information on host variables, see Host variables in
SQLJ.

In general, SQL tokens are case insensitive (except for identifiers delimited by
double quotation marks), and can be written in upper, lower, or mixed case. Java
tokens, however, are case sensitive. For clarity in examples, case insensitive SQL
tokens are uppercase, and Java tokens are lowercase or mixed case. Throughout
this chapter, the lowercase null is used to represent the Java “null” value, and the
uppercase NULL is used to represent the SQL “null” value.

The following kinds of SQL constructs may appear in SQLJ programs:

v Queries
For example, SELECT statements and expressions.
v SQL Data Change statements (DML)
For example, INSERT, UPDATE, DELETE.
v Data statements
For example, FETCH, SELECT..INTO.

134 AS/400 Developer Kit for Java

 v Transaction Control statements
For example, COMMIT, ROLLBACK, etc.
v Data Definition Language (DDL, also known as Schema Manipulation Language)
statements
For example, CREATE, DROP, ALTER.
v Calls to stored procedures
For example, CALL MYPROC(:x, :y, :z)
v Invocations of stored functions
For example, VALUES( MYFUN(:x) )
For an example of embedded SQLJ, see Example: Embedding SQL Statements in
your Java application.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Compiling and running SQLJ programs

If your Java program has embedded SQLJ statements, you need to follow a
special procedure in order to compile and run it. To compile and run your
structured query language for Java (SQLJ) Program, follow these steps.
Note:Before you begin, set up your CLASSPATH to contain the following:
/QIBM/ProdData/Java400/ext/sqlj_classes.jar
/QIBM/ProdData/Java400/ext/translator.zip
/QIBM/ProdData/Java400/ext/runtime.zip
1. Use the SQLJ translator, sqlj, on your Java source code with embedded SQL to
generate Java source code and associated profiles. There will be one profile
generated for each connection.
For example, type in the command:
sqlj MyClass.sqlj
Where MyClass.sqlj is the name of your SQLJ file. In this example, the SQLJ
translator will generate a MyClass.java source code file and any associated
profiles. The associated profiles will be named MyClass_SJProfile0.ser,
MyClass_SJProfile1.ser, MyClass_SJProfile2.ser, and so on.

Note: The SQLJ translator automatically compiles the translated Java source
code into a class file unless you explicitly turn off the compile option with the
-compile=false clause.
2. Use the SQLJ Profile Customizer tool, db2profc, to install DB2 SQLJ
Customizers on generated profiles and create the DB2 packages on the local
system.
For example, type in the command:
db2profc MyClass_SJProfile0.ser
Where MyClass_SJProfile0.ser is the name of the profile on which the DB2
SQLJ Customizer will run.

Note: This step is optional but is recommended to increase runtime

performance.
3. Run the Java class file just like any other Java class file.

Chapter 7. Accessing databases using AS/400 Developer Kit for Java DB2 SQLJ support 135
 For example, type in:
java MyClass
Where MyClass is the name of your Java class file.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Host variables in Structured Query Language for Java

Arguments to embedded SQL statements are passed through host variables. Host
variables are variables of the host language, and they can appear in SQL
statements. Hose variables have up to three parts:
v A colon (:) prefix.
v A Java host variable that is a Java identifier for a parameter, variable, or field.
v An optional parameter mode identifier.
This mode identifier can be one of the following:
IN, OUT, or INOUT.
The evaluation of a Java identifier does not have side effects in a Java program, so
it may appear multiple times in the Java code generated to replace an SQLJ clause.

The following query contains the host variable, :x. This host variable is the Java
variable, field, or parameter x that is visible in the scope containing the query.

SELECT COL1, COL2 FROM TABLE1 WHERE :x > COL3

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Structured Query Language for Java profiles

Profiles are generated by the SQLJ Translator, sqlj, when you translate the SQLJ
source file. Profiles are serialized binary files. That is why these files have a .ser
extension. These files contain the SQL statements from the associated SQLJ source
file.

To generate profiles from your SQLJ source code, run the SQLJ translator, sqlj, on
your .sqlj file.

For more information, see Compiling and running SQLJ Programs.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Embedding SQL Statements in your Java application

The following example SQLJ application, App.sqlj, uses static SQL to retrieve
and update data from the EMPLOYEE table of the DB2 sample database.

Example: Embedding SQL Statements in your Java application:

136 AS/400 Developer Kit for Java

import java.sql.*;
import sqlj.runtime.*;
import sqlj.runtime.ref.*;
#sql iterator App_Cursor1 (String empno, String firstnme) ; // 1
#sql iterator App_Cursor2 (String) ;
class App
{
/**********************
** Register Driver **
**********************/
static
{
try
{
Class.forName(“com.ibm.db2.jdbc.app.DB2Driver”).newInstance();
}
catch (Exception e)
{
e.printStackTrace();
}
}
/********************
** Main **
********************/
public static void main(String argv[])
{
try
{
App_Cursor1 cursor1;
App_Cursor2 cursor2;
String str1 = null;
String str2 = null;
long count1;
// URL is jdbc:db2:dbname
String url = “jdbc:db2:sample”;
DefaultContext ctx = DefaultContext.getDefaultContext();
if (ctx == null)
{
try
{
// connect with default id/password
Connection con = DriverManager.getConnection(url);
con.setAutoCommit(false);
ctx = new DefaultContext(con);
}
catch (SQLException e)
{
System.out.println(“Error: could not get a default context”);
System.err.println(e) ;
System.exit(1);
}
DefaultContext.setDefaultContext(ctx);
}
// retrieve data from the database
System.out.println(“Retrieve some data from the database.”);
#sql cursor1 = {SELECT empno, firstnme FROM employee}; // 2
// display the result set
// cursor1.next() returns false when there are no more rows
System.out.println(“Received results:”);
while (cursor1.next()) // 3
{
str1 = cursor1.empno(); // 4
str2 = cursor1.firstnme();
System.out.print (“ empno= ” + str1);
System.out.print (“ firstname= ” + str2);
System.out.println(“”);
}

Chapter 7. Accessing databases using AS/400 Developer Kit for Java DB2 SQLJ support 137
 cursor1.close(); // 9
// retrieve number of employee from the database
#sql { SELECT count(*) into :count1 FROM employee }; // 5
if (1 == count1)
System.out.println (“There is 1 row in employee table”);
else
System.out.println (“There are ” + count1
+ “ rows in employee table”);
// update the database
System.out.println(“Update the database.”);
#sql { UPDATE employee SET firstnme = 'SHILI' WHERE empno = '000010' };
// retrieve the updated data from the database
System.out.println(“Retrieve the updated data from the database.”);
str1 = “000010”;
#sql cursor2 = {SELECT firstnme FROM employee WHERE empno = :str1}; // 6
// display the result set
// cursor2.next() returns false when there are no more rows
System.out.println(“Received results:”);
while (true)
{
#sql { FETCH :cursor2 INTO :str2 }; // 7
if (cursor2.endFetch()) break; // 8
System.out.print (“ empno= ” + str1);
System.out.print (“ firstname= ” + str2);
System.out.println(“”);
}
cursor2.close(); // 9
// rollback the update
System.out.println(“Rollback the update.”);
#sql { ROLLBACK work };
System.out.println(“Rollback done.”);
}
catch( Exception e )
{
e.printStackTrace();
}
}
}
1. Declare iterators. This section declares two types of iterators:
App_Cursor1
Declares column data types and names, and returns the values of the
columns according to column name (Named binding to columns).
App_Cursor2
Declares column data types, and returns the values of the columns by
column position (Positional binding to columns).
2. Initialize the iterator. The iterator object cursor1 is initialized using the result
of a query. The query stores the result in cursor1.
3. Advance the iterator to the next row. The cursor1.next() method returns a
Boolean false if there are no more rows to retrieve.
4. Move the data. The named accessor method empno() returns the value of the
column named empno on the current row. The named accessor method
firstnme() returns the value of the column named firstnme on the current row.
5. SELECT data into a host variable. The SELECT statement passes the number
of rows in the table into the host variable count1.
6. Initialize the iterator. The iterator object cursor2 is initialized using the result
of a query. The query stores the result in cursor2.
7. Retrieve the data. The FETCH statement returns the current value of the first
column declared in the ByPos cursor from the result table into the host variable
str2.

138 AS/400 Developer Kit for Java

 8. Check the success of a FETCH..INTO statement. The endFetch() method
returns a Boolean true if the iterator is not positioned on a row, that is, if the
last attempt to fetch a row failed. The endFetch() method returns false if the
last attempt to fetch a row was successful. DB2 attempts to fetch a row when
the next() method is called. A FETCH...INTO statement implicitly calls the
next() method.
9. Close the iterators. The close() method releases any resources held by the
iterators. You should explicitly close iterators to ensure that system resources
are released in a timely fashion.
For background information on this example, see Embedding SQL Statements in
your Java application.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

The structured query language for Java (SQLJ) translator (sqlj)

The SQLJ translator, sqlj, generates a serialized profile containing information
about the SQL operations found in the SQLJ program. The SQLJ translator uses the
/QIBM/ProdData/Java400/ext/translator.zip file.

For more information on sqlj command line options, refer to the SQLJ User’s Guide
and Reference supplied in the Implementation from www.sqlj.org .

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Precompiling SQL statements in a profile using the DB2 SQLJ profile

customizer, db2profc
You can use the DB2 SQLJ Profile Customizer, db2profc, to make your Java
application work more efficiently with your database.
The DB2 SQLJ Profile Customizer does the following:
v Precompiles the SQL statements that are stored in a profile and generates a
package in the DB2 database.
v Customizes the SQLJ profile by replacing the SQL statements with references to
the associated statement in the package that was created.
To precompile the SQL statements in a profile, type in the following at the Qshell
command prompt:
db2profc MyClass_SJProfile0.ser
Where MyClass_SJProfile0.ser is the name of the profile you wish to precompile.

DB2 SQLJ Profile Customizer usage and syntax

db2profc[options] <SQLJ profile name>

Where SQLJ profile name is the name of the profile to be printed and options is
the list of options you want.
The options available for db2profp are:
-url=<JDBC URL>

Chapter 7. Accessing databases using AS/400 Developer Kit for Java DB2 SQLJ support 139
 -user=<user name>
-password=<password>
-package=<library name/ package name>
-commitctrl=<commitment control>
-datefmt=<date format>
-datesep=<date separator>
-timefmt=<time format>
-timesep=<time separator>
-decimalpt=<decimal point>
-stmtCCSID=<coded character set identifier for the SQL statement
text>
-sorttbl=<library name/sort sequence table name>
-langID=<language identifier>

For detailed descriptions of these options, see below.

-url=<JDBC URL>
Where JDBC URL is the url of the JDBC connection. The syntax for the url
is:
“jdbc:db2:systemName”
For more information, see Database access using the AS/400 Developer Kit
for Java JDBC driver.
-user=<user name>
Where user name is your user name. The default value is the userid of the
current user that is signed on for local connection.
-password=<password>
Where password is your password. The default value is the password of
the current user that is signed on for local connection.
-package=<library name/package name>
Where library name is the library where the package will be put, and
package name is the name of the package to be generated. The default
library name is QUSRSYS. The default package name will be generated
from the name of the profile. The maximum length for the package name
is 10 characters. Because the SQLJ profile name will always be longer than
10 characters, the default package name that is constructed will be different
from the profile name. The default package name will be constructed by
concatenating the first letters of the profile name with the profile key
number. If the profile key number is greater than 10 characters long then
the last 10 characters of the profile key number will be used for the default
package name. For example, the following chart shows some profile names
and their default package names:

Profile name Default package name

App_SJProfile0 App_SJPro0
App_SJProfile01234 App_S01234
App_SJProfile012345678 A012345678
App_SJProfile01234567891 1234567891

140 AS/400 Developer Kit for Java

-commitctrl=<commitment control>
Where commitment control is the level of commitment control you want.
Commitment control can have any one of the following character values:

Value Definition
C *CHG. Dirty reads, non-repeatable reads and
phantom reads are possible.
S *CS. Dirty reads are not possible but
non-repeatable reads and phantom reads are
possible.
A *ALL. Dirty reads and non-repeatable reads
are not possible but phantom reads are
possible.
N *NONE. Dirty reads, non-repeatable reads,
and phantom reads are not possible. This is
the default.

-datefmt=<date format>
Where date format is the type of date formatting you want. Date format
can have any one of the following values:

Value Definition
USA IBM USA standard (mm.dd.yyyy,hh:mm
a.m., hh:mm p.m.)
ISO International Standards Organization
(yyyy-mm-dd, hh.mm.ss) This is the default.
EUR IBM European Standard (dd.mm.yyyy,
hh.mm.ss)
JIS Japanese Industrial Standard Christian Era
(yyyy-mm-dd, hh:mm:ss)
MDY Month/Day/Year (mm/d/yy)
DMY Day/Month/Year (dd/mm/yy)
YMD Year/Month/Day (yy/mm/dd)
JUL Julian (yy/ddd)

Date format is used when accessing date result columns. All output date
fields are returned in the specified format. For input date strings, the
specified value is used to determine whether the date is specified ina valid
format. The default value is ISO.
-datesep=<date separator>
Where date separator is the type of separator you want to use. Date
separator is used when accessing date result columns. Date separator can
be any of the following values:

Value Definition
/ A slash is used.
. A period is used.
, A comma is used.
- A dash is used. This is the default.
blank A space is used.

-timefmt=<time format>
Where time format is the format you want to use to display time fields.
Time format is used when accessing time result columns. For input time
strings, the specified value is used to determine whether the time is
specified in a valid format. Time format can be any one of the following
values:

Chapter 7. Accessing databases using AS/400 Developer Kit for Java DB2 SQLJ support 141
 Value Definition
USA IBM USA standard (mm.dd.yyyy,hh:mm
a.m., hh:mm p.m.)
ISO International Standards Organization
(yyyy-mm-dd, hh.mm.ss) This is the default.
EUR IBM European Standard (dd.mm.yyyy,
hh.mm.ss)
JIS Japanese Industrial Standard Christian Era
(yyyy-mm-dd, hh:mm:ss)
HMS Hour/Minute/Second (hh:mm:ss)

-timesep=<time separator>
Where time separator is the character you wish to use to access your time
result columns. Time separator can be any one of the following values:

Value Definition
: A colon is used.
. A period is used. This is the default.
, A comma is used.
blank A space is used.

-decimalpt=<decimal point>
Where decimal point is the decimal point you want to use. The decimal
point is used for numeric constants in SQL statements. Decimal point can
be any one of the following values:

Value Definition
. A period is used. This is the default.
, A comma is used.

-stmtCCSID=<CCSID>
Where CCSID is the coded character set identifier for the SQL statements
that are prepared into the package. The value of the job during
customization time is the default value.
-sorttbl=<library name/sort sequence table name>
Where library name/sort sequence table name is the location and table
name of the sort sequence table you want to use. The sort sequence table is
used for string comparisons in SQL statements. The library name and sort
sequence table name each have limits of 10 characters. The default value is
taken from the job during customization time.
-langID=<language identifier>
Where language identifier is the language identifier you want to use.
The default value for the language identifier is taken from the current job
during customization time. The language identifier is used in conjunction
with the sort sequence table.

For a more detailed information on any of the above fields, see DB2 for AS/400
SQL Programming, SC41-5611

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

142 AS/400 Developer Kit for Java

Printing the contents of DB2 SQLJ profiles (db2profp and profp)
The DB2 SQLJ Profile Printer, db2profp, prints the contents of a DB2
customized profile in plain text. The Profile Printer, profp, prints the contents of
profiles generated by the SQLJ translator in plain text.

To print the content of the profiles generated by the SQLJ translator in plain text,
use the profp utility as follows:
profp MyClass_SJProfile0.ser
Where MyClass_SJProfile0.ser is the name of the profile you wish to print.

To print the content of the DB2 customized version of the profile in plain text, use
the db2profp utility as follows:
db2profp MyClass_SJProfile0.ser
Where MyClass_SJProfile0.ser is the name of the profile you wish to print.

Note: If you run db2profp on an uncustomized profile, it will simply tell you that
the profile has not been customized. If you run profp on a customized profile, it
will display the contents of the profile without the customizations.

DB2 SQLJ Profile Printer usage and syntax:

db2profp [options] <SQLJ profile name>

Where SQLJ profile name is the name of the profile to be printed and options is
the list of options you want.

The options available for db2profp are:

-url=<JDBC URL>
Where JDBC URL is the url you wish to connect to. See Connecting to an
AS/400 database using the AS/400 Developer Kit for Java JDBC driver for
more information.
-user=<user name>
Where user name is the user name is your user profile.
-password=<password>
Where password is the password of your user profile.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

The SQLJ profile auditor installer (profdb)

The SQLJ profile auditor installer (profdb) installs and uninstalls debugging
class-auditors. The debugging class-auditors are installed into an existing set of
binary profiles. Once the debugging class-auditors are installed, all RTStatement
and RTResultSet calls made during application run time are logged. They can be
logged to a file or standard output. The logs can then be inspected to verify the
behavior and trace errors of the application. Note that only the calls made to the
underlying RTStatement and RTResultSetcall interface at run time are audited.

Chapter 7. Accessing databases using AS/400 Developer Kit for Java DB2 SQLJ support 143
 To install debugging class-auditors, enter the following at the Qshell command
prompt:
profdb MyClass_SJProfile0.ser

Where MyClass_SJProfile0.ser is the name of the profile that was generated by

the SQLJ Translator.
To uninstall debugging class-auditors, enter the following at the Qshell
command prompt:
profdb -Cuninstall MyClass_SJProfile.ser

Where MyClass_SJProfile0.ser is the name of the profile that was generated by

the SQLJ Translator.

For more information on profdb command line options, see www.sqlj.org ,

select the Implementation category and go to the
sqlj.runtime.profile.util.AuditorInstaller class that is in the Runtime API
documentation.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Converting a serialized profile instance to Java class format using the

SQLJ profile conversion tool (profconv)
The SQLJ profile conversion tool (profconv) converts a serialized profile
instance to Java class format. The profconv tool is needed because some browsers
do not support loading a serialized object from a resource file that is associated
with an applet. Run the profconv utility to perform the conversion.

To run the profconv utility, type the following on the Qshell command line:
profconv MyApp_SJProfile0.ser
Where MyApp_SJProfile0.ser is the name of profile instance you wish to convert.

The profconvtool invokes sqlj -ser2class. See sqlj for command line options.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

144 AS/400 Developer Kit for Java

Chapter 8. Running your Java application on a host that does
not have a graphical user interface

If you want to run your Java application on a host that does not have a
graphical user interface (GUI), such as an AS/400 system, you can either the
Remote Abstract Window Toolkit (AWT) or the Class Broker for Java (CBJ).

You use Remote AWT with install and administration interfaces of server
applications. These interfaces typically have a minimum of complex graphics and
highly-interactive content. Remote AWT distributes AWT processing between
AS/400 and a workstation. So, responsiveness of graphic-intensive and
highly-interactive operations are not as fast as AWT implementations on platforms
with locally-attached graphic terminals. To use Remote AWT, see setting up
Remote AWT.

You can use the CBJ for high performance GUI services. Since Remote AWT is not
recommended for complex graphics or highly-interactive operations, you can use
the CBJ instead, which was designed for these environments. To use CBJ, see
setting up CBJ.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Setting up the Remote Abstract Window Toolkit for Java on a remote

display
With the Remote Abstract Window Toolkit (AWT), you can run Java AWT
graphical programs without making any changes on AS/400 and display the
graphics remotely. To use Remote AWT you must have Transmission Control
Protocol/Internet Protocol (TCP/IP) set up, and Sun Microsystems, Inc., Java
Development Kit (JDK) 1.1.x or Java 2 SDK (J2SDK), Standard Edition, version 1.2.
installed on your AS/400 and remote display.

You can use any graphics-capable hardware, including IBM Network Station, as a
remote display for Remote AWT if it meets these requirements:
v Graphics-capable hardware that runs Windows 95, Windows NT 4.0, IBM
Operating System/2 (OS/2), Sun Solaris, or AIX
v Configured hardware to access your AS/400 with TCP/IP
v Java Development Kit 1.1.x (JDK 1.1.7 or later is recommended) or J2SDK,
version 1.2.
To set up Remote AWT, complete these tasks:
1. Make the Remote AWT class files accessible to the remote display by copying
the files to the remote display or mapping the path to a network drive on the
remote display.
2. Add RAWTGui.zip or RAWTGui.jar to the CLASSPATH of the remote
displayFor JDK 1.1.x, add the RAWTGui.zip file to the CLASSPATH of the
remote display by setting the CLASSPATH environment variable or by using
the -classpath parameter of the java command. For J2SDK, version 1.2,

© Copyright IBM Corp. 1998, 1999 145

 the RAWTGui.jar file is automatically added to the CLASSPATH when using
-jarparameter of the java command.
3. Start Remote AWT on the remote display.
For details and hints for using Remote AWT, see these topics:
v Running a Java program using Remote Abstract Window Toolkit provides
instructions on how to run a Java program with AS/400 using multiple JDKs
and Netscape.
v Printing with the Remote Abstract Window Toolkit explains how to print, which
is the same as standard Java AWT printing. It also shows you how to print to
AS/400.
v Remote Abstract Window Toolkit properties shows you how to run a Remote
AWT application using the os400.class.path.rawt property.
v Remote Abstract Window Toolkit SecurityManager restrictions provides
information about the restrictions that apply when you are running Java
applications using Remote AWT under the control of a SecurityManager.
For more information about setting up TCP/IP, please see “How do I set up

TCP/IP” in the 0S/400 TCP/IP Configuration and Reference, SC41-5420 book.

See Example: Setting up the Remote Abstract Window Toolkit for Java on a
Windows remote display, for an example of how to set up Remote AWT.

For more information about AWT, see the Abstract Window Toolkit by Sun
Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Setting up the Remote Abstract Window Toolkit for

Java on a Windows remote display
This example shows one way that you can set up Remote AWT on a Windows
remote display. There are many other ways you can do this, depending on your
preference. You can use a similar process on other remote display operating
systems. The setup and starting process are automated with a Windows “.bat” file
or other programming facility that the remote display operating system provides.

To set up the Remote Abstract Window Toolkit (AWT) for Java on a Windows
remote display, do these tasks:
v Make the Remote AWT class files accessible to the remote display.
Copy the Remote AWT class files to the remote display. Copy
/QIBM/ProdData/Java400/jdk117/RAWTGui.zip to c:\rawt\RAWTGui.zip or
/QIBM/ProdData/Java400/jdk12/RAWTGui.jar to c:\rawt2\RAWTGui.jar

v Start the Remote AWT on the remote display by entering this on the command
line:
java -classpath c:\jdk1.1.7\lib\classes.zip;c:\rawt\RAWTGui.zip
java com.ibm.rawt.server.RAWTPCServer

or
java -jar c:\rawt2\RAWTGui.jar

146 AS/400 Developer Kit for Java

 For more information, see Setting up the Remote Abstract Window Toolkit for Java
on a remote display.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Making the Remote Abstract Window Toolkit for Java class

files accessible to the remote display
To make the Remote Abstract Window Toolkit (AWT) class files accessible to the
remote display, follow these steps for either Java Development Kit (JDK) 1.1. x or
Java 2 SDK (J2SDK), Standard Edition, version 1.2.

If you are using JDK 1.1.x, you can either:

v Copy the Remote AWT class files to the remote display.
The Remote AWT files are installed with the AS/400 Developer Kit for Java in
two ZIP files: /QIBM/ProdData/Java400/jdk1.1.x/RAWTApplHost.zip and
/QIBM/ProdData/Java400/jdk1.1.x/RAWTGui.zip.
The RAWTApplHost.zip file contains the Remote AWT classes for AS/400. The
RAWTGui.zip file contains the Remote AWT classes for your remote display.
Copy RAWTGui.zip from /QIBM/ProdData/Java400/jdk1.1.x to your remote
display.
v Map the path, /QIBM/ProdData/Java400/jdk1.1.x/RAWTGui.zip, to a network
drive on your remote display.

If you are using J2SDK, version 1.2, you can either:

v Copy the Remote AWT class files to the remote display.
The Remote AWT files are installed with the AS/400 Developer Kit for Java in
two JAR files: /QIBM/ProdData/Java400/jdk1.2/RAWTAHost.jar and
/QIBM/ProdData/Java400/jdk1.2/RAWTGui.jar
The RAWTAHost.jar file contains the Remote AWT classes for AS/400. The
RAWTGui.jar file contains the Remote AWT classes for your remote display.
Copy RAWTGui.jar from /QIBM/ProdData/Java400/jdk1.2 to a network drive
on your remote display.
v Map the path, /QIBM/ProdData/Java400/jdk1.2/RAWTGui.jar, to a network
drive on your remote display.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Adding RAWTGui.zip or RAWTGui.jar to the CLASSPATH of

the remote display
Setting the CLASSPATH allows the Remote Abstract Window Toolkit (AWT)
classes to be found by the Java virtual machine on the remote display. To add the
RAWTGui.zip file to the CLASSPATH of the remote display, do either of these
steps:
v Set the CLASSPATH environment variable. See the Java Development Kit (JDK)
information for your remote display for details.
Add the path where the RAWTGui.zip file is located to the CLASSPATH
environment variable.

Chapter 8. Running your Java application on a host that does not have a graphical user interface 147
 v Use the -classpath parameter of the java command.
When you use the java command to start Remote AWT, you can use the
-classpath parameter to specify a CLASSPATH. The CLASSPATH includes the
path where the RAWTGui.zip file is located.
For example, in Windows, the CLASSPATH parameter may look like this:
-classpath c:\jdk1.1.7\lib\classes.zip;c:\rawt\RAWTGui.zip

J2SDK, version 1.2 JAR support sets the CLASSPATH, so you do not need
to explicitly set the CLASSPATH parameter. To set the classpath and start
Remote AWT on a remote display enter this command:
java -jar <PATH>RAWTGui.jar

where <PATH> is the fully qualified drive and directory where the RAWTGui.jar
file is located. For example, java -jar c:\rawt2\RAWTGui.jar.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Starting the Remote Abstract Window Toolkit for Java on a

remote display
You need to start the server daemon on your remote display once and it stays
active until you end it. Java programs that exit on AS/400 do not end the server.

Note: The Welcome dialog stays active when you start the server daemon. When
the Welcome dialog display closes, the server daemon ends. You can minimize the
Welcome dialog display while the server daemon is active and use the display to
end the server daemon.

To start the Remote Abstract Window Toolkit (AWT) server daemon for JDK 1.1.x,
enter this on the command line:
java com.ibm.rawt.server.RAWTPCServer

To start the Remote AWT server daemon for J2SDK, version 1.2, enter this on
the command line:
java -jar <PATH>RAWTGui.jar

where “PATH” is the fully qualified drive and directory where the RAWTGui.jar
file is located. For example, java -jar c:\rawt2\RAWTGui.jar .

The server daemon selects the first free port above 2000 when the Java application
connects using Remote AWT. The Java application uses this port until the
application ends. Additional Java applications are connected to subsequent free
ports above 2000. The available range of ports goes up to 9999.

For more information about setting up TCP/IP, see “How do I set up TCP/IP” in

the OS/400 TCP/IP Configuration and Reference, SC41-5420 book.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

148 AS/400 Developer Kit for Java

Running a Java program using Remote Abstract Window
Toolkit
To run Java using the Remote Abstract Window Toolkit (AWT):
1. Start Remote AWT on the remote display.
2. Start the Java program on AS/400.
a. Enter the Run Java (RUNJVA) command on the command line.
Note: You must define the Java classpath to the Java program.
b. Press F4 (Prompt).
c. Enter the Java program class name on the class parameter line.
d. Press F10 (Additional parameters).
e. Press the Page Down key.
f. Enter RmtAwtServer on the next property name parameter line.
g. Enter the Transmission Control Protocol/Internet Protocol (TCP/IP) address
(for example, 1.1.11.11) of the remote display on the next property value
parameter line.
h. Enter os400.class.path.rawt on the property name parameter line.
i. Enter 1 on the property value parameter line.

j. Enter +for more properties.

k. Enter java.version on the property name parameter line.

l. Enter 1.2 on the property value parameter line.

The command line should look like this:
java class (classname) prop((RmtAwtServer '1.1.11.11') (os400.class.path.rawt 1)(java versio

m. Press Enter.
You can also run a Java program using Remote AWT with Netscape.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Running a Java program using Remote Abstract Window Toolkit

with Netscape
When running Java applications with Netscape, you can run them one of two
ways.

One option is to start the Remote Abstract Window Toolkit (AWT) server within
the Netscape Java virtual machine by opening an HTML file that contains
com.ibm.rawt.server.StartRAWT.class. For example, see the RAWT.html file below.
Once started, you can then start a Java application on your AS/400.

Or, you can start the Remote AWT server within the Netscape Java virtual machine
by opening an HTML file that contains com.ibm.rawt.server.StartRAWT400.class
and the AS/400 Toolbox for Java classes. For example, see the RAWT400.html file
shown below. Once started, you can sign on to your AS/400 where the Java
application resides and start the application.

Running within the Remote AWT server within the Netscape Java virtual
machine:

Chapter 8. Running your Java application on a host that does not have a graphical user interface 149
 To run the Remote AWT server within the Netscape Java virtual machine follow
these steps:
1. Edit this example .html file for your specific installation information for
RAWTGui.zip. This file, RAWT.html, starts Remote AWT within the Netscape
Java virtual machine.
<HTML>
<BODY TEXT=“#000000” LINK=“#0000EE” VLINK=“#551A8B” ALINK=“#FF0000”>
<CENTER>
<APPLET CODE=“com.ibm.rawt.server.StartRAWT.class”
codebase=“file://C|remote_awt\jdk1.1.7\lib\RAWTGui.zip”
WIDTH=600 HEIGHT=50>
</APPLET>
</CENTER>
</BODY>
</HTML>
2. Browse the RAWT.html page with Netscape 4.05 or higher. After granting all of
the requested privileges, Netscape starts the Remote AWT server and runs it
within its Java virtual machine.
3. Start a Java application on your AS/400 using Remote AWT.
4. After you exit the application, click on the Reload button while pushing the
Shift key to start the Remote AWT server again.
Running the Remote AWT server within the Netscape Java virtual machine and
signing on to your AS/400:

To run the Remote AWT server within the Netscape Java virtual machine and sign
on to your AS/400 follow these steps:
1. Edit this example .html file for your specific installation information for
jt400.zip and RAWTGui.zip. This file, RAWT400.html, starts Remote AWT and
uses the AS/400 Toolbox for Java to sign on to AS/400.
<HTML>
<BODY TEXT=“#000000” LINK=“#0000EE” VLINK=“#551A8B” ALINK=“#FF0000”>
<CENTER>
<APPLET ARCHIVE=“file://C\jt400\lib\jt400.zip”
code=“com.ibm.rawt.server.StartRAWT400.class”
codebase=“file://C|remote_awt\jdk1.1.1\lib\RAWTGui.zip”
WIDTH=600 HEIGHT=50>
</APPLET>
</CENTER>
</BODY>
</HTML>
2. Browse this RAWT400.html page with Netscape 4.05. After granting all of the
requested privileges, Netscape starts the Remote AWT applet that displays a
panel where you can do any of these options:
v Sign on to your AS/400 with Remote AWT using AS/400 Toolbox for Java to
access AS/400.
v Enter the Java application name and arguments with Remote AWT
properties.
v Push the Start Application button to start the specified Java application with
Remote AWT.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

150 AS/400 Developer Kit for Java

Printing with the Remote Abstract Window Toolkit
Printing with the Remote Abstract Window Toolkit (AWT) is the same as standard
Java AWT printing. The Remote AWT remote display processes print output and
directs the output to any printer that is known to the remote display operating
system. This can be a printer that is directly attached to the remote display, or a
network printer that is known to the remote display operating system.

You can select to print on the remote display or to an AS/400. A new print dialog
displays when an application issues a print request. The print request allows you
to select either a Remote Display printer or OS/400 printer. If you select OS/400
printer, a sign on dialog display appears. Once you have signed on, the Print
Dialog display appears. You can specify the OS/400 print queue, print file, file and
banner page title. You can also select paper size, orientation, and number of copies.

To use remote printing, you must install the AS/400 Toolbox for Java (5763-JC1)
and add this to your classpath on AS/400:
QIBM/ProdData/HTTP/Public/jt400/lib/jt400.zip

You can update the classpath by adding the classpath environment variable or by
using the classpath parameter.

Note:If this message appears while printing to AS/400, either the AS/400 Toolbox
for Java is not installed or the AS/400 Toolbox for Java classes are not in the
classpath.
Failed to load class file: com/ibm/as400/access/PrintObjectList.class
Exception occurred during event dispatching:
java.lang.NoClassDefFoundError: com/ibm/as400/access/PrintObjectList

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Remote Abstract Window Toolkit properties

When running a Java Remote AWT application on the AS/400 system, the
os400.class.path.rawt property must be used with a value of 1. There are a
number of default properties that are required when you use Remote AWT. These
default properties along with the proper version of Remote AWT and the
CLASSPATH are set when you use the os400.class.path.rawt property. The version
of Remote AWT is set according to the JDK version, which is either the default
version, if not specified, or the version that you specify with the java.version
property.

Here are the default properties that are required for Remote AWT.

For JDK 1.1.x:

v awt.toolkit=com.ibm.rawt.CToolkit
For J2SDK, version 1.2:
v awt.toolkit=com.ibm.rawt2.ahost.java.awt.AHToolkit
v java.awt.graphicsenv=com.ibm.rawt2.ahost.java.awt.AHGraphicsEnvironment

v java.awt.printerjob=com.ibm.rawt2.ahost.java.awt.print.AHPrinterjob
Remote AWT properties for remote display:

Chapter 8. Running your Java application on a host that does not have a graphical user interface 151
 If the server daemon or Java application abnormally ends with this message, check
the Java version on your remote display.
The JDK version in the Application-host/User-station is incompatible with the Remote-AWT version...

To check the version level, enter java -version on the command line. You can use
this new property on a remote display if you have a problem with the JDK
version. This property is not applicable for the AS/400. If the version is not at level
1.1.x, then you must install the proper level. If it is at level 1.1.x, you can run the
Remote AWT server and or the Java application with this property that indicates
the Java version: -DJdkVersion=1.1.x.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Remote Abstract Window Toolkit SecurityManager restrictions

Java applications that use the Remote Abstract Window Toolkit (AWT) running
under the control of a SecurityManager have some restrictions. Remote AWT
classes start methods, which call SecurityManager check methods in cases where
the SecurityManager is set. In these cases, a Java application that runs with Remote
AWT may encounter a SecurityException. The check methods that are called as a
result of running with Remote AWT are:
v SecurityManager.checkAccess(..)
v SecurityManager.checkMemberAccess(..)
v SecurityManager.checkExit(..)
v SecurityManager.checkRead(String file)
v SecurityManager.checkConnect(...)
v SecurityManager.checkListen(...)
v SecurityManager.checkAccept(...)
v SecurityManager.checkPropertiesAccess(..)

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Setting up the Class Broker for Java on a remote display

With the Class Broker for Java (CBJ) you can run Class Broker for
Java-enabled Java graphical programs on AS/400 and display the graphics
remotely.

You can either install CBJ yourself or have the system administrator install it for
you. If the system administrator installs the product, all programmers can share
the same Java code.

You can either install CBJ on Windows 95/98/NT, UNIX, or AS/400. In most
circumstances, you must install CBJ on your client machine and server machine.

Note:If your client machine is running a client applet that is accessed through a
web server on the server machine, then you do not need to install CBJ on the client
machine.

To install CBJ on AS/400, see Installing Class Broker for Java on AS/400.

152 AS/400 Developer Kit for Java

 To install CBJ on your workstation, see Installing Class Broker for Java on
Windows 95/98/NT or UNIX .

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Installing Class Broker for Java on AS/400

To install Class Broker for Java (CBJ) on AS/400, follow these steps:
1. Make sure that the AS/400 Developer Kit for Java is properly installed. See
Installing the AS/400 Developer Kit for Java to test installation.
2. Select a directory in the integrated file system to store the CBJ package named
cbj_1.1.jar. For example, /usr/local.
3. Start the Qshell Interpreter by entering the QSH command and go to the
directory that you selected in the integrated file system. For example,
/usr/local. When you install the AS/400 Developer Kit for Java, the
cbj_1.1.jar package is installed in QIBM/ProdData/Java400/ext.
4. Enter this command in Qshell:
jar xvf “PATH”cbj_1.1.jar

“PATH” is the directory path where the cbj_1.1.jar package is located. For
example, QIBM/ProdData/Java400/ext.

The CBJ files are extracted into the subdirectory, named /usr/local/JCBroker.
See Package content of cbj_.1.1.jar for more information.
5. Create an Java program on AS/400 for jcb.jar, by entering this command:
CRTJVAPGM CLSF('/usr/local/JCBroker/lib/jcb.jar')
6. If you want to use the CBJ classes (not in debug mode), you have to add
JCBroker\lib and JCBroker\lib\jcb.jar to the classpath option in the Java
command line. We do not recommended that you add JCBroker\lib and
JCBroker\lib\jcb.jar to the CLASSPATH environment variable, because it
might conflict with class loading when you run applets that set applet_jcb.jar
in the ARCHIVE tag.
7. If you want to run CBJ in debug mode, replace jcb.jar with jcbd.jar in the
classpath or override the classpath value on the Java command line. You can
also use this command:

CRTJVAPGM CLSF('/usr/local/JCBroker/lib/jcbd.jar')
8. For more information on CBJ APIs, running demos, editing properties,
designing and writing CBJ applications, and other topics, refer to the
JCBroker/index.html file in the cpj_1.1.jar package.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Installing Class Broker for Java on Windows or UNIX

To install Class Broker for Java (CBJ) on Windows, follow these steps:
1. Make sure that either JDK/JRE1.1 or JDK/JRE1.2 is properly installed.
2. Select a directory in to store the CBJ package, named cbj_1.1.jar. For example,
C:\.

Chapter 8. Running your Java application on a host that does not have a graphical user interface 153
 3. Change to your directory (C:\) and enter this command:
C:\ > jar xvf cbj_1.1.jar

The CBJ files are extracted and are copied into the directory. See Package
content of cbj_.1.1.jar for more information.
4. If you want to use the CBJ classes (not in debug mode), add C:\JCBroker\lib
and C:\JCBroker\lib\jcb.jar to the classpath option on the Java command
line. Note:We do not recommended that you add it to the system CLASSPATH
environment variable, because it might conflict with class loading when
running applets that set applet_jcb.jar in the ARCHIVE tag.
5. To run CBJ in debug mode, replace jcb.jar with jcbd.jar in the classpath.
To install CBJ on UNIX follow the same step for Windows, except for the
following system dependent changes:
v Replace the Windows file separator “\” with the UNIX file separator “/”.
v Replace the Windows classpath separator “;” with the UNIX classpath
separator “:”.
v Replace the Windows system environment variables “%XXX%” with the
UNIX system environment variables “$XXX”.
6. For more information on CBJ APIs, running demos, editing properties,
designing and writing CBJ applications, and other topics, refer to the
JCBroker/index.html file in the cpj_1.1.jar package.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Package content of cbj_1.1.jar

Here is the CBJ package (cbj_1.1.jar). The bold items denote main directories
of subdirectories. The non-bold items denote files.
JCBroker
|
|____ demo
| |______ bin
| |______ binx
| |______ html
| |______ images
| |______ lib
| | |___ discovery
| | |___ distreetable
| | |___ ftp
| | |___ hellojcb
| | |___ jcbcalc
| | |___ jcbchat
| | |___ lhellojcb
| | |___ remotethread
| | |___ stylepad
| | |___ websmdemo
| |______ log
| |______ src
|____ doc
| |_______ api
| |_______ guide
| |_______ FAQ.html
| |_______ quickStart.html
|____ lib
| |________ com
| | |____ ibm

154 AS/400 Developer Kit for Java

 | | |______ jcb
| | |____ resources
| | |_______ JCB.properties
| |________ jcb.jar
| |________ jcbd.jar
| |________ applet_jcb.jar
| |________ applet_jcbd.jar
| |________ Editor.class
|____ src
| |________ com (for designated users only)
| | |_____ ibm
| | |_____ jcb
| | | |___ proxies
| | | |___ resources
| | | |___ u t i l
| | |_____ jcbimpl
| | |___ transport
| |________ version.log
|_______ index.html (open it)

The next level of directories under the JCBroker directory consists of the this data:

demo

This directory contains these subdirectories: bin, binx, html, images, lib, log and
src. These directories contain the Windows executable, UNIX executable, HTML
pages, GIF files, class files, and source code (for some examples) of several demo
applications. You can run these demo examples by following the demo
instructions. The log directory is a placeholder for debug log files.

doc

This directory contains these two subdirectories: api and guide. The CBJ API guide
and a user guide about CBJ are stored here. The API documentation was generated
with the J2SDK, version 1.2, javadoc tool. To browse the API document or the user
guide, open the index.html file in the corresponding directory. The user guide is an
introductory level document, whereas the QuickStart guide is a fast track entry
document.

This directory also contains a FAQ.html file and the quickStart.html gile that
explains how to install and use CBJ, and shows you how to run the demo
examples.

lib

This directory contains the CBJ classes and resources that are needed for you to
develop, run, and deploy new CBJ based applications. The classes are packaged in
the jcb.jar file, For debug mode, the classes are packaged in the jcbd.jar file. The
classes that are included in the ARCHIVE tag of an applet are packaged in the
applet_jcb.jar file. For debug mode, the classes are packaged in the applet_ jcbd.jar
file. The JCB properties file, named JCB.properties, is in the
com/ibm/jcb/resources subdirectory. It is read by the CBJ runtime when started.
You can change this file to reflect your preferences. The properties are explained in
the installation and setting up section. The properties that only to applets are
contained in the applet_JCB.properties file, which is part of the applet_ jcb.jar and
applet_ jcbd.jar. You can also change this file to reflect your preferences when
running in applet mode. To change this file, run the Editor Java application that
resides in this directory.

Chapter 8. Running your Java application on a host that does not have a graphical user interface 155
 src

This directory contains the CBJ source code and the internal version log file, called
version.log. The directory is empty except for selected packages.

index.html

This is the starting page that references you to the rest of the documentation.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

156 AS/400 Developer Kit for Java

Chapter 9. Java security
The majority of the Java programs that run on AS/400 are applications, not
applets, so the “sandbox” security model does not restrict them. From a security
point of view, Java applications are subject to the same security restrictions as any
other program on AS/400. To run a Java program on AS/400, you must have
authority to the class file in the integrated file system. Once the program starts, it
runs under the user’s authority.

You can use adopted authority to access objects with the authority of the user that
is running the program, and the program owner’s authority. Adopted authority
temporarily gives a user authority to objects that they would not have originally
had authority to access. See the Create Java Program (CRTJVAPGM) command
information for details on the two new adopted authority parameters, which are
USRPRF and USEADPAUT.

The bytecode loader and verifier, within the Java virtual machine, also provide a
measure of Java security using the Java security model. Just as with applets, the
bytecode loader and verifier check that the bytecodes are valid and data types are
used properly. They also check that registers and memory are accessed correctly,
and that the stack does not overflow or underflow. These checks ensure that the
Java virtual machine can safely run the class without compromising the integrity of
the system.

The Secure sockets layer (SSL) Java Standard Extension to JDK 1.1 is another item
of security supported by AS/400 Developer Kit for Java. SSL provides a means of
authenticating a server and a client to provide privacy and data integrity. All SSL
communication begins with a “handshake” between the server and the client.
During a handshake, SSL negotiates the cipher suite that the client and server use
to communicate with each other. This cipher suite is a combination of the various
security features available through SSL. The combination of a number of different
security features provides increased security for client and server communications.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java security model

You can download Java applets from any system; thus security mechanisms exist
within the Java virtual machine to protect against malicious applets. The Java
runtime system verifies the bytecodes as the Java virtual machine loads them. This
ensures that they are valid bytecodes and that the code does not violate any of the
restrictions that the Java virtual machine places on Java applets. Java applets are
restricted in what operations they can perform, how they access memory, and how
they use the Java virtual machine. The restrictions are in place to prevent a Java
applet from gaining access to underlying operating system or data on the system.
This is the “sandbox” security model, because the Java applet can only “play” in
its own sandbox.

The “sandbox” security model is a combination of the class loader, class file
verifier, and the java.lang.SecurityManager class.

© Copyright IBM Corp. 1998, 1999 157

 For more information about security, see the Security by Sun Microsystems, Inc.
documentation and Securing your Java applications with SSL.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Making a Java application secure with secure sockets layer

You can use the secure sockets layer (SSL) to make your Java application more
secure. SSL does the following to improve the security of your applicaiton:
v Protects communication data through encryption.
v Authenticates remote user IDs.
v Authenticates remote system names.
Note:SSL uses a digital certificate to encrypt the socket communication of your
Java application. Digital certificates are an Internet standard for identifying secure
systems, users, and applications. You can control digital certificates using IBM
Digital Certificate Manager. For more information, see IBM Digital Certificate
Manager.

To make your Java application more secure by using SSL:

v Prepare AS/400 to support SSL.
v Design your Java application to use SSL by:
– Modifying your Java socket code to use socket factories if you do not use
socket factories already.
– Modifying your Java code to use SSL.
v Use a digital certificate to make your Java application more secure by:
1. Choosing a type of digital certificate to use.
2. Using the digital certificate when you run your application.
You can also register your Java application as a secure application by using the
QsyRegisterAppForCertUse API. For more information, see the
QsyRegisterAppForCertUse section in the System API Reference: Security APIs

book .

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Preparing AS/400 for secure sockets layer support

To prepare your system to use secure sockets layer (SSL), you need to install the
Digital Certificate Manager LP:
v 5769-SS1 OS/400 - Digital Certificate Manager
You also need to install one of these Cryptographic Access Provider LPs:
v 5769-AC1 Cryptographic Access Provider 40-Bit
v 5769-AC2 Cryptographic Access Provider 56-Bit
v 5769-AC3 Cryptographic Access Provider 128-Bit
You also need to make sure you can access or create a digital certificate on your
system. For more information on AS/400 digital certificate management and the
Internet, see Getting started with IBM Digital Certificate Manager.

158 AS/400 Developer Kit for Java

For more information on AS/400 security in general, see Firewall: getting started.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Cryptographic Access Providers

The Cryptographic Access Providers offer many cipher suites for your system to
use. A cipher suite is a combination of different security features. This list shows
which cipher suite each Cryptographic Access Provider offers:
5769-AC1 Cryptographic Access Provider 40-Bit
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
5769-AC2 Cryptographic Access Provider 56-Bit
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_DES_CBC_MD5
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
5769-AC3 Cryptographic Access Provider 128-Bit
SSL_RSA_WITH_NULL_MD5
SSL_RSA_WITH_NULL_SHA
SSL_RSA_EXPORT_WITH_RC4_40_MD5
SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5
SSL_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_DES_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_RC2_CBC_128_MD5
SSL_RSA_WITH_DES_CBC_MD5
SSL_RSA_WITH_3DES_EDE_CBC_MD5

You may be limited on the Cryptographic Access Provider that you can choose
from, depending on which country you are in. Once you load a Cryptographic
Access Provider, you can use any of the cipher suites that that Access Provider
offers.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 9. Java security 159

 Choosing a digital certificate to use
You should consider several factors when deciding which digital certificate to use.
You can use your system’s default certificate or you can specify another certificate
to use.

You want to use your system’s default certificate if:

v You do not have any specific security requirements for your Java application.
v You do not know what kind of security you need for your Java application.
v Your system’s default certificate meets the security requirements for your Java
application.
Note: If you decide that you want to use your system’s default certificate, check
with your system administrator to make sure that a default system certificate has
been created. For more information on digital certificate management, see Getting
started with IBM Digital Certificate Manager.

If you do not want to use your system’s default certificate, you need to choose a
different certificate to use. You can choose from two types of certificates:
v User certificate that identifies the user of the application.
v System certificate that identifies the system on which the application is running.
These questions can help you decide whether to use a user certificate or a system
certificate:
v Does your Java application run as a client application or a server application?
– If your application runs as a client application, you probably want to use a
user certificate.
– If your application runs as a server application, you probably want to use a
system certificate.
v Do you want the certificate to identify the user who is working with the
application or the system on which the application is running?
– If you want the certificate to identify the user who is working with the
application, then you want to use a user certificate.
– If you want the certificate to identify on which system the application is
running, then you want to use a system certificate.
Once you know what kind of certificate you need, you can choose from any of the
digital certificates in any of the certificate containers that you are able to access.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Using the digital certificate when you run your Java

application
To use secure sockets layer (SSL), you need to run your Java application using a
digital certificate.

To specify which digital certificate to use, use the following properties:

v -os400.certificateContainer
v -os400.certificateLabel
For example, if you want run the Java application MyClass.class using the digital
certificate MYCERTIFICATE, and MYCERTIFICATE was in the digital certificate
container YOURDCC, then the java command would look like this:

160 AS/400 Developer Kit for Java

java -os400.certificateContainer=YOURDCC
-os400.certificateLabel=MYCERTIFICATE MyClass

If you have not already decided which digital certificate to use, see deciding which
digital certificate to use. You may also decide to use your system’s default
certificate, which is stored in the system’s default certificate container.

To use your system’s default digital certificate, you do not need to specify a
certificate or a certificate container anywhere. Your Java application uses your
system’s default digital certificate automatically.

Continue reading for more information on the following topics:

v Digital certificates and the -os400.certificateLabel property (page “Digital
certificates and the -os400.certificateLabel property”)
v Digital certificate containers and the -os400.certificateContainer property (page
“Digital certificate containers and the -os400.certificateContainer property”)
For more information on AS/400 digital certificate management and the Internet,
see Getting started with IBM Digital Certificate Manager.

Digital certificates and the -os400.certificateLabel property

Digital certificates are an Internet standard for identifying secure systems, users,
and applications. Digital certificates are stored in digital certificate containers. If
you want to use a digital certificate container’s default certificate, you do not need
to specify a certificate label. If you want to use a specific digital certificate, you
must specify that certificate’s label in the java command using this property:
-os400.certificateLabel=

For example, if the name of the certificate you want to use is MYCERTIFICATE,
then the java command you enter would look like this:
java -os400.certificateLabel=MYCERTIFICATE MyClass

In this example, the Java application MyClass would use the certificate
MYCERTIFICATE. MYCERTIFICATE would need to be in the system’s default
certificate container in order to be used by MyClass.

Digital certificate containers and the -os400.certificateContainer

property
Digital certificate containers store digital certificates. If you want to use the AS/400
system default certificate container, you do not need to specify a certificate
container. To use a specific digital certificate container, you need to specify that
digital certificate container in the java command using this property:
-os400.certificateContainer=

For example, if the name of the certificate container that contains the digital
certificate you want to use is named MYDCC, then the java command you enter
would look like this:
java -os400.certificateContainer=MYDCC MyClass

In this example, the Java application, named MyClass.class, would run on the
system by using the default digital certificate that is in the digital certificate
container named MYDCC. Any sockets that you create in the application use the
default certificate that is in MYDCC to identify themselves and make all of their
communications secure.

Chapter 9. Java security 161

 If you wanted to use the digital certificate MYCERTIFICATE in the digital
certificate container, then the java command that you would enter would look like
this:
java -os400.certificateContainer=MYDCC
-os400.certificateLabel=MYCERTIFICATE MyClass

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Modifying your Java code to use socket factories

To use secure sockets layer (SSL) with your existing code, you must first modify
your code to use socket factories.

To modify your code to use socket factories:

1. Add this line to your program to import the SocketFactory class:
import javax.net.*;
2. Add a line that declares an instance of a SocketFactory object. For example:
SocketFactory socketFactory
3. Initialize the SocketFactory instance by setting it equal to the method
SocketFactory.getDefault(). For example:
socketFactory = SocketFactory.getDefault();
v The whole declaration of the SocketFactory should look like this:
SocketFactory socketFactory =
SocketFactory.getDefault();
4. Initialize your existing sockets. Call the SocketFactory method
createSocket(host,port) on your socket factory for each socket you declare.
Your socket declarations should now look like this:
Socket s = socketFactory.createSocket(host,port);

s is the socket that is being created.

socketFactory is the SocketFactory that was created in step 2.
host is a string variable that represents the name of a host server.
port is an integer variable that represents the port number of the socket
connection.
When you have completed all of these steps, your code uses socket factories. You
do not need to make any other changes to your code. All of the methods that you
call and all the syntax with your sockets still work.

See Examples: Modifying your Java code to use server socket factories for an
example of a client program being converted to use socket factories.

See Example: Modifying your Java code to use client socket factories for an
example of a client program being converted to use socket factories.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Examples: Modifying your Java code to use server socket

factories
These examples show you how to modify a simple socket class, named
simpleSocketServer, so that it uses socket factories to create all of the sockets. The
first example shows you the simpleSocketServer class without socket factories. The

162 AS/400 Developer Kit for Java

second example shows you the simpleSocketServer class with socket factories. In
the second example, simpleSocketServer is renamed to factorySocketServer.

Example 1: Socket server program without socket factories

/* File simpleSocketServer.java*/
import java.net.*;
import java.io.*;
public class simpleSocketServer {
public static void main (String args[]) throws IOException {
int serverPort = 3000;
if (args.length < 1) {
System.out.println(“java simpleSocketServer serverPort”);
System.out.println(“Defaulting to port 3000 since serverPort not specified.”);
}
else
serverPort = new Integer(args[0]).intValue();
System.out.println(“Establishing server socket at port ” + serverPort);
ServerSocket serverSocket =
new ServerSocket(serverPort);
// a real server would handle more than just one client like this...
Socket s = serverSocket.accept();
BufferedInputStream is = new BufferedInputStream(s.getInputStream());
BufferedOutputStream os = new BufferedOutputStream(s.getOutputStream());
// This server just echoes back what you send it...
byte buffer[] = new byte[4096];
int bytesRead;
// read until “eof” returned
while ((bytesRead = is.read(buffer)) > 0) {
os.write(buffer, 0, bytesRead); // write it back
os.flush(); // flush the output buffer
}
s.close();
serverSocket.close();
} // end main()
} // end class definition

Example 2: Simple socket server program with socket factories

/* File factorySocketServer.java */
// need to import javax.net to pick up the ServerSocketFactory class
import javax.net.*;
import java.net.*;
import java.io.*;
public class factorySocketServer {
public static void main (String args[]) throws IOException {
int serverPort = 3000;
if (args.length < 1) {
System.out.println(“java simpleSocketServer serverPort”);
System.out.println(“Defaulting to port 3000 since serverPort not specified.”);
}
else
serverPort = new Integer(args[0]).intValue();
System.out.println(“Establishing server socket at port ” + serverPort);
// Change the original simpleSocketServer to use a
// ServerSocketFactory to create server sockets.
ServerSocketFactory serverSocketFactory =
ServerSocketFactory.getDefault();
// Now have the factory create the server socket. This is the last
// change from the original program.
ServerSocket serverSocket =
serverSocketFactory.createServerSocket(serverPort);
// a real server would handle more than just one client like this...
Socket s = serverSocket.accept();
BufferedInputStream is = new BufferedInputStream(s.getInputStream());
BufferedOutputStream os = new BufferedOutputStream(s.getOutputStream());
// This server just echoes back what you send it...

Chapter 9. Java security 163

 byte buffer[] = new byte[4096];
int bytesRead;
while ((bytesRead = is.read(buffer)) > 0) {
os.write(buffer, 0, bytesRead);
os.flush();
}
s.close();
serverSocket.close();
}
}

For background information, see modifying your code to use socket factories.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Examples: Modifying your Java code to use client socket

factories
These examples show you how to modify a simple socket class, named
simpleSocketClient, so that it uses socket factories to create all of the sockets. The
first example shows you the simpleSocketClient class without socket factories. The
second example shows you the simpleSocketClient class with socket factories. In
the second example, simpleSocketClient is renamed to factorySocketClient.

Example 1: Socket client program without socket factories

/* Simple Socket Client Program */
import java.net.*;
import java.io.*;
public class simpleSocketClient {
public static void main (String args[]) throws IOException {
int serverPort = 3000;
if (args.length < 1) {
System.out.println(“java simpleSocketClient serverHost serverPort”);
System.out.println(“serverPort defaults to 3000 if not specified.”);
return;
}
if (args.length == 2)
serverPort = new Integer(args[1]).intValue();
System.out.println(“Connecting to host ” + args[0] + “ at port ” +
serverPort);
// Create the socket and connect to the server.
Socket s = new Socket(args[0], serverPort);
.
.
.
// The rest of the program continues on from here.

Example 2: Simple socket client program with socket factories

/* Simple Socket Factory Client Program */
// Notice that javax.net.* is imported to pick up the SocketFactory class.
import javax.net.*;
import java.net.*;
import java.io.*;
public class factorySocketClient {
public static void main (String args[]) throws IOException {
int serverPort = 3000;
if (args.length < 1) {
System.out.println(“java factorySocketClient serverHost serverPort”);
System.out.println(“serverPort defaults to 3000 if not specified.”);
return;
}
if (args.length == 2)
serverPort = new Integer(args[1]).intValue();

164 AS/400 Developer Kit for Java

 System.out.println(“Connecting to host ” + args[0] + “ at port ” +
serverPort);
// Change the original simpleSocketClient program to create a
// SocketFactory and then use the socket factory to create sockets.
SocketFactory socketFactory = SocketFactory.getDefault();
// Now the factory creates the socket. This is the last change
// to the original simpleSocketClient program.
Socket s = socketFactory.createSocket(args[0], serverPort);
.
.
.
// The rest of the program continues on from here.

For background information, see modifying your code to use socket factories.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Modifying your Java code to use secure sockets layer

If your code already uses socket factories to create its sockets, then you can add
secure socket layer (SSL) support to your program. If your code does not already
use socket factories, see modifying your code to use socket factories.

To modify your code to use SSL:

v Import javax.net.ssl.* to add SSL support:
import javax.net.ssl.*;
v Declare a SocketFactory by using SSLSocketFactory to initialize it:
SocketFactory newSF = SSLSocketFactory.getDefault();
v Use your new SocketFactory to initialize your sockets the same way that you
used your old SocketFactory:
Socket s = newSF.createSocket(args[0], serverPort);
Your code now uses SSL support. You do not need to make any other changes to
your code.

See Examples: Modifying your Java client to use secure sockets layer and
Examples: Modifying your Java server to use secure sockets layer for example
code.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Examples: Modifying your Java server to use secure sockets

layer
These examples show you how to modify one class, named factorySocketServer, to
use secure sockets layer (SSL).

The first example shows you the factorySocketServer class not using SSL. The
second example shows you the same class, renamed factorySSLSocketServer, using
SSL.

Example 1: Simple factorySocketServer class without SSL support

/* File factorySocketServer.java */
// need to import javax.net to pick up the ServerSocketFactory class
import javax.net.*;
import java.net.*;

Chapter 9. Java security 165

 import java.io.*;
public class factorySocketServer {
public static void main (String args[]) throws IOException {
int serverPort = 3000;
if (args.length < 1) {
System.out.println(“java simpleSocketServer serverPort”);
System.out.println(“Defaulting to port 3000 since serverPort not specified.”);
}
else
serverPort = new Integer(args[0]).intValue();
System.out.println(“Establishing server socket at port ” + serverPort);
// Change the original simpleSocketServer to use a
// ServerSocketFactory to create server sockets.
ServerSocketFactory serverSocketFactory =
ServerSocketFactory.getDefault();
// Now have the factory create the server socket. This is the last
// change from the original program.
ServerSocket serverSocket =
serverSocketFactory.createServerSocket(serverPort);
// a real server would handle more than just one client like this...
Socket s = serverSocket.accept();
BufferedInputStream is = new BufferedInputStream(s.getInputStream());
BufferedOutputStream os = new BufferedOutputStream(s.getOutputStream());
// This server just echoes back what you send it.
byte buffer[] = new byte[4096];
int bytesRead;
while ((bytesRead = is.read(buffer)) > 0) {
os.write(buffer, 0, bytesRead);
os.flush();
}
s.close();
serverSocket.close();
}
}

Example 2: Simple factorySocketServer class with SSL support

/* File factorySocketServer.java */
// need to import javax.net to pick up the ServerSocketFactory class
import javax.net.*;
import java.net.*;
import java.io.*;
public class factorySocketServer {
public static void main (String args[]) throws IOException {
int serverPort = 3000;
if (args.length < 1) {
System.out.println(“java simpleSocketServer serverPort”);
System.out.println(“Defaulting to port 3000 since serverPort not specified.”);
}
else
serverPort = new Integer(args[0]).intValue();
System.out.println(“Establishing server socket at port ” + serverPort);
// Change the original simpleSocketServer to use a
// ServerSocketFactory to create server sockets.
ServerSocketFactory serverSocketFactory =
ServerSocketFactory.getDefault();
// Now have the factory create the server socket. This is the last
// change from the original program.
ServerSocket serverSocket =
serverSocketFactory.createServerSocket(serverPort);
// a real server would handle more than just one client like this...
Socket s = serverSocket.accept();
BufferedInputStream is = new BufferedInputStream(s.getInputStream());
BufferedOutputStream os = new BufferedOutputStream(s.getOutputStream());
// This server just echoes back what you send it.
byte buffer[] = new byte[4096];
int bytesRead;

166 AS/400 Developer Kit for Java

 while ((bytesRead = is.read(buffer)) > 0) {
os.write(buffer, 0, bytesRead);
os.flush();
}
s.close();
serverSocket.close();
}
}

For background information, see modifying your Java code to use secure sockets
layer.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Examples: Modifying your Java client to use secure sockets

layer
These examples show you how to modify one class, named factorySocketClient, to
use secure sockets layer (SSL).

The first example shows you the factorySocketClient class not using SSL. The
second example shows you the same class, renamed factorySSLSocketClient, using
SSL.

Example 1: Simple factorySocketClient class without SSL support

/* Simple Socket Factory Client Program */
import javax.net.*;
import java.net.*;
import java.io.*;
public class factorySocketClient {
public static void main (String args[]) throws IOException {
int serverPort = 3000;
if (args.length < 1) {
System.out.println(“java factorySocketClient serverHost serverPort”);
System.out.println(“serverPort defaults to 3000 if not specified.”);
return;
}
if (args.length == 2)
serverPort = new Integer(args[1]).intValue();
System.out.println(“Connecting to host ” + args[0] + “ at port ” +
serverPort);
SocketFactory socketFactory = SocketFactory.getDefault();
Socket s = socketFactory.createSocket(args[0], serverPort);
.
.
.
// The rest of the program continues on from here.

Example 2: Simple factorySocketClient class with SSL support

// Notice that we import javax.net.ssl.* to pick up SSL support
import javax.net.ssl.*;
import javax.net.*;
import java.net.*;
import java.io.*;
public class factorySSLSocketClient {
public static void main (String args[]) throws IOException {
int serverPort = 3000;
if (args.length < 1) {
System.out.println(“java factorySSLSocketClient serverHost serverPort”);
System.out.println(“serverPort defaults to 3000 if not specified.”);
return;
}

Chapter 9. Java security 167

 if (args.length == 2)
serverPort = new Integer(args[1]).intValue();
System.out.println(“Connecting to host ” + args[0] + “ at port ” +
serverPort);
// Change this to create an SSLSocketFactory instead of a SocketFactory.
SocketFactory socketFactory = SSLSocketFactory.getDefault();
// We don't need to change anything else.
// That's the beauty of using factories!
Socket s = socketFactory.createSocket(args[0], serverPort);
.
.
.
// The rest of the program continues on from here.

For background information, see modifying your Java code to use secure sockets
layer.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

168 AS/400 Developer Kit for Java

Chapter 10. Creating an internationalized Java program
If you need to customize a Java program for a specific region of the world, you
can create an internationalized Java program with Java locales.

Creating an internationalized Java program involves these steps:

1. Isolating the locale-sensitive code and data. For example, strings, dates, and
numbers in your program.
2. Setting or getting the locale using the Locale class.
3. Formatting dates and numbers to specify a locale if you do not want to use the
default locale.
4. Creating resource bundles to handle strings and other locale-sensitive data.
To carry out these tasks in your own Java programs, refer to these examples:
v Internationalization of dates using the java.util.DateFormat class
v Internationalization of numeric display using the java.util.NumberFormat class
v Internationalization of locale-specific data using the java.util.ResourceBundle
class
For more information about internationalization, click on any of these links:

v AS/400 National Language Support, SC41-5101

v AS/400 International Application Development, SC41-5603

v Internationalization by Sun Microsystems, Inc.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java locales
A locale is a geographic or political region of the world that shares the same
language and customs. In Java, the Locale class represents a locale.

Supported Java locales:

The AS/400 Developer Kit for Java supports these locales. The AS/400 job
LANGID and CNTRYID determine the default locale. See Java system properties
for more details.

Locale Name in JDK 1.1.6 ISO Locale Name Language/Country

ar ar_EG Arabic/Egypt
be be_BY Belorussian/Belarus
bg bg_BG Bulgarian/Bulgaria
ca ca_ES Catalan/Spain
cs cs_CZ Czech/Czech Republic
da da_DK Danish/Denmark
de de_DE German/Germany
de_AT de_AT German/Austria
de_CH de_CH German/Switzerland
el el_GR Greek/Greece

© Copyright IBM Corp. 1998, 1999 169

 Locale Name in JDK 1.1.6 ISO Locale Name Language/Country
en en_US English/USA
en_AU en_AU English/Australia
en_CA en_CA English/Canada
en_GB en_GM English/Great Britain
en_IE en_IE English/Ireland
en_NZ en_NZ English/New Zealand
en_ZA en_ZA English/South Africa
es es_ES Spanish/Spain
es_AR es_AR Spanish/Argentina
es_BO es_BO Spanish/Bolivia
es_CL es_CL Spanish/Chile
es_CR es_CR Spanish/Costa Rica
es_DO es_DO Spanish/Dominican Republic
es_EC es_EC Spanish/Ecuador
es_GT es_GT Spanish/Guatemala
es_HN es_HN Spanish/Honduras
es_MX es_MX Spanish/Mexico
es_NI es_NI Spanish/Nicaragua
es_PA es_PA Spanish/Panama
es_PE es_PE Spanish/Peru
es_PR es_PR Spanish/Puerto Rico
es_PY es_PY Spanish/Paraguay
es_SV es_SV Spanish/El Salvador
es_UY es_UY Spanish/Uruguay
es_VE es_VE Spanish/Venezuela
et et_EE Estonian/Estonia
fi fi_FI Finnish/Finland
fr fr_FR French/France
fr_BE fr_BE French/Belgium
fr_CA fr_CA French/Canada
fr_CH fr_CH French/Switzerland
hr hr_HR Croatian/Croatia
hu hu_HU Hungarian/Hungary
is is_IS Icelandic/Iceland
it it_IT Italian/Italy
it_CH it_CH Italian/Switzerland
iw iw_IL Hebrew/Israel
ja ja_JP Japanese/Japan
ko ko_KR Korean/Korea
lt lt_LT Lithuanian/Lithuania
lv lv_LV Latvian/Latvia
mk mk_MK Macedonian/Macedonia
nl nl_NL Dutch/Netherlands
nl_BE nl_BE Dutch/Belgium
no no_NO_B Norwegian/Norway
no_NO_NY no_NO_NY Norwegian/Norway, NY
pl pl_PL Polish/Poland
pt pt_PT Portuguese/Portugal
ro ro_RO Romanian/Romania
ru ru_RU Russian/Russia
sh sh_SP Serbo-Croatian/Serbia
sk sk_SK Slovak/Slovakia
sl sl_SI Slovene/Slovenian
sq sq_AL Albanian/Albania

170 AS/400 Developer Kit for Java

 Locale Name in JDK 1.1.6 ISO Locale Name Language/Country
sr sr_SP Serbian/Serbia
sv sv_SE Swedish/Sweden
tr tr_TR Turkish/Turkey
uk uk_UA Ukrainian/Ukraine
zh zh_CN Simplified Chinese/China
zh_TW zh_TW Traditional Chinese/Taiwan

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Internationalization of dates using the java.util.DateFormat

class
This example shows how you can use locales to format dates.

Example 1: Demonstrates use of java.util.DateFormat class for internationalization

of dates
//************************
// File: DateExample.java
//************************
import java.text.*;
import java.util.*;
import java.util.Date;
public class DateExample {
public static void main(String args[]) {
// Get the Date
Date now = new Date();
// Get date formatters for default, German, and French locales
DateFormat theDate = DateFormat.getDateInstance(DateFormat.LONG);
DateFormat germanDate = DateFormat.getDateInstance(DateFormat.LONG, Locale.GERMANY);
DateFormat frenchDate = DateFormat.getDateInstance(DateFormat.LONG, Locale.FRANCE);
// Format and print the dates
System.out.println(“Date in the default locale: ” + theDate.format(now));
System.out.println(“Date in the German locale : ” + germanDate.format(now));
System.out.println(“Date in the French locale : ” + frenchDate.format(now));
}
}

For more information, see creating an internationalized Java program.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Internationalization of numeric display using the

java.util.NumberFormat class
This example shows how you can use locales to format numbers.

Example 1: Demonstrates use of java.util.NumberFormat class for

internationalization of numeric output
//**************************
// File: NumberExample.java
//**************************
import java.lang.*;
import java.text.*;
import java.util.*;

Chapter 10. Creating an internationalized Java program 171

 public class NumberExample {
public static void main(String args[]) throws NumberFormatException {
// The number to format
double number = 12345.678;
// Get formatters for default, Spanish, and Japanese locales
NumberFormat defaultFormat = NumberFormat.getInstance();
NumberFormat spanishFormat = NumberFormat.getInstance(new
Locale(“es”, “ES”));
NumberFormat japaneseFormat = NumberFormat.getInstance(Locale.JAPAN);
// Print out number in the default, Spanish, and Japanese formats
// (Note: NumberFormat is not necessary for the default format)
System.out.println(“The number formatted for the default locale; ” +
defaultFormat.format(number));
System.out.println(“The number formatted for the Spanish locale; ” +
spanishFormat.format(number));
System.out.println(“The number formatted for the Japanese locale; ” +
japaneseFormat.format(number));
}
}

For more information, see creating an internationalized Java program.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Internationalization of locale-specific data using the

java.util.ResourceBundle class
This example shows how you can use locales with resource bundles to
internationalize program strings.

These property files are required for the ResourceBundleExample program to work
as intended:
Contents of RBExample.properties
Hello.text=Hello
Contents of RBExample_de.properties
Hello.text=Guten Tag
Contents of RBExample_fr_FR.properties
Hello.text=Bonjour

Example 1: Demonstrates use of java.util.ResourceBundle class for

internationalization of locale-specific data
//*********************************
// File: ResourceBundleExample.java
//*********************************
import java.util.*;
public class ResourceBundleExample {
public static void main(String args[]) throws MissingResourceException {
String resourceName = “RBExample”;
ResourceBundle rb;
// Default locale
rb = ResourceBundle.getBundle(resourceName);
System.out.println(“Default : ” + rb.getString(“Hello” + “.text”));
// Request a resource bundle with explicitly specified locale
rb = ResourceBundle.getBundle(resourceName, Locale.GERMANY);
System.out.println(“German : ” + rb.getString(“Hello” + “.text”));
// No property file for China in this example... will use default
rb = ResourceBundle.getBundle(resourceName, Locale.CHINA);
System.out.println(“Chinese : ” + rb.getString(“Hello” + “.text”));

172 AS/400 Developer Kit for Java

 // Here is another way to do it...
Locale.setDefault(Locale.FRANCE);
rb = ResourceBundle.getBundle(resourceName);
System.out.println(“French : ” + rb.getString(“Hello” + “.text”));
// No property file for China in this example... will use default, which is now fr_FR.
rb = ResourceBundle.getBundle(resourceName, Locale.CHINA);
System.out.println(“Chinese : ” + rb.getString(“Hello” + “.text”));
}
}

For more information, see creating an internationalized Java program.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 10. Creating an internationalized Java program 173

174 AS/400 Developer Kit for Java
Chapter 11. Tuning Java program performance with the
AS/400 Developer Kit for Java
You should take several aspects of Java application performance into consideration
when building a Java application for AS/400. Here are some links to details and
hints on how you can get better performance:
v Use the Create Java Program (CRTJVAPGM) command before running Java class
files, JAR files, or ZIP files to improve the runtime performance of your Java
code.
v Change your optimization levels to achieve the best transformation performance.
v Carefully set your values for optimal garbage collection performance.
v Only use native methods to start system functions that are relatively long
running and are not available directly in Java.
v Use the javac -o option at compilation time to perform method inlining and
significantly improve your method call performance.
v Use Java exceptions in cases that are not the normal flow through your
application.
Use these tools with the Performance Explorer (PEX) to locate performance
problems in your Java programs:
v You can collect Java trace events using the AS/400 Java virtual machine.
v To determine the time that is spent in each Java method, use Java call traces.
v Java profiling locates the relative amount of CPU time that is spent in each Java
method and all system functions that are in use by your Java program.
v Use the Java Performance Data Collector to provide profile information about
the programs that run on AS/400.
Any job session can start and end PEX. Normally, the data that is collected is
system wide and pertains to all jobs on the system, including your Java programs.
At times it may be necessary to start and stop the performance collection from
inside a Java application. This reduces the collection time and may reduce the large
volume of data that is usually produced by a call/return trace. PEX cannot run
from within a Java thread. To start and stop a collection you need to write a native
method that communicates to an independent job though a queue or shared
memory. Then, the second job starts and stops the collection at the appropriate
time.

In addition to application-level performance data, you can use existing AS/400

system level performance tools. These tools report statistics on a Java thread basis.

For examples of PEX reports, see the Performance Tools/400, SC41-4340 book.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

© Copyright IBM Corp. 1998, 1999 175

Java runtime performance considerations
To greatly improve the runtime performance of your Java code, use the Create Java
Program (CRTJVAPGM) command before running Java class files, JAR files, or ZIP
files. The CRTJVAPGM command uses the bytecodes to create a Java program,
which contains optimized native instructions for AS/400, and associates the Java
program object with the class file, JAR file, or ZIP file.

If the CRTJVAPGM command is not used before running a Java class file, JAR file,
or ZIP file, then the Java code runs more slowly the first time, because an
optimized Java program at optimization level 10 is created. Future runs will be
much faster because the Java program is saved and remains associated with the
class file or JAR file. Running the bytecodes interpretively may provide acceptable
performance during application development, but you may want to use the
CRTJVAPGM command before running the Java code in a production environment.

A Just-In-Time compiler improves performance by compiling code, which is

optimized to a particular Java virtual machine runtime environment. You should
compare the benefit of this type of optimization to the time that it takes to
generate this code each time a Java virtual machine is created.

If your program is running slowly, enter the Display Java Program (DSPJVAPGM)
command to view the attributes of a Java program.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java transformation performance considerations

You can determine the speed of transformation by the optimization level that you
set. Optimization level 10 transforms the fastest, but the resulting program is
generally slower than one set at a higher optimization level. Optimization level 40
takes longer to transform, but is likely to run faster.

At optimization level 40, some Java program optimizations are not 100 percent
Java compatible. Thus, a few programs that do not run at level 40, may run at
level 30 instead. You can run programs that do not run at optimization level 40 by
using licensed internal code optimization LICOPT parameter strings. However,
performance at level 30 may be sufficient for your program.

If you are having problems running Java code that seemed to work on another
Java virtual machine, try using optimization level 30 instead of level 40. If this
works, and your performance is acceptable, you do not need to do anything else. If
you need better performance, see LICOPT parameter strings for information on
how to enable and disable various forms of optimization. For example, you could
first try creating the program using OPTIMIZE(40) LICOPT(NoPreresolveExtRef). If
your application contains dead calls to classes that are not available, this LICOPT
value allows your program to run without problems.

To determine what level of optimization your Java programs were created at, you
can use the Display Java Program (DSPJVAPGM) command. To change the
optimization level of your Java program, use the Create Java Program
(CRTJVAPGM) command.

176 AS/400 Developer Kit for Java

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Java garbage collection performance considerations

Garbage collection on the AS/400 Java virtual machine operates in a continuous
asynchronous mode. The garbage collection-initial size (GCHINL) parameter on the
Run Java (RUNJVA) command may affect application performance. This parameter
specifies the amount of new object space that is allowed between garbage
collections. A small value may cause too much garbage collection overhead. A large
value may limit garbage collection and cause out of memory errors. However, for
most applications, the default values should be correct.

Garbage collection determines that an object is no longer needed by evaluating

whether there are any valid references to that object.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java Native Method Invocation performance considerations

Native method invocation on AS/400 may not perform as well as native method
invocation on other platforms. Java on AS/400 has been optimized by moving the
Java virtual machine below the machine interface (MI). Native method invocation
requires a call to above MI code and may require expensive Java Native Interface
(JNI) calls back into the Java virtual machine. Native methods should not carry out
small routines, which you can easily write in Java. Only use native methods to
start system functions that are relatively long running and are not available
directly in Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java method inlining performance considerations

Method inlining can significantly improve method call performance. Any method
that is final is a potential candidate for inlining. The inline feature is available on
AS/400 through the javac -o option at compilation time. The size of your class
files and transformed Java program increases if you use the javac -o option. You
should consider both the space and performance characteristics of your application
when using the -o option.

The Java transformer enables inlining for optimization level 30 and optimization
level 40. Optimization level 30 enables some inlining of final methods within a
single class. Optimization level 40 enables inlining of final methods within a ZIP
file or JAR file. You can control method inlining with the AllowInlining and
NoAllowInlining LICOPT parameter strings. The AS/400 interpreter does not
perform method inlining.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 11. Tuning Java program performance with the AS/400 Developer Kit for Java 177
Java exception performance considerations
AS/400 exception architecture allows versatile interrupt and retry capabilities. It
allows mixed language interaction. Throwing Java exceptions on AS/400 may be
more expensive than on other platforms. This should not affect overall application
performance unless Java exceptions are routinely used in the normal application
path.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java event trace performance tools

The AS/400 Java virtual machine enables the trace of certain Java events. These
events can be collected without any instrumentation in the Java code. These events
include activities, such as garbage collection, thread creation, class loading, and
locking. The Run Java (RUNJVA) command does not specify these events. Instead,
you create a Performance Explorer (PEX) definition and use the Start Performance
Explorer (STRPEX) command to collect the events. Each event contains useful
performance information, such as time stamp and central processing unit (CPU)
cycles. You can trace both Java events and other system activities, such as disk
input and output, with the same trace definition.

For a complete description of the Java events, see the Performance Tools/400,

SC41-4340 book.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Java call trace performance tools

Java method call traces provide significant performance information about the time
that is spent in each Java method. On other Java virtual machines you may have
used the -prof (profiling) option on the java command. To enable method call
tracing on AS/400, you must specify the Enable Performance Collection
(ENBPFRCOL) command on the Create Java Program (CRTJVAPGM) command
line. After creating your Java program with this keyword, you can start the
collection of method call traces by using a Performance Explorer (PEX) definition
that includes the call/return trace type.

Call/return trace output produced with the Print Performance Explorer Report
(PRTPEXRPT) command shows the central processing unit (CPU) time for each call
for every Java method that is traced. In some cases, you may not be able to enable
all of the class files for call return tracing. Or, you may be calling native methods
and system functions that are not enabled for tracing. In this situation, all of the
CPU time that is spent in these methods or system functions accumulates. Then, it
is reported to the last Java method that is called and has been enabled.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

178 AS/400 Developer Kit for Java

Java profiling performance tools
System wide central processing unit (CPU) profiling calculates the relative amount
of CPU time that is spent in each Java method and all system functions in use by
your Java program. Use a Performance Explorer (PEX) definition that traces
performance monitor counter overflow (*PMCO) run cycle events. Samples are
typically specified in intervals of one millisecond. To collect a valid trace profile,
you should run your Java application until it accumulates two to three minutes of
CPU time. This should produce over 100,000 samples. The Print Performance
Explorer Report (PRTPEXRPT) command produces a histogram of CPU time that is
spent across the entire application. This includes every Java method and all
system-level activity. The Performance Data Collector (PDC) tool also provides
profile information about the programs that run on AS/400.

Note: CPU profiling does not show relative CPU usage for Java programs that are
interpreted.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Collecting Java performance data

To collect Java performance data on AS/400, follow these steps:
1. Create a Performance Explorer (PEX) definition that specifies:
v A user-defined name
v Type of data collection
v Job name
v Series of system events that you would like to collect system information
about

Note: A PEX definition of *STATS is preferable to a *TRACE definition if the

output that you want is the java_g -prof type, and you know the specific job
name of the Java program.

Here is an example of a *STATS definition: ADDPEXDFN DFN(YOURDFN)

JOB(*ALL/YOURID/QJVACMDSRV) DTAORG(*HIER) TEXT(’your stats definition’)
This *STATS definition does not get all Java events running. Only the Java
events that are in your own Java session are profiled. This mode of operation
may increase the time that it takes to run the Java program.

Here is an example of a *TRACE definition: ADDPEXDFN DFN(YOURDFN)

TYPE(*TRACE) JOB(*ALL) TRCTYPE(*SLTEVT) SLTEVT(*YES) PGMEVT(*JVAENTRY
*JVAEXIT) This *TRACE definition collects any Java entry event and exit event
from any Java program in the system that you create with
ENBPFRCOL(*ENTRYEXIT). This causes the analysis of this type of collection
to be slower than a *STATS trace, depending on how many Java program
events you have and the duration of the PEX data collection.
2. Enable the *JVAENTRY and *JVAEXIT, under the program events category on
the PEX definition, so that PEX recognizes the Java entry and exits. Note: If
you are running the Java code using the Just-in-time (JIT) compiler, you do not
enable entry and exit as you would if you were using the CRTJVAPGM
command for direct execution. Instead, JIT generates code with entry and exit
hooks when you use the os400.enbprfcol system property.

Chapter 11. Tuning Java program performance with the AS/400 Developer Kit for Java 179
 3. Prepare the Java program to report program events to the AS/400 Performance
Data Collector. You can do this by using the Create Java Program
(CRTJVAPGM) command on any Java program that you want to report
performance data on. You must create the Java program by using the
ENBPFRCOL(*ENTRYEXIT) parameter.
Note: You must repeat this step for every Java program that you want to collect
performance data on. If you do not perform this step, no performance data is
collected by the PEX and no output is produced by running the Java
Performance Data Converter (JPDC) tool.
4. Start the PEX data collection by using the Start Performance Explorer (STRPEX)
command.
5. Run the program that you would like to analyze. This program should not be
in a production environment. It will generate a large amount of data in a small
amount of time. You should limit the collection time to five minutes. A Java
Program that runs for this amount of time generates a lot of PEX system data.
If too much data is collected, an unreasonable amount of time is required to
process the data.
6. End the PEX data collection by using the End Performance Explorer (ENDPEX)
command.
Note: If this is not the first time that you have ended PEX data collection, you
must specify a replace file of *YES or it will not save your data.
7. Run the JPDC tool.
8. Connect the integrated file system directory to the system with the viewer of
your choice: java_g -prof viewer or Jinsight viewer. You can copy this file from
AS/400 and use it as input to any suitable profiling tool.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Performance Data Collector tool

The Performance Data Collector (PDC) tool provides profile information about the
programs that run on AS/400.

The industry-standard profile option on many Java virtual machines depends on

the implementation of the java_g feature. This is a special debug version of the
Java virtual machine, which offers the -prof option. You specify this option on a
call to a Java program. When you specify this option, the Java virtual machine
produces a record file that contains information about which parts of the Java
program were operating during the duration of the program. The Java virtual
machine generates this information in real time.

On AS/400, the Performance Explorer (PEX) feature analyzes programs and

record-specific system events. A DB/2 database stores this information and
retrieves it using SQL functions. PEX information is the repository for specific
program information that produces Java profile data. This profile data is
compatible with java_g -prof program profile information. The Java Performance
Data Converter (JPDC) tool provides java_g -prof program output and program
profile information for a specific IBM tool, which is known as Jinsight.

For information on how collect Java performance data, see collecting Java
performance data.

180 AS/400 Developer Kit for Java

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Java Performance Data Converter tool

The Java Performance Data Converter (JDPC) tool provides a way for you to create
Java performance data about the Java programs that are running on AS/400. This
performance data is compatible with the performance data output of Sun
Microsystems, Inc.’s Java virtual machine java_g -prof option and IBM Jinsight
output.

Note: The JDPC tool does not produce readable output. Use a Java profiling tool
that accepts java_g -prof or Jinsight data to analyze your data.

The JDPC tool accesses the AS/400 Performance Explorer (PEX) data that DB2/400
(using JDBC) stores. It converts the data to either Jinsight or general performance
types. Then, JDPC stores the output file in the integrated file system at a
user-specified location.

Note: You must follow appropriate AS/400 PEX data collection procedures to
collect PEX data while running your specified Java application on AS/400. You
must set a PEX definition with defines the entrance and exit of a program or a
collect and store procedure. For details on how collect PEX data and set a PEX

definition, see the Performance Tools/400, SC41-4340 book.

For information on how to run JPDC, see Running the Java Performance Data
Converter.

You can start the JPDC program by using either the Qshell command line interface
or Run Java (RUNJVA) command.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Running the Java Performance Data Converter

To run the Java Performance Data Converter (JPDC) for performance data
collection, follow these steps.
1. Enter the first input argument, which is either general for the java_g -prof or
jinsight for Jinsight output.
2. Enter the second input argument, which is the name of the Performance
Explorer (PEX) definition that was used to collect the data.
Note: You should restrict this name to four or five characters, because of the
internal use of connections of this name.
3. Enter the third input argument, which is the name of the file that the JPDC tool
generates. This generated file writes to your current integrated file system
directory. Use the cd (PF4) command to specify an integrated file system
current directory.
4. Enter the fourth input argument, which is the name of the AS/400 host
relational database directory entry. Use the Work with Relational Database
Directory Entry (WRKRDBDIRE) command to see what the name is. It is the
only relational database where the *LOCAL is indicated.

Chapter 11. Tuning Java program performance with the AS/400 Developer Kit for Java 181
 To operate this code the /QIBM/ProdData/Java400/ext/JPDC.jar file must be in
the Java classpath on AS/400. When the program is done running, a text output
file can be found in the current directory.

You can run JPDC by using the AS/400 command line or Qshell environment. See
Example: Running the Java Performance Data Converter for details.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Example: Running the Java Performance Data Converter

You can either use the AS/400 command line or the Qshell environment to run the
Java Performance Data Converter (JPDC).

Using the AS/400 command line:

1. Enter the Run Java (RUNJVA) command or JAVA command on the AS/400
command line.
2. Enter com.ibm.as400.jpdc.JPDC on the class parameter line.
3. Enter general pexdfn mydir/myfile myrdbdire on the parameter line.
4. Enter ’/QIBM/ProdData/Java400/ext/JPDC.jar’ on the classpath parameter line.
Note: You can omit the classpath if the ’/QIBM/ProdData/Java400/ext/JPDC.jar’
string is in the CLASSPATH environment variable. You can use either the Add
Environment Variable (ADDENVVAR) command, Change Environment
Variable (CHGENVVAR) command, or Work with Environment Variable
(WRKENVVAR) command to add this string to the CLASSPATH environment
variable.
Using the Qshell environment:
1. Enter the Start Qshell (STRQSH) command to start the Qshell Interpreter.
2. Enter this on the command line:
java -classpath /QIBM/ProdData/Java400/ext/JPDC.jar com.ibm.as400/jpdc/JPDC
jiinsight pexdfn mydir/myfile myrdbdire

Note: You can omit the classpath if the ’/QIBM/ProdData/Java400/ext/JPDC.jar’

string is added to your current environment. You can use either the
ADDENVVAR command, CHGENVVAR, or WRKENVVAR command to add
this string to your current environment.
For background information, see running the Java Performance Data Converter .

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

182 AS/400 Developer Kit for Java

Chapter 12. Debugging programs using the AS/400 Developer
Kit for Java
If you need to debug your Java programs, select one of these options:
v Debugging a Java program
v Debugging Java and native method programs
v Debugging a Java program from another display
v Debugging servlets
When you debug a Java program, your Java program is actually running in the
Java virtual machine in a batch immediate (BCI) job. Your source code displays in
the interactive display, but the Java program is not running there. It is running in
the other job, which is a serviced job. When your Java program ends, the serviced
job ends, and a message displays, stating that Job being serviced ended.

The interface between the two jobs is established when you specify the *DEBUG
option on the Run Java (RUNJVA) command.

For more information about the system debugger, see the ILE C Programmer’s

Guide, SC09-2515 book , and online help information.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Debugging a Java program

There are many different ways to debug a Java program. You can use the *DEBUG
option to view the source code before running the program. Then, you can set
breakpoints, or step over or into a program to analyze errors while the program is
running.

To debug Java programs:

1. Compile the Java program by using the DEBUG option, which is the -g option
on the javac tool. See Debugging Java programs by using the *DEBUG option
for more details.
2. Insert the class file (.class) and source file (.java) in the same directory on
AS/400.
3. Run the Java program by using the Run Java (RUNJVA) command on the
AS/400 command line. Specify OPTION(*DEBUG) on the Run Java (RUNJVA)
command.
4. The Java program source displays.
5. Press F6 (Add/Clear breakpoint) to set breakpoints, or press F10 (Step) to step
through the program. For more information about setting breakpoints, see
setting breakpoints. For details on stepping, see Stepping through Java
programs to debug.
Note:While using breakpoints and steps, check the logical flow of the Java
program, then view and change variables, as necessary.

© Copyright IBM Corp. 1998, 1999 183

 [ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]
]

Debugging Java programs by using the *DEBUG option

Use the *DEBUG option to view the source code before running the program. The
*DEBUG option allows you to set breakpoints within the code.

To use the *DEBUG option, enter the Run Java (RUNJVA) command that is
followed by the name of your classfile and OPTION(*DEBUG) on the command
line. For example, the AS/400 command line should look like this:
RUNJVA CLASS(classname) OPTION(*DEBUG)

Note: If you are not authorized to use the Start Service Job (STRSRVJOB)
command, OPTION(*DEBUG) is ignored.

To view the debugging displays, see Initial debugging displays for Java programs.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Initial debugging displays for Java programs

As you debug your Java programs, follow these example displays for your
programs. These displays show an example program, named Hellod.
v Enter ADDENVVAR ENVVAR(CLASSPATH) VALUE (’/MYDIR’).
v Enter this command: RUNJVA CLASS(HELLOD) OPTION(*DEBUG). Insert the name of
your Java program in place of HELLOD.
v Wait for the Display Module Source display to display. This is the source for the
HELLOD Java program.
+————————————————————————————————————————+
| Display Module Source |
| |
| Class file name: HELLOD |
| 1 import java.lang.*; |
| 2 |
| 3 public class Hellod extends Object |
| 4 { |
| 5 int k; |
| 6 int l; |
| 7 int m; |
| 8 int n; |
| 9 int o; |
| 10 int p; |
| 11 String myString; |
| 12 Hellod myHellod; |
| 13 int myArray[]; |
| 14 |
| 15 public Hellod() |
| More... |
| Debug . . . |
| |
| F3=End program F6=Add/Clear breakpoint F10=Step F11=Display variable |
| F12=Resume F17=Watch variable F18=Work with watch F24=More keys |
| |
+————————————————————————————————————————+
v Press F14 (Work with Module List).

184 AS/400 Developer Kit for Java

 v The Work with Module List display is shown. You can add other classes and
programs to debug by entering option 1 (Add program). Display their source
with option 5 (Display module source).
+————————————————————————————————————————+
| Work with Module List |
| System: AS400 |
| Type options, press enter. |
| 1=Add program 4=Remove program 5=Display module source |
| 8=Work with module breakpoints |
| |
| Opt Program/module Library Type |
| *LIBL *SRVPGM |
| HELLOD *CLASS Selected |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| Bottom |
| Command |
| ===> |
| F3=Exit F4=Prompt F5=Refresh F9=Retrieve F12=Cancel |
| F22=Display class file name |
| |
+————————————————————————————————————————+
v When adding a class to debug, you may need to enter a package-qualified class
name that is longer than the Program/module input field. To enter a longer
name, follow these steps:
1. Enter Option 1 (Add program).
2. Leave the Program/module field blank.
3. Leave the library field as *LIBL.
4. Enter *CLASS for Type.
5. Press Enter.
6. A pop up window is displayed where you have more room to enter the
package-qualified class file name.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Setting breakpoints
The running of a program can be controlled with breakpoints. Breakpoints stop a
running program at a specific statement.

To set breakpoints:
1. Place the cursor on the line of code where you would like to set a breakpoint.
2. Press F6 (Add/Clear breakpoint) to set the breakpoint.
3. Press F12 (Resume) to run the program.
Note:Just before the line of code runs, where the breakpoint is set, the program
source is displayed indicating that the breakpoint was hit.
+————————————————————————————————————————+
| Display Module Source |
| |

Chapter 12. Debugging programs using the AS/400 Developer Kit for Java 185
 |Current thread: 00000019 Stopped thread: 00000019 |
|Class file name: Hellod |
|35 public static void main(String[] args) |
|36 { |
|37 int i,j,h,B[],D[][]; |
|38 Hellod A=new Hellod(); |
|39 A.myHellod = A; |
|40 Hellod C[]; |
|41 C = new Hellod[5]; |
|42 for (int counter=0; counter<2; counter++) { |
|43 C[counter] = new Hellod(); |
|44 C[counter].myHellod = C[counter]; |
|45 } |
|46 C[2] = A; |
|47 C[0].myString = null; |
|48 C[0].myHellod = null; |
| |
|49 A.method1(); |
|Debug . . . |
| |
|F3=End program F6=Add/Clear breakpoint F10=Step F11=Display variable |
|F12=Resume F17=Watch variable F18=Work with watch F24=More key |
|Breakpoint added to line 41. |
+————————————————————————————————————————+

When you hit a breakpoint, if you want to set breakpoints that are only hit within
the current thread, use the TBREAK command.

For more information about system debugger commands, see the ILE C

Programmer’s Guide, SC09-2515 book, and online help information.

For information about evaluating variables when a program stops running at a

breakpoint, see Evaluating variables in Java programs.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Stepping through Java programs to debug

You can step through your program while debugging. You can either step over or
step into other functions. Java programs and native methods can use the step
function.

When the program source first displays, you can start stepping. The program stops
before running the first statement. Press F10 (Step). Continue to press F10 (Step) to
step through the program. Press F22 (Step into) to step into any function that your
program calls. You can also start stepping anytime a breakpoint is hit. For
information about setting breakpoints, see Setting breakpoints.
+————————————————————————————————————————+
| Display Module Source |
| |
|Current thread: 00000019 Stopped thread: 00000019 |
|Class file name: Hellod |
|35 public static void main(String[] args) |
|36 { |
|37 int i,j,h,B[],D[][]; |
|38 Hellod A=new Hellod(); |
|39 A.myHellod = A; |
|40 Hellod C[]; |
|41 C = new Hellod[5]; |
|42 for (int counter=0; counter<2; counter++) { |

186 AS/400 Developer Kit for Java

|43 C[counter] = new Hellod(); |
|44 C[counter].myHellod = C[counter]; |
|45 } |
|46 C[2] = A; |
|47 C[0].myString = null; |
|48 C[0].myHellod = null; |
|49 A.method1(); |
|Debug . . . |
| |
|F3=End program F6=Add/Clear breakpoint F10=Step F11=Display variable |
|F12=Resume F17=Watch variable F18=Work with watch F24=More key |
|Step completed at line 42 in thread 00000019 |
+————————————————————————————————————————+

To stop stepping and continue running the program, press F12 (Resume).

For more information about stepping, see the ILE C Programmer’s Guide,

SC09-2515 book, and online help information.

For information about evaluating variables when a program stops running at a

step, see Evaluating variables in Java programs.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Evaluating variables in Java programs

There are two ways to evaluate a variable when a program stops running at a
breakpoint or step:
v Enter EVAL VariableName on the debug command line.
v Put the cursor on the variable name in the displayed source code and press F11
(Display variable).
Use the EVAL command for evaluating variables in a Java program.
Note:You can also change the contents of a variable by using the EVAL command.
For more information about the variations of the EVAL command, see the ILE C

Programmer’s Guide, SC09-2515 book, and online help information.

When looking at variables in a Java program, note the following:

v If you evaluate a variable that is an instance of a Java class, the first line of the
display shows what kind of object it is. It also shows an identifier for the object.
Following the first display line, the contents of each data member in the object
displays. If the variable is null, the first line of the display indicates that it is
null. Asterisks show the contents of each data member (of a null object).
v If you evaluate a variable that is a Java string object, the contents of that string
displays. If the string is null, then null displays.
v You cannot change a variable that is a string.
v If you evaluate a variable that is an array, ’ARR’ displays followed by an
identifier for that array. You can evaluate elements of the array by using a
subscript of the variable name. If the array is null, then null displays.
v You cannot change a variable that is an array. You can change an element of an
array if it is not an array of strings or objects.
v For variables that are arrays, you can specify arrayname.length to see how many
elements are in the array.

Chapter 12. Debugging programs using the AS/400 Developer Kit for Java 187
 v If you want to see the contents of a variable that is a data member of a class,
you can specify classvariable.membername.
v If you try to evaluate a variable before it has been initialized one of two things
can happen. Either a Variable not available to display message is shown, or
the unitialized contents of the variable are shown, which could be a strange
value.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Debugging Java and native method programs

You can debug Java programs and native method programs at the same time.
While you are debugging your source on the interactive display, you can debug a
native method that is programmed in C, which is within a service program
(*SRVPGM).

To debug Java programs and native method programs at once:

1. Press F14 (Work with module list) when your Java program source displays to
show the Work with Module List (WRKMODLST) display.
2. Select option 1 (Add program) to add your service program.
3. Select option 5 (Display module source) to display the *MODULE that you
want to debug and the source.
4. Press F6 (Add/Clear breakpoint) to set breakpoints in the service program. For
more information about setting breakpoints, see Setting breakpoints.
5. Press F12 (Resume) to run the program.
Note:When the breakpoint is hit in your service program, the program will stop
running, and the source for the service program displays.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Debugging a Java program from another display

While debugging a Java program, the program source displays whenever it
encounters a breakpoint. This may interfere with the display output of the Java
program. To avoid this, debug the Java program from another display. The output
from the Java program displays where the Java command is running and the
program source shows on the other display.

To debug Java from another display:

1. The Java program must be held, while you start setting up to debug.
You can hold the Java program by making the program:
v Wait for input from the keyboard.
v Wait for a time interval.
v Loop to test a variable, which requires that you set a value to eventually get
the Java program out of the loop.
2. Once the Java program is held, go to another display to perform these steps:
a. Enter the Work with Active Jobs (WRKACTJOB) command on the command
line.

188 AS/400 Developer Kit for Java

 b. Find the batch immediate (BCI) job where your Java program is running.
Look under the Subsystem/Job listing for QJVACMDSRV. Look under the
User listing for your User ID. Look under Type for BCI.
c. Enter option 5 to work with that job.
d. At the top of the Work with Job display, the Number, User, and Job is
displayed. Enter STRSRVJOB Number/User/Job.
e. Enter STRDBG CLASS(classname). Classname is the name of the Java class
that you want to debug. It can either be the class name that you specified
on the Java command, or it can be another class.
f. The source for that class appears in the Display Module Source display.
g. Set breakpoints, by pressing F6 (Add/Clear breakpoint), whenever you
would like to stop in that Java class. Press F14 to add other classes,
programs, or service programs to debug. For more information about
setting breakpoints, see setting breakpoints.
h. Press F12 (Resume) to continue running the program.
3. Stop holding your original Java program. When the breakpoints are hit, the
Display Module Source display appears on the display where the Start Service
Job (STRSRVJOB) command and the Start Debug (STRDBG) command were
entered. When the Java program ends, a Job being serviced ended message
appears.
4. Enter the End Debug (ENDDBG) command.
5. Enter the End Service Job (ENDSRVJOB) command.
See QIBM_CHILD_JOB_SNDINQMSG environment variable for more information
about this variable that controls whether the BCI job waits before calling the Java
virtual machine.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

QIBM_CHILD_JOB_SNDINQMSG environment variable

The QIBM_CHILD_JOB_SNDINQMSG environment variable is the variable that
controls whether the batch immediate (BCI) job, where the Java virtual machine
runs, waits before starting the Java virtual machine.

If you set the environment variable to 1 when the Run Java (RUNJVA) command
runs, a message is sent to the user’s message queue. The message is sent before the
Java virtual machine starts in the BCI job. The message looks like this:
Spawned (child) process 023173/JOB/QJVACMDSRV is stopped (G C)

To view this message, enter SYSREQ and select option 4.

The BCI job waits until you enter a reply to this message. A reply of (G) starts the
Java virtual machine.

You can set breakpoints in a *SRVPGM or *PGM, which the BCI job calls, before
replying to the message.
Note: You cannot set breakpoints in a Java class, because at this point, the Java
virtual machine has not been started.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 12. Debugging programs using the AS/400 Developer Kit for Java 189
Debugging servlets
Debugging servlets is more complicated than debugging regular Java
applications, since servlets run in the Java runtime of the IBM HTTP Server.

To debug a servlet, follow these steps:

1. Use the javac -gcommand in the Qshell Interpreter to compile your servlet.
2. Copy the source code (.java file) and compiled code (.class file) to
/QIBM/ProdData/Java400.
3. Run the Create Java Program (CRTJVAPGM) command against the .class file
using optimization level 10, OPTIMIZE(10).
4. Start the server.
5. Run the Start Service Job (STRSRVJOB) command on the job where the servlet
will run.
6. Enter STRDBG CLASS(myServlet), where myServlet is the name of your servlet.
The source should be displayed.
7. Set a breakpoint in the servlet and press F12.
8. Run your servlet. When the servlet hits the breakpoint, you can continue
debugging.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

190 AS/400 Developer Kit for Java

Chapter 13. Troubleshooting the AS/400 Developer Kit for
Java
If you encounter problems while using the AS/400 Developer Kit for Java, take
any of these steps to determine the source of the problem.
v Find the job log from the job that ran the Java command. Also, look for the job
log from the batch immediate (BCI) job where the Java program ran to analyze
the cause of failure.
v Collect useful data for an authorized program analysis report (APAR).
v Apply program-temporary fixes (PTFs).
v Know how to get support if you detect a potential defect in the AS/400
Developer Kit for Java.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Finding job logs for Java problem analysis

Use the job log from the job that ran the Java command, and the batch immediate
(BCI) job log where the Java program ran, to analyze causes of a Java failure. They
both may contain important error information.

There are two ways to find the job log for the BCI job. You can find the name of
the BCI job that is logged in the job log of the job that ran the Java command.
Then, use that job name to find the job log for the BCI job.

You can also find the job log for the BCI job by following these steps:
1. Enter the Work with Submitted Jobs (WRKSBMJOB) command on the AS/400
command line.
2. Go to the bottom of the list.
3. Look for the last job in the list, called QJVACMDSRV.
4. Enter option 8 (Work with Spooled Files) for that job.
5. A file called QPJOBLOG displays.
6. Press F11 to see view 2 of the spooled files.
7. Verify that the date and time match the date and time when the failure
occurred.
Note:If the date and time do not match the date and time when you signed off,
continue looking through the list of submitted jobs. Try to find a
QJVACMDSRV job log with a date and time that matches when you signed off.
If you are unable to find a job log for the BCI job, one may not have been
produced. This happens if you set the ENDSEP value for the QDFTJOBD job
description too high or the LOG value for the QDFTJOBD job description specifies
*NOLIST. Check these values, and change them so that a job log is produced for
the BCI job.

To produce a job log for the job that ran the Run Java (RUNJVA) command.
1. Enter SIGNOFF *LIST.
2. Then, sign back on.

© Copyright IBM Corp. 1998, 1999 191

 3. Enter the Work with Spooled Files (WRKSPLF) command on the AS/400
command line.
4. Go to the bottom of the list.
5. Find a file named QPJOBLOG.
6. Press F11.
7. Verify that the date and time match the date and time when you entered the
signoff command. Note: If the date and time do not match the date and time
when you signed off, continue looking through the list of submitted jobs. Try to
find a QJVACMDSRV job log with a date and time that matches when you
signed off.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Collecting data for Java problem analysis

To collect data for an authorized program analysis report (APAR):
1. Include a complete description of the problem.
2. Save the Java class file that caused the problem while running.
3. You can use the SAV command to save objects from the integrated file system.
You may need to save other class files that this program needs to run. You may
also want to save and send in an entire directory for IBM to use when trying to
reproduce the problem, if necessary. This is an example of how to save an
entire directory.
Example:
SAV DEV('/QSYS.LIB/TAP01.DEVD') OBJ(('/mydir'))

If possible, save the source files for any Java classes that are involved in the
problem. This is helpful to IBM when reproducing and analyzing the problem.
4. Save any service programs that contain native methods that are needed to run
the program.
5. Save any data files that are needed to run the Java program.
6. Add a complete description of how to reproduce the problem. This should
include:
v The value of the CLASSPATH environment variable.
v A description of the Java command that was run.
v A description of how to respond to any input that is required by the
program.
7. Include any vertical licensed internal code (VLIC) logs that have occurred near
the time of failure.
8. Add the job log from both the interactive job and the BCI job where the Java
virtual machine was running.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

192 AS/400 Developer Kit for Java

Getting support for the AS/400 Developer Kit for Java
Support services for the AS/400 Developer Kit for Java are provided under the
usual terms and conditions for AS/400 software products. Support services include
program services, voice support, and consulting services. Use the online

information that is provided at IBM AS/400 Home Page under the topic
“Support” for more information. Use IBM Support Services for 5769-JV1 (AS/400
Developer Kit for Java). Or, contact your local IBM representative.

You may, at IBM direction, be required to obtain a more current level of the
AS/400 Developer Kit for Java to receive Continued Program Services. For more
information, see support for multiple Java Development Kits (JDKs).

Resolving defects of the AS/400 Developer Kit for Java program are supported
under program services or voice support. Resolving application programming or
debugging issues are supported under consulting services.

The AS/400 Developer Kit for Java application program interface (API) calls are
supported under consulting services, unless:
1. It is clearly a Java API defect as demonstrated by re-creation in a relatively
simple program.
2. It is a question that asks for documentation clarification,
3. It is a question about the location of samples or documentation.
All programming assistance is supported under consulting services. This includes
the program samples that are provided in the AS/400 Developer Kit for Java
licensed program (LP) product. Additional samples may be available on the

Internet at IBM AS/400 Home Page on an unsupported basis.

The AS/400 Developer Kit for Java LP provides information about solving
problems. If you believe that there is a potential defect in the AS/400 Developer
Kit for Java API, a simple program that demonstrates the error is required.

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

Chapter 13. Troubleshooting the AS/400 Developer Kit for Java 193
194 AS/400 Developer Kit for Java
Chapter 14. Code examples for the AS/400 Developer Kit for
Java
CL Commands:
v CRTJVAPGM
v CHGJVAPGM
v RUNJVA
v DLTJVAPGM

v DMPJVM
v DSPJVAPGM
Other Programming Languages:
v Calling another Java program
v Calling a CL program
v Calling a CL command
v Input and output streams
v Sockets
v Calling Java from C
v Calling Java from RPG
v Invocation API
JDBC:
v Connecting
v Statement interface
v PreparedStatement interface
v CallableStatement interface
v ResultSet interface
v DatabaseMetaData interface
v JDBC application
v Embedding SQL Statements
SQLJ:
v Embedding SQL Statements in your Java application
Remote Abstract Window Toolkit:
v Setting up Remote AWT
Secure sockets layer:
v Socket factories
v Server socket factories
v Secure sockets layer
v Secure sockets layer server
Internationalization:
v DateFormat
v NumberFormat
v ResourceBundle

© Copyright IBM Corp. 1998, 1999 195

 Performance tools:
v Java Performance Data Converter

[ Information Center Home Page | Feedback [ Legal | AS/400 Glossary ]

]

196 AS/400 Developer Kit for Java




Printed in U.S.A.