enterprise toolkit for os/390 · getting started with the building of java executables .....81...

IBM VisualAge® for Java™, Version 3.5

Enterprise Toolkit for OS/390

��

Edition notice

This edition applies to Version 3.5 of IBM VisualAge for Java and to all subsequent releases and modifications untilotherwise indicated in new editions.

© Copyright International Business Machines Corporation 1997, 2000. All rights reserved.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Note!Before using this information and the product it supports, be sure to read the generalinformation under Notices.

Contents

Chapter 1. Enterprise Toolkit for OS/390 1Release compatibility . . . . . . . . . . . 1ET/390 limitations . . . . . . . . . . . . 2OS/390 Java development on the host . . . . . . 3OS/390 Java development at the workstation . . . 4OS/390 Java development differences on the hostand at the workstation . . . . . . . . . . . 4

Chapter 2. Working in the IntegratedDevelopment Environment. . . . . . . 7ET/390 properties . . . . . . . . . . . . 7Inheritance of ET/390 properties. . . . . . . . 8

Chapter 3. OS/390 Java programobjects. . . . . . . . . . . . . . . 11OS/390 Java executables and Dynamic LinkLibraries . . . . . . . . . . . . . . . 11OS/390 Java executables . . . . . . . . . . 11OS/390 Java Dynamic Link Libraries (DLLs) . . . 12Resource files in Java executables or DLLs . . . . 14Naming and placement of OS/390 Java DLLs onHFS . . . . . . . . . . . . . . . . . 15OS/390 UNIX run-time CLASSPATH searches forJava DLLs . . . . . . . . . . . . . . . 16Supplied Version 3.0 classes . . . . . . . . . 18

Chapter 4. Building OS/390 Javaexecutables and DLLs . . . . . . . . 19OS/390 Java incremental rebinding . . . . . . 19Building OS/390 Java executables and DLLs with .oFiles . . . . . . . . . . . . . . . . . 20Selectively include and exclude classes for OS/390bytecode binding . . . . . . . . . . . . 22Scenarios: Building OS/390 Java applications . . . 23

Chapter 5. OS/390 Java CICS/ESAsupport . . . . . . . . . . . . . . 27

Chapter 6. Writing OS/390 Javaapplications . . . . . . . . . . . . 31RRBC considerations for interpreted Java andOS/390 program objects . . . . . . . . . . 31Verifying the input bytecode. . . . . . . . . 33Writing OS/390 JNI applications . . . . . . . 33

OS/390 JNI support for native methods . . . . 33Use of Java types double and float (OS/390) . . 34Use of OS/390 double, float (OS/390) . . . . 35Use of Java BigInteger and BigDecimal (OS/390) 36Use of va_list (OS/390) . . . . . . . . . 37Codepage considerations for string literals innative methods (OS/390) . . . . . . . . . 37Long long data type support (OS/390) . . . . 38

Unicode and EBCDIC conversions in Java and C(OS/390) . . . . . . . . . . . . . . 40Character arguments passed toJNI_CreateJavaVM . . . . . . . . . . . 41

Chapter 7. Setting up the environment 43Setting up and using the ET/390 feature. . . . . 43Setting up the Open Edition environment . . . . 44Troubleshooting installation . . . . . . . . . 45Getting F1 Help for the ET/390 properties windows 47Replacing the precompiled Version 2 classes . . . 47

Chapter 8. Building and running Javaapplications in the OS/390 shell . . . . 51Compiling OS/390 interpreted Java applications . . 51Compiling OS/390 interpreted Java for debugging 51Building OS/390 Java executables and DLLs . . . 52

Building OS/390 Java executables on HFS . . . 52Building OS/390 Java executables in PDSEmembers . . . . . . . . . . . . . . 53Building OS/390 Java DLLs on HFS . . . . . 53Building OS/390 Java DLLs in PDSE Members 54Building a Java executable or DLL in two steps 55Binding Language Environment run-time options 57Identifying OS/390 unsupported Java code . . . 57Building Java executables or DLLs for debugging 58

Building Java programs to run under CICS/ESA . . 59Building CICS Java programs on the host . . . 59Defining resources to CICS/ESA to run a newJava executable (OS/390) . . . . . . . . . 59Building OS/390 Java executables in PDSEmembers . . . . . . . . . . . . . . 60Refreshing CICS programs (OS/390) . . . . . 60Building CICS/ESA Java programs for debugging 61

Running interpreted Java in the OS/390 JVM . . . 62Running Java bytecode in the OS/390 JVM . . . 62Debugging Java bytecode in the OS/390 JVM . . 62

Running Java executables and DLLs under OS/390UNIX . . . . . . . . . . . . . . . . 63

Running HFS Java executables in OS/390 UNIX 63Running a Java Executable that is in a PDSEmember . . . . . . . . . . . . . . 64Running HFS Java DLLs in OS/390 UNIX . . . 65Accessing HFS Java DLLs under OS/390 UNIXat run time . . . . . . . . . . . . . 66Accessing PDSE Java DLLs under OS/390 UNIX 67Debugging Java executables and DLLs . . . . 67

Running Java programs under CICS/ESA . . . . 69Running CICS Java programs . . . . . . . 69Accessing Java resource files under CICS . . . 70Preparing the run-time environment to accessJava DLLs under CICS/ESA . . . . . . . . 71Defining resources to CICS/ESA to access a JavaDLL . . . . . . . . . . . . . . . . 71Debugging CICS/ESA Java programs. . . . . 72

© Copyright IBM Corp. 1997, 2000 iii

Chapter 9. Building and running Javaapplications using VisualAge for Java . 75Connecting to OS/390 from VisualAge for Java . . 75

Logging on to OS/390 . . . . . . . . . . 75Adding OS/390 host session. . . . . . . . 75Refreshing the OS/390 host session . . . . . 77Logging off from OS/390 . . . . . . . . . 78Creating projects for OS/390 Java applications. . 78

Building custom JLLs . . . . . . . . . . . 79Building custom JLLs with ET/390 . . . . . 79

Building interpreted Java applications for OS/390 80Compiling OS/390 interpreted Java applications 80Compiling OS/390 interpreted Java fordebugging . . . . . . . . . . . . . . 80

Building OS/390 Java executables and DLLs . . . 81Getting started with the building of Javaexecutables . . . . . . . . . . . . . 81Building OS/390 Java executables . . . . . . 82Building OS/390 Java DLLs . . . . . . . . 83Binding Language Environment run-time options 85Building an OS/390 Java executable or DLL intwo steps . . . . . . . . . . . . . . 85Identifying OS/390 unsupported Java code . . . 86Changing ET/390 properties. . . . . . . . 87Building OS/390 Java executables and DLLs fordebugging . . . . . . . . . . . . . . 87Building OS/390 Java executables and DLLs fortracing . . . . . . . . . . . . . . . 88Binding Java resource files into Java executablesor DLLs . . . . . . . . . . . . . . 89

Building Java programs to run under CICS/ESA . . 89Building Java executables and DLLs to run underCICS/ESA. . . . . . . . . . . . . . 89Building CICS/ESA Java executables and DLLsfor debugging . . . . . . . . . . . . 90

Running OS/390 Java applications from the IDE . . 91Running Java bytecode in the OS/390 JVM . . . 91Debugging Java bytecode in the OS/390 JVM . . 92Running OS/390 Java executables . . . . . . 93Debugging OS/390 Java executables . . . . . 94Tracing OS/390 Java executables and DLLs. . . 95Building Java executables and DLLs using JCL 96

Chapter 10. Overview of OS/390bytecode binder’s JDK support . . . . 99java.lang support under OS/390 UNIX . . . . . 99java.lang support in the CICS/ESA environment 100java.io support in the CICS/ESA environment . . 101java.util.zip support in the CICS/ESA environment 102java.beans support in the OS/390 UNIX andCICS/ESA environments . . . . . . . . . 102JNI support in the OS/390 UNIX and CICS/ESAenvironments . . . . . . . . . . . . . 103Java system properties for OS/390 UNIX . . . . 104

Chapter 11. Commands to build andrun Java program objects . . . . . . 107hpj command (OS/390) . . . . . . . . . . 107hpj Command options . . . . . . . . . . 113

OS/390 hpj command option: -alias=name . . . 113

OS/390 hpj command option:-architecture=0|1|2|3 . . . . . . . . . 114OS/390 hpj command option: -BLIST$type$ 115OS/390 hpj command option: -BXREF$YES |NO$ . . . . . . . . . . . . . . . 116OS/390 hpj command option: -c . . . . . . 116OS/390 hpj command option: -check . . . . 117OS/390 hpj command option: -classpath . . . 118OS/390 hpj command option: -collapse . . . . 119OS/390 hpj command option: -comment=string 121OS/390 hpj command option: -compress . . . 121OS/390 hpj command option: -d path . . . . 121OS/390 hpj command option: -exclude=name |-include=name . . . . . . . . . . . . 123OS/390 hpj command option: -jll | -exe . . . 124OS/390 hpj command option: -follow . . . . 125OS/390 hpj command option: -g=[hook |nohook] . . . . . . . . . . . . . . 126OS/390 hpj command option: -help . . . . . 127OS/390 hpj command option: -inlrpt . . . . 127OS/390 hpj command option:-lerunopts=“string” . . . . . . . . . . 128OS/390 hpj command option: -list=[offset |nooffset] . . . . . . . . . . . . . . 129OS/390 hpj command option: -main=classname 130OS/390 hpj command option: -make . . . . 131OS/390 hpj command option: -maxmem=size 131OS/390 hpj command option: -O . . . . . . 132OS/390 hpj command option: -o=name . . . . 133OS/390 hpj command option: -partial=name . . 134OS/390 hpj command option: -resource . . . 135OS/390 hpj command option: -spill=size . . . 138OS/390 hpj command option: -stub . . . . 138OS/390 hpj command option: -t=dir . . . . . 139OS/390 hpj command option: -target . . . . 140OS/390 hpj command option: -tran . . . . . 141OS/390 hpj command option: -tune=0|1|2|3 143OS/390 hpj command option: -verbose . . . . 144OS/390 hpj command option: -v . . . . . . 144OS/390 shell command syntax to run HFS Javaexecutables . . . . . . . . . . . . . 145hpjava command (OS/390) . . . . . . . . 146

Chapter 12. Run-time options andenvironment variables . . . . . . . 149OS/390 Language Environment run-time options 149OS/390 bytecode binder and Java run-timeenvironment variables . . . . . . . . . . 150Improving performance by specifying environmentvariable options . . . . . . . . . . . . 151Applications targeted for IMS . . . . . . . . 152

Chapter 13. jport utility . . . . . . . 153

Chapter 14. ET/390 Java Install Datafile . . . . . . . . . . . . . . . . 157Specifying the host codepage and workstationcodepage in the ET/390 Java install data file . . . 158

iv ET/390

Chapter 15. hpj command options inET/390 properties . . . . . . . . . 161

Chapter 16. Specifying the DLL searchorder when using System.loadLibrary() . . . . . . . . . . . . . . . . . 165

Chapter 17. Euro-currency support 167

Chapter 18. Run-time errors . . . . . 169

Chapter 19. Troubleshooting Exportand Bind, Run Executable and DebugEx operations . . . . . . . . . . . 171

Chapter 20. MVS batch support . . . 173

Chapter 21. High-performancecompiler programming APIs . . . . . 177

Chapter 22. Samples . . . . . . . . 191Example JNI: Java calling C native method and Ccalling Java method . . . . . . . . . . . 191Example JNI_JVM: C program invoking JVM and aJava method. . . . . . . . . . . . . . 192Example JNIETYPES: Java program calling Cfunction and passing different emulated datatypes . . . . . . . . . . . . . . . . 192

Notices . . . . . . . . . . . . . . 193

Programming interface information 195

Trademarks and service marks . . . . 197

Contents v

vi ET/390

Chapter 1. Enterprise Toolkit for OS/390

VisualAge for Java, Enterprise Edition for OS/390 includes the Enterprise Toolkitfor OS/390 (ET/390) which allows you to quickly and easily develop enterpriseapplications in Java. With this powerful tool, you can code Java programs at theworkstation and export your code to run in a remote OS/390 Java Virtual Machine(JVM). Furthermore, if you want to improve the performance of your Java code forthe OS/390 environment, you can use ET/390 to bind your Java bytecode intooptimized object code to run under OS/390 UNIX System Services. The fullybound object code runs as an executable or DLL in the OS/390 shell. In general,object code runs significantly faster than the bytecode in a JVM or Just-In-Time(JIT) environment. In addition to writing Java applications for OS/390 UNIX, youcan also write your enterprise’s CICS applications in Java because ET/390 alsobinds Java bytecode into object code to run under CICS/ESA.

ET/390 not only provides additional functionality, but it also supplies acomprehensive suite of development tools. ET/390 extends the VisualAge for Javatool set by including an interactive debugger and the Performance Analyzer. Thedebugger lets you debug your Java bytecode as it runs in the OS/390 JVM, as wellas your Java object code as it runs in the OS/390 shell or under CICS/ESA. Thedebugger’s graphical user interface at the workstation lets you step through yoursource code and/or change the contents of memory, variables, registers, and thestack. The Performance Analyzer complements the debugger by allowing you totake a trace of the Java object code as it runs in the OS/390 shell. You can usegraphical and textual diagrams at the workstation to analyze the complete historyof method calls captured in the trace file and identify parts of the Java code thatyou may want to tune.

Java development on the host (OS/390)OS/390 Java development at the workstationIntroducing the Performance AnalyzerOS/390 Java executables and Dynamic Link Libraries

Release compatibilityWhen using the current version of the high-performance compiler, note thefollowing:v This release of the high-performance compiler contains performance

improvements and changes in functionality which result in changes to thecompiler. Applications compiled with an earlier version of the high-performancecompiler will no longer be compatible with the latest version of the Javarun-time library, and must be recompiled with the latest version of thehigh-performance compiler.

v The Integrated Development Environment (IDE) in VisualAge for Java, Version3.5, is at the Java 1.2 level. The high-performance compiler on the S/390 host isat the Java 1.1 level. Due to these discrepancies in the JDK levels, werecommend that users of the high-performance compiler use Version 3.0x ofVisualAge for Java, which is based on JDK 1.1.7. Refer to the related referencesat the bottom of this page for further details.

© Copyright IBM Corp. 1997, 2000 1

v Certain methods exist in both JDK1.2.2 and JDK1.1.8 and have the samesignature, but are implemented differently. Classes using such methods willcompile properly in both enviroments, but might have different behaviors at runtime. This means that if you develop your code in VisualAge for Java, Version3.5, at the Java 2 level, and your code runs in a certain way inside the IDE, youcannot be sure that it will have the same behavior when running in thehigh-performance compiler or the JVM on the S/390 at the Java 1.1.8 level.

These kind of problems cannot be detected by the jport utility. For moreinformation about incompatibilities between the two JDK levels, go to this Website: http://java.sun.com/products/jdk/1.2/compatibility.html.

v The following interfaces support types that are new in the Java 2 SDK:– java.sql.ResultSet– java.sql.CallableStatement– java.sql.PreparedStatement– java.sql.Connection

Source code that implements these interfaces and compiles correctly in the Java2 SDK will fail to compile under JDK 1.1 because the new types added tojava.sql are not present in the JDK 1.1 release. This means that you cannot usethese interfaces if you develop applications in a Java 2 environment but deploythem in a Java 1 environment, eventhough the interfaces are also in JDK 1.1.

Enterprise Toolkit for OS/390ET/390 LimitationsOS/390 Java development on the hostOS/390 Java development at the workstationOS/390 Java development differences on the host and at the workstation

jport utility

ET/390 limitationsThis section describes ET/390 limitations.

IDE exporting to NFS mounted drivesWhile exporting files to an NFS mounted drive using the ET/390 Export and Bindaction, you may experience intermittent problems with the export portion of theaction. This is caused by a known problem with the VisualAge for Java IDEexporting to NFS mounted drives. When it happens, just retry the operation.

Remote building, running and debugging of Java applicationsThe ET/390 Export and Bind, Run Executable, Debug Executable, Run Main, andDebug Main actions from the VisualAge for Java’s IDE performs remote executionson the OS/390 host. To achieve this, a command file is sent via FTP to the host forexecution. There is a known intermittent problem in that the FTP operation is notsynchronous and may result in error messages such as /tmp/useridbind.cmd:FSUM7351 not found in the VisualAge for Java Log. When this happens, just retrythe operation.

JDK classes.zip fileThe JDK classes.zip file shipped as part of the high-performance compiler does not

2 ET/390

contain all the classes included in the JVM classes.zip file. In particular, thesun.tools.* classes are not complete. You can obtain these classes from othersources, such as the JVM/390 classes.zip file.

Resource filesResource files which are contained in .zip or .jar files are not accessible fromcompiled Java. The workaround is to use resource files as flat files: that is, removethem from the .jar or .zip files, and then specify their location on the CLASSPATH.

ET/390 propertiesInheritance of ET/390 properties

Changing ET/390 properties (IDE)Running OS/390 Java executables (IDE)Debugging OS/390 Java executables (IDE)

OS/390 Java development on the hostBesides running interpreted Java in the OS/390 JVM, you can use VisualAge forJava’s Enterprise Toolkit for OS/390 (ET/390) to bind Java bytecode into Javaexecutables or DLLs that run in the OS/390 UNIX or CICS/ESA environments. TheJava bytecode files can be produced using VisualAge for Java, or by using thejavaccommand in the OS/390 shell or on other systems. The following commandsare used in an OS/390 shell to build and run Java executables and DLLs on thehost:v hpj command

Takes Java bytecode files and binds them into Java executables or DLLs that rununder OS/390 UNIX or CICS/ESA.

v hpjava commandLoads and runs (non-CICS) Java DLLs that have main methods.

Commands are not required to run Java executables.

Enterprise Toolkit for OS/390OS/390 Java development at the workstationOS/390 Java development differences on the host and at the workstation

Compiling OS/390 interpreted Java applicationsBuilding OS/390 Java executables on HFSBuilding OS/390 Java DLLs on HFSBuilding OS/390 Java executables in PDSE membersBuilding OS/390 Java DLLs in PDSE membersSetting up and using the ET/390 FeatureSetting up the Open Edition environment

hpj commandhpjava commandOS/390 shell command syntax to run HFS Java executable

Chapter 1. Enterprise Toolkit for OS/390 3

OS/390 Java development at the workstationInterpreted Java running in the OS/390 JVMWith VisualAge for Java, you can build Java applications on the workstation andremotely run them in the OS/390 JVM. Simply create a project for your Javaapplication in the VisualAge for Java IDE and select the run main action to run theJava code in the JVM at the workstation or remotely in the OS/390 JVM.

Fully bound OS/390 Java program objectsThe Enterprise Toolkit for OS/390 (ET/390) allows you to build and run fullybound Java program objects in the OS/390 UNIX and CICS/ESA environments. Byinvoking the ET/390 export and bind action on your VisualAge for Java project,you send class files to the OS/390 host session to bind them into executable code.Resource files may also be exported and bound into the DLL or executable. Systemand error messages are reported back at the workstation’s VisualAge for Javaconsole. You can also specify that the system verifies the portability of your Javacode for the OS/390 UNIX and CICS server environments.

After binding the application, you can select ET/390 run executable action to runthe Java executable remotely in an OS/390 shell. Bind options and LanguageEnvironment run-time options can be set at the workstation and sent to the host.Remote debugging and tracing of the Java application is also available.

Java development on the host (OS/390)OS/390 Java development differences on the host and at the workstationOS/390 Java executables and Dynamic Link Libraries

Compiling OS/390 interpreted Java applicationsGetting started with the building of OS/390 Java executablesBuilding OS/390 Java DLLs

OS/390 Java development differences on the host and at theworkstation

Because of interface and tool differences for Java application development in theOS/390 shell and the VisualAge for Java’s Integrated Development Environment(IDE), the level of support that is available when you build your Java applicationsunder these two environments are not the same. Here are some of the differences:v Some options for the hpj command cannot be selected or specified in the

ET/390 properties panels at the workstation. Also there may be defaultdifferences for the options in the ET/390 properties panels and the hpjcommand’s options in the OS/390 shell. See hpj command options in ET/390properties for more information on these defaults.

v When working with VisualAge for Java projects, you cannot build Javaexecutables or DLLs from classes that belong to different packages.

v When working in the VisualAge for Java IDE, if you do not specify a name forthe HFS Java executable or DLL that you are building, a default name based onthe package name is provided.

4 ET/390

v If you select Bind run-time optionsin the VisualAge for Java ET/390 properties’Bind Options panel, all the Language Environment run-time options specified inthe Run-Time Options, Advanced Run-Time Options, Debugging Options, andTracing Options panels are bound.

v If you decide to build your Java application in two steps, that is generate all thepartially bound program objects (.o, .ro, .mo files) in the first step and then, inanother step, bind these objects into a Java executable or DLL, you can onlyperform the second step natively on OS/390.

v You cannot invoke CICS Java programs from the VisualAge for Java IDE.v You cannot run the hpjava command in an OS/390 shell from the workstation.

Enterprise Toolkit for OS/390Java development on the host (OS/390)OS/390 Java development at the workstationET/390 properties

hpj commandhpjava command-resource

Chapter 1. Enterprise Toolkit for OS/390 5

6 ET/390

Chapter 2. Working in the Integrated DevelopmentEnvironment

ET/390 propertiesYou can use the VisualAge for Java Integrated Development Environment (IDE) todevelop Java applications to run in the OS/390 UNIX or CICS/ESA environments.To let you control the Enterprise ToolKit for OS/390 (ET/390) actions that youwant to perform, every object (project, package, class) has its own set of ET/390properties. The panels in ET/390 properties allow you to set the bytecode binderoptions, Language Environment run-time options, OS/390 environment variables,and java command options so that the following ET/390 actions can besuccessfully performed at the host:v Export and bind Java bytecode into an OS/390 Java executable or DLLv Run the OS/390 Java executable (optionally with tracing) in the OS/390 shellv Run Java bytecode in the OS/390 JVMv Debug the OS/390 Java executable as it runs in the OS/390 shellv Debug the Java bytecode as it runs in the OS/390 JVM

ET/390 properties contain the following panels:v Export and Bind Session

Provides general information for the ET/390 export and bind action.– Bind Options

Provides bytecode binder options to build the OS/390 Java executable or DLLon the host.

– Advanced Bind OptionsProvides additional bytecode binder options to build the OS/390 Javaexecutable or DLL on the host.

v Run Executable SessionProvides general information for ET/390 run executable and debug executableaction.– Run-Time Options

Provides Language Environment run-time options when running ordebugging the Java executable in the remote OS/390 shell.

– Advanced Run-Time OptionsProvides additional Language Environment run-time options when runningor debugging the Java executable in the remote OS/390 shell.

– Debugging OptionsProvides Language Environment run-time options for debugging the OS/390Java executable as it runs in the remote OS/390 shell.

– Tracing OptionsProvides Language Environment run-time option and environment variablesettings for tracing the OS/390 Java executable as it runs in the remoteOS/390 shell.

v Run Main SessionProvides general information for ET/390 run main action.– Run-Time Options

Provides java command options when running interpreted Java in the OS/390JVM.


If you do not change the ET/390 properties for the selected object, its settings areinherited from the parent object. See the details on the inheritance of properties inthe related topics.

Sets of ET/390 propertiesEvery project, package, or class object has a set of ET/390 properties for each hostsession. Each set of ET/390 properties has two versions, a development version anda production version. You can, therefore, pre-set and save two versions of ET/390properties for the object for a particular host session and simply select (in theET/390 Session panels) which version to use for your ET/390 bind, run, anddebug actions.

OS/390 Java development at the workstationInheritance of ET/390 properties

Getting F1 Help for the ET/390 properties windowsGetting started with the building of OS/390 Java executables

hpj command options in ET/390 properties

Inheritance of ET/390 propertiesEvery project, package, and class object in the VisualAge for Java IDE has its ownET/390 properties which allow you to specify ET/390 bind, run, and debugoptions. When you create a project with packages and classes, you will often setthe ET/390 properties for a host session either at the project level or the packagelevel. If you do not change the object’s ET/390 properties (no customization), theseproperties are inherited from the object to which it belongs. For example, if you donot modify the ET/390 properties of all the class objects for host sessionAKYS1234, then their properties are inherited from the ET/390 properties of theirpackage for the same host session; similarly unmodified ET/390 properties of thepackages are inherited from the ET/390 properties of their projects for the samehost session. The options are inherited from the options in the same host sessionand version (production or development); that is, production properties inheritfrom production properties and development properties inherit from developmentproperties. Icons appear in the ET/390 Properties’ tree (left side of the window) toindicate if there are customized (modified) versions of properties for each panel.The icons are as follows:v

Indicates that this panel is inheriting properties from its parentv

Indicates that this panel is using the local (customized) copy of properties

These icons indicate which version of the properties will be selected for ET/390actions.

8 ET/390

To help you quickly reset a version of your ET/390 properties to the parent’sdefault settings, you can click the

Default to Parent/Use Local button at the bottom of each ET/390 properties panel.Click the button to toggle between the default settings and your customizedsettings. The setting of this switch only affects the version of options (developmentor production) that you are working on. You know which version you are workingon by looking at the Development and Production radio buttons at the top of eachpanel.

OS/390 Java development at the workstationET/390 properties

Getting started with the building of OS/390 Java executables


Chapter 2. Working in the Integrated Development Environment 9

10 ET/390

Chapter 3. OS/390 Java program objects

OS/390 Java executables and Dynamic Link LibrariesThe OS/390 bytecode binder generates fully bound OS/390 program objects whichare:v Java executables

orv Java dynamic link libraries (DLLs).

These Java program objects run in an OS/390 shell or under CICS/ESA. The JDKcore packages for the OS/390 environment are shipped as Java DLLs.

OS/390 Java CICS/ESA supportScenarios: Building OS/390 Java applications

OS/390 bytecode binder’s JDK 1.1.6 support

OS/390 Java executablesOS/390 Java executables are sometimes referred to as extended text decks or loadmodules. They are also fully bound program objects. All references to JDK classes arerun-time Java DLL calls. You cannot build statically bound modules.

Class with a main method is requiredIn a Java executable, there must be at least one class that contains a main method.If there is more than one class with a main method, specify which class should beused as the entry point when you are building the Java executable. If you do notspecify the entry point, the input class files followed by the dependency list ofclasses are searched for a main method and the first class containing a mainmethod is used as the entry point.

Placement and naming of Java executablesAll Java executables must reside either on HFS or in PDSE members. Note:Javaexecutables or DLLs that run in the CICS environment must reside in PDSEmembers. The HFS Java executable can have any file name with or without a fileextension, for example, helloWorld. If a name is not specified for the Javaexecutable when binding the module, it is named a.out in the current directory.

Finding the Java executable at run timeWhen running a Java executable in an OS/390 shell, the PATH environmentvariable is used to locate the module. If the executable is in a PDSE member, theSTEPLIB is used to locate the Java executable running under OS/390 UNIX andthe DFHRPL concatenation is used to locate the Java executable running underCICS/ESA.

Finding Java resources at run timeJava resources are found using the CLASSPATH environment variable. If a givenresource has been bound into an executable using the high-performance compiler,symbolic or external links will be used to locate the resource. These links are


generated by the high-performance compiler at compile time and placed in auser-specified directory. The user must include this directory in the run-timeCLASSPATH. External links to resources are created for executables in PDSEs,otherwise symbolic links are generated.

OS/390 Java executables and Dynamic Link LibrariesOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applications

Building OS/390 Java executables on HFSBuilding OS/390 Java executables in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsBuilding CICS Java programsRunning HFS Java executablesRunning a Java executable that is in a PDSE memberGetting started with the building of OS/390 Java executables (IDE)Running OS/390 Java executables and DLLs (IDE)

OS/390 Java Dynamic Link Libraries (DLLs)An OS/390 Java dynamic link library (DLL) is a collection of the methods andvariables from one or more Java classes in a module that is dynamically run whenaccessed from a separate application module. Usually you would build a Java DLLfor classes in a single package, but if you wish to, you can build one that containsclasses from several Java packages. A Java DLL can also have main methods. Torun a Java DLL as an executable, use the hpjava command.

JDK packagesThe JDK core packages for the OS/390 and CICS/ESA environments are shippedas Java DLLs. Although your Java applications use these JDK classes, they are notbound with your Java executables and DLLs; therefore, the JDK DLLs are requiredat run time, they are a part of the Java run-time library.

Nonlocal references to Java classesA Java DLL can include classes from one or more packages. At run time, a Javaapplication may reference Java methods and variables that are in another JavaDLL. An example is a reference to one of the JDK classes. When there is areference to a Java class that is not in the Java executable or DLL that is running,we call this a nonlocal reference.

Invoking Java DLLsIn a Java application, nonlocal method and variable references to Java DLLs areresolved dynamically at run time. All references to JDK classes invoke the JDKDLLs. The loading of Java DLLs from another Java object module is implicit; theuser does not have to code explicit instructions to load the Java DLLs. The systemis able to resolve the nonlocal references and load the modules without the use ofdefinition side decks.

OS/390 UNIX: Finding Java DLLs at run timeAt run time, when there is a nonlocal reference to a class, the system uses theclass’s Java package name to find the DLL. It first searches the loaded Java

12 ET/390

modules. If the required Java DLL is not found, the paths in the CLASSPATHenvironment variable are used together with the Java package names to locate theDLL.

If you have built your Java DLL into a PDSE member, you need to specify anexternal link from the HFS file system to the PDSE member so that the Java runtime will locate the Java DLL when searching for the DLL. See the related conceptsfor details about run-time CLASSPATH searches for Java DLLs.

OS/390 UNIX: Finding Java resources at run timeJava resources are also found using the CLASSPATH environment variable. If agiven resource has been bound into an executable or DLL using thehigh-performance compiler, symbolic or external links will be used to locate theresource. These links are generated by the high-performance compiler at compiletime and placed in a userspecified directory. The user must include this directory in the run-timeCLASSPATH. External links to resources are created for executables or DLLs inPDSEs, otherwise symbolic links are generated.

CICS/ESA: Finding Java DLLs at run timeWhen running a CICS Java program and there is a nonlocal reference to a class,the system uses the class’s Java package name to find the DLL. All referenced JavaDLLs in the CICS/ESA environment must reside in PDSE members. The loadedJava modules and then the PDSEs that are listed in the DFHRPL concatenation aresearched. Alias names for the PDSE members are used to find the required DLL.Once the Java DLL for the package is found, the system searches the DLL for therequired class.

Sometimes CICS Java applications access Java resource files. Before these resourcefiles can be used under CICS, they must either be bound with the Java executablethat uses them, or they must be built into a Java DLL in a PDSE member. See the-resource option for more information on creating resource Java DLLs.

HFS Java DLLsYou must explicitly name all your Java DLLs when building your application inthe OS/390 shell. An HFS Java DLL must have the file extension, .jll. See relatedconcepts for more information on naming Java DLLs. HFS Java DLLs are notaccessible in the CICS/ESA environment.

Java DLLs in PDSE membersJava DLLs can be written to PDSE members. Java DLLs that run in the CICSenvironment must reside in PDSE members. Alias names are required for JavaDLLs that reside in PDSE members. See related concepts for more information onnaming and placement of Java DLLs in PDSE members.

hpjava commandYou can run a non-CICS Java DLL in an OS/390 shell by using the hpjavacommand. You specify a class name with the command, for example:hpjava abc.staff.queryDB.queryMain

The system expects that the specified class contains a main method with thefollowing signature:public static void main (String argv[])

See related references for more information on running Java DLLs.

Chapter 3. OS/390 Java program objects 13

Naming and placement of OS/390 Java DLLs on HFSNaming and placement of OS/390 Java DLLs in PDSE membersOS/390 UNIX run-time CLASSPATH searches for Java DLLsOS/390 Java executablesOS/390 Java CICS/ESA support

Building OS/390 Java DLLs on HFSBuilding OS/390 Java DLLs in PDSE membersBuilding CICS Java programsRunning HFS Java DLLsAccessing HFS Java DLLs under OS/390 UNIXAccessing PDSE Java DLLs under OS/390 UNIXRunning CICS Java programsAccessing Java resource files under CICS

hpj commandhpjava command-resource

Resource files in Java executables or DLLsHFS resource files can be built into a Java executable or DLL. You can bind theresource files with Java classes in a Java executable or bind the resources files in aJava DLL, as follows:v Bind the resource files with the Java classes in a Java executable. The -resource

bind option is used to build the Java executable. These resource files are onlyaccessible to the Java executable that contains them and to any Java DLL calledby the Java executable. Other Java executables will not have access to theseproperties.

v Bind the resource files into a Java DLL. The Java DLL can contain Java classes aswell as resource files. The -resource bind option is used in to build this JavaDLL. The bytecode binder automatically generates an alias name for each of theresource files. These resource files are accessible to other Java executables orDLLs running under OS/390 UNIX or CICS/ESA.

Note: See the build scenarios in related concepts for more information on the useof the -resource bind option.

Accessing the resource files in executables or DLLsTo access resource files which have been bound into an executable or DLL usingthe -resource option, do the following:v

Do the following:1. Ensure that the CLASSPATH environment variable is set correctly at run

time. When resources are bound into an executable, you can use the -toptionto create the required external or symbolic links. Use the -t option to specifythe path/directory which will be added to the CLASSPATH at runtime. Inother words, the -toption specifies which directory to create the external orsymbolic links in. If -t is not specified, no links will be created. Alternatively,

14 ET/390

you can create your own links. The -t option also generates a script with thelinks extension which can be run if the links are damaged.

2. Ensure that any executables or DLLs which are located in a PDSE areaccessible in the STEPLIB environment variable. A PDSE which containsresources must be added to the STEPLIB as follows:export STEPLIB=FRED.PDSE.RESDLL:$STEPLIB

v CICS: To access these resource files under CICS/ESA, concatenate the PDSE toDFHRPL and define resources to CICS/ESA for the Java DLL.

OS/390 Java Dynamic Link Libraries (DLLs)OS/390 Java CICS/ESA supportScenarios: Building OS/390 Java applications

Accessing Java resource files under CICS

hpj command-resource-t=dir

Naming and placement of OS/390 Java DLLs on HFSA Java DLL usually contains classes from one Java package. When you arebuilding your Java DLL in the OS/390 shell, you control the naming andplacement of the DLL, and, therefore, you should be aware of the followingconsiderations.

Recommended naming for HFS Java DLLsYou must explicitly name all your Java DLLs when you are building them in theOS/390 shell. All HFS Java DLLs must have .jll file extensions. In general, youshould name the Java DLL with its subpackage name and put it in the directoryone level higher than its class files. For example, if you have a package,abc.staff.queryDB, you should name the Java DLL, queryDB.jll, and place it in theabc/staff directory.

If you are building the HFS Java DLL from the VisualAge for Java IDE, ET/390follows the above recommendation in generating default names for the HFS JavaDLLs. It also, by default, writes the Java DLLs in the directory one level higherthan its class files.

Finding the Java DLL at run timeAt run time when there is a nonlocal reference to a class, the system uses theclass’s Java package name to find the DLL. It first searches the loaded Java DLLs.If the required DLL is not found, the paths in the CLASSPATH environmentvariable are used together with parts of the Java package name to locate the JavaDLL. See related topics for more information on CLASSPATH searches. Once theJava DLL for the package is found, the system searches the DLL for the requiredclass.

ExampleFor example, an executable calls a method in a Java DLL, as follows:abc.staff.queryDB.readDB.getRecord();


If you set the following CLASSPATH environment variable at run time:export CLASSPATH=/home/ts123456

The ET/390 run-time system appends /abc/staff/queryDB.jll to /home/ts123456and looks for the readDB class in /home/ts123456/abc/staff/queryDB.jll.

See related concepts for more information on CLASSPATH searches.

Exceptions to naming and placement of Java DLLsIf there are classes from more than one package in the Java DLL or if you do notname or place the Java DLLs as recommended, you must make sure that theCLASSPATH environment variable is correctly set at run time so that the systemcan find your Java DLLs.

OS/390 Java Dynamic Link Libraries (DLLs)Naming and placement of OS/390 Java DLLs in PDSE membersOS/390 UNIX run-time CLASSPATH searches for Java DLLs

Building OS/390 Java DLLs on HFSRunning HFS Java DLLsAccessing HFS Java DLLs under OS/390 UNIX

hpj command

OS/390 UNIX run-time CLASSPATH searches for Java DLLsWhen running Java programs in the OS/390 UNIX environment, the systemdynamically searches for the required Java DLLs. When there is a nonlocalreference to a class, the system uses the class’s Java package name to find theDLL. It first searches the loaded Java DLLs. If the required Java DLL is not found,the paths in the CLASSPATH environment variable are used to find these DLLs soit is important that you correctly set the CLASSPATH environment variable.

Setting CLASSPATH for HFS Java DLLsIn general, when setting the CLASSPATH for HFS Java DLLs, do not include theJava package name or the Java DLL file name (.jll file) in the paths, for example:export CLASSPATH=/home/user1:.:/Java/dlls:$CLASSPATH

When the run-time system encounters a specified path in the CLASSPATHenvironment variable, it appends the referenced package name to the path to locatethe Java DLL. In the above example, to locate a nonlocal reference to the method,abc.staff.queryDB.readDB.getRecord(), the run-time system appends variations ofthe package name to the path in the following sequence and looks for those DLLfiles:1. /abc.jll2. /abc/staff.jll3. /abc/staff/queryDB.jll

PDSEs in CLASSPATHIf you have built your Java DLL into a PDSE member, you need to specify an

16 ET/390

external link from the HFS file system to the PDSE member so that the Javaruntime will locate the Java DLL when searching for the DLL. In the exampleabove, if the file abc/staff.jll was an external link to a PDSE member, the PDSEmember would have been loaded when this HFS Java DLL was referenced. Youcan use the -t option of the hpj command to specify an external link. Refer to therelated references at the bottom of this page for details.

ZIP files in CLASSPATHYou can build Java DLLs that contain classes from multiple packages. Such JavaDLLs can be easily built by bundling all the .class files for all the packages in aZIP file and specifying the ZIP file with the hpj command. See the scenarios in therelated topics for more information on building Java applications with ZIP files.

Normally, you do not specify file names in the CLASSPATH environment variable,but ZIP files are exceptions. At run time, you can set the CLASSPATH to theinclude ZIP files, and the system uses these ZIP file names to find the Java DLLs.See steps 9 through 12 in the example.

CLASSPATH for Java DLLs built from JAR filesYou can build Java DLLs from JAR files. However, at run time, if you specified aJAR file in the CLASSPATH environment variable, the system ignores it whensearching for Java DLLs.

Example of searches using CLASSPATHThe following example shows how the system uses the CLASSPATH environmentvariable to find Java DLLs at run time.

Assume that you have built a Java DLL that has the following classes:v abc.staff.queryDB.connectDBv abc.staff.queryDB.readDBv abc.staff.queryDB.disconnectDB

Your Java application calls a nonlocal method,abc.staff.queryDB.readDB.getRecord(). The system uses the CLASSPATHenvironment variable to locate the Java DLL that has the class, readDB .CLASSPATH is set as follows:CLASSPATH=/home/user1:.:/home/dev/my.jll:/home/resource.jar:/home/ts123456/your.zip

The system searches for the Java DLL that has readDB class. The loaded Java DLLsare searched first. If the required Java DLL is not found, the system looks for JavaDLLs using the CLASSPATH environment variable in the following sequence:1. /home/user1/abc.jll

2. /home/user1/abc/staff.jll

3. /home/user1/abc/staff/queryDB.jll

4. ./abc.jll

5. ./abc/staff.jll

6. ./abc/staff/queryDB.jll

7. /home/ts123456/your.jll

8. /home/ts123456/your/abc.jll

9. /home/ts123456/your/abc/staff.jll

10. /home/ts123456/your/abc/staff/queryDB.jll

Notes on the example:


1. The system expects that the HFS Java DLL’s file name has a .jll file extension.The first part of the package name is concatenated to the first path in theCLASSPATH environment variable to form the fully qualified file name/home/user1/abc.jll. The system looks for this file and if it exists, it looks forthe class readDB in that file.

2. If the Java DLL cannot be found or if the DLL does not contain the requiredclass, the system continues the search by using parts of the package name as .jllfiles. This can be seen in steps 2-3.

3. The system sequentially uses the paths specified in the CLASSPATHenvironment variable to construct the fully qualified Java DLL file names.

4. When a specific file is specified in the CLASSPATH environment variable, it isused “as is” without any changes. For example /home/dev/my.jll in step 7 isused as specified in CLASSPATH.

5. When a JAR file is specified in the CLASSPATH environment variable, it isignored. For example, the /home/r esource.jar file is not searched after step 7.The JAR file is used to provide resource files at run time. They are not used tosearch for Java DLLs.

6. When a ZIP file is specified in the CLASSPATH environment variable, it is firstused as if it is a .jll file, as in step 8. If the Java DLL file is not found, the ZIPfile name becomes part of the path and the package names of the referencedclass are added to locate the Java DLL, as in steps 9-11.

OS/390 Java Dynamic Link Libraries (DLLs)Naming and placement of OS/390 Java DLLs on HFSNaming and placement of OS/390 Java DLLs in PDSE membersScenarios: Building OS/390 Java applications

hpj command-t=dir

Supplied Version 3.0 classesThe run-time library feature of the high-performance compiler now includesVersion 3.0 classes in the following JAR files:v eablib.jar: contains classes for the run time for Enterprise Access Builder

commands, business objects, terminal type records, and COBOL type recordsv recjava.jar: contains classes for the IBM Record Java library, and C type recordsv ivjdab.jar: contains the classes to access relational data

Replacing the precompiled Version 2 classes

18 ET/390

Chapter 4. Building OS/390 Java executables and DLLs

OS/390 Java incremental rebindingDuring application development, you may rebuild your Java executables and DLLsnumerous times. The Enterprise ToolKit for OS/390 (ET/390) increases yourproductivity by supporting incremental rebinding when you rebuild your Javaexecutables and DLLs to run in the OS/390 UNIX or CICS/ESA environments.With incremental rebinding, the bytecode binder only rebinds the out-of-dateprogram objects and the classes that extend or use them. You will not have toremember all the class dependencies in your Java code, because the bytecodebinder will do this verification for you.

Note: Because the build environment for developing OS/390 Java applications onthe workstation is different from that of the host, different levels of incrementalrebind are available for the two environments. Refer to the related informationsection for more details on OS/390 Java development at the workstation..

The following discussions on incremental rebinding applies to the building ofOS/390 Java program objects using the hpj command in an OS/390 shell.

-follow and -makeWhen you have a complex application with many interdependencies in the classes,you will find that the -make bind option is very handy in rebuilding Javaexecutables and DLLs. The -make option identifies all the outdated and missing .ofiles and forces a bytecode rebinding of these classes. With the -follow option,-make becomes even more powerful, because the bytecode binder also reviews the.o files for the referenced classes to see if rebinds are necessary. The bytecodebinder is intelligent enough to understand the dependency of the classes and doesall the necessary rebinds. The -make option is also more efficient because current.o files are not rebound. Note: Make sure that when you rebuild your Javaexecutable or DLL, you specify the same hpj options as when you originally builtthe module; otherwise you may get unexpected results. See the scenarios in therelated topics for some examples on the use of the -make and -follow options.

-partialWhen you want to replace a few classes in an existing Java executable or DLL andyou know exactly which ones you want to rebind, use the -partial bind option. The-partial=name option forces a bytecode rebinding of classes that have the nameprefix, and the existing Java executable or DLL is refreshed with the new .o file(s).The other program objects remain the same in the module. For example, if youwant to debug one of the classes in a Java executable, you can first build theexecutable with the -nog option and then rebuild the executable with -partial topoint to the class that you want to rebind and, at the same time, specify -g togenerate program hooks for debugging:hpj -o=MyExe MyPackage.Main

hpj -o=MyExe MyPackage.Main -partial=MyPackage.refClass -g

The first hpj command builds MyExe with the default -nog option. The second hpjcommand forces a rebinding of MyPackage.refClass class with the -g option andrebuilds MyExe, replacing MyPackage.refClass with its updated program object.

You cannot specify both -make and -partial in the same hpj command.


OS/390 Java development on the hostOS/390 Java development at the workstationOS/390 Java executables and Dynamic Link LibrariesScenarios: Building OS/390 Java applicationsBuilding OS/390 Java executables and DLLs with .o filesSelectively include and exclude classes for OS/390 bytecode binding

hpj command-follow-make-partial=name

Building OS/390 Java executables and DLLs with .o FilesFor some Java applications, you may choose to first bind all your classes into .ofiles, and then, in a separate step, bind the .o files into a Java executable or DLL.For example, you may want to break the bind into two steps when you want tobind different classes with different options. When you do this, you will bespecifying the .o input files with the hpj command in the second step. You alsohave to specify one .mo file as one of the input files (which is used as the entrypoint) when you are building a Java executable. If you want to bind LanguageEnvironment run-time options to the Java executable, you must also specify the .rofile in the second build step.

Note:You can perform the first part of your build to create the OS/390 .o fileseither using the VisualAge for Java’s ET/390 export and bind action or using thehpj command in the OS/390 shell, but you can only perform the second part ofyour build (that is, binding all the .o files into the executable or DLL) in an OS/390shell using the hpjcommand.

If you are building your Java executable or DLL in two steps, make sure that youspecify all the classes for the Java executable or DLL in all the hpj commands thatare used to generate the .o files. That is, if you use several hpjcommands (so thatyou can specify different bind options) to generate the required .o files, you mustspecify the complete list of classes for the Java executable or DLL in each of thesehpj commands. See the -c option for an example of such a build.

Main methods and .mo files for Java executablesIn the second build step when you bind .o files to create your Java executable, youhave to specify exactly one .mo input file in your hpj command for theexecutable’s build, for example,hpj -o=MyExe Main.mo Main.o refClass.o

Make sure that you include the correct .mo file. The .mo file should be for the classthat you want to establish as the entry point for your Java executable. You cannotspecify the -main option in the second build step when binding the .o files into theJava executable.

Note: .mo files are not used in Java DLL builds.

-lerunopts and .ro files for Java executablesWhen you specify -lerunopts in the hpj command, the system generates a .ro

20 ET/390

object file. The .ro object contains the run-time options that you want to pass to theLanguage Environment run time. When you perform the bytecode binding and theJava executable binding all in one hpj command (that is without the -c option), thesystem automatically binds the .ro file with the other .o files into the Javaexecutable. However, if you decide to do the bytecode binding in one step(creating all the .o files) and then do the object binding into the Java executable inanother step, you should specify the -lerunopts option when you are building the.o file for the main class (specify -main and -lerunopts options in the same hpjcommand) and the .ro file will be generated with the .mo file and other .o files.

Note: -lerunopts cannot be used for DLLs builds.

-resource and .bo filesThe -resource option is used to generate a single program object (resource.bo file)from all the resource files found in the specified ZIP and JAR files that are input tothe hpj command. The resource.bo output file is bound with your Java executableor Java DLL.

In the first bind step when you specify -resource in the hpjcommand, the systemgenerates a .bo object file containing all the resource files from specified JAR orZIP files. This .bo file can be one of the program object files that you specify whenyou are binding .o files into a Java executable or DLL that is written to a PDSEmember, for example:hpj -jll -o=//'FRED.PDSE.LOAD(DLLWRES)'“

/home/ts123456/test/objects/*.*o-alias=abc.staff.queryDB.jll-t=/home/ts123456/test

The .bo file will be included in the Java DLL build. An alias name is specified forthe Java package because Java classes are included in the bind. Alias names for theresource files are automatically generated for you. Links will be createdautomatically due to the -t option being specified.

Finding the .o filesIf you did the bytecode bind with -nocollapse, your Java application’s .o files arespread out in different directories. When you use the hpj command to bind the .ofiles into a Java executable or DLL, you may find it cumbersome to have toindividually specify all the .o files residing in different directories. Therefore, tomake it easier for you to do the build, you should consider using the -collapse and-d options to write all the .o files into a single separate directory. Then, when youbuild the Java executable or DLL, you can use wild card characters to get all the .ofiles from one directory, for example:hpj -exe -o=queryEmp /home/ts123456/test/objects/*.o

/home/ts123456/test/objects/abc.staff.queryDB.queryMain.mo

Specifying options for the .o bindWhen you are using the hpj command to bind .o files into a Java executable orDLL, the options that you may want to use are -t, -jll, -exe, -o, -alias, -BLIST, and-BXREF. The other hpjoptions, for example -main, -lerunopts, -resource, and -g,are not applicable in this situation; they should have been specified with the hpjcommands that were used to generate the .o files.

OS/390 Java development on the hostOS/390 Java executables and Dynamic Link LibrariesScenarios: Building OS/390 Java applications

Chapter 4. Building OS/390 Java executables and DLLs 21

OS/390 Java incremental rebindingSelectively include and exclude classes for OS/390 bytecode binding

hpj command-c-collapse-d=path-lerunopts-main=class-partial=name-resource-t=dir

Selectively include and exclude classes for OS/390 bytecode bindingWhen building Java executables and DLLs, you may find that you want to includeor exclude certain classes in the module. You can use the -include and -excludeoptions together to shortlist the classes that are to be bound. See the descriptionsof the -include and -exclude options to understand how they should be specifiedin the hpj command.

Using -exclude without -includeYou can use the -exclude option without the -include option to exclude specifiedand referenced classes. The following are some examples of excluding classes thathave the abc.staff.queryDB.r prefix:1. hpj -o=queryEmp abc.staff.queryDB.queryMain

-exclude=abc.staff.queryDB.r*

2. hpj -jll -o=../queryDB.jll abc.zip -exclude=abc.staff.queryDB.r*

In the first example, if abc.staff.queryDB.queryMain references classes with theabc.staff..queryDB.r prefix, they will be excluded in the queryEmp executable.Similarly, in the second example, all classes in abc.zip that have theabc.staff.queryDB.r prefix and all referenced class that have this prefix, will beexcluded from the build.

Using -include without -excludeUse the -include option to include more classes in the build, as follows:hpj -o=queryEmp -nofollow -classpath=/home/ts123456/app.zip

abc.staff.queryDB.queryMain-include=abc.staff.queryDB.r*

In the example, queryEmp executable contains abc.staff.queryDB.queryMain classand other classes that have abc.staff.queryDB.r prefix in the app.zip file.

Using -include and -exclude togetherYou may also use the -include and -exclude options together to select the classesthat you want the bytecode binder to process. The sequence of the -include and-exclude options is very important because the options are processed in the orderin which they are specified in the hpj command. Consider the following:hpj -jll -o=/home/ts123456/abc/staff/queryDB.jll

-classpath=/home/ts123456/app/app.zip-include=abc.staff.verifyDB.*

-exclude=abc.staff.verifyDB.read*

22 ET/390

-include=abc.staff.verifyDB.readDB-include=abc.staff.newDB.*

-exclude=abc.staff.newDB.connectDB

In the example, the bytecode binder builds a Java DLL, queryDB.jll from a list ofclasses specified by the -include and -exclude options:1. The bytecode binder processes -include=abc.staff.verifyDB.* on the command

line and adds all the classes in abc.staff.verifyDB package and their referencedclasses (-follow is the default) to the list of files to be bound.

2. Next the bytecode binder processes -exclude=abc.staff.verifyDB.read* on thecommand line and removes all the classes with the prefixabc.staff.verifyDB.read from the list of files to be bound.

3. Then the bytecode binder processes -include=abc.staff.verifyDB.readDB andadds this class to the list of files to be bound. abc.staff.verifyDB.readDB doesnot reference other user classes so no referenced classes are added to the list offiles to be bound.

4. Next, the bytecode binder processes -include=abc.staff.newDB.* on thecommand line and adds all the classes in abc.staff.newDB package and theirreferenced classes to the list of files to be bound.

5. Finally, the bytecode binder processes -exclude=abc.staff.newDB.connectDB andremoves this class from the list of files to be bound.

Read the -include and -exclude option for more information on the use of-classpath and ZIP or JAR files to improve bytecode binding performance.

OS/390 Java development on the hostOS/390 Java executables and Dynamic Link LibrariesScenarios: Building OS/390 Java applicationsOS/390 Java incremental rebindingBuilding OS/390 Java executables and DLLs with .o files

hpj command-classpath=path-exclude=name | -include=name-follow

Scenarios: Building OS/390 Java applicationsThe OS/390 bytecode binder provides the hpj command with many options sothat you can build both simple and complex Java applications. The followingscenarios help you understand the interrelationship between some of these optionsso that you can quickly start to build your own Java applications.1. Scenario I: Build a simple HFS Java executable (page 23)2. Scenario II: Build an HFS Java DLL (page 24)3. Scenario III: Use a JAR or ZIP file to build a Java DLL in a PDSE member (page

25)4. Scenario IV: Build a PDSE Java DLL that contains resource files (page 25)

Scenario IYou want to build a Java executable from a package that has two classes, asfollows:


v MyExe.MainContains the main method, and it references MyExe.refClass.

v MyExe.refClassDoes not reference any other user Java class.

To build the HFS Java executable, use the following hpj command:hpj -make -o=MyExe MyExe.Main

Both classes are bound because -follow option is the default. When the applicationis built for the first time, the -makeoption is not useful, but there is no harm inspecifying it. -exe is the default and the Java executable MyExe is built.

If you subsequently modify MyExe.refClass, you can use the same hpj command torebuild MyExe. This time, the -make option is very useful because it tells thebytecode binder to automatically regenerate any outdated .o files and if a classextends or uses the outdated class, it, too, will be rebuilt. In this example, thebytecode binder regenerates both .o files because MyExe.refClass has beenupdated since the last build, and MyExe.Main references MyExe.refClass.

Scenario IIYou want to build a Java DLL with many classes that are not necessarily related.The classes are as follows:v MyPackage.Readv MyPackage.Writev MyPackage.Utilities

Specifying one class with the hpj command and using -follow will not work inthis build scenario because these classes do not reference each other. You can, ofcourse, specify all three classes on the command line, but a simpler hpj commandcan be used as follows:hpj -jll -nofollow -o=MyPackage.jll

-classpath=MyPackage.zip-include=MyPackage.* -make

You can use multiple -include and -excludeoptions to specify the classes that youwant to bind without using a ZIP file, so long as the -classpathis correctly set tofind the classes. In this example the three classes are zipped into MyPackage.zip.The hpj command builds MyPackage.jll with the three classes. Because you do notwant referenced classes to be included in the DLL, the -nofollow option isrequired.

If subsequently you updated one or two of the classes and you want to rebuildMyPackage.jll with all the updated code, you can use the same hpj command.However, if you want to rebuild MyPackage and only update one of the classes,you should use the -partial option, as follows:hpj -jll -o=MyPackage.jll -include=MyPackage.*

-nofollow -classpath=MyPackage.zip-partial=MyPackage.Write

In this example, MyPackage.jll is rebuilt, and MyPackage.Write class is updated inthe Java DLL. In this rebuild, you simply replace the -make option in the initialbuild with the -partial option. You cannot specify both -make and -partial optionsin the same hpj command. You can specify the -partial option multiple times in asingle hpj command. -partialforces a bytecode rebinding of that class, and it is also

24 ET/390

more efficient than the -make option when you know ahead of time the classesthat you want to rebind. You can also specify the wildcard character (*) in the-partial option.

Scenario IIIYou can specify ZIP or JAR input files in the hpj command. This is appropriatewhen you want to include all the classes in the ZIP or JAR file into the build. Forexample app.jar contains two Java packages, abc.staff.queryDB andabc.staff.verifyDB. To build a Java DLL in the PDSE member, MYPACK, for all theclasses in app.jar, use the hpj command as follows:hpj app.jar -jll -nofollow

-o=“//'FRED.PDSE.LOAD(MYPACK)'”-alias=abc/staff/queryDB.jll-alias=abc/staff/verifyDB.jll-t=.

Alias names are required for Java DLLs written to PDSE members. One alias nameis specified for each Java package that is in the Java DLL. All the classes in app.jarare included in the Java DLL. All resource files in the JAR file are ignored becausethe -resourceoption is not specified. The Java DLL is written to MYPACK inFRED.PDSE.LOAD data set. The -t option must be specified in order to create linksin HFS which use the specified aliases.

If you only want to include a subset of the classes in the ZIP or JAR file, youshould use the -include and -exclude options and specify the ZIP or JAR file not asan input file but as a file in the -classpath option, as follows:hpj -jll -nofollow -o=“//'FRED.PDSE.LOAD(MYDLL)'”

-alias=abc/staff/queryDB.jll-alias=abc/staff/verifyDB.jll-classpath=app.zip:$CLASSPATH-include=abc.staff.*-exclude=abc.staff.verifyDB.r*-t=.

In this example, a subset of the classes in the ZIP file is used in the build. Forexample, if there is a abc.staff.verifyDB.read class in the ZIP file, it would not beincluded in the MYDLL PDSE member. An alias name is specified for each Javapackage.

Scenario IVIf your CICS Java program accesses Java resource files at run time, you must usethe -resource option to migrate your HFS resource files to a Java executable orDLL in a PDSE member. The -resource option applies to resource files that are ineither ZIP or JAR files. Assuming that all your Java bytecode and resource files arein app.jar, you can build the PDSE Java DLL as follows:hpj -jll -o=“//'FRED.PDSE.APP(BUNDLE1)'”

/home/ts123456/app.jar -exclude=* -resource -t=.

-exclude=*excluded all the Java classes from the build. With the -resource option,all resource files in app.jar are bound into a .bo file and built into BUNDLE1. Aliasnames for all the resource files in app.jar are automatically created for you. Followthe steps to set up the PDSE Java DLL for the CICS environment, and your CICSJava programs can access these resource files in BUNDLE1 as if it is any other JavaDLL in a PDSE member.


If the -exclude option was not specified in the example, then all the classes in theZIP file and their referenced classes (-follow is the default) would have beenincluded in the Java DLL. If that is your intention, then specify alias names for allthe Java packages that are in the DLL.

See related concepts for more information on resource files in PDSE members.

OS/390 Java development on the hostOS/390 Java executables and Dynamic Link LibrariesOS/390 Java CICS/ESA supportBuilding OS/390 Java executables and DLLs with .o filesOS/390 Java incremental rebindingSelectively include and exclude classes for OS/390 bytecode bindingResource files in PDSE members

Preparing run-time environment to access Java DLLs under CICS/ESA

hpj command-follow-make-partial=name-resource

26 ET/390

Chapter 5. OS/390 Java CICS/ESA support

You can use VisualAge for Java to develop Java application programs that useCICS services and execute under CICS Transaction Server for OS/390 Release 1.3.You can develop your applications on a workstation or in the OS/390 UNIXSystem Services shell. For more information about developing CICS programs, goto the “CICS Program Development” topic in the Concepts section of this onlineinformation.

ET/390 enables you to write Java programs that run in the CICS/ESAenvironment. These Java programs must be bound into Java executables or DLLsthat reside in PDSE members before they can run under CICS.v CICS Java Programs can be invoked with EXEC CICS LINK(ProgramName)

commands, by an IIOP client, or from devices such as 3270s with a transactionID. These CICS Java programs are Java executables and they may use the CICSJava APIs.

v Java DLLs are referenced by CICS Java programs. They may use the CICS JavaAPIs. The JDK DLLs are examples of Java DLLs.

JDK supportBecause of the nature of OS/390 and CICS applications, some of the JDK packages,classes, and methods are not supported; for example, CICS Java applications donot support multithreading. When you build CICS Java applications in theVisualAge for Java IDE, you can specify that the system Verify the portability ofthe code. Then, as part of the bind process, HTML files listing unsupportedpackages, classes, methods, and fields will be generated for your Java classes. Ifyou build your CICS Java program in an OS/390 shell, you can run the jportutility to verify the portability of your Java code.

CICS Java APICICS provides a Java class library, known as JCICS, supplied in dfjcics.jar. JCICSallows you to access CICS resources and integrate your Java programs withprograms written in other languages. Most of the functions of the CICS EXEC APIare supported.

There is no CICS translator for Java. A CICS Java program is compiled and boundlike any other Java executable.

You can build CICS/ESA Java applications using VisualAge for Java on aworkstation, but you can only invoke them on the host system. You can invoke theCICS transaction on the host system, and then debug the Java program using theremote debugger at the workstation.

Building Java programs to run under CICS/ESAAll Java program objects running in the CICS/ESA environment must reside inPDSE members and you must specify alias names for all these Java DLLs whenyou are building them. See Naming and Placement of OS/390 Java DLLs in PDSEMembers under related concepts for more information on alias names. The PDSEsthat contain Java executables or DLLs must be concatenated to DFHRPL.


You can build CICS/ESA Java applications using VisualAge for Java on aworkstation, but you can only invoke them on the host system. You can invoke theCICS transaction on the host system, and then debug the Java program using theremote debugger at the workstation.

Handling resource files in CICS/ESABefore resource files can be accessed by CICS Java programs, you must migrateHFS resource files to PDSE members. See the related concepts at the end of thispage for more information about resource files in PDSE members.

Setting Java system propertiesSystem properties can be accessed using the System.GetProperty(String s) call.These properties are initialized from the following sources:v The following properties are set with environment variables before running the

CICS Java Program. Environment variables can be set with the ENVARLanguage Environment run-time option. For CICS applications, the hpjcommand’s -lerunopts option allows you to set and bind LanguageEnvironment run-time options with the CICS Java program.– user.language

Set via the environment variables: LC_ALL, LC_CTYPE or LANG.– user.timezone

Set via the environment variable TZ.v CICS task and user-specific property values set during the initialization of the

Java environment for CICS programs. are shown in the following table.

System Property Value

java.version 1.1.6

java.vendor IBM Corporation

java.vendor.url http://www.ibm.com/

java.home null

java.class.version 45.3

java.class.path

os.name OS/390

os.arch 390

os.version CTS 1.3

file.separator /

path.separator :

line.separator

user.dir constant value “ ”

user.home constant value “ ”

user.name “ ”

OS/390 Java executables and Dynamic Link LibrariesNaming and placement of OS/390 Java DLLs in PDSE membersResource files in PDSE members

28 ET/390

Building CICS Java programs on the hostRunning CICS Java programsGetting started with the building of OS/390 Java executablesPreparing run-time environment to access Java DLLsAccessing Java resource files under CICS

Overview of OS/390 bytecode binder’s JDK supportjava.lang support in the CICS/ESA environmentjava.io support in the CICS/ESA environmentjava.beans support in the OS/390 UNIX and CICS/ESA environmentsjava.util.zip support in the CICS/ESA environmentJNI support in OS/390 UNIX and CICS/ESA environmentsjport utility

Chapter 5. OS/390 Java CICS/ESA support 29

30 ET/390

Chapter 6. Writing OS/390 Java applications

RRBC considerations for interpreted Java and OS/390 program objectsRRBC for interpreted JavaWith interpreted Java, you can make changes to your Java classes withoutrequiring the modification of other classes that use your Java code. Consider theclass:class Auto {

Auto(int max) {this.min = 0;this.max = max;

}int maximumSpeed() {

return max;}int minimumSpeed() {

return min;}private int min;private int max;

}

The Auto class can be extended or used by another class, as follows:class Porsche extends Auto {

Porsche() {super(200);

}}

Later, you add new methods and fields to the Auto class and delete some methodsand fields that are not directly referenced. For example, you add a new methodcalled cylinders(), and at the same time delete the method, minimumSpeed(), andthe private variable, min, as follows:class Auto {

Auto(int max) {this.cyls= 4;this.max = max;


return max;}int cylinders() {

return cyls;}private int cyls;private int max;

}

The Porsche class does not have to be rebuilt as a result of these changes to theAuto class because the Java interpreter determines what methods and fields areavailable in a class when the class is loaded.

RRBC for fully bound program objectsHowever, the methods and fields that are available in a class for statically boundJava program objects (executables or DLLs) are determined at bind time. In theabove example, when the Auto class was updated, the Porsche class would alsohave to be rebuilt so as to function correctly. This is required because methods and


fields are mapped to offsets in an object. These offsets will be incorrect when fieldsare added, deleted or moved. These offsets will also be incorrect when methods areadded, deleted or moved.

To develop a statically bound class library with RRBC characteristics, you need toanticipate changes in classes and provide place-holder fields and methods that youmay want to add. Also you should not delete fields and methods in these classes.In the above example, you could have written the Auto class as follows:class Auto {

Auto(int max) {this.min = 0;this.max = max;this.dummy =null;


return max;}int minimumSpeed() {

return min;}private int min;private int max;private Object dummy; /* place holder for the future */

}

The Auto class could then be modified as follows and the Porsche class that uses itwill not have to be rebuilt :class Auto {

Auto(int max) {this.max = max;this.ext = new AutoExtension(4);


return max;}int minimumSpeed() { /* retained for RRBC compatibility */

return min;}private int min; /* retained for RRBC compatibility */private int max;private AutoExtension ext; /* use placeholder object now to add more data */

}class AutoExtension {

AutoExtension(int cyls) {this.cyls = cyls;

}int cylinders() {

return cyls;}private int cyls;

}

OS/390 Java incremental rebinding

Overview of OS/390 bytecode binder’s JDK support

32 ET/390

Verifying the input bytecodeIf you are running the high-performance compiler from the command line, youshould ensure that the bytecode you want to compile is free of errors. You can usetools such as JAVAP to ensure that your bytecode can be compiled successfully.The high-performance compiler will produce unpredictable results from bytecodethat is corrupt or that contains errors.

If you use ET/390 to compile your bytecode, ET/390 checks the bytecode to ensureit can be compiled, so you do not need to check it separately using another tool.

Writing OS/390 JNI applications

OS/390 JNI support for native methodsOS/390 Java executables and DLLs support the new JDK 1.1 Java Native Interface(JNI) for native methods written in C and C++. JavaSoft’s Java Native InterfaceSpecification describes the generic details of this interface for native methodprogrammers. However, OS/390 native method programmers must deal with thefollowing issues:v Use of Java types double and floatv Use of OS/390 double and floatv Use of Java BigInteger and BigDecimalv Use of va_listv Long long data type supportv Codepage considerations for string literals in native methodsv EBCDIC and UNICODE conversions in Java and C

RestrictionsThe following restrictions apply when using JNI:v Java primitive type, long, maps to jlong native type, which is the OS/390 C

integer data type long long. Language Environment Math Library support is notavailable for long long types.

v See related reference information for additional restrictions when using JDKpackages.

Note:There are some implementation differences for JNI native code supportbetween OS/390 Java program objects and interpreted Java running in the OS/390JVM. To understand the JNI support for native code when running interpretedJava, refer to the JNI Support documentation for OS/390 UNIX.

When compiling native C or C++ code, it is required that the JNI header files usedbe those found in the $IBMHPJ_HOME/include directory as opposed to those inthe $JAVA_HOME/include directory. For users who choose to support bothinterpretted and compiled scenarios, two versions of the DLLs will be required.One way to handle this situation is to name the DLL used with the staticallycompiled Java differently. In this way the Java code may be coded to query thesystem property ibmhpj.version and determine which dll to load.

OS/390 Java CICS/ESA support

Chapter 6. Writing OS/390 Java applications 33

Java system properties for OS/390 UNIXJDK JNI support in OS/390 UNIX and CICS/ESA environmentsExample JNI: Java calling a C native method and C calling a Java methodExample JNI_JVM: C program invoking JVM and a Java methodExample JNIETYPES: Java program calling C function and passing different datatypes

Use of Java types double and float (OS/390)The JNI Types and Data Structures section of the JavaSoft Java Native Interface(JNI) Specification describes in detail the mapping of Java types to native C types.However, special emulation of Java double and float types are required for theOS/390 environment.

Native methods may deal with Java double and float types for the followingreasons:v To receive such variables as native method parametersv To inspect or modify such instance or class variables directlyv To return such a variable as the native method return valuev To pass such variables as parameter data when invoking other Java methods

from a native method

Emulated typesOS/390 native methods emulate the Java double and float types using the typenames shown in the following table. The emulation is provided so that theseobjects may be handled as single entities, and, in the case of double and float, toprovide the IEEE 754 standard support required by the Java language.

Type Used in JavaSource

Native MethodParameter Types

Alternative Types Size in Bytes

double jdouble double_t 8

float jfloat float_t 4

Note: You do not have to use these types if your native methods do notmanipulate the Java types, double and float. Also, you could use both theemulated type support, as well as the OS/390 native floating point types, providedyou are careful during coding.

The native method parameter types should be used when defining a nativemethod implementation so that the C/C++ compiler can match the nativemethod’s signature with the signature of the method in the header file that isgenerated with the javah utility. Typedefs are used to map these types to thealternative types (also shown in the above table). However, if you use the jdoubleand jfloat types, you will minimize any future rework should OS/390 providenative support for IEEE 754 float and double types.

There are three principal steps in developing native methods:1. Declare the native method(s) as native in the Java program.2. Generate the dependent header file for the Java program (using javah).3. Compile and link your native method(s) as a DLL.

34 ET/390

The generated header file includes several other headers which are distributedwith the JDK. Among the headers is float_md.h, which enumerates the operationsthat can be performed on variables of each of the emulated types using macrosand function calls.

The emulation support is not automatically available. Specify -DNEEDSIEEE754 tothe C or C++ compiler to select emulated IEEE 754 floating point support andmath library functions.

Note that if your native methods reference any of jdouble, jfloat, double_t, float_ttypes, and you have not specified -DNEEDSIEEE754 when you compile the nativecode, the float_md.h will map these to the OS/390 native double and float,respectively, which might produce unexpected results.

Emulated Floating Point TypesJDK header file float_md.h defines a range of macros and functions, whichtypically include “dbl”, “double”, “flt”, or “float” at the start or the end of themacro or function name. There are also some double_t and float_t constantsdefined. If you have compiled with -DNEEDSIEEE754, jdouble and double_t typesare equivalent, as are jfloat and float_t.

Examples of functions provided by float_md.h

v flt2dbl() takes a jfloat or float_t and returns it as a jdouble or double_t.v dbl2nat() takes a jdouble or double_t and returns it as an ESA/390 native

double.v dbl_sqrt() takes a jdouble or double_t and returns the square root result as a

jdouble or double_t.v dbl2str() and flt2str() convert their arguments into EBCDIC string

representations.

Note: Compared with the standard C/C++ math library set of functions, onlythose required by Java are available through float_md.h. Other standard C/C++math library functions may be used by including math.h in your native methodsource file. Choose the arguments that you use with other standard math libraryfunctions carefully, and, if necessary, convert the results for use by Java.

Example of using the emulated typesThe following coding examples are available with the product:v Java calling a C native method and C calling a Java methodv Java program calling C function and passing different data types

OS/390 JNI support for native methods

Use of OS/390 double and floatUse of Java BigInteger and BigDecimalUse of va_listCodepage considerations for string literals in native methodsLong long data type support

Use of OS/390 double, float (OS/390)At present, OS/390 native floating point support does not represent float anddouble values in the manner described in IEEE Standard for Binary Floating-Point


Arithmetic (ANSI/IEEE Std 754-1985). The OS/390 UNIX C and C++ compilerssupport the float, double, and long double types implemented as 4-byte, 8-byte,and 16-byte storage elements. As well, the binary layout of mantissa and exponentparts differs from the IEEE 754 implementation.

Your native methods can use native float and double types, including the use ofmath functions, provided that you do not pass these values to Java without firstconverting them to associated Java types.

You may want to use some of the following conversion functions provided byfloat_md.h:v tofloat()

Converts native float to jfloat.v flt2nat()

Converts jfloat to native float.v todouble()

Converts native double to jdouble.v dbl2nat()

Converts jdouble to native double.

OS/390 native double and float perform faster than the emulated types becausethey are implemented in microcode rather than application-level code.Consequently, the associated math library functions also performs faster.


Use of Java types double and floatUse of Java BigInteger and BigDecimalUse of va_listCodepage considerations for string literals in native methodsLong long data type supportExample JNI: Java calling a C native method and C calling a Java methodExample JNI_JVM: C program invoking JVM and a Java methodExample JNIETYPES: Java program calling C function and passing different datatypes

Use of Java BigInteger and BigDecimal (OS/390)BigInteger and BigDecimal classes provide arbitrary size variables to Javaprograms. JDK 1.1 JNI provides a wide range of functions to access andmanipulate BigInteger and BigDecimal objects and methods similar to the wayother classes’ objects and methods are accessed and manipulated.


Use of Java types double and floatUse of OS/390 double and float

36 ET/390

Use of va_listCodepage considerations for string literals in native methodsLong long data type support

Use of va_list (OS/390)The JavaSoft Java Native Interface (JNI) provides a range of functions, for exampleCallBooleanMethodV(), to which you can pass the necessary arguments using asingle va_list argument. Two different header files are used to handle va_listarguments: stdarg.h and varargs.h. In your native methods, use the stdarg.h headerfile.

In OS/390 UNIX, there are two different implementations of va_list and theassociated macros va_start(), va_arg(), and va_end(). When you use stdarg.h,compile your native methods without specifying -D_VARARG_EXT_; otherwise,unexpected results will occur.


Use of Java types double and floatUse of OS/390 double and floatUse of Java BigInteger and BigDecimalCodepage considerations for string literals in native methodsLong long data type support

Codepage considerations for string literals in native methods(OS/390)

The Enterprise ToolKit for OS/390 handles strings in both Unicode or UTF-8format. Native methods may deal with these types for the following reasons:v To receive such variables as native method parametersv To inspect or modify such instance or class variables directlyv To return such a variable as the native method return valuev To pass such variables as parameter data when invoking other Java methods

from a native method

The JNI specification describes the types required by each JNI API.

There are two approaches that may be taken when coding the native methods thatpasses string literals to Java methods or to the JVM.

Approach 1Compile your C/C++ program with -CONVLIT (“ISO8859-1”) to convert stringliterals within a compilation unit to ASCII. The -CONVLIT option affects all thesource files that are processed within a compilation unit, including system headerfiles. The rest of the program’s string literals will use what is specified in the-LOCALE option.

Only convert strings to EBCDIC when passing them to any code that requiresEBCDIC, for example, the C Run-Time Library. C library functions __atoe() andiconv() can be used.


The following table shows the format of string literals when using -CONVLIT:

Java Virtual Machine Unicode/UTF-8

Native method ASCII

C Run-Time Library EBCDIC

Approach 2Convert strings to UNICODE/UTF-8 before passing them to Java methods or theJVM.

The following table shows the format of string literals in the differentenvironments:

Java Virtual Machine Unicode/UTF-8

Native method EBCDIC

C Run-Time Library EBCDIC

JNI conversion APIA number of JNI API functions in jni_convert have been provided to help with theconversion of string literals:v GetStringPlatform

Converts a Java string to a null-terminated C string.v GetstringPlatformLength

Returns the length in bytes of the output buffer that would be needed to holdthe converted Java string, including a null terminating byte.

v NewStringPlatformConverts a null-terminated C string to a Java string object.

This support is available by linking the native method with jni_convert.o.

ExamplesThe following code examples demonstrate the use of the jni_convert functions:v Java calling a C native method and C calling a Java methodv EBCDIC and UNICODE conversions in Java and C


Use of Java types double and floatUse of OS/390 double and floatUse of Java BigInteger and BigDecimalUse of va_listLong long data type support

Long long data type support (OS/390)ET/390 uses the C/C++ long long native data type (available in OS/390 Version 2Release 4) when the C/C++ program is compiled with LANGLVL(EXTENDED). Itsupports regular arithmetic and bitwise operations (such as +, -,*x. >>, ==) forjlong or int64_t (long long data types). However, there is no math functionssupport with this data type.

38 ET/390

Note: OS/390 Version 2 Release 4 and 5 have restricted support for long longnative data type.

JVM for OS/390, which runs interpreted Java, has a different implementation oflong long emulation. It uses emulation calls (ll_* functions) defined inlonglong_md.h and you have to compile your C/C++ native code with-DNEEDSLONGLONG. To use the same C and C++ native code with interpretedJava applications on OS/390 and fully bound Java program objects on OS/390, usell_* functions in your C/C++ native code. There is no penalty in performancewhen using ll_* functions. You may want to use some of the conversion functionssuch as ll2str() which converts jlong to EBCDIC strings, and ll_strtoll() whichconverts EBCDIC strings to jlong.

Using the strtoll() functionPrior to Language Environment (LE) V2R9, there is no documented support for thestrtoll() function. Before LE V2R9 provided support for strtoll() function, thehigh-performance compiler provided its own version of strtoll() in the form ofll_strtoll().If you make use of ll_strtoll() and you have an older application (that is, withobjects created prior to the availability of PTF UQ41004), and you rebind youapplication with this PTF, you might encounter the following message during thebind step of your application:IEW2456E 9207 SYMBOL strtoll UNRESOLVED. MEMBER COULD NOT BE INCLUDED FROMTHE DESIGNATED CALL LIBRARY.If you see this message, you need to do one of the following:v Recompile your application with PTF Version 2.4 or later, orv Rebind your application with an additional import card: IMPORT

CODE,HPJDLL,strtoll

To rebind your application, you can take one of two approaches:v Create a sidedeck (.x file) with only the import card, orv Modify the existing HPJDLL.x sidedeck to include that import card

It is better to use the first approach for a couple of reasons. HPJDLL.x sidedeckwill remain untouched and therefore less likely to be damaged in case it wasmodified incorrectly. Additionally, if you decide to use the version of strtoll() fromLE V2R9 and above, there will be no conflict with the version shipped withhigh-performance compiler. The two versions are not functionally identical.To modify or create your own sidedeck, do the following:1. Do not attempt to create or modify the sidedeck under HFS. Always perform

this operation under TSO using the ISPF editor.2. The attribute of the sidedeck must be:

Record Format: FB (Fixed Block)Record Length: 80Block size : 3200

3. To modify HPJDLL.x, do the following:a. Use the oget command to place a copy of HPJDLL.x into a PDS with the

above attributes. Treat the sidedeck as a binary file. For example:oget ’/usr/lpp/hpj/lib/HPJDLL.x’ JAVA.SIDEDECK(HPJDLL) BINARY

b. Add the import statement into the sidedeck. Where you place the importstatement is not important.

c. Use the oput command to restore the modified copy of HPJDLL.x from thePDS back into HFS. For example:oput JAVA.SIDEDECK(HPJDLL) ’/usr/lpp/hpj/lib/HPJDLL.x’ BINARY


4. Rebind your application with the modified sidedeck. This should take care ofthe bind error.


Use of Java types double and floatUse of OS/390 double and floatUse of Java BigInteger and BigDecimalUse of va_listCodepage considerations for string literals in native methodsExample JNI: Java calling a C native method and C calling a Java methodExample JNI_JVM: C program invoking JVM and a Java methodExample JNIETYPES: Java program calling C function and passing different datatypes

Unicode and EBCDIC conversions in Java and C (OS/390)The Java platform uses a 16-bit encoding, Unicode, as its native characterencoding; however, when you build Java applications to run in the OS/390 andCICS/ESA environments, you may want to handle text data in other encodings,particularly EBCDIC. Java provides a set of classes that convert many standardcharacter encodings to and from Unicode. Java programs that deal withnon-Unicode text data will convert that data into Unicode, process the data asUnicode, then convert the result back to the external character encoding. When youhave server applications with mixed Java and C code, you may need to convertdata from one encoding to another and pass data between your Java applicationand the C native code. In such situations, you have a choice of doing the necessaryconversions in the Java code or C code.

Conversion in Java codeThe JDK encoding for EBCDIC is code page1047. See JDK supported encodingsdocumentation for the complete list of supported encodings. If most of your data isin EBCDIC, you can use the default file encoding. Then your data in byte arrayswill be encoding to EBCDIC and the PrintStream class produces output using thesystem’s default character encoding. Conversions are automatically handled andyou can pass EBCDIC data to your native C code.

If you only want to call a few services using EBCDIC data, you can use getBytesmethod to convert a String from Unicode to EBCDIC. Using these methods, youcan convert your data to EBCDIC in your Java program and pass it to the native Ccode.

The following example assumes the EBCDIC file encoding, and it also shows thecreation of a string using a different encoding. unicodeString will contain aUnicode representation of the first parameter passed to main. nativeString willcontain a native (in our case EBCDIC) representation of the first parameter passedto main.public class UnicodeAndNative {

public static void main(String args[]) {String unicodeString = args[0];byte[] nativeString = unicodeString.getBytes();

}}

40 ET/390

Conversion in native C codeIf you choose to pass Unicode to your native C code and do the Unicode toEBCDIC conversions in your C program, the following example shows the Cfunctions that you can use to perform the conversions:#include <jni.h>#include “inoutstr.h”#include <stdio.h>#include <string.h>#include <stdlib.h>#include <jni_convert.h>JNIEXPORT jstring JNICALLJava_inoutstr_inoutstringcall (JNIEnv *env, jobject obj, jstring jstr){

char *s;const char *eretstr = “This string is returned”;jstring jretstr;jint length;jint ret;/* Turn jstring into EBCDIC string */ret = GetStringPlatformLength(env, jstr, &length, 0);if (ret == -2)

return 0;s = (char*) malloc(length);if (s != NULL) {

ret = GetStringPlatform(env, jstr, s, length, 0);printf(“Native method received = %s\n”, s);free(s);

}/* Convert EBCDIC string into Java string */ret = NewStringPlatform(env, eretstr, &jretstr, 0);return jretstr;

}

You can access code examples in example.mvs/jni_convert directory under theinstallation root specified by the IBMHPJ_HOME environment variable.


Character arguments passed to JNI_CreateJavaVMAll Java VM initialization arguments of type character that are passed to thehigh-performance compiler using the JNI_CreateJavaVM invocation (3rd argument)must be passed using ASCII rather than EBCDIC code points. This includesproperties, classpath, etc.


JDK JNI support in the OS/390 UNIX and CICS/ESA environments


42 ET/390

Chapter 7. Setting up the environment

Before you can use ET/390, the following must be set up.

On OS/390

The following must be set up by the host system administrator:v NFS daemon has to be running on OS/390v REXEC daemon has to be running on OS/390v OMVS FTP Server has to be running on OS/390v Write access needs to be set up to the /tmp directory on OS/390v For VisualAge for Java Version 2, the TCP parameter SBDATACONN needs to

be configured on the host to define conversions between EBCDIC and ASCIIcode pages when performing ET/390 Run Executable, Debug Executable, RunMain, and Debug Main actions from the VisualAge for Java’s IntegratedDevelopment Environment. See the OS/390 TCP/IP OpenEdition: ConfigurationGuide for more information about defining this parameter.

On Microsoft Windows NT

For the NFS Client for Windows NT, you need to perform a binary mount for theHFS directory to which class files will be exported.

Setting up and using the ET/390 featureTroubleshooting installation

Setting up and using the ET/390 featureAfter you install the ET/390 Feature for VisualAge for Java, you need to performseveral steps to ensure the Feature runs properly so you can build and run Javaapplications. This section lists the steps you need to follow and the sections in theonline information that provide details.1. Ensure that the ET/390 Java Install Data file on OS/390 contains the correct

information. This file provides the host session’s ET/390 Java installationinformaton to VisualAge for Java, and is usually prepared by the systemprogrammer. For more information about the Java Install Data File, see the listof related references at the end of this page.A sample ET/390 Java Install Data file can be found on the host in the rootdirectory where the host product was installed.

2. Provide logon information to OS/390, and OS/390 host session information toVisualAge for Java. For details, read the sections about logging on to OS/390and adding an OS/390 host session listed in the related tasks at the end of thispage.When you add the OS/390 host session, ET/390 downloads and permanentlysaves a copy of the ET/390 Java Install Data File to the workstation for yourET/390 development work.If the system programmer modifies the ET/390 Java Install Data file, you willneed to download the updated copy of the Data file. For details, read thesection about refreshing an OS/390 host session listed in the related tasks at theend of this page.


3. You can now create a project. For details, read the section about creatingprojects for OS/390 Java applications listed in the related tasks at the end ofthis page.

4. Once you create a project, you can build and run your code. For details, readthe sections about building Java applications and executables listed in therelated tasks at the end of this page.

Setting up the environmentTroubleshooting installationLogging on to OS/390Adding OS/390 host sessionRefreshing OS/390 host sessionCreating projects for OS/390 Java applicationsBuilding interpreted Java applications for OS/390v Compiling OS/390 interpreted Java applicationsv Compiling OS/390 interpreted Java for debugging

Building OS/390 Java Executables and DLLsv Getting started with the building of OS/390 Java executablesv Building OS/390 Java executablesv Building OS/390 Java DLLsv Binding Language Environment run-time optionsv Building an OS/390 Java executable or DLL in two stepsv Identifying OS/390 unsupported Java codev Changing ET/390 propertiesv Building OS/390 Java executables and DLLs for debuggingv Building Java executables and DLLs for tracing

Running OS/390 Java Applications from VisualAge for Javav Running Java bytecode in the OS/390 JVMv Debugging Java bytecode in the OS/390 JVMv Running OS/390 Java executablesv Debugging OS/390 Java executablesv Tracing OS/390 Java executables and DLLs

ET/390 Java Install Data file

Setting up the Open Edition environmentIf you choose to build your applications in the native Open Edition (OE)environment, there are a number of environment variables which must be setbefore the high-performance compiler will function. The table below summarizesthe environment variables that might need to be set for both build and executiontime. For detailed information about the variables, refere to the related referencesat the bottom of this page.

The environment variables are set automatically for you if you build yourapplications using the ET/390 feature of VisualAge for Java. The variables are setbased on the settings in the ET/390 Java Install Data file. Refer to the related tasksand references for details.

44 ET/390

Environment variable name Build time Execution time

IBMHPJ_HOME Required Required

IBMHPJ_RTL Required Not used

IBMHPJ_OPTS Not used Optional for specifying javarun-time options

STEPLIB Required (may be inDynamic LPA)

Required (may be inDynamic LPA)

CLASSPATH Optional (may use -classpathoption for user classes)

Optional (used to access userclasses in jll’s)

LIBPATH Required Optional (used to access JNIdll’s)

PATH Required for hpj or jportcommands

Required for hpjava or userexecutables

There are numerous options available to the system programmer which make someof these settings unnecessary. For example, the system programmer may haveloaded the SHPJMOD and SHPOMOD datasets into dynamic LPA. Not only willthis significantly improve run-time performance, but it also eliminates the need tospecify the STEPLIB environment variable.

A typical users profile may look like the following:

export IBMHPJ_HOME=/usr/lpp/hpjexport IBMHPJ_RTL=CEE.SCEELKED:CEE.SCEELKEX:CEE.SCEEOBJ:CEE.SCEECPPexport STEPLIB=HPJAVA.V2R0M0.SHPJMOD:HPJAVA.V2R0M0.SHPOMODexport CLASSPATH=/usr/ts12345/my.jarexport LIBPATH=$IBMHPJ_HOME/lib:/usr/ts12345/my.dllexport PATH=$IBMHPJ_HOME/bin:/usr/ts12345/bin

The above profile assumes the following:v The compiler and run-time PDSE’s have not been installed into Dynamic LPA.v The C run-time libraries have been installed into LPA.

Setting up and using the ET/390 feature

-classpathhpj commandhpjava commandET/390 Java Install Data filejport utilityOS/390 bytecode binder and Java run-time environment variables

Troubleshooting installationIf you are having problems getting started, you might have connectivity problemsor there may be some utilities that are not running as expected on the OS/390system. For proper performance, ET/390 requires the following:v NFS client on the workstationv NFS server daemon on OS/390

Chapter 7. Setting up the environment 45

v FTP server daemon on OS/390v REXEC server daemon running on OS/390.

VisualAge for Java supplies the REXEC and FTP clients as part of it’s tooling. Youcan use the REXEC and FTP clients that come with Microsoft Windows NT 4.0 tomanually test the connection to ensure that you have proper connectivity.

Examples to Test Your Installation

The examples below assume that you have installed Windows NT into theC:\WINNT directory. Take note of the following:v Where <host-name> is specified, enter the name of the OS/390 host system to

which you are connecting in either dotted decimal form or a name). Forexample: torolabb.torolab.ibm.com or 3.7.5.2.

v Where <username> is specified, enter the name of your userid on the OS/390host system. For example: TS34123, if that is your userid on OS/390.

v Where <file system> is specified, enter the fully qualified name of the HFS filesystem that you want to use for development. For example: /u/mike, if that isyour home directory under the Unix System Services environment.

To test REXEC, do the following:1. Go to the command line.2. Enter C:\WINNT\system32\rexec <host-name> -l <username> echo “Hello”3. Enter the password for <username>.

Hello should be written to the screen.

If this test doesn’t work, then your OS/390 REXEC server daemon might beconfigured to accept TSO commands, but not Unix System Services commands.Contact your system programmer to ensure that the REXEC server running on thedefault REXEC port is for Unix System Services.

To test FTP:1. Go to the command line.2. Create a small text file by entering dir >tmp.txt3. Enter C:\WINNT\system32\ftp <host-name>

4. Enter <username>.

5. Enter the password for <username>.

6. Enter PUT TMP.TXT7. Enter GET TMP.TXT newtmp.txt8. Enter QUIT9. Verify that TMP.TXT and NEWTMP.TXT are identical by comparing the files.

Enter COMP TMP.TXT NEWTMP.TXT

If the files are not identical, the translation table being used on OS/390 might notbe correct. Contact your system programmer to ensure that the table has beenupdated as outlined in the Program Directory.

To test NFS:1. Go to the command line.2. Mount a drive to the file system on OS/390 that you want to use for

development in binary read/write mode. The syntax of this command will varyfor different NFS clients. For Hummingbird Maestro, enter NET USE<Drive-letter>: \\<host-name>\/hfs/<file system>,binary

46 ET/390

3. Change directories to <Drive-letter>. For example, if you mounted your filesystem as drive K, enter K:

4. Use the drive as if it were a local drive.5. To ensure that you have basic NFS connectivity, enter DIR, which will display

all the files on your host system.6. To ensure that you can create files, enter DIR >tmp.txt7. To ensure that the files you create are valid, enter CAT tmp.txt

If you can’t view files, make sure you have set up NFS correctly.

If you can’t create files, make sure you have mounted the drive as writable.

Setting up the environmentSetting up and using the ET/390 feature

Getting F1 Help for the ET/390 properties windowsOnline Help is provided for each panel of the ET/390 Properties windows. Theonline Help for each panel includes information about the various parts of thepanel, including fields, check boxes, and buttons.

To see the Help for a panel, do the following:1. Select the name of the panel from the list on the left side of the Properties

Window.2. Press F1. The Help for the panel you selected appears in your browser.

Note: If you click somewhere other than on the left and press F1, you won’treceive help, so you will need to click again on the left panel.

ET/390 properties

Replacing the precompiled Version 2 classesThere are a number of classes used to support the EXEC CICS LINK interface.These classes supply a record which implements the IByteBuffer interface to CICS.There are four packages which are supplied in two JAR files: eablib.jar and therecjava.jar. Only a subset of the packages in these JAR files are required, andtherefore only the following packages are precompiled into PDSE’s:v com.ibm.recordv com.ibm.record.utilv com.ibm.record.ctypesv com.ibm.ivj.eab.record.cobol

The first two packages are the base record framework classes. The third package(com.ibm.record.ctypes) is for use with C language records, and the last one is foruse with COBOL language records. The first 3 packages are contained in therecjava.jar file. The 4th is contained in the eablib.jar file. Additional packages in theeablib.jar file are not precompiled because they are not required to support theEXEC CICS LINK interface.


Both versions 2.0 and 3.0 of these JAR files are shipped with the run-time libraryfeature of Visual Age for Java, Enterprise Edition for OS/390.

When the product is installed, version 2.0 is enabled as the default. This includesboth JAR files and external links which can be found in the lib directory of the rootinstallation directory, as well as the statically compiled members in the SHPOMODPDSE.

The version 3.0 library is not enabled by default since applications built withversion 2.0 are not binary compatible with 3.0. In order to exploit theenhancements built into version 3.0, you must enable the library and recompileyour applications. For additional information regarding binary compatibility, referto the RRBC considerations in the related concepts at the bottom of this page.

In order to enable the version 3.0 library, you must complete several steps asdescribed in the sections that follow. These steps can be done by the systemadministrator if the libraries are meant to be shared. The location and permissionson the links as well as the PDSE containing the new members will determine howthe library will be shared.

The following sections assume that the system administrator will be building thelinks into the common lib directory. The system administrator might also choose toload the PDSE into the dynamic link pack area for performance reasons.

Compiling the Enterprise Access Bean Library Version 3.0To compile the library, do the following:1. Allocate a LIBRARY dataset, with the following characteristics:

Data Set Name HLQ.HPJEABV3.LOADPDSE // Change appropriatelySpace units BLKSPrimary quantity 150Secondary quantity 50Directory blocks 0Record format URecord length 0Block size 32760Data set name type LIBRARY

2. Build the three modules HPOCOBOL, HPOCTYPE, HPORECRD into the aboveLIBRARY dataset. The modules should be named as specified.

hpj -jll -collapse -O -nofollow -make \-o=“//'HLQ.HPJEABV3.LOADPDSE(HPORECRD)'” \-classpath=$IBMHPJ_HOME/lib/recjavaV3.jar \-include=com.ibm.record.* \-exclude=com.ibm.record.IByteBuffer \-include=com.ibm.record.util.* \-exclude=com.ibm.record.ctypes.* \-alias=com/ibm/record.jll \-alias=com/ibm/record/util.jll \> HPORECRDV3.log 2>&1hpj -jll -collapse -O -nofollow -make \-o=“//'HLQ.HPJEABV3.LOADPDSE(HPOCTYPE)'” \-classpath=$IBMHPJ_HOME/lib/recjavaV3.jar \-include=com.ibm.record.ctypes.* \-alias=com/ibm/record/ctypes.jll \> HPOCTYPEV3.log 2>&1hpj -jll -collapse -O -nofollow -make \-o=“//'HLQ.HPJEABV3.LOADPDSE(HPOCOBOL)'” \-classpath=$IBMHPJ_HOME/lib/eablibV3.jar:

48 ET/390

$IBMHPJ_HOME/lib/recjavaV3.jar \-include=com.ibm.ivj.eab.record.cobol.* \-alias=com/ibm/ivj/eab/record/cobol.jll \> HPOCOBOLV3.log 2>&1

Note: Since no new links are required, the -toption of the hpj command is notspecified. The links created in the current directory may be removed as theyalready exist in $IBMHPJ_HOME/lib.

Recompiling all applications which will be run using the EAB version 3.0libraryTo recompile the applications, do the following:1. Add eablibV3.jar and recjavaV3.jar in the beginning of your classpath. You may

either use the export command, or specify the classpath using -classpath optionof the hpj command.export CLASSPATH=$IBMHPJ_HOME/lib/eablibV3.jar:

$IBMHPJ_HOME/lib/recjavaV3.jar:$CLASSPATH

2. Recompile all applications which will be run using the EAB version 3.0 libraryas you have done before.

Setting up the run-time environment to enable EAB Version 2 or Version 3 orbothWhen setting up the run-time environment, note the following:1. If you plan to use only version 3 of the Enterprise Access Bean Library, you can

choose to add the modules from the LIBRARY dataset created earlier in yourLink Pack Area for performance reasons.

2. If you plan to use only version 2 of the Enterprise Access Bean Library, you canchoose to add the modules from the HPJ runtime library dataset in your LinkPack Area for performance reasons.

3. If you plan to have some applications using Version 2 and some using Version3 of the Enterprise Access Bean Library you have to use STEPLIB to controlwhich library the modules will be loaded from.v If your application uses Version 2 of the Enterprise Access Bean Library,

then put the high-performance compiler run-time library in the STEPLIBconcatenation.

v If your application uses Version 3 of the Enterprise Access Bean Library,then in the STEPLIB concatenation, you will need to specify the librarydataset containing version 3 modules before the high-performance compilerrun-time library.

RRBC considerations for interpreted Java and OS/390 program objects

-classpath-t=dir


50 ET/390

Chapter 8. Building and running Java applications in theOS/390 shell

Compiling OS/390 interpreted Java applicationsIn an OS/390 shell, use the javac command to compile your HFS Java source filesinto bytecode. Refer to OS/390 UNIX documentation for more details on the use ofthe javac command.

If you want to debug your code, use the -g option to ensure that debuginformation is generated for the classes.

OS/390 Java development on the host

Compiling interpreted Java for debuggingRunning Java bytecode in the OS/390 JVMDebugging Java bytecode in the OS/390 JVM

-t=dir

Compiling OS/390 interpreted Java for debuggingIf you use the javac command in the OS/390 shell to compile your code fordebugging, you can set breakpoints and step through your source code withoutusing any compiler options. Use the -g compile option if you want to examinelocal, class instance and static variables while debugging. For example, compilehelloWorld as follows:javac -g helloWorld

Java source filesJava source files are required for debugging. For UNIX System Services, the sourcecan either be on host or workstation. For CICS, the source must be on theworkstation.

The debugger searches for Java source files in the following locations:1. Paths in the environment variable IVJ_DBG_REMOTE_SEARCH_PATH (if set).

For example, the variable can be set like this:/home/user/project/dir1;/home/user/project/dir2;This variable is set on Windows NT under System Properties. This variable isused to search the HFS directories and partitioned datasets on the OS/390 hostfor a requested source file. If more than one directory is specified, the namesmust be separated by a semicolon.

2. The file name specified at compile time.3. Paths in the environment variable IVJ_DBG_PATH (if set). For example, the

variable can be set like this:C:\project\dir1;C:\project\dir2;This variable is set on Windows NT under System Properties. This variable is


used to locate source files on the workstation. If the source file cannot belocated in any of the above directories, a dialog box opens requesting the pathname for the source file. The path name you enter is searched for the sourcefile.

Refer to OS/390 UNIX documentation for more details on the use of the javaccommand.


Compiling OS/390 interpreted Java applicationsRunning Java bytecode in the OS/390 JVMDebugging Java bytecode in the OS/390 JVM

Building OS/390 Java executables and DLLs

Building OS/390 Java executables on HFSWhen you are working in an OS/390 shell, build the HFS Java executable with thehpj command as follows:cd /home/ts123456hpj -o=queryEmp abc.staff.queryDB.queryMain -make

Notes:

1. The -exe option does not have to be specified. It is the default if -jll is notspecified.

2. The easiest way to build a Java executable is to specify the main class name asinputto the hpj command. Because of the default -follow option, the bytecodebinder finds all referenced classes and also binds them.

3. Since the example does not specify the -main option, the binder finds the firstinput class (abc.staff.queryDB.queryMain) that has the main method and usesthat as the entry point.

4. The -o option is used to name and place the Java executable, queryEmp. If youdo not use the -o option, the Java executable is named a.out, and it is written tothe current directory.

5. The -make option does not do anything when you are building a new Javaexecutable, but it is useful when you want to rebuild the Java executable. Seethe scenarios under related topics for more information on the -makeoption.

OS/390 Java development on the hostOS/390 Java executablesScenarios: Building OS/390 Java applications

Building Java executables and DLLs for debuggingBuilding OS/390 Java executables in PDSE membersBuilding Java executables and DLLs for tracingBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time options

52 ET/390

Identifying OS/390 unsupported Java codeRunning HFS Java executables in OS/390 UNIX

hpj command

Building OS/390 Java executables in PDSE membersWhen you are working in the OS/390 shell, build the Java executable in a PDSEmember with the hpj command as follows:cd /home/ts123456hpj -o=“//'FRED.LOADLIB(QUERYEMP)'”

abc.staff.queryDB.queryMain

Notes:




4. The -o option must be used to place the Java executable in the PDSE member.In the example, the Java executable is written to a member called QUERYEMPin the data set, FRED.LOADLIB. The data set name must be preceded bydouble slashes (//) and single quotation marks are used to indicate that thisname is a fully qualified data set name. Double quotation marks (“) arerequired around the whole PDSE specification.

OS/390 Java development on the hostOS/390 Java executablesOS/390 Java CICS/ESA supportScenarios: Building OS/390 Java applications

Building Java executables and DLLs for debuggingBuilding OS/390 Java executables on HFSBuilding CICS Java programsBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java codeRunning a Java executable that is in a PDSE member

hpj command

Building OS/390 Java DLLs on HFSWhen you are working in the OS/390 shell, build the HFS Java DLL with the hpjcommand as follows:

Chapter 8. Building and running Java applications in the OS/390 shell 53

cd /home/ts123456hpj -jll -classpath=/home/ts123456 -o=abc/staff/queryDB.jll

-include=abc.staff.queryDB.* -make

Notes:

1. The -jll option is required to build a Java DLL.2. If you are building a Java DLL with all the classes in a package, using the

-include option with a wildcard is a fast way to specify all the classes. TheCLASSPATH is used to find the specified classes. You should also specify a-classpath option to limit the search for the include classes. The JDK classes areautomatically added before the paths in the -classpath option.

3. Because of the default -follow option, the bytecode binder finds all referencedclasses and also binds them. Specify -nofollow if you do not want to includereferenced classes in the bind.

4. The -o option is used to name and place the Java DLL, queryDB.jll. You mustspecify the -o option.

5. The -make option does not do anything when you are building a new JavaDLL, but it is useful when you want to rebuild the Java DLL. See the scenariosunder related topics for more information on the -makeoption.

OS/390 Java development on the hostOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applicationsNaming and placement of OS/390 Java DLLs in PDSE members

Building Java executables and DLLs for debuggingBuilding OS/390 Java DLLs in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java codeRunning HFS Java DLLsDebugging Java executables and DLLsAccessing HFS Java DLLs under OS/390 UNIX

hpj command

Building OS/390 Java DLLs in PDSE MembersWhen you are working in the OS/390 shell, build the Java DLL in a PDSE memberwith the hpj command as follows:cd /home/ts123456hpj -jll -classpath=/home/ts123456 -include=abc.staff.queryDB.*

-o=“//'FRED.DLL(QUERYEMP)'”-alias=abc/staff/queryDB.jll

-make-t=.

Notes:

1. The -jll option is required to build a Java DLL.2. If you are building a Java DLL with all the classes in a package, using the

-include option with a wildcard is a fast way to specify all the classes. TheCLASSPATH is used to find the specified classes. You may want to also specify

54 ET/390

a -classpathoption to limit the search for the include classes. The JDK classesare automatically added before the specified paths in the -classpath option.

3. Because of the default -follow option, the bytecode binder finds all referencedclasses and also binds them. Specify -nofollow if you do not want to includereferenced classes in the build.

4. The -o option must be used to place the Java DLL in the PDSE member. In theexample, the Java DLL is written to a member called QUERYEMP in the dataset, FRED.DLL. The data set name must be preceded by double slashes (//)and single quotation marks are used to indicate that this name is a fullyqualified data set name. Double quotation marks (“) are required around thewhole PDSE specification.

5. The -alias option must be specified for Java DLLs that are written to PDSEmembers.

6. The -make option does not do anything when you are building a new JavaDLL, but it is useful when you want to rebuild the Java DLL. See the scenariosunder related topics for more information on the -makeoption.

OS/390 Java development on the hostOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applicationsNaming and placement of OS/390 Java DLLs in PDSE membersOS/390 UNIX run-time CLASSPATH searches for Java DLLsResource files in PDSE members

Building Java executables and DLLs for debuggingBuilding OS/390 Java DLLs in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java codeRunning HFS Java DLLsDebugging Java executables and DLLsAccessing HFS Java DLLs under OS/390 UNIX

hpj command

Building a Java executable or DLL in two stepsWhen you are working in the OS/390 shell, you can build your Java executable orDLL in two steps:1. Specify the -c option to generate all the partially bound program objects (.o,

.mo, .ro, and .bo files). Optionally, you can specify the -jll option to generatethe root.bo file. For details about the root.bo file, refer to the hpj commandrelated reference.

2. Specify all the partially bound program objects (.o, .mo, .ro, and .bo files,including root.bo) as input files to the hpj command, and bind them into therequired Java executable or DLL.

For example, generate the Java executable queryEmp in two steps as follows:


cd /home/ts123456hpj -c abc.staff.queryDB.queryMain

-main=abc.staff.queryDB.queryMain-collapse -d=/home/obj

-lerunopts=“stack(,,any,) termthdact(dump)”

cd /home/objhpj -exe -o=/home/ts123456/queryEmp

abc.staff.queryDB.queryMain.moabc.staff.queryDB.queryMain.ro

*.o

Notes:

1. The first hpj command generates all the .o files, the .mo file and the .ro file in/home/obj. The -c option prevents the binding of the .o files into the Javaexecutable. The -main option identifies the class containing the main methodand a .mo file is generated for that class (in addition to the .o file). Because the-collapse and -d options are specified, all the partially bound program objectsare written to a single directory, /home/obj. This will make it easier to specifythe input .o files in the second hpj command.

2. The second hpj command binds all the specified .o, .mo, and .ro files to createthe Java executable, queryEmp. The .mo file must be specified for the classcontaining the main method. The .ro file contains the Language Environmentrun-time options. Note that the -main option is not specified in the secondhpjcommand. See related concepts for more information on building Javaexecutables and DLLs.

3. If you are building a Java executable in a PDSE member, you can specify the-resource option on the compile step to create a resource.bo file. You will alsocreate an intermediate file called resource.aliases which contains informationrequired by the high-performance compiler at bind time to create links for the-toption.You would then include the resource.bo file as an input file to the bind step aswell as specify a directory for the links in the -t option. This resource.aliases filewill have been created in the same directory as the resource.bo file during Step1. Step 2 will look for this file where it foun the .bo file.

OS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applicationsBuilding OS/390 Java executables and DLLs with .o files

Building OS/390 Java executables on HFSBuilding OS/390 Java executables in PDSE membersBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java code

hpj command-resource

56 ET/390

Binding Language Environment run-time optionsWhen you are working in the OS/390 shell, you can bind Language Environmentrun-time options into the Java executable that you are building. You cannot bindLanguage Environment run-time options to a Java DLL. Use the -lerunopts optionwith the hpj command as follows:cd /home/ts123456hpj abc.staff.queryDB.queryMain

-o=queryEmp-lerunopts=“stack(,,any,) termthdact(dump)”

-make

Notes:

1. The -lerunopts option lists the Language Environment run-time options thatyou want to bind into queryEmp. A queryMain.ro file containing the run-timeoptions is also generated.

2. The Java executable, queryEmp, is created in the /home/ts123456 directory.When you run the executable, the run-time options will be passed to LanguageEnvironment run time.

Language Environment run-time options specified at run time take precedenceover those specified at build time. If they are not specified at run time, theLanguage Environment run-time options specified at build time (hpj command’s-lerunopts option) are used.


Building OS/390 Java executables on HFSBuilding OS/390 Java executables in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsIdentifying OS/390 unsupported Java code

hpj command-lerunopts

Identifying OS/390 unsupported Java codeWhen you are building OS/390 Java executables or DLLs in the OS/390 shell, usethe jport utility to identify Java code that is not supported under OS/390 UNIX orCICS/ESA. The jport utility reads Java bytecode files and generates HTML filesthat list the unsupported packages, classes, methods, and fields for the OS/390UNIX or CICS/ESA environments.

Overview of OS/390 bytecode binder’s JDK supporthpj commandjport utility


Building Java executables or DLLs for debuggingTo build Java executables or DLLs for debugging, follow these steps:1. Compile Java source files that you want to debug with the javac -g option.2. Build the Java executable and DLLs that you want to debug, using the -g

option with the hpjcommand.3. You may bind Language Environment TEST run-time option to your Java

executable. Use the -lerunopts option with the hpjcommand as follows:-lerunopts=“test(,,,VADTCPIP&wkst_id%portid:*)”

wkst_id is the numeric IP address of your workstation or the TCP/IP name ofyour workstation.

portid is the TCP/IP port ID (this is optional and defaults to 8000). If specified,the value must match the portid value that was specified when the debuggerdaemon was started.

-lerunopts binds the Language Environment TEST run-time option to the Javaexecutable so that when you run the executable, debugging is started. Note:You cannot bind Language Environment run-time options to Java DLLs. Whenthe Java executable is running in debug mode, the Java DLLs that it calls canalso be debugged if they were built with the hpj command’s -g option.

If you do not bind the TEST run-time option with your Java executable, youcan use the _CEE_RUNOPTS environment variable to set the TEST run-timeoption prior to running your program. See related tasks on how to debugJava executables in the OS/390 shell.

Java Source FilesJava source files are required for debugging. They can reside either on the host oron the workstation that is running the debugger daemon.

For information about starting the debugger daemon on the workstation go to the“Starting the Debugger Daemon at the Workstation” topic by following this path:in the Tasks section of the online information click on “Targeting Programs forOS/390”, “Building and Running Java Applications in the OS/390 Shell”,“Running Java Programs under CICS/ESA”, “Starting the Debugger Daemon atthe Workstation”.

OS/390 Java cevelopment on the hostOS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applications

Building OS/390 Java executables on HFSBuilding OS/390 Java executables in PDSE membersBinding Language Environment run-Time optionsIdentifying OS/390 unsupported Java codeDebugging Java executables and DLLs

58 ET/390

hpj command-g[=hook|nohook]-lerunopts

Building Java programs to run under CICS/ESA

Building CICS Java programs on the hostCICS transactions that are written in Java must be built as Java executables. Theymust reside in PDSE members. To build Java executables that are CICStransactions, you have to:1. Define resources to CICS/ESA2. Build Java executables in PDSE members3. Refresh CICS programs

OS/390 Java CICS/ESA supportOS/390 Java executables and Dynamic Link Libraries

Running CICS Java programsPreparing run-time environment to access Java DLLs

OS/390 bytecode binder’s JDK 1.1.6 supporthpj command-resource

Defining resources to CICS/ESA to run a new Java executable(OS/390)

To run a new Java executable under CICS/ESA, you have to define the resources:program and transaction, to CICS. CICS automatically makes the programdefinitions if you set PGAIPGM=ACTIVE in the System Initialization Parameter(SIT). With CEDA, you can update the running CICS system.

Define the resources to CICS, as follows:1. Start up CICS.2. Make resource definitions available to active CICS system, as follows:

ceda install trans(trid) group(test)

test is your group.


Building CICS Java programsPreparing run-time environment to access Java DLLsRefresh CICS programsRunning CICS Java programs


OS/390 bytecode binder’s JDK 1.1.6 supporthpj command

Building OS/390 Java executables in PDSE membersWhen you are working in the OS/390 shell, build the Java executable in a PDSEmember with the hpj command as follows:cd /home/ts123456hpj -o=“//'FRED.LOADLIB(QUERYEMP)'”

abc.staff.queryDB.queryMain

Notes:




4. The -o option must be used to place the Java executable in the PDSE member.In the example, the Java executable is written to a member called QUERYEMPin the data set, FRED.LOADLIB. The data set name must be preceded bydouble slashes (//) and single quotation marks are used to indicate that thisname is a fully qualified data set name. Double quotation marks (“) arerequired around the whole PDSE specification.

OS/390 Java development on the hostOS/390 Java executablesOS/390 Java CICS/ESA supportScenarios: Building OS/390 Java applications

Building Java executables and DLLs for debuggingBuilding OS/390 Java executables on HFSBuilding CICS Java programsBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java codeRunning a Java executable that is in a PDSE member

hpj command

Refreshing CICS programs (OS/390)Once CICS has loaded your Java program, it will continue to use this copy of theprogram. If you have rebuilt your CICS Java executable or DLL, you should runthe following master terminal transaction so that CICS knows that it is to use anew copy of the program for all new transaction requests:CEMT SET PROGRAM(membername) PHASEIN

60 ET/390

where membername is a PDSE member of the CICS program that your areattempting to refresh.

Note: If you are building CICS Java programs with VisualAge for Java, selectRefresh CICS Programin the ET/390 properties’ Bind Options panel and thesystem will automatically refresh the program for you.


Building CICS Java programsRunning CICS Java programsAccessing Java resource files under CICSPreparing run-time environment to access Java DLLs under CICS/ESADebugging CICS Java programs


Building CICS/ESA Java programs for debuggingYou can build CICS/ESA Java Programs in the OS/390 shell on the host orremotely from the VisualAge for Java IDE. However, you can only initiate therunning of your CICS Java executable on the host system.

Define resources to CICS/ESA for the Java executable. Then in the OS/390 shell,build the CICS/ESA Java Programs for debugging as follows:1. Compile Java source files that you want to debug with the javac command’s -g

option.2. Build the Java executable and the Java DLLs that you want to debug, using the

-g option with the hpjcommand.3. Build your Java executable using the -lerunopts option with the hpjcommand,

for example:-lerunopts=test(,,,VADTCPIP&wkst_id%portid:*)wkst_id is the numeric IP address of your workstation or the TCP/IP name ofyour workstation.portid is the TCP/IP port ID (this is optional and defaults to 8000). If specified,the value must match the portid value that was specified when the debuggerdaemon was started.-lerunopts binds the Language Environment TEST run-time option to the Javaexecutable so that when you run the executable, debugging is started. Thedaemon also uses port 8000 as the default when started.Note: -lerunopts option cannot be used when building Java DLLs. When theCICS Java executable is running with debugging, the Java DLLs that theexecutable calls can also be debugged if they were built with the hpjcommand’s -g option.

Java source files are required for debugging. They can reside either on the host orthe workstation that is running the debugger daemon. For CICS, Java source filesmust reside on the workstation, since CICS can not access HFS files directly.


Additionally, make sure that the IVJ_DBG_PATH environment variable is set onthe workstation that has your source files.

Refresh the CICS Java executable after each rebuild.



Building CICS Java programsRunning CICS Java programsPreparing run-time environment to access Java DLLs

OS/390 Bytecode Binder’s JDK 1.1.6 Supporthpj Command

Running interpreted Java in the OS/390 JVM

Running Java bytecode in the OS/390 JVMRun the Java bytecode in an OS/390 shell by using the java command. Use exportcommand to set any required environment variables prior to running the Javaapplication, for example:export CLASSPATH=.:/home/ts123456:$CLASSPATHjava abc.staff.queryDB.queryMain

See OS/390 UNIX documentation for more information on the java command.


Compiling OS/390 interpreted Java applicationsCompiling interpreted Java for debuggingDebugging Java bytecode in the OS/390 JVM

Debugging Java bytecode in the OS/390 JVMYou can debug your Java bytecode as it is running in the OS/390 JVM. To debugOS/390 interpreted Java code, follow these steps:1. Start the debugger daemon at the workstation which includes the setting of

environment variables. If some of your Java source files are at the workstation,

62 ET/390

set the IVJ_DBG_PATH environment variable at the workstation. See relatedtasks for more information on how to start the debugger daemon at theworkstation.

2. In the OS/390 shell, use the export command to set the JAVA_COMPILERtooff, as follows:export JAVA_COMPILER=off

3. In the OS/390 shell, use the export command to set the CLASSPATHenvironment variable to point to the location of the source files that are on thehost, for example:export CLASSPATH=/home/ts123456:$CLASSPATH

The debugger searches for the Java source files using the CLASSPATH, similarto the way the JVM searches for classes.

4. In the OS/390 shell, use the jdbug command to run your Java application(instead of the java command), as follows:jdbug -quiport=portid -qhost=wkst_id [className parm1 parm2...]



className parm1 parm2... is the fully qualified name of the Java class that youwant to debug and its parameters, for example, abc.staff.queryDB.queryMainN12345, where the class name is abc.staff.queryDB.queryMain and theparameter is N12345. If you do not specify the className and its requiredparameters, you will be prompted to enter them.

Your Java class will start to run with debugging.



Compiling interpreted Java for debuggingCompiling OS/390 interpreted Java applicationsRunning Java bytecode in the OS/390 JVM

Running Java executables and DLLs under OS/390 UNIX

Running HFS Java executables in OS/390 UNIXWhen running an HFS Java executable in the OS/390 shell, set the followingenvironment variables:


1. Add the ET/390 run time and the Language Environment run time to theSTEPLIB, for example:export STEPLIB=hlq1.SHPOMOD:hlq2.SCEERUN

Note: The data set names are examples of the run-time libraries. hlq1 and hlq2are high-level qualifiers for the ET/390 and Language Environmentinstallations, respectively. Make sure that you specify the correct names forthese data sets. You do not have to include the ET/390 run-time library andLanguage Environment run-time library in the STEPLIB if they are in the LPA(which is recommended).

2. Either set the current directory to the one containing your Java executable, orset the PATH environment variable to point to the location of the executable’sfile. Enter the executable’s file name in an OS/390 shell to run it, for example:export PATH=/home/ts123456queryEmp

3. Set the CLASSPATH environment variable to point to the location of therun-time library, for example:

export CLASSPATH=/usr/lpp/hpj/libwhere /usr/lpp/hpj is the default directory where the high-performancecompiler is installed.

A Java executable is expected to have a main method. If you run the executableand there is no main method, an error is displayed.


Building OS/390 Java executables on HFSBuilding Java executables and DLLs for debuggingBuilding OS/390 Java executables in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java code

hpj command

Running a Java Executable that is in a PDSE memberIf the Java executable is in a PDSE member, FRED.LOADLIB(QUERYEMP), run itin the OS/390 shell as follows:1. Create a temporary directory:

mkdir temp

2. Create an empty file for your executable:cd temptouch queryemp

The file that you create must have the same name as your PDSE member name.3. Change the mode for the file to make it an executable file (u+x) and to turn on

its sticky bit (u+t):

64 ET/390

chmod u+xt queryemp

Because you have turned on queryemp’s sticky bit, OS/390 UNIX will searchfor queryemp in the STEPLIB, the link pack area (LPA), or link listconcatenation.

4. Set the STEPLIB environment variable to include your PDSE:export STEPLIB=FRED.LOADLIB:$STEPLIB

Specify fully qualified PDSE names in the STEPLIB.5. Set the PATH environment variable to the current or temp directory:

export PATH=.:orexport PATH=/home/ts123456/temp

6. Set the CLASSPATH environment variable to point to the location of JDK classlibraries. For example:export CLASSPATH=/usr/lpp/hpj/JDK class librarieswhere /usr/lpp/hpj is the default directory where the high-performancecompiler is installed.

7. Run the executable:queryemp

The system changes queryemp to uppercase and looks through the STEPLIB tofind a PDSE with a member name of QUERYEMP.


Building Java executables and DLLs for debuggingBuilding OS/390 Java executables in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java code

hpj command

Running HFS Java DLLs in OS/390 UNIXTo run an HFS Java DLL in the OS/390 shell, you can use the hpjava command.The DLL must have a class that contains a main method that is defined as follows:package A.B.C.D;class classname {

public static void main (String argv[]) {...

}}

Run the DLL specifying the class name in the hpjavacommand, as follows:hpjava A.B.C.D.classname


OS/390 Java development on the hostOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applicationsNaming and placement of OS/390 Java DLLs in PDSE membersOS/390 UNIX run-time CLASSPATH searches for Java DLLsResource files in PDSE members

Building Java executables and DLLs for debuggingBuilding OS/390 Java DLLs in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java codeAccessing HFS Java DLLs under OS/390 UNIXDebugging Java executables and DLLs

hpj commandhpjava command

Accessing HFS Java DLLs under OS/390 UNIX at run timeHFS Java DLLs can only be accessed by Java executables or DLLs running underOS/390 UNIX. To access the HFS Java DLL at run time, set the CLASSPATHenvironment variable before you run your executable.

ExampleIf your HFS Java DLL, queryDB.jll, is in /home/ts123456/abc/staff, enter thefollowing export command in the OS/390 shell:export CLASSPATH=/home/ts123456:$CLASSPATH

When there is a reference to abc.staff.queryDB.readDB class in this Java DLL,queryDB.jll will be found from the first path that you included in the CLASSPATHenvironment variable.

When specifying paths in the CLASSPATH environment variable (used for JavaDLL searches) at run time, make sure that you have search permission on alldirectory components of the path names. If you do not have search permissions forthe paths, you will get an error similar to the following:

Failed to find class QueryEmp during resolution of class EmpHist in module/pkg1/pkg2/employee.jll .

Note: You must also have execute permission for the Java DLLs that yourapplication requires.

OS/390 Java development on the hostOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applications

Building OS/390 Java DLLs on HFSBuilding Java executables and DLLs for debugging

66 ET/390

Building OS/390 Java DLLs in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsIdentifying OS/390 unsupported Java codeRunning HFS Java DLLsDebugging Java executables and DLLs

hpj command

Accessing PDSE Java DLLs under OS/390 UNIXJava DLLs that are in PDSE members can be accessed by Java executables or DLLsrunning under OS/390 UNIX and CICS/ESA. To access a PDSE Java DLL underOS/390 UNIX, set the STEPLIB and CLASSPATH environment variables before yourun your executable, as follows:1. Include your Java DLL’s PDSE in the STEPLIB. For example, if the Java DLL is

in FRED.PDSE.LOAD(READ1), specify the following export command in theOS/390 shell:export STEPLIB=FRED.PDSE.LOAD:$STEPLIB

The STEPLIB now includes the PDSE that contains the Java DLL.2. Use external links to STEPLIB data sets, and specify the CLASSPATH as if the

Java DLL is in an HFS directory as shown in this example:ln -e QUERYEMP /home/test/pkg1.jll

QUERYEMP is the PDSE member containing pkg1.jll. You can then specify thesearch path /home/test for pkg1.jll in the CLASSPATH using the exportcommand as follows:export classpath=/home/hfs/dlls:/home/test:$CLASSPATH

At run time, after the unsuccessful search through the /home/hfs/dllsdirectory, the search of home/test/pkg1.jll (which is the link to QUERYEMP)will successfully load the Java DLL in the PDSE memberFRED.PDSE.LOAD(QUERYEMP).

OS/390 Java executablesScenarios: Building OS/390 Java applicationsOS/390 UNIX run-time CLASSPATH searches for HFS Java DLLs

hpj command

Debugging Java executables and DLLsYou can debug Java executables and DLLs that are running in the OS/390 shell.When you debug the Java executable, all Java DLLs that it calls will also bedebugged if they were built with the -g bind option. To debug the Javaexecutable, follow these steps:1. Start the debugger daemon at the workstation which includes the setting of

environment variables. If your Java source files are at the workstation, set theIVJ_DBG_PATH environment variable at the workstation. If your Java source


files are on the host, set the IVJ_DBG_REMOTE_SEARCH_PATH environmentvariable. See related tasks for more information on how to start the debuggerdaemon at the workstation.

2. In the OS/390 shell, set the PATH environment variable to point to the locationof the executable’s file, for example:export PATH=/home/ts123456

3. In the OS/390 shell, use the export command to set the STEPLIB to include thedebugger’s load library, the ET/390 run-time library and the LanguageEnvironment run-time library, for example:export STEPLIB=EQAW.V1R2M0.SEQAMOD:hlq1.SHPOMOD:hlq2.SCEERUN:USERID.PROJ1.LOAD

Note: The data set names are examples of the run-time libraries. hlq1 and hlq2are high-level qualifiers for the ET/390 and Language Environmentinstallations, respectively. Make sure that you specify the correct names forthese data sets. You do not have to include the ET/390 run-time library andLanguage Environment run-time library in the STEPLIB if they are in the LPA(which is recommended).

4. If you used the -lerunoptsoption to bind the TEST run-time option to the Javaexecutable, you do not need to perform this step.In the OS/390 shell, use the export command to set the _CEE_RUNOPTSenvironment variable to pass the Language Environment run-time option,TEST(,,,VADTCPIP&wkst_id%portid:*), for example:export _CEE_RUNOPTS=“TEST(,,,VADTCPIP&wkst_id%portid:*)”



5. In the OS/390 shell, enter the executable’s file name to run it, for example:queryEmp

If the Java executable resides in a PDSE member, follow the instructions inrunning a Java executable that is in a PDSE.

To simplify some of these steps, you can create a shell script and use it to set theSTEPLIB and _CEE_RUNOPTS (TEST run-time option) environment variables andrun your Java executable. For example, the shell script can contain the followingstatements:

#dbg - shell script to debug programexport STEPLIB=EQAW.V1R2M0.SEQAMOD:$STEPLIBexport _CEE_RUNOPTS=“TEST(,,,VADTCPIP&wkst_id%portid:*)” $*&

You would invoke your program for debugging with:dbg program_name

where program_name is the name of the program you want to debug.

Additional information about using the debugger is found in the onlineinformation for the Debugger for ET/390 component.

68 ET/390

OS/390 Java development on the hostOS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applications

Building Java executables and DLLs for debuggingBuilding OS/390 Java executables in PDSE membersBinding Language Environment run-time optionsRunning a Java executable that is in a PDSE memberIdentifying OS/390 unsupported Java code


Running Java programs under CICS/ESA

Running CICS Java programsCICS programs that are written in Java must be built as Java executables, exceptIIOP programs which are built as Java DLLs. They must reside in PDSEmembers. You run the CICS Java programs (like any other CICS transaction) onthe host via EXEC CICS LINK(ProgramName), by an IIOP client, or from devicessuch as 3270s via a transaction ID. However, before running the Java executable,you may need to do one or more of the following steps:1. If you want to pass environment variables, use the -lerunopts option to pass

the Language Environment ENVAR run-time option which sets theenvironment variables, for example:hpj -o=“//’A.LOAD(ABC)’” abc.staff.queryDB.queryMain-lerunopts=“ENVAR(TZ=ESTSTD, LC_CTYPE=type)”

2. If the CICS transaction accesses read-only Java system resource files (such asJavaBeans stored as serialised objects in .ser files), you must first bind theseresource files into a PDSE member.

3. Concatenate the following to DFHRPL:v PDSE containing the CICS Java programv All referenced DLLs, for example:

– JDK DLLs– CICS Java API DLLs (if used)

v All resource PDSEs4. Define resources to CICS/ESA for the transaction that you want to run.5. Run the CICS Java program with one of the following methods:

v Entering a four-character transaction ID from a CICS terminalv Coding an EXEC CICS LINK PROGRAM(programName) command in a CICS

program to invoke the CICS Java program that you want to run.v Using Corba IDL to start the CICS Java program from an IIOP client.



Building CICS Java programsAccessing Java resource files under CICSPreparing run-time environment to access Java DLLs under CICS/ESADebugging CICS Java programs


Accessing Java resource files under CICSIf the CICS application accesses read-only Java resource files (such as JavaBeansstored as object serializations), you must bind these resource files into a Java DLLin a PDSE member or bind them with the Java executable. The hpj command’s-resource option can be used in the OS/390 shell to help you bind HFS resourcefiles to a PDSE member, as follows:1. Package all referenced resource files into one or more JAR or ZIP files.2. Specify the -resource option in an hpj command to create a PDSE Java DLL

containing all the resource files. For example, the following hpj commandbinds all the resource files in app1.zip, app2.zip, and app3.jar into APP123 inthe PDSE, FRED.PDSE.APP.hpj -nofollow -jll -o=“//'FRED.PDSE.APP(APP123)'”

app1.zip app2.zip app3.jar exclude=*-resource

The PDSE member, APP123, contains the Java DLL which contains all theresource files in the ZIP and JAR files. The -exclude=* excluded all the classesfrom the build. An alias name for each resource file is automatically added forthe PDSE member.

To access the resource files in this PDSE Java DLL, you must concatenate the PDSEcontaining the Java DLL to DFHRPL and define resources to CICS/ESA for theJava DLL.

You can also use the -resource option to bind the resource files with the Javaclasses that use them in a Java executable that is written to a PDSE member.

OS/390 Java CICS/ESA supportResource files in PDSE members

Running CICS Java programsPreparing run-time environment to access Java DLLs under CICS/ESADebugging CICS/ESA Java programs

hpj command-resourceOS/390 bytecode binder’s JDK 1.1.6 support

70 ET/390

Preparing the run-time environment to access Java DLLsunder CICS/ESA

Only Java DLLs residing in PDSE members can be accessed under the CICSenvironment. Once you have built the Java DLL in a PDSE member, follow thesesteps before running the CICS Java program that references the classes in the DLL:1. Concatenate the PDSE containing the Java DLL to DFHRPL.2. Define resources to CICS/ESA for a new Java DLL

If the CICS Java program also accesses Java resource files, you must first bindthese resource files into a Java DLL in a PDSE member. Then treat the Java DLLlike any other PDSE Java DLL and follow the above steps so that the resource filescan be accessed under CICS.


Running CICS Java programsAccessing Java resource files under CICSDebugging CICS/ESA Java programs

hpj command-resourceOS/390 bytecode binder’s JDK 1.1.6 support

Defining resources to CICS/ESA to access a Java DLLTo access a newly built Java DLL in the CICS/ESA environment, you have todefine the program resource to CICS. You can use the online definition transactionCEDA to define resources to your CICS system while the system is running, orallow CICS to install the program definition automatically. With CEDA, you canupdate both the CICS system definition (CSD) file and the running CICS system.

Define the program resource to CICS, as shown below. You might need to defineadditional resources to CICS for your program to run, depending on what yourprogram does. For details on CICS application programming, see the CICSdocumentation.1. Start up CICS.2. Enter the following to add the program to the CICS Processing Program Table

(PPT):ceda define program(member) group(test)

member is the PDSE primary member name, and test is your group.3. Make resource definition available to active CICS system, as follows:

ceda install group(test)

test is your group.

OS/390 Java CICS/ESA supportOS/390 Java Dynamic Link Libraries (DLLs)Resource files in PDSE members


Building OS/390 Java DLLs in PDSE membersRunning CICS Java programsAccessing Java resource files under CICSPreparing run-time environment to access Java DLLs under CICS/ESADebugging CICS/ESA Java programs

OS/390 bytecode binder’s JDK 1.1.6 supporthpj command-resource

Debugging CICS/ESA Java programsBefore you can debug CICS Java programs, you must prepare the CICSenvironment as follows:1. Refresh CICS definitions for the debugger. You can find these definitions in the

EQACCSD member of the debugger’s SEQASAMP data set. Also refer to theDebug Tool Installation manual for customization information for CICS/ESA.

2. Concatenate the debugger’s load library and the Language Environmentrun-time library to DFHRPL.

3. Set up, Configure, and Start CICS TCP/IP. For a detailed explanation on howto start TCP/IP in CICS, see CICS TCP/IP Socket Interface Guide andReference.

4. Start the debugger daemon at the workstation which includes the setting ofenvironment variables. If your Java source files are at the workstation, set theIVJ_DBG_PATH environment variable at the workstation. See related tasks formore information on how to start the debugger daemon at the workstation.

5. Run the CICS Java executable which was built with -g and-lerunopts=“test(,,,VADTCPIP&wkst_id%portid:*)”. wkst_id is the numeric IPaddress of your workstation or the TCP/IP name of your workstation. portid isthe TCP/IP port ID (this is optional and defaults to 8000). If specified, thevalue must match the portid value that was specified when the debuggerdaemon was started.If some of the Java source files are at the host, the Java executable must havebeen built with the ENVAR run-time option in -lerunopts. See relatedinformation for more instructions on building CICS/ESA Java Programs forDebugging.

Running the CICS Java executable will initiate a debugging session. This CICS Javaexecutable and any of the Java DLLs that it calls can be debugged if they werebuilt with the -g option (javac and hpj commands).

Additional information about using the debugger is found in the onlineinformation for the Debugger for ET/390 component.


Building OS/390 Java DLLs in PDSE membersBuilding CICS Java programsBuilding CICS/ESA Java programs for debugging

72 ET/390

Running CICS Java programsAccessing Java resource files under CICSPreparing run-time environment to access Java DLLs under CICS/ESA



74 ET/390

Chapter 9. Building and running Java applications usingVisualAge for Java

Connecting to OS/390 from VisualAge for Java

Logging on to OS/390When you use the VisualAge for Java IDE to bind and run your OS/390 Javaapplications, you have to provide OS/390 logon information. You can save logonIDs and passwords for the host sessions that you want to use, and they will besaved for approximately 6 hours. To provide the OS/390 logon information, followthese steps:1. Select Workspace...Tools...ET/390...Logon Data to start up the dialog window.2. In the OS/390 Logon Data window, select the host session from the drop-down

list.Note:v If you do not see the session that you want, click Cancel to close the window

and add the OS/390 host session. See related information on how to do this.v If VisualAge for Java automatically opened this logon dialog for you because

you did not save the logon data before selecting an ET/390 action, the hostsession ID would have been selected for you.

3. Enter your logon ID and password in the entry fields.4. Click Save to save the logon data.

ET/390 will automatically perform the logon for you when you select the ET/390actions.

Note: You can build CICS Java programs from the IDE, but you cannot invokeCICS Java programs from the IDE.

OS/390 Java development at the workstationET/390 propertiesInheritance of ET/390 properties

Adding OS/390 host sessionRefreshing OS/390 host sessionLogging off from OS/390Compiling OS/390 interpreted Java applicationsGetting started with the building of OS/390 Java executables

ET/390 Java Install Data filehpj command options in ET/390 properties

Adding OS/390 host sessionWhen you use the VisualAge for Java IDE to bind and run your OS/390 Javaapplications, you have to provide the OS/390 host session’s information to


VisualAge for Java. When you install the product on the host, the host session’sinformation in the ET/390 Java Install Data file is created by the SystemProgrammer. When you add the host session, ET/390 downloads a copy of theET/390 Java Install Data file to the workstation and permanently saves a copy of itfor your ET/390 development work. It is likely that you only have to add theOS/390 Host Session once before you use the host session and never have torefresh it afterwards. See related references for more information on the ET/390Java Install Data file. To add the OS/390 host session, follow these steps:1. Select Workspace...Tools...ET/390...Host sessions to open the ET/390 Host

Sessions window.2. The host session should not be listed in the table in the ET/390 Host Sessions

window. Click Add and the ET/390 Add Host Session window opens.3. Fill in the following:

v The Host Session IDThis value is case-sensitive and has to match the host session name in theET/390 Java Install Data file (@@HPJHOSTNAME tag).

v The TCP/IP addressIf this is not specified, it defaults to the host session ID.

v The full path and file name of the ET/390 Java Install Data file.See your system programmer if you do not know this information.

v The FTP ID and password that will be used to download the file4. Click Retrieve to retrieve the file from the host and display the contents of the

ET/390 Java Install Data file. The ET/390 Java Install Data window opens.5. You can scroll to view the contents of the file. You cannot edit the file. If you

want to change the contents of the file, you have to do it on the host. If youchange the file’s contents after you have displayed its contents, make sure thatyou do another Retrieve to download the new copy of the file.

6. Click Close to close the window and return to the ET/390 Add Host Sessionwindow.

7. Click Add to close the window and store the information in VisualAge for Java.The host session has been added and you can see it listed in the table in theET/390 Host Sessions window.

8. Click Done to close the ET/390 Host Sessions window.


Logging on to OS/390Refreshing OS/390 host sessionLogging off from OS/390Compiling OS/390 interpreted Java applicationsGetting started with the building of OS/390 Java executables


76 ET/390

Refreshing the OS/390 host sessionIf the information in the ET/390 Java Install Data file on the host has changed, youhave to refresh the copy of this information in VisualAge for Java. To refresh theOS/390 host session, follow these steps:1. Select Workspace...Tools...ET/390...Host sessions to open the ET/390 Host

Sessions window.2. The host session is listed in the table in the ET/390 Host Sessions window.

Select the host session that you want to refresh and click Refresh. The ET/390Refresh Host Session window opens.

3. Update the following:v Host Session ID

This value is case-sensitive and has to match the host session name in theET/390 Java Install Data file (@@HPJHOSTNAME tag).

v TCP/IP addressIf this is not specified, it defaults to the host session ID.

v The full path and file name of the ET/390 Java Install Data file.See your system programmer if you do not know this information.

v The FTP ID and password that will be used to download the file4. Click Retrieve to retrieve the file from the host and display the contents of the

ET/390 Java Install Data file. The ET/390 Java Install Data window opens.5. You can scroll to view the contents of the file. You cannot edit the file. If you

want to change the contents of the file, you have to do it on the host. If youchange the file’s contents after you have displayed its contents, make sure thatyou do another Retrieve to download the new copy of the file.

6. Click Close to close the window and return to the ET/390 Refresh Host Sessionwindow.

7. Click Refresh to close the window and store the information in VisualAge forJava. The host session has been refreshed and you can see the updated hostsession listed in the table in the ET/390 Host Sessions window.

8. Click Done to close the ET/390 Host Sessions window.

Note: If you want to delete a host session, use the Delete button in the ET/390Host Sessions window.


Logging on to OS/390Logging off from OS/390Compiling OS/390 interpreted Java applicationsGetting started with the building of OS/390 Java executables


Chapter 9. Building and running Java applications using VisualAge for Java 77

Logging off from OS/390When you use the VisualAge for Java IDE to bind and run your OS/390 Javaapplications, ET/390 automatically does the log on and off from the OS/390 hostsession.

Note: You can build CICS Java programs from the IDE, but you cannot invokeCICS Java programs from the IDE.


Logging on to OS/390Refreshing OS/390 host sessionCompiling OS/390 interpreted Java applicationsGetting started with the building of OS/390 Java executables


Creating projects for OS/390 Java applicationsIn the VisualAge for Java’s IDE, create a project for OS/390 Java applications likeany other Java application that you want to run at the workstation. However,when you are creating a package you should not select default package. ET/390actions do not run on default packages.

OS/390 Java development at the workstationET/390 properties

Logging on to OS/390Adding OS/390 host sessionGetting started with the building of OS/390 Java executablesCreating a projectCreating a packageCreating a classImporting files from the file system


78 ET/390

Building custom JLLs

Building custom JLLs with ET/390When building JLLs using ET/390, the tool will create by default one JLL per Javapackage. In many cases this model is not satisfacatory. It is important to have theflexibility to decide how many JLLs you want to create for a given project, andwhich classes to build into a given JLL.

By default, ET/390 will add all the classes in a Java package to a JLL, but you caninclude other classes into this JLL by adding an -include statement in the Otherbind options text field in the Advanced Bind Options properties panel for the Javapackage. Similarly, you can exclude some of the classes in the package from theJLL by using an -exclude statement.

For more information about the -include and -exclude options of the hpjcommand, refer to the related references at the bottom of this page.

An example using the VisualAge for Java IDELet’s consider a simple example of a project containing 3 packages. The projectRecJava contains the following packages:v com.ibm.recordv com.ibm.record.ctypesv com.ibm.record.util

By default, ET/390 will create 3 JLLs, one for each package. However, we want tocreate just one JLL containing all the classes in the project. To do this, you woulddo the following:1. In the VisualAge for Java Workbench, right-click on the RecJava project, and

from the pop-up menu click Tools > ET/390 > Properties.

2. In the Export and Bind Options properties panel, set Mount point on hostandMounted directory for class filesfor the RecJava project as follows:v Mount point on host: /usr/ts12345/v Mounted directory for class files: X:\recjava where X: is a binary NFS

mounted drive.3. Set all the other options in the Properties Panels as required, and click OK to

save your changes.4. In the VisualAge for Java Workbench, export all the class files in the project to

X:\recjava by right-clicking on the RecJava project and selecting Export fromthe pop-up menu.

5. In the Workbench, right-click the com.ibm.record package, and from the pop-upmenu click Tools > ET/390 > Properties.

6. Go to the Advanced Bind Options page, and add the following statement in theOther bind options text field:-include=com.ibm.record.ctypes.* -include=com.ibm.record.util.*.

7. In the Workbench, right-click the com.ibm.record package, and from the pop-upmenu click Tools > ET/390 > Export and Bind.A JLL containing all the classesin the project will be built.

This is a simple example, but using this method you can build your customizedJLLs using the VisualAge for Java IDE. When using this method, you should notethe following:


v If you export your classes to a different location than the one specified in theExport and Bind Session properties panel, then you must add this location to theBind CLASSPATH field in the Export and Bind Session properties panel inorder for ET/390 to find these classes at build time.

v If you build your JLLs into a PDSE, make sure that you add the necessary -aliasoptions of the hpj command to the Other bind options text field in theAdvanced Bind Options properties panel in addition to the -include and-exclude options of the hpj command.

-alias-exclude=name | -include=name

Building interpreted Java applications for OS/390

Compiling OS/390 interpreted Java applicationsWhen you are working in the VisualAge for Java IDE, your Java source code iscompiled when you perform a Save. However, if you want to run the Javabytecode in the OS/390 JVM, you have to export the bytecode to an nfs mounteddrive outside of the IDE, as follows:

Export the Java bytecode to the host

1. In a DOS window, do a net useto access the HFS on the OS/390 host.2. Select the Java package or class that you want to run.3. From the VisualAge for Java IDE, select File and then Export from the menu

bar.4. In the SmartGuide, select Export bytecodeand export the code to the mounted

drive for the HFS.


Logging on to OS/390Adding OS/390 host sessionRefreshing OS/390 host sessionLogging off from OS/390Compiling OS/390 interpreted Java for debuggingRunning Java bytecode in the OS/390 JVMDebugging Java bytecode in the OS/390 JVM


Compiling OS/390 interpreted Java for debuggingIf you use the javac command in the OS/390 shell to compile your code fordebugging, you can set breakpoints and step through your source code without

80 ET/390

using any compiler options. Use the -g compile option if you want to examinelocal, class instance and static variables while debugging. For example, compilehelloWorld as follows:javac -g helloWorld

Java source filesJava source files are required for debugging. For UNIX System Services, the sourcecan either be on host or workstation. For CICS, the source must be on theworkstation.

The debugger searches for Java source files in the following locations:1. Paths in the environment variable IVJ_DBG_REMOTE_SEARCH_PATH (if set).

For example, the variable can be set like this:/home/user/project/dir1;/home/user/project/dir2;This variable is set on Windows NT under System Properties. This variable isused to search the HFS directories and partitioned datasets on the OS/390 hostfor a requested source file. If more than one directory is specified, the namesmust be separated by a semicolon.

2. The file name specified at compile time.3. Paths in the environment variable IVJ_DBG_PATH (if set). For example, the

variable can be set like this:C:\project\dir1;C:\project\dir2;This variable is set on Windows NT under System Properties. This variable isused to locate source files on the workstation. If the source file cannot belocated in any of the above directories, a dialog box opens requesting the pathname for the source file. The path name you enter is searched for the sourcefile.

Refer to OS/390 UNIX documentation for more details on the use of the javaccommand.


Compiling OS/390 interpreted Java applicationsRunning Java bytecode in the OS/390 JVMDebugging Java bytecode in the OS/390 JVM

Building OS/390 Java executables and DLLs

Getting started with the building of Java executablesIf you are building OS/390 Java executables from the VisualAge for Java IDE forthe first time, follow these steps:1. Create Projects for OS/390 Java Applications.2. Create Java classes, enter your Java code, and save the classes. You can also

import Java code into the package. See related tasks for instructions on how toimport code.

3. Find out the following information:v Host session that you want to usev ET/390 Java Install Data file path and file name on the host session that you

want to use for the ET/390 bind and run actions.


v Your FTP ID and password, which will be used to download the ET/390Java Install Data file from the host.

v Your host session logon ID and password.4. Add OS/390 host session.5. Log on to OS/390.6. Build OS/390 Java executables.7. Run OS/390 Java executables.

OS/390 Java development at the workstationOS/390 Java executablesET/390 propertiesInheritance of ET/390 properties

Changing ET/390 propertiesCreating a projectCreating a packageCreating a classImporting files from the file system


Building OS/390 Java executablesYou can build OS/390 Java executables from the VisualAge for Java IDE. Theexport phase of the ET/390 export and bind action automatically creates a newversion for the exported classes. This is to keep track of the classes that have beenexported so that a file that has not changed will not be exported again the nexttime the ET/390 export and bind action is selected.

Note: If you want to explicitly force the export of a particular class that has notchanged since it was last exported, you will have to create an open edition of theclass by selecting the class, clicking mouse button 2, and then selectingManage...Create open edition.

Before doing the build, set the ET/390 properties as follows:1. Make sure that you have added the host session that you want to use for your

ET/390 actions. See related tasks for more information on how to do this.2. Do a net use to access the host’s HFS.3. Select the package and click mouse button 2.4. From the pop-up menu, select Tools...ET/390...Properties.5. In the ET/390 Properties select the Export and Bind Session panel in the tree

on the left side of the window. The panel opens up on the right side of thewindow.

6. In the Export and Bind Session panel, set the Host Session, Option set,Mount point on host, and Mounted directory for class files. Also set otheroptions that you require.Note: When you are building the Java executable in a PDSE member, specify a

82 ET/390

fully qualified PDSE name in Directory for executable or DLL (for example,//’FRED.PDSE.LOAD’). The member name is specified in the Bind Optionspanel.

7. In the ET/390 Properties select the Bind Options panel in the tree on the leftside of the window. The panel opens up on the right side of the window.

8. In the Bind Options panel, select Build a Java executable option. SpecifyMain class namein the Bind Options panel if there is more than one mainclass in the package. Also set other options that you require.If you want to force an export of all the bytecode files to the host (even if theyhave not changed since the last export) and rebind all the classes to generate anew Java executable, replacing the old one, select Rebuild all in this panel.If you want to explicitly force the export of a particular class, see the note atthe top of this page.

9. In the ET/390 Properties select the Advanced Bind Options panel in the treeon the left side of the window. The panel opens up on the right side of thewindow.

10. In the Advanced Bind Options panel, set the options that you require.11. Click OK to update and close the ET/390 Properties window.

To build the OS/390 Java executable, follow these steps:1. Select the package and click mouse button 2.2. From the pop-up menu, select Tools...ET/390...Export and bind.

The Java executable is created on the host. Build messages appear in the logwindows.


Logging on to OS/390Adding OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesBuilding OS/390 Java DLLsBuilding an OS/390 Java executable or DLL in two stepsBuilding OS/390 Java executables and DLLs for debuggingBuilding Java executables and DLLs for tracingRunning OS/390 Java executablesChanging ET/390 properties (IDE)


Building OS/390 Java DLLsYou can build OS/390 Java DLLs from the VisualAge for Java IDE. The exportphase of the ET/390 export and bind action automatically creates a new versionfor the exported classes. This is to keep track of the classes that have been


exported so that a file that has not changed will not be exported again the nexttime the ET/390 export and bind action is selected.

Note: If you want to explicitly force the export of a particular class that has notchanged since its last export, you will have to create an open edition of the classby selecting the class, clicking mouse button 2, and then selecting Manage...Createopen edition.

Before doing the build, set the ET/390 properties as follows:1. Make sure that you have added the host session that you want to use for your

ET/390 actions. See related tasks for more information on how to do this.2. Do a net use to access the host’s HFS.3. Select the package and click mouse button 2.4. From the pop-up menu, select Tools...ET/390...Properties.5. In the ET/390 Properties select the Export and Bind Session panel in the tree

on the left side of the window. The panel opens up on the right side of thewindow.

6. In the Export and Bind Session panel, set the Host Session, Option set,Mount point on host, and Mounted directory for class files. Also set otheroptions that you require.Note: When you are building the Java DLL in a PDSE member, specify a fullyqualified PDSE name in Directory for executable or DLL (for example,//’FRED.PDSE.DLL’). The member name is specified in the Bind Optionspanel.

7. In the ET/390 Properties select the Bind Options panel in the tree on the leftside of the window. The panel opens up on the right side of the window.

8. In the Bind Options panel, select Build a Java DLL option. Also set otheroptions that you require.If you want to force an export of all the bytecode files to the host (even if theyhave not changed since the last export) and rebind all the classes to generate anew Java DLL, replacing the old one, select Rebuild all in this panel.If you want to explicitly force the export of a particular class, see the note atthe top of this page.

9. In the ET/390 Properties select the Advanced Bind Options panel in the treeon the left side of the window. The panel opens up on the right side of thewindow.

10. In the Advanced Bind Options panel, set the options that you require.11. Click OK to update and close the ET/390 Properties window.

To build the OS/390 Java executable, follow these steps:1. Select the package and click mouse button 2.2. From the pop-up menu, select Tools...ET/390...Export and bind.

The Java DLL is created on the host. Build messages appear in the log windows.

OS/390 Java development at the workstationOS/390 Java Dynamic Link Libraries (DLLs)ET/390 propertiesInheritance of ET/390 properties

84 ET/390

Logging on to OS/390Adding OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesBuilding an OS/390 Java executable or DLL in two stepsBuilding OS/390 Java executables and DLLs for debuggingBuilding Java executables and DLLs for tracingChanging ET/390 properties

ET/390 Java Install Data filehpj Command Options in ET/390 properties

Binding Language Environment run-time optionsIf you want to bind Language Environment run-time options in the Javaexecutable, (for the package) select Bind run-time options in the ET/390properties’ Bind Options panel and make sure that you have set the run-timeoptions in the Run-Time Options, Advanced Run-Time Options, DebuggingOptions, and Tracing Options panels. Note: The set of development or productionoptions selected for the bind depends on the Option setselection in the ET/390properties’ Run Executable Session panel.

OS/390 Java development at the workstationET/390 propertiesInheritance of ET/390 propertiesOS/390 Java executables

Logging on to OS/390Adding OS/390 host sessionRefreshing OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesBuilding an OS/390 Java executable or DLL in two stepsBuilding OS/390 Java executables and DLLs for debuggingBuilding Java executables and DLLs for tracingChanging ET/390 properties


Building an OS/390 Java executable or DLL in two stepsUsually you would build your Java executable and DLL with a single ET/390export and bind action. However, if you want to use the ET/390 export and bindaction to generate partially bound objects (.o, .mo, .ro files), and later bind theseobjects into a Java executable or DLL, you can follow these steps:1. With VisualAge for Java, build the .o files by specifying Object files only in the

ET/390 properties’ Advanced Bind Options panel. Select a project or a packageand select ET/390 export and bind action. The bytecode files are automaticallyexported to host and the .o files are created on the host. If you also want to


export the Java source files, you have to do an net useto the OS/390 HFS andselect File...Export from the menu bar in the IDE so that your Java source fileswill be exported to the host.

2. Using the high performance compiler in the OS/390 shell, or using the systembinder directly, bind the .o files into the Java executable or DLL. This stepcannot be done at the workstation. See related topics for more information onbuilding with .o files.

OS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applicationsBuilding OS/390 Java executables and DLLs with .o files

Building OS/390 Java executablesBuilding OS/390 Java DLLsChanging ET/390 propertiesIdentifying OS/390 unsupported Java code

hpj command

Identifying OS/390 unsupported Java codeWhen you are building the OS/390 Java executable or DLL in the VisualAge forJava IDE,1. Select the project or package. Click mouse button 2 and select

Tools...ET/390...Properties.2. Select Verify portability of code in the ET/390 properties’ Bind Optionspanel.

You also have to select Both Java and class filesand specify Local directory forJava files in the Export and Bind Session panel.

3. Select the project or package. Click mouse button 2 and selectTools...ET/390...Export and bind.

After the bind, use a browser to view the _StartHere.htm file which is in thedirectory that you specified for Local directory for Java files. The file contains alist of unsupported Java code in your application. Also note that ET/390 verifiesyour code for either the OS/390 UNIX environment or the CICS/ESA environment.Your selection of CICS application in the Bind Options panel determines theenvironment for the verification.


Logging on to OS/390Adding OS/390 host sessionRefreshing OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executables

86 ET/390


Changing ET/390 propertiesUse the options in the ET/390 properties panels to control the following ET/390actions that you want to perform with your Java code:v Export and bind Java bytecode into OS/390 executable codev Run the OS/390 Java executable in an OS/390 shellv Run Java bytecode in the OS/390 JVMv Debug the Java bytecode that is running in the OS/390 JVMv Debug the OS/390 Java executable that is running the OS/390 shell

To open the ET/390 properties panel to change options, follow these steps:1. Select the object (project, package, or class).2. Click mouse button 2 to get a menu.3. Select Tools...ET/390... Properties.

To view or change options, select the panel in the tree and the options will bedisplayed in the right panel. To get help information while you are updatingproperties, press F1. Once you have opened the ET/390 properties panels, yourchanges for all the panels are posted when you click OK.

If you have never changed the ET/390 properties for the selected object, thesettings are inherited. See the details on the inheritance of Properties in the relatedtopics.


Logging on to OS/390Adding OS/390 host sessionRefreshing OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesBuilding OS/390 Java DLLs


Building OS/390 Java executables and DLLs for debuggingYou can build Java executables and DLLs for debugging from the VisualAge forJava IDE using the ET/390 export and bind action. This build is the same as anyother Java executable or DLL’s build except change the following ET/390properties for the package before you perform the action:


v Select Both Java and class filesfor exporting in the ET/390 Properties Exportand Bind Session panel. Enter the local drive where source is to be exported inthe Local drive for Java files entry field.

v Select Data for debug and traceand With hooks in the ET/390 Bind Optionspanel.

OS/390 Java development at the workstationET/390 propertiesInheritance of ET/390 propertiesOS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)

Logging on to OS/390Adding OS/390 host sessionRefreshing OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesBuilding OS/390 Java DLLsBuilding an OS/390 Java executable or DLL in two stepsBuilding Java executables and DLLs for tracingChanging ET/390 properties (IDE)


Building OS/390 Java executables and DLLs for tracingYou build Java executables and DLLs for tracing from the VisualAge for Java IDEusing the ET/390 export and bind action. This build is the same as any other Javaexecutable or DLL’s build except change the following ET/390 properties for thepackage before you perform the action:v Select Data for debug and traceand With hooks in the ET/390 Bind Options

panel.


Logging on to OS/390Adding OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesCreating a trace fileTracing a specific DLLStarting the Performance Analyzer to analyze a trace fileDownloading the trace file from the hostChanging ET/390 Properties (IDE)

88 ET/390


Binding Java resource files into Java executables or DLLsTo include Java resource files into the Java executable or DLL, select Includeresources in the ET/390 Bind Options panel. Note that this option is enabled justat the package level. A jar file containing all the resources associated with theproject is created and uploaded to the host. The jar file containing the resources forthe project is created and uploaded only if some of the resource files have beenmodified. To force the creation and upload of the jar file, select Rebuild all in theBind Options panel.

To include Java resource files, do the following:1. Select the package for which you want to include resource files.2. Click the mouse button 2. From the pop-up menu, selectTools...ET/390...Properties.3. In the ET/390 Properties dialog, select the Export and Bind Session panel and goto Bind Options. The Bind Options panel will open up on the right side of thewindow.4. Select Include resources.5. Click OK to update, and close the ET/390 Properties window.The name of the jar file is going to be ProjectX_resources.jar, where ProjectX is thename of the project which contains the selected package. This jar file will beexported to the host into the root directory,where the root directory is obtained by combining the Mount point on host andMounted directory forclass files from the Export and Bind Session panel.Example: If Mount point on host is /home/ts123456 and Mounted directory forclass files is W:\current then the root directory will be /home/ts123456/current.Build the Executable or DLL as usual by selecting Tools...ET/390...Export and Bind.


Getting started with the building of OS/390 Java executablesChanging ET/390 properties (IDE)

Building Java programs to run under CICS/ESA

Building Java executables and DLLs to run under CICS/ESAYou can build CICS/ESA Java Programs from VisualAge for Java IDE. However,you cannot initiate the running of your CICS Java executable from the IDE.

Building Java executables


1. Define Resources to CICS/ESA.2. Set the ET/390 properties. This build is the same as any other Java executable’s

build except for the following ET/390 properties settings for the package:v Select CICS application and Refresh CICS program in the ET/390

properties’ Bind Options panel.Note: For Refresh CICS programto work, the @@HPJCICSEXCI tag must bespecified in the ET/390 Java Install Data file. For details about this tag, referto the ET/390 Java Install Data file topic in the related references at thebottom of this page.

v Specify fully qualified PDSE name in Directory for executable or DLL in theET/390 properties’ Export and Bind Session panel.

v Specify PDSE member name in the ET/390 properties Bind Options panel.v If you want to pass Language Environment run-time options, you must bind

the run-time options by selecting Bind run-time options in the ET/390properties’ Bind Options panel and make sure that you have set the run-timeoptions in the Run-Time Options, Advanced Run-Time Options panels.

3. Select the ET/390 export and bind action to build the CICS Java executable.

Building Java DLLs

1. You can build Java DLLs to run under CICS/ESA. This build is the same asany other Java DLL’s build except for the following ET/390 properties settingsfor the package:v Select CICS application and Refresh CICS program in the ET/390


v Specify a fully qualified PDSE name in Directory for executable or DLL inthe ET/390 properties’ Export and Bind Session panel.

v Specify PDSE member name in the ET/390 properties’ Bind Options panel.2. Select the ET/390 export and bind action to build the CICS Java DLL.



OS/390 bytecode binder’s JDK 1.1.6 supporthpj commandET/390 Java Install Data file

Building CICS/ESA Java executables and DLLs for debuggingYou can build CICS/ESA Java Programs from VisualAge for Java IDE. However,you cannot initiate the running of your CICS Java executable from the IDE.

Build Java Executable

90 ET/390

1. Define resources to CICS/ESA.2. Set the ET/390 properties. This build is the same as any other Java executable’s

build except for the following ET/390 properties settings for the package:v Select CICS application and Refresh CICS program in the ET/390


v Specify fully qualified PDSE name in Directory for executable or DLL in theET/390 properties’ Export and Bind Session panel.

v Specify PDSE member name in the ET/390 properties Bind Options panel.v Select Data for debug and trace and With hooksin the ET/390 properties’

Bind Options panel.v You must bind the Language Environment run-time options by selecting

Bind run-time options in the ET/390 properties’ Bind Options panel andmake sure that you have set the run-time options in the Run-Time Options,Advanced Run-Time Options, and Debugging Options panels.

3. Select the ET/390 export and bind action to build the CICS Java executable.

Build Java DLL

1. Set the ET/390 properties. You can build Java DLLs to run in debug modeunder CICS/ESA. This build is the same as any other Java DLL’s build exceptfor the following ET/390 properties settings for the package:v Specify a fully qualified PDSE name in Directory for executable or DLL in

the ET/390 properties’ Export and Bind Session panel.v Specify PDSE member name in the ET/390 properties’ Bind Options panel.v Select Data for debug and trace and With hooksin the ET/390 properties’

Bind Options panel.2. Select the ET/390 export and bind action to build the CICS Java DLL.



OS/390 bytecode binder’s JDK 1.1.6 supporthpj commandET/390 Java Install Data file

Running OS/390 Java applications from the IDE

Running Java bytecode in the OS/390 JVMWhen you are working in the VisualAge for Java IDE, you can run your project’sJava bytecode that has main methods in the OS/390 JVM as follows:1. Compile your Java program. Refer to related tasks for more information on

how to do this.


2. Set the host session and CLASSPATH in the ET/390 properties’ Run MainSessionpanel.a. Select the Java package or class that you want to run.b. Click right mouse button and select ET/390 and then Properties to open the

Properties panels.c. In the displayed tree structure in the left panel, select Run Main Session to

open the panel.d. Select the Host Session that you want to run the Java bytecode. If the host

session that you want to use is not listed, click Cancel to close the ET/390properties panels and add the host session before attempting this task.

e. In the CLASSPATH entry, type the host HFS directory where you havepreviously exported the code so that the OS/390 JVM can find the Javabytecode.

f. Click OK to update and close the properties panels.3. Run the Java Bytecode on the remote host

a. In the VisualAge for Java IDE, select the Java package or class that youwant to run.

b. Click right mouse button and select ET/390and then Run Main to run thecode. If you have not specified the OS/390 logon ID and password for thehost session, you will be prompted to enter the information before thesystem connects to the host.

Remote run information is displayed in the Log windows.


Logging on to OS/390Adding OS/390 host sessionLogging off from OS/390Compiling OS/390 interpreted Java applicationsCompiling OS/390 interpreted Java for debuggingChanging ET/390 properties


Debugging Java bytecode in the OS/390 JVMWhen developing OS/390 Java applications in the VisualAge for Java IDE, you candebug interpreted Java as it runs in the OS/390 JVM by following these steps:1. Make sure that the Java bytecode that you want to debug was compiled for

debugging. See related tasks for more information on how to do this.2. Make sure that you have added the host session that you want to use for your

ET/390 actions. See related tasks for more information on how to do this.3. Set the the following ET/390 properties’ Run Main Session and its Run-Time

Options panels as described in the related tasks on running Java bytecode inthe OS/390 JVM.

92 ET/390

Note:v The Run Main Session panel identifies the host session that you are using

and whether the development or production version of the options are to beused to run the Java bytecode.

v You must have exported your source files to a local directory by selecting theFile...Export menu items in the IDE. See related information on compilingOS/390 interpreted Java for Debugging for additional instructions on how todo this. Specify the path to find the source files in the Local directory forJava files in the Run Main Session panel. The debugger uses this location tofind your source files.

4. Select the project or package that you want to debug.5. Click mouse button 2 and from the menu, select Tools...ET/390...Debug main.

The workstation debugger daemon is started for you. When the workstationdebugger daemon is started, a window is opened. Note:Do not close this window.You can minimize it, but closing the window would bring down the daemon, andhost debugger will not be able to connect to it. When the Java bytecode runs in theOS/390 JVM, debugging is started.


Logging on to OS/390Adding OS/390 host sessionLogging off from OS/390Compiling OS/390 interpreted Java for debuggingRunning Java bytecode in the OS/390 JVMChanging ET/390 properties


Running OS/390 Java executablesTo run the OS/390 Java executable from the VisualAge for Java IDE, follow thesesteps:1. Make sure that you have added the host session that you want to use for your

ET/390 actions. See related tasks for more information on how to do this.2. Set the following ET/390 properties panels: Run Executable Session, Run-Time

Options, Advanced Run-Time Options, and Tracing Options (if required). Seerelated tasks on how to change ET/390 properties. Note: The Run ExecutableSession panel identifies the host session that you are using and whether thedevelopment or production version of the options are to be used to run theexecutable.

3. Select the project or package that you want to run.4. Click mouse button 2 and from the menu, select Tools...ET/390...Run

executable.



Logging on to OS/390Adding OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesBuilding an OS/390 Java executable or DLL in two stepsChanging ET/390 properties (IDE)


Debugging OS/390 Java executablesTo debug an OS/390 Java executable from the VisualAge for Java IDE, follow thesesteps:1. Make sure that the Java executable and any Java DLLs (called by the

executable) that you want to debug are built for debugging. See related tasksfor more information on how to do this.

2. Make sure that you have added the host session that you want to use for yourET/390 actions. See related tasks for more information on how to do this.

3. Set the following ET/390 properties panels: Run Executable Session, Run-TimeOptions, Advanced Run-Time Options, and Debugging Options. See relatedtasks on how to change ET/390 properties.Note:v The Run Executable Session panel identifies the host session that you are

using and whether the development or production version of the options areto be used to run the executable.

v You must have exported your source files to a local directory when you builtyour Java executable and DLLs. At run time, the ET/390’s debugger uses theLocal directory for Java files in the Export and Bind Session panel to findyour source files.

4. Select the project or package that you want to debug.5. Click mouse button 2 and from the menu, select Tools...ET/390...Debug

executable.

The workstation debugger daemon is started for you. Note:Do not close thiswindow. You can minimize it, but closing the window would bring down thedaemon, and host debugger will not be able to connect to it. When the executableruns on the host, debugging is started.


94 ET/390

Logging on to OS/390Adding OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesBuilding OS/390 Java executables and DLLs for debuggingChanging ET/390 properties (IDE)


Tracing OS/390 Java executables and DLLsRun Java executables for tracing from the VisualAge for Java IDE using the ET/390run executable action. The following changes to the ET/390 properties panels arerequired for the package:v Select Generate trace and Mounted directory for trace file in the ET/390

properties’ Run Executable Session panel.v Specify the tracing options in the ET/390 properties’ Tracing Options panel.

When you trace a Java executable, you also trace any Java DLLs that it calls,provided they were built for tracing.

Note: Tracing is disabled when you debug your Java executable; that is, if youselect the ET/390 debug executable action and the Generate trace option isselected in the Run Executable Session panel, no trace files will be generated.

See related tasks for more information on how to start the Performance Analyzerto analyze a trace file.

OS/390 Java development at the workstationOS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)ET/390 PropertiesInheritance of ET/390 Properties

Logging on to OS/390Adding OS/390 host sessionLogging off from OS/390Getting started with the building of OS/390 Java executablesBuilding Java executables and DLLs for tracingChanging ET/390 propertiesCreating a trace fileTracing a specific DLLStarting the Performance Analyzer to analyze a trace fileDownloading the trace file from the host



Building Java executables and DLLs using JCLThe following is a JCL example that is used to build a Java executable://<job card>//*//* Example of building a Java executable consisting of 2 classes,//* Main and Class1, both in the package ExeXmp.//*//* Assume that the following has been performed to generate//* the object decks for the JLL.//*//* hpj -c -d=<hfs root> -exe JLLExe.Main JLLExe.Class1//*//* The object decks now need to be bound into a Java executable.//* The object decks to be bound consists of the object decks for each//* class as well as 2 additional object decks generated by hpj//* that must be INCLUDED first when building the module.//* These object decks are put in the directory where the main//* object deck for the executable will be written - in this case//* Main.o, and are named using the name of the main class with an//* extension of 'mo' and 'ro'. In our example, these parts are//* called Main.mo and Main.ro.//* The entry point of all HPJ DLL's and all HPJ executables is//* CEESTART.//*//PM3LKED EXEC PGM=IEWL,// PARM='MAP,RENT,MSGLEVEL=4,CASE=MIXED,COMPAT=CURR'//SYSLMOD DD DSN=<output data set>,DISP=SHR//SYSLIB DD DSN=<language environment high-level qualifier>.SCEELKED,DISP=SHR// DD DSN=<language environment high-level qualifier>.SCEELKEX,DISP=SHR// DD DSN=<language environment high-level qualifier>.SCEECPP,DISP=SHR//SYSLIN DD *

INCLUDE '<hfs root>/ExeXmp/Main.mo'INCLUDE '<hfs root>/ExeXmp/Main.ro'INCLUDE '<hfs root>/ExeXmp/Main.o'INCLUDE '<hfs root>/ExeXmp/Class1.o'ENTRY CEESTARTNAME 'EXEXMP'(R)

/*//SYSPRINT DD SYSOUT=*

The following is a JCL example that is used to build a Java DLL://<job card>//*//* Example of building a Java DLL (jll) consisting of 2 classes,//* Class1 and Class2, both in the package JLLXmp.//*//* Assume that the following has been performed to generate//* the object decks for the JLL.//*//* hpj -c -d=<hfs root> -jll JLLXmp.Class1 JLLXmp.Class2//*//* The object decks now need to be bound into a Java DLL. The set//* of object decks to be bound consists of the object decks for each//* class as well as an additional object deck generated by hpj//* that must be INCLUDED first when building the module.//* The entry point of all HPJ DLL's and all HPJ executables is//* CEESTART.//* An ALIAS card for each package present in the JLL must also be//* specified if the JLL is to be used under CICS« TS 1.3//* If you are not using CICS, you can choose to either bind your//* JLL into the HFS file system or you can bind the JLL into a PDSE//* and create an external link from the HFS file system to your JLL//* (you may wish to bind into a PDSE if you want to put your//* resultant JLL into the dynamic LPA).//*

96 ET/390

//PM3LKED EXEC PGM=IEWL,// PARM='MAP,RENT,MSGLEVEL=4,CASE=MIXED,COMPAT=CURR'//SYSLMOD DD DSN=<output data set>,DISP=SHR//SYSLIB DD DSN=<language environment high-level qualifier>.SCEELKED,DISP=SHR// DD DSN=<language environment high-level qualifier>.SCEELKEX,DISP=SHR// DD DSN=<language environment high-level qualifier>.SCEECPP,DISP=SHR//SYSLIN DD *

INCLUDE '<hfs root>/root.bo'INCLUDE '<hfs root>/JLLXmp/Class1.o'INCLUDE '<hfs root>/JLLXmp/Class2.o'ENTRY CEESTARTALIAS 'JLLXmp.jll'NAME 'MYCLASS'(R)

/*//SYSPRINT DD SYSOUT=*


98 ET/390

Chapter 10. Overview of OS/390 bytecode binder’s JDKsupport

The OS/390 bytecode binder and run time supports a subset of JDK 1.1.6 in theOS/390 UNIX and CICS/ESA environments, as shown in the following table:

JDK Packages/Classes CICS/ESA Support OS/390 UNIX Support

java.lang Partial Partial

java.lang.reflect Full Full

java.math Full Full

java.io Partial Full

java.util Full Full

java.util.zip Partial Full

java.text Full Full

java.applet None None

java.awt, java.awt.* None None

java.beans Partial Partial

java.net None Full

java.security, java.security.* None Full

java.sql (jdbc) None Full

Enterprise Java None Full

java.rmi, java.rmi.* None Full

CICS Java API Full None

JavaSoft’s JNI Partial Partial

Enterprise Toolkit for OS/390OS/390 Java CICS/ESA support

Identifying OS/390 unsupported Java code (OS/390 Shell)Identifying OS/390 unsupported Java code (IDE)

jport utility

java.lang support under OS/390 UNIXThe following java.lang classes and methods are not supported in the OS/390UNIX environment:v java.lang.ClassLoader with the exception of

java.lang.ClassLoader.getSystemResourceAsStream()v java.lang.Compiler


v java.lang.Runtime methods:– java.lang.Runtime.traceInstructions(boolean on)– java.lang.Runtime.traceMethodCalls(boolean on)

v java.lang.Thread methods:– java.lang.Thread.setPriority()– java.lang.Thread.getPriority()



OS/390 bytecode binder’s JDK 1.1.6 supportJNI support in the OS/390 UNIX and CICS/ESA environmentsjava.beans support in the OS/390 UNIX and CICS/ESA environmentsjport utility

java.lang support in the CICS/ESA environmentThe following java.lang classes and methods are not supported in the CICS/ESAenvironment:v java.lang.Class.getResource(String)v java.lang.ClassLoader with the exception of

java.lang.ClassLoader.getSystemResourceAsStream()v java.lang.Compilerv java.lang.Object methods:

– java.lang.Object.notify()– java.lang.Object.notifyAll()– java.lang.Object.wait(long)– java.lang.Object.wait(long,int)– java.lang.Object.wait()

v java.lang.Processv java.lang.Runnablev java.lang.Runtime methods

– java.lang.Runtime.freeMemory()– java.lang.Runtime.totalMemory()– java.lang.Runtime.traceInstructions(boolean)– java.lang.Runtime.traceMethodCalls(boolean)– java.lang.Runtime.exit(int)– java.lang.Runtime.exec(String)– java.lang.Runtime.exec(String,String[])– java.lang.Runtime.exec(String[])– java.lang.Runtime.exec(String[],String[])

v java.lang.SecurityManager methods:

100 ET/390

– java.lang.SecurityManager.checkAccess(Thread)– java.lang.SecurityManager.checkAccess(ThreadGroup)– java.lang.SecurityManager.checkMulticast(INetAddress)– java.lang.SecurityManager.checkMulticast(INetAddress, byte)– java.lang.SecurityManager.getThreadGroup()

v java.lang.System methods:– java.lang.System.exit(int)

v java.lang.Threadv java.lang.ThreadGroup



OS/390 bytecode binder’s JDK 1.1.6 supportjava.lang support in OS/390 UNIXjava.lang support in the CICS/ESA environmentjava.io support in the CICS/ESA environmentjava.beans support in the OS/390 UNIX and CICS/ESA environmentsJNI support in the OS/390 UNIX and CICS/ESA environmentsjport utility

java.io support in the CICS/ESA environmentThe following java.io classes and methods are not supported in the CICS/ESAenvironment:v java.io.Filev java.io.FileReader(File)v java.io.FileReader(String)v java.io.FileWriter(File)v java.io.FileWriter(String)v java.io.FileWriter(String, Boolean)v java.io.FilenameFilterv java.io.FileInputStream(File)v java.io.FileInputStream(String)v java.io.FileOutputStream(File)v java.io.FileOutputStream(String)v java.io.FileOutputStream(String, Boolean)v java.io.PipedInputStreamv java.io.PipedOutputStreamv java.io.PipedReaderv java.io.PipedWriterv java.io.RandomAccessFile

Chapter 10. Overview of OS/390 bytecode binder’s JDK support 101




java.util.zip support in the CICS/ESA environmentThe java.util.zip package is supported in the CICS/ESA environment except for thejava.util.zip.ZipFile class.



OS/390 bytecode binder’s JDK 1.1.6 supportjava.io support in the CICS/ESA environmentjava.beans support in the CICS/ESA environmentjava.lang support in the CICS/ESA environmentJNI support in the OS/390 UNIX and CICS/ESA environmentsjport utility

java.beans support in the OS/390 UNIX and CICS/ESA environmentsThe java.beans classes and methods that are not supported in the OS/390 UNIXand CICS/ESA environments are primarily design time classes. In the OS/390shell, you can run Java programs that use beans, provided they do have anygraphical user interface.

The following java.beans methods are not supported in the OS/390 UNIX andCICS/ESA environments:v java.beans.BeanInfo

– java.beans.BeanInfo.getIcon()v java.beans.SimpleBeanInfo

– java.beans.SimpleBeanInfo.getIcon()

102 ET/390

– java.beans.SimpleBeanInfo.loadImage(String)v java.beans.PropertyEditor

– java.beans.PropertyEditor.getCustomEditor()– java.beans.PropertyEditor.paintValue(Graphics, Rectangle)

v java.beans.PropertyEditorSupport– java.beans.PropertyEditorSupport.getCustomEditor()– java.beans.PropertyEditorSupport.paintValue(Graphics, Rectangle)

v java.beans.Visibility– java.beans.Visibility.okToUseGui()

The following java.beans classes and methods have restricted support in theOS/390 UNIX and CICS/ESA environments:v java.beans.Beans

– java.beans.Beans.setDesignTime(boolean)May only be used with an argument value of false.

– java.beans.Beans.setGuiAvailable(boolean)May only be used with an argument value of false.




JNI support in the OS/390 UNIX and CICS/ESA environmentsThe following JNI support is restricted when building Java executables or DLLs torun in OS/390 UNIX and CICS/ESA environments:v DefineClass class is not supported.v CreateJavaVM class is only supported in the OS/390 UNIX environment, and it

has limited support in that only one JVM per process is supported.v DestroyJavaVM class is not supported.v Threading methods are not supported in the CICS environment because it is a

single-thread environment.




OS/390 bytecode binder’s JDK 1.1.6 supportjava.lang support in OS/390 UNIXjava.lang support in the CICS/ESA environmentjava.io support in the CICS/ESA environmentjava.beans support in the OS/390 UNIX and CICS/ESA environmentsjport utility

Java system properties for OS/390 UNIXSystem properties are available via the System.GetProperty(String s) call. For Javaexecutables and DLLs running under OS/390 UNIX, these properties are initializedfrom the following sources:v The following properties are set with the related environment variables before

running the Java Program.– user.language

Set via the environment variables: LC_ALL, LC_CTYPE or LANG.– user.timezone

Set via the environment variable TZ.– user.dir

Current working directory– user.home

Initial working directory– user.name

User ID– java.version

1.1.6– java.vendor

IBM Corporation– java.vendor.url

http://www.ibm.com/– java.home

Value of JAVA_HOME environment variable– java.class.version

45.3– java.class.path

Value of the CLASSPATH environment variable– os.name

OS/390– os.arch

390– os.version

Is the OS/390 version.– file.separator

/

104 ET/390

– path.separator:

– line.separator


Overview of OS/390 bytecode binder’s JDK support


106 ET/390

Chapter 11. Commands to build and run Java program objects

hpj command (OS/390)The Enterprise Toolkit for OS/390 allows you to build Java executables and DLLsin an OS/390 shell. You can use the hpj command to bind Java bytecode files intoa Java executable or DLL that runs in the OS/390 UNIX or CICS/ESAenvironment.

Syntaxhpj command has the following syntax:hpj {[options] inputfiles [options]}...

The options can appear before, after, or between input file names. All the optionsapply to all the input files. In the following example, the -jll, -o, -alias, -list, and-O options apply to all three classes (temp1, temp2, and temp3):hpj -jll -o=“//PDSE.LOADLIB(MEM1)”

-classpath=/home/ts123456:.:$CLASSPATH-alias=abc/staff/queryDB.jllabc.staff.queryDB.temp1 abc.staff.queryDB.temp2-list abc.staff.queryDB.temp3 -O

If the same option appears more than once, the last occurrence of the option isused.

Input filesAll input files must be on HFS except Java executables and Java DLLs, which canbe PDSE members. inputfiles may be one or more of the following:v Class names (CLASSPATH is used to find the files)

For example,hpj -o=queryEmp abc.staff.queryDB.queryMain

v Partially bound program objects (.o files)For example,hpj -o=queryEmp abc.staff.queryDB.queryMain.mo

abc.staff.queryDB.readDB.ov JAR files (.jar) containing packages or classes

For example,hpj -o=queryEmp abcstaff.jar -classpath=queryEmp.jarabcstaff.jar tells the high-performance compiler which classes to compile. Theclasses, however, must be loaded from the CLASSPATH.

v ZIP files (.zip) containing packages or classesFor example,hpj -o=queryEmp abcstaff.zip

If an input file’s name begins with a dash (-), specify “— ” before the file name.For example, if your input file is -hello.zip, specify the hpj command as follows:hpj -list -o=hello — -hello.zip

Output filesThe output files generated by the hpj command include the following:v A Java executable or Java DLL on HFS or in a PDSE memberv Partially bound program objects (.o, .mo, .ro, .bo files) on HFS


v Listing files (.lst files) on HFSv A binder map (.map file) on HFSv A script file (.link file) on HFS when the -t option is specified.

Error messages are sent to stderr.

Java executable and DLL fileThe hpj command binds classes to generate either one of the following fully boundprogram objects:v A Java executable when the -exe option is specified or when neither -jllnor -exe

is specified.v A Java DLL when the -jll option is specified.

The Java executable and DLL can be written either to HFS or to a PDSE member:v HFS

Java executable files residing on HFS can have any file names with or withoutfile extensions. The default file name for a Java executable is a.out. Java DLLfiles residing on HFS must have .jll file extensions.

v PDSE MemberTo specify a PDSE data set and member name, you must use the -o option. ForJava DLLs residing in PDSE members, you must also use the -alias option togive the member an HFS-like DLL name. For Java DLLs residing in a PDSEmember running under OE, you must specify the -t and -alias option. Javaexecutables or DLLs running under CICS must reside in PDSE members.

.o filesPartially bound program objects, .o files, are automatically generated by the hpjcommand. One .o file is created for each class. The name of the .o file is the classname. These .o files must be written to HFS. The -collapse and -d options can beused to control the placement of .o files.

.mo fileThe partially bound program object, .mo file, is automatically generated by the hpjcommand. If -jll is specified, the .mo file is not generated. When the -mainoptionis specified, a .mo file is generated (in addition to the .o file) for the specified mainclass. If -main is not specified and the -c option is specified, a .mo file is generated(in addition to the .o file) for the first class that contains a main method. The nameand placement of the .mo files is the same as that of the .o file for the main class.

.ro fileThe partially bound program object, .ro file, is automatically generated by the hpjcommand. One .ro file is generated. You can only bind the .ro file to a Javaexecutable. The name and placement of the .ro files is the same as that of the .o filefor the main class. To change the default run-time options, use the -lerunoptsoption.

.bo filesThe partially bound program object, resource.bo file, is automatically generated bythe hpj command when the -resource option is specified. One resource.bo file isgenerated for all the resource files in the specified ZIP and JAR files. Theresource.bo file is written to the -d directory (if it is specified), or the currentdirectory.

When building a Java DLL, a partially bound program object, the root.bo file, isgenerated. This file is written to the current directory or the directory pointed to

108 ET/390

by the -d option. When you build your Java DLL with a single hpj command, theroot.bo object is automatically bound to the Java DLL, and you need not beconcerned with this file.

.lst filesListings, .lst files, are generated by the hpj command when -listand/or -inlrptoptions are specified. One file is generated for each class. The name of the .lst fileis the class name. These .lst files are written to the same HFS directories as thecorresponding .o files.

.map fileThe binder map, .map file, is always generated unless both -BNOLIST and-BXREF(NO) are specified. The file is written to the same location as the Javaexecutable or DLL. However, if the Java executable or DLL is written to a PDSEmember, the .map file is written to the current directory.

.syslin fileThe .syslin file contains the list of program objects that are bound in Javaexecutable or DLL. It is generated when the -verbose option is specified. The file iswritten to the same location as the Java executable or DLL. However, if the Javaexecutable or DLL is written to a PDSE member, the .syslin file is written to thecurrent directory.

.link fileWhen the -t option is specified, the .link file is generated. It contains thecommands that generate the links of the resource file or jll file with the HFS nameto the real executable to dll module.

hpj command optionsThe optionsfor the hpj command can be entered sequentially with blank separators.

Option Default Abbreviated Form Description

— None None Signifies that the nextargument is a filename. It is usedbefore a file namethat begins with adash (-).

-alias=name None -ali =name Specifies an aliasname for the JavaDLL that is beingwritten to a PDSEmember.

-architecture=0|1|2|3 -architecture=0 -arc=0|1|2|3 Generates optimizedcode for the specifiedhardware architecturegroup.

-BLIST$type$|-BNOLIST

-BLIST(SUMMARY) None Specifies the type ofinformation to bewritten to the bindermap.

-BXREF$YES|NO$ -BXREF(NO) None Includes crossreference list ofmethods and data inthe binder map.

Chapter 11. Commands to build and run Java program objects 109


-c|-noc

-noc None -c specifies thatbytecode binding isdone to generate .ofiles and that nofurther binding takesplace to generate theJava executable orDLL. -noc specifiesthat in addition togenerating .o files,the objects are boundinto a Java executableor DLL.

-check=args -check=all -che Controls whethernormal Javarun-time checks areperformed.

-classpath=pathor-classpath path

If the option is notspecified, theclasspath is set to thebytecode binder’sJDK classes and thecontents of theCLASSPATHenvironment variable(in that order). If-classpath is notspecified and theCLASSPATHenvironment variableis not set, the JDKclasses followed bythe current directory(.) is used.

-cla Specifies paths thatare used to search forJava classes forbytecode binding. If-classpath option isspecified,CLASSPATH is set tothe specified classesfollowed by the JDKclasses.

-collapse| -nocollapse

-nocollapse -col |-nocol Specifies that all .oand .lst files are to bewritten to onedirectory.

-comment=“string” None -comm=“string” Specifies a string oftext to be placed inthe generated objectmodule. The stringwill be printed inLanguageEnvironmentformatted dumps.

-compress|-nocompress

-nocompress -comp |-nocomp -compressspecifieswhether to generatesmaller modules.Method names andline numbers aresuppressed.

110 ET/390


-d=pathor-dpath

If -d is not specified,.o and .lst files arewritten to the samelocation as their .classfiles.

None Specifies the rootdirectory for writing.o and .lst files.

-exclude=name |-include=name

No defaults -exc | -inc Specifies theclasses, packages, orsets of packages toinclude or excludefrom the bind.

-exe | -jll -exe None Specifies whether aJava DLL orexecutable is to begenerated.

-follow | -nofollow -nofollow -fol Specifies if referencedclasses are bound inthe object module.

-g[=hook|nohook]|-g[ hook|nohook]|-nog

-nog None Generates debuggingand tracinginformation.

-help | ? If hpj command isspecified without anyoptions or files, -helpis assumed.

-hel Displays help textfor the hpjcommand.

-inlrpt|noinlrpt

-noinlrpt -inlr|-noinlr

Writes an inlinereport to the .lstlisting file.

-lerunopts=“string” If this option is notspecified, the defaultLanguageEnvironmentrun-time options arebound with the Javaexecutable.

-ler Binds a list ofLanguageEnvironmentrun-time optionswith the Javaexecutable. A .roobject is generated.

-list=[offset|nooffset]| nolist

-nolist -lis=[offset|nooffset]-nolis

Creates apseudo-assemblerlisting for each .classfile. Also specifies ifoffset addressesshould be relative tothe entry point or tothe start of eachmethod.

-main=classname If -main is notspecified, defaults tothe first class withmain method foundduring the binding ofa Java executable.

-mai Specifies the classthat contains themain startup methodwhen building a Javaexecutable. A .mo fileis generated.



-make | -nomake -nomake -mak Instructs thebytecode binder tobind out-of-date ormissing programobjects and build theJava executable orDLL.

-maxmem=size|-nomaxmem

-nomaxmem -max|-nomax

Restrictsoptimizations bylimiting the storageto the specified size.

-o=name |-oname HFS Java executableis a.out in the currentdirectory. There is nodefault name for JavaDLL and whencreating programobjects in PDSEmembers.

None Specifies the name ofthe Java executableor DLL.

-O-noO

-noO None Generates optimizedcode.

-partial=name If this option is notspecified, the systemrebinds all thespecified classes into.o files and rebuildsthe Java executableor DLL.

-par Binds specifiedclasses (in name) andrebuilds the Javaexecutable or DLL.

-resource |-noresource

-noresource -res | -nores Generates .bo file forresource files in ZIPand JAR files.

-spill=size| -nospill

-spill=128 -spi=size| -nospi

Restricts the spillarea.

-t=dir None None Specifies the rootdirectory or run-timeCLASSPATH for theresources and/or jlls.They are eithersymbolic links to anHFS executable/jllfile, or an externallink to the PDSE dataset member specifiedby the -o option.

-tune=0|1|2|3 Default depends on-arc option setting.

-tun=0|1|2 Generates optimizedcode for the specifiedarchitecture group totake advantage ofarchitecturaldifferences inconditions such asthe scheduling ofinstructions.

112 ET/390


-verbose The bytecode binderis not running inverbose mode.

-ver Displays a list of the.class files tostdout as they arebound andgenerates the .syslinfile.

Java development on the host (OS/390)OS/390 Java executables and Dynamic Link LibrariesScenarios: Building OS/390 Java applicationsOS/390 Java incremental rebindingBuilding OS/390 Java executables and DLLs with .o filesSelectively include and exclude classes for OS/390 bytecode binding

Building OS/390 Java executables on HFSBuilding OS/390 Java executables in PDSE membersBuilding OS/390 Java DLLs on HFSBuilding OS/390 Java DLLs in PDSE membersBuilding an OS/390 Java executable or DLL in two stepsBinding Language Environment run-time optionsBuilding Java executables and DLLs for debuggingBuilding CICS Java programsBuilding CICS/ESA Java programs for debuggingAccessing Java resource files under CICS


hpj Command options

OS/390 hpj command option: -alias=nameSyntax: -alias=name

Default: None

Abbreviated form: -ali

Example: hpj -jll -o=“//LOADLIB(QUERY2A)” -alias=abc/staff/queryDB1.jll-include=abc.staff.queryDB.* -t=.

Use the -aliasoption to specify an alias (HFS-like) name for a Java executable orDLL that is being written to a PDSE member. -aliasmust be specified for all JavaDLLs that reside in PDSE members. An HFS file with the alias name will becreated under the directory specified by the -t option. This file is an external linkto the PDSE data set member specified by the -o option.

Why Alias Names Are RequiredWhen DLLs are dynamically loaded at run time, the system uses Java package


names to find the Java DLLs. Since the PDSE member name is not long enough tocontain the full package name, the alias name is used to provide this packageinformation.

Format of Alias NamesThe alias name is made up of the Java package name specified as paths and thesubpackage name becomes the module name with a .jll extension. For example, ifthe Java DLL is built from all the classes in the package, abc.staff.queryDB, thealias name would be abc/staff/queryDB.jll.

More Than One Alias NameYou can specify more than one alias name for a PDSE member by using -aliasmultiple times. For example, you are building a DLL from two packages:v abc/staff/queryDB1v abc/staff/queryDB2

Use the following hpj command to build the Java DLL in a PDSE member:hpj -jll -o=“//LOADLIB(QUERY2A)”

-alias=abc/staff/queryDB1.jll-alias=abc/staff/queryDB2.jll-include=abc.staff.*-t=.

As shown in the example, you should specify one alias name for each package.

When using the -resource option to bind HFS resource files into a Java DLL in aPDSE member, alias names for the resource files are automatically generated by thebinder. Alias names are only required for PDSE members that will be run underCICS.

Naming and placement of OS/390 Java DLLs in PDSE members

Building OS/390 Java DLLs in PDSE members

hpj command

OS/390 hpj command option: -architecture=0|1|2|3Syntax: -architecture={0|1|2|3}

Default: -architecture=0

Abbreviated form: -arc={0|1|2|3}

Example: hpj -arch=1 abc.staff.queryDB.queryMain

Use this option to specify the architecture for which the program object’sinstructions are to be generated. It allows the optimizer to take advantage ofspecific hardware instruction sets. The user specifies the architecture group towhich a model number belongs.

Four architecture groups support current models:

114 ET/390

v 0The default value. It generates executable code on all models.

v 1Produces code optimized for the following models:– 9021-520, 9021-640, 9021-660, 9021-740, 9021-820, 9021-860, and 9021-900– 9021-xx1 and 9021-xx2– 9672-Rx1, 9672-Exx, and 9672-Pxx

v 2Produces code optimized for these models and the models that follow on fromthem: :– 9672-Rx2, 9672-Rx3, 9672-Rx4, and 2003

v 3Produces code optimized for the 9672 YX6 and follow-on models. This includesgenerating code that exploits IEEE support.

Notes:

v A comment noting the level of the architecture is generated in your objectmodule to help you diagnose your program. Code compiled at architecturegroup 1 runs on machines in that group and later machines, including those inarchitecture group 2. It may not run on earlier machines. Code compiled atarchitecture group 2 may not run on architecture group 1 or earlier machines.

v This option has no effect if -noO is specified.v The value of architecture affects the -tune default value.

hpj command-tune=0|1|2|3

OS/390 hpj command option: -BLIST$type$Syntax: -BLIST$type$ | -BNOLIST

Default: -BLIST$SUMMARY$

Abbreviated form:None

Restriction:Cannot be specified with -c option.

Example: hpj -BLIST$ALL$ abc.staff.queryDB.queryMain

Use the -BLIST option to specify the type of information to be written to thebinder listing (also referred to as the binder map). type can be any one of thefollowing:v ALL

Produces a listing of individual function calls, a save summary, controlstatements, and messages.

v SUMMARYProduces a listing of the summary information, which includes processingoptions, module attributes, a save summary, and the entry point summary. Asummary of the modules is written only if the suboption SUMMARY or ALL isspecified. -BLIST$SUMMARY$ is the default.

v NOIMPProduces the same output as SUMMARY, but suppresses IMPORT controlstatement information.


v STMTProduces a listing of control statements and binder messages.

v OFFProduces a listing that only contains binder messages.

-BNOLIST is equivalent to -BLIST$OFF$.

The file is written as an HFS file with .map file extension. The file name is thesame as the file name of the Java program object (executable or DLL), and thebinder map is written to the same location as the Java program object. However,if the program object is written to a PDSE member, the file name is the subpackagename of its first -alias name, if it is specified; otherwise, the PDSE member name isused as the binder map’s file name. The binder map is then written to the currentdirectory. For example, the following hpj command is used to create the Java DLL:hpj -jll -o=“//LOADLIB(QUERYEMP)”

-BLIST -alias=abc/staff/queryDB.jll-include=abc.staff.queryDB.*

The binder map, queryDB.map, is written to the current directory.

hpj command-BXREF$YES|NO$

OS/390 hpj command option: -BXREF$YES | NO$Syntax: -BXREF$YES$ | -BXREF(NO)

Default: -BXREF$NO$


Restriction:Cannot be specified with the -c option.

Example: hpj -BXREF$YES$ abc.staff.queryDB.queryMain

Specifies that a cross-referenced list of data variables is to be included in the binderlisting (.map file). If the -BXREF$NO$ option is in effect, the cross-referencedlist of data variables is not generated.

The name of the binder listing (also called binder map) and location of the file isdiscussed in the -BLIST option.

hpj command-BLIST$type$

OS/390 hpj command option: -cSyntax: -c | -noc

Default: -noc


Restriction:Cannot be specified with -BXREF, -BLIST, or -aliasoptions.

116 ET/390

Example: hpj -c abc.staff.queryDB.queryMain

The -c option specifies that only partially bound program objects are to begenerated. The Java executable or DLL is not created. If you want to specifydifferent hpj options for different classes, you may want to use the -c option toseparately create .o files and then bind all the .o files into a Java executable or DLLusing another hpj command. For example, if you want to turn on debuginformation for one of the classes, you can use the -c option as follows:cd /home/ts123456hpj -c -classpath=.

-include=abc.staff.queryDB.*-d=/test -collapse

hpj -c -g -classpath=.-include=abc.staff.queryDB.*-partial=abc.staff.queryDB.readDB-d=/test -collapse

hpj -jll o=/home/ts123456/abc/staff/queryDB.jll /test/*.o

Note: If you are building your Java executable or DLL in two steps as wedescribed in the example, make sure that you specify all the classes for the Javaexecutable or DLL in all the hpj commands that are used to generate the required.o files. Notice that in the above example the complete list of classes for the JavaDLL is specified in the first two hpj commands.

The Java executable, queryDB, is built with the last hpj command.

Note:The -c option also generates the following partially bound objects:v .bo file when -resource option is specifiedv .mo file when -main option is specified or when there is a class with a main

methodv .ro file when -lerunopts option is specified

Scenarios: Building OS/390 Java applicationsBuilding OS/390 Java executables and DLLs with .o files

Building an OS/390 Java executable or DLL in two steps

hpj Command

OS/390 hpj command option: -checkSyntax: -check=args

Default: -check=all

Abbreviated form:-che

Example: hpj -check=null:bnds:zdiv -o=queryEmpabc.staff.queryDB.queryMain

The -check option controls whether normal Java run-time checks are performed.The args argument may be any one of the following values:


v allPerform all run-time checks.

v nonePerform no run-time checks.

v null | nonullnullspecifies that null pointer checks are performed. nonull specifies that nullpointer checks are not performed.

v bnds | nobndsbnds specifies that array bounds checks are performed. nobnds specifies thatarray bounds checks are not performed.

v zdiv | nozdivzdiv specifies that zero divisor checks are performed. nozdiv specifies that zerodivisor checks are not performed.

v astr | noastrastr specifies that array store conformance checks are performed. noastr specifiesthat array store conformance checks are not performed.

All arguments must be separated by a colon (:); for example:-check=null:bnds:zdiv

The arguments are processed from left to right. Multiple run-time checkspecifications cause the arguments to be accumulated in a left-to-right order. Theright-most argument processed takes precedence over any contradicting argumentsthat appear to the left.

The -check option is used to improve performance of the Java code, but thegenerated code is not conformant with the language. No exceptions will be thrownfor conditions that are not checked. For example, if -check=nonull is specified anda null object is dereferenced, an exception will not be thrown; instead, a LanguageEnvironment run-time exception may result.

hpj command

OS/390 hpj command option: -classpathSyntax: -classpath=path | -classpath path

Default: If the option is not specified, the classpath is set to the bytecode binder’sJDK classes and the contents of the CLASSPATH environment variable (in thatorder). If -classpath is not specified and the CLASSPATH environment variable isnot set, the JDK classes followed by the current directory (.) is used.


Example: hpj -classpath=.:/home/ts123456/app.zip:/home/buildabc.staff.queryDB.queryMain

Use this option to specify the bytecode binder’s search paths for:v Specified classesv Referenced classes

If -classpath option is specified, CLASSPATH is set to the specified classesfollowed by the JDK classes, and the CLASSPATH environment variable is notused.

118 ET/390

If the option is not specified, the classpath is set to the bytecode binder’s JDKclasses and the contents of the CLASSPATH environment variable (in that order). If-classpath is not specified and the CLASSPATH environment variable is not set, theJDK classes followed by the current directory (.) is used.

pathYou can specify more than one path by separating them with colons (:). If youspecify -classpath,include the paths for all referenced classes. If the currentdirectory is required, add that to the paths. The current directory can be specifiedas a period (.). You do not have to specify the bytecode binder’s JDK classes in thepath because they are automatically added before the path that you specified.

You can specify JAR files and ZIP files in the -classpath option (as seen in theabove example) and the system will search these files to find the required classes.

If -classpath is specified several times in the hpj command, the last one is used.

hpj command

OS/390 hpj command option: -collapseSyntax: -collapse | -nocollapse

Default: -nocollapse

Abbreviated form: -col | -nocol

Example: hpj -collapse -list abc.staff.queryDB.queryMain

This option specifies that the partially bound program objects (.o files) and listings(.lst files) are to be written to one directory. The hpj command generates .o filesautomatically. If either -list or -inlrpt option is specified, .lst files are generated.One .o and one .lst file are created for each class. If -collapse is specified, .o and.lst files are written to either the -droot directory, if -dis specified, or the currentdirectory, if -d is not specified, and package subdirectories are not used or created.The names of the .o and .lst files are fully qualified with the package name. Forexample, you have the following classes:v /home/ts123456/abc/staff/queryDB/connectDB.classv /home/ts123456/abc/staff/queryDB/readDB.classv /home/ts123456/abc/staff/queryDB/disconnectDB.class

You can put all the generated .o and .lst files in the current directory as follows:cd /home/ts123456hpj -collapse -list -jll -include=abc.staff.queryDB.*

The following files are written to the current directory, /home/ts123456:v abc.staff.queryDB.connectDB.ov abc.staff.queryDB.readDB.ov abc.staff.queryDB.disconnectDB.ov abc.staff.queryDB.connectDB.lstv abc.staff.queryDB.readDB.lstv abc.staff.queryDB.disconnectDB.lst


-nocollapseIf -collapse is not specified (same as -nocollapse), the .o and .lst files are written tothe directories of the corresponding .class files and the file names are not qualifiedwith their package names. For example, if the following hpj command is specified,cd /home/ts123456hpj -list -jll -include=abc.staff.queryDB.*

Then, the following files are written to /home/ts123456/abc/staff/queryDB:v connectDB.ov readDB.ov disconnectDB.ov connectDB.lstv readDB.lstv disconnectDB.lst

-d and -collapse optionsThe -d option can be specified together with -collapse to write all the .o and .lstfiles into one directory which is not the current directory. Using the above example,if the following hpj command is specified,cd /home/ts123456hpj -collapse -list -jll -d=/home/objects

-include=abc.staff.queryDB.*

Then, the following files are written to /home/objects:v abc.staff.queryDB.connectDB.ov abc.staff.queryDB.readDB.ov abc.staff.queryDB.disconnectDB.ov abc.staff.queryDB.connectDB.lstv abc.staff.queryDB.readDB.lstv abc.staff.queryDB.disconnectDB.lst

Input ZIP and JAR filesIf -collapse is not specified (or -nocollapse is specified) and there are input ZIP orJAR files, the .o and .lst files for the classes in the ZIP and JAR files are written tothe same directories as their corresponding .class files following the directorystructure in the ZIP file (subdirectories are created) . The file names of the .o and.lst files are not qualified with their package names.

Note:The above discussion on the placement of .o files also applies to .mo and .rofiles if they are generated by the hpj command.



hpj command-d=path

120 ET/390

OS/390 hpj command option: -comment=stringSyntax: -comment=“string”

Default: None

Abbreviated form:-comm

Example:hpj -comment=“Version 5” abc.staff.queryDB.queryMain

This option writes a text string in the object module. This string is loaded intomemory when the program is running. If the application fails abnormally, thestring is displayed in the traceback. If this option is specified multiple times, thelast one is used. All characters, including DBCS characters, are valid as part of thestring when they are between the double quotation marks.

The following restrictions apply to the specified string:v The string cannot exceed 64 characters in length. If it does, the string is

truncated to 64 characters.v If the string contains the double quotation marks symbol (“), put a back slash

(\) before it, for example, -comment=”Test \“V5\”“.

hpj command

OS/390 hpj command option: -compressSyntax: -compress | -nocompress

Default: -nocompress

Abbreviated form:-comp | -nocomp

Restrictions:Cannot be specified with -g option.

Example: hpj -compress -o=queryEmp abc.staff.queryDB.queryMain

The -compressoption generates smaller load modules. The system removes methodnames and line numbers in the generated modules. Should you get a LanguageEnvironment traceback, this information will not be present.

Compressed modules cannot be debugged with the debugger.

hpj command-g[=hook|nohook]

OS/390 hpj command option: -d pathSyntax: -d=path | -d path

Default: If -d option is not specified, the .o and .lst files are written to the samelocation as their corresponding .class files unless the input file is a ZIP or JAR file.



Example: hpj -d=/home/objectlib -list hello

Use this option to specify the root directory where the partially bound programobjects (.o files) and listing files (.lst files) are to be written. The hpj commandautomatically generates the .o files when it binds the .class files. It also generatesthe .lst files if you have specified either the -list or -inlrpt option. One .o or .lst fileis created for each class.

The .o and .lst files are placed under the -d root directory in a tree structuremirroring the package directory structure for the .class files. The specified rootdirectory must exist. For example, if the class abc.staff.queryDB.connectDB in/home/ts123456/abc/staff/queryDB is bound as follows:cd /home/ts123456hpj -d=/home/ofiles -jll abc.staff.queryDB.connectDB

The connectDB.o file is written to /home/ofiles/abc/staff/queryDB. If thesubdirectories under the root directory do not exist, they are automatically created.

-d option is not specifiedIf neither the -d nor the -collapse option is specified, the .o and .lst files arewritten to the same location as their corresponding .class files. If -d is not specifiedand -collapse option is specified, the .o and .lst files are written to the currentdirectory.

Classes in ZIP or JAR filesIf -d is not specified and you are binding classes from ZIP or JAR files, the .o and.lst files are written to the same directory as their corresponding .class files in thezipped file. The file names are not qualified with their package names.

If -d is specified and you are binding classes from ZIP or JAR files, the .o and .lstfiles are written to subdirectories under the -d root directory. If required, thesubdirectories are created and the .o and .lst files are put into the samesubdirectories as their corresponding .class files but they are in a different rootdirectory. The file names are not qualified with package names.

Note:The above discussion on the placement of .o files also applies to .mo and .rofiles if they are generated by the hpj command.



hpj command-collapse-inlrpt-list=[offset| nooffset]

122 ET/390

OS/390 hpj command option: -exclude=name | -include=nameSyntax: -exclude=name | -include=name

Default: No defaults

Abbreviated form: -exc | -inc

Example: hpj -o=deptQ -classpath=/home/test/a.zip-include=cde.staff.*

-exclude=abc.dept.updateDB.*-O -list

The -include and -exclude options allow you to quickly specify groups of classesand also selectively include and exclude classes in the Java executable or DLL thatyou are building. -exclude only applies to classes that are specified prior to thisoption in the command line. With -follow, the -exclude option also applies toreferenced classes preceding the -exclude in the command line. You may choose touse -include and -exclude options individually, or together.

name can be a class name, or it can be a prefix with a wild card, asterisk (*), tomean all classes with the specified prefix, for example, -include=abc.st* or-exclude=abc.staff.*. You can only specify one name per -include or -excludeoption. To specify more than one name, specify -include or -exclude multipletimes.

The -exclude option applies to the classes (and their referenced classes with the-follow option) specified thus far in the command line. If no classes are specifiedbefore the -exclude option, then -exclude is ignored.

Note: The -include and -exclude options do not apply to any resource files in theinput ZIP or JAR files.

If you specify -include and -exclude options multiple times in the hpjcommand,the -include and -exclude options are processed in the sequence in which they arespecified. For example, you are building a Java executable with the following hpjcommand:hpj -o=empQ -classpath=/home/ts123456/app.zip

-include=abc.staff.*-exclude=abc.staff.queryDB.*-exclude=abc.staff.queryDB.readDB

The second -exclude option does not do anything because theabc.staff.queryDB.readDB class was already excluded by the first -exclude option.

You can specify consecutive -include options without any -exclude between them.You can also specify consecutive -excludeoptions.

See related concepts for more information on the use of these two options.

Specifying -classpath to Limit -include SearchesWhen you specify the -include=name option, the bytecode binder searches throughall the paths in the CLASSPATH environment variable to find all the classes thatmeet the name search criteria. If you have a long CLASSPATH, especially if you areusing the default CLASSPATH environment variable, it may take a very long timeto complete the search. Therefore, it is a good practice to always specify the-classpath option to limit the searches when using -include.


ZIP and JAR files with -includeThe -include option also works very efficiently when you use it with ZIP or JARfiles in CLASSPATH environment variable. For example, if you have a set of Javapackages for your application, combining all your class files into a single ZIP orJAR file and specifying that file in the -classpath option is very simple. You canthen use the -include option to include the required classes for binding, as shownin the following example:hpj -o=deptQ -classpath=./app.zip

-include=abc.staff.*-exclude=abc.staff.updateDB.* -O -list

Note: If you are zipping up the class files, make sure that the directory structure inthe ZIP file matches that of the package structure.

From the app.zip file in the example, all the classes in abc.staff package, with theexception of the classes in abc.staff.updateDB package, are bound.

-include/-exclude and -make/-partialThe -include and -exclude options are processed first to determine which classeswill be included in the Java executable or DLL that you are building. These optionsdo not determine if bytecode binding takes place. If the Java executable or DLL isbeing created for the first time, all the classes for that executable or DLL arebound, thus creating the .o files. When you are rebuilding a Java executable orDLL, the -make or -partial options are applied against the list of classes to beincluded in the Java executable or DLL to determine which classes are to berebound.

Selectively include and exclude classes for OS/390 bytecode binding

hpj command-classpath=path-make-partial=name

OS/390 hpj command option: -jll | -exeSyntax: -exe | -jll

Default: -exe


Restrictions:None

Example: hpj -jll -o=/home/abc/pkg1.jll -include=abc.pkg1.*

Specify -jll if you want to bind the Java classes into a Java DLL. By default, the-exe option is assumed.

The HFS Java executable or DLL is written to the current directory if no paths arespecified in the -ooption. If you want to place the Java executable or DLL inanother directory, specify paths with the executable or DLL name in the -o optionas shown in the above example.

124 ET/390

Java executablesIf the Java executable is not explicitly named with -o option, its default name isa.out and it is written to the current directory. You may also want to explicitlyname the entry point for your executable by using the -main option.

Java DLLsIf -jll is specified, the -o option must also be specified to name the DLL. If the-main option is specified with the -jll option, the -main option is ignored and awarning message is displayed.

PDSE member for Java executable or DLLIf the Java executable or DLL is written to a PDSE member, specify double slashesin the -o option followed by the PDSE data set and member name. Put doublequotation marks (“) around the whole string. You must also specify alias HFS-likenames for the PDSE members that contain Java DLLs (by using the -aliasoption). For example:hpj -jll -o=”//LOADLIB(QUERY2A)“ -alias=abc/staff/queryDB.jll


OS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)

Building OS/390 Java executables on HFSBuilding OS/390 Java executables in PDSE membersBuilding OS/390 Java DLLs on HFSBuilding OS/390 Java DLLs in PDSE members

hpj command-alias-main=class

OS/390 hpj command option: -followSyntax: -follow | -nofollow

Default: -follow

Abbreviated form:-fol | -nofol

Restrictions:Cannot specify the -coption with -follow.

Example: hpj -nofollow abc.staff.queryDB.queryMain

This option specifies that the classes referenced by the listed classes (except the JDKclasses) are to be included in the Java executable or DLL that you are building.

This option allows you to create Java executables or DLLs without having to list allinput classes in the hpj command. With -follow, the system automatically finds allreferenced classes and binds them. This is the default behavior.


ExampleFor example, to create a Java executable, empQ, from the following classes:v abc.staff.queryDB.queryMain (has the main method)v abc.staff.queryDB.connectDBv abc.staff.queryDB.readDBv abc.staff.queryDB.disconnectDB

Use the following hpj command:cd /home/testhpj -o=empQ abc.staff.queryDB.queryMain

By default, the system assumes -exe and -follow, and if -main is not specified, itlooks for the first class that has a main method (queryMain) to be the entry pointfor empQ. Because of -follow, the binder goes and finds all the referenced classes(which includes connectDB, readDB, and disconnectDB) and binds them into theexecutable. Taking advantage of the -follow option, you can easily bind the Javaexecutable by specifying only the class with the main method.

OS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applications

hpj command-exe | -jll-main=class

OS/390 hpj command option: -g=[hook | nohook]Syntax: -g=[hook | nohook] | -nog

Default: -nog


Restrictions:Cannot be specified with -compress option.

Example: hpj -g=nohook abc.staff.queryDB.queryMain

Use this option to generate symbol tables and program hooks, which are used bythe debugger and the Performance Analyzer. The -g option controls the amount ofinformation that is generated.

If -g is specified with no parameter, -g=hook is assumed. -nog means that nodebug or trace information is generated.

Specify -g=hook, if you want to look at the flow of your code with thePerformance Analyzer or the debugger. Full debugger support is only available ifyou select -g-hook and -noO.

If you specify -g-hook and -O, only method entry, method exit, call begin, and callreturn hooks are generated. Specify these options only if you want to use the

126 ET/390

Performance Analyzer on your code. You will not be able to debug your code. Nosymbol information is generated whenever -O is specified, and, therefore, youcannot display any variables.

If you specify -g=nohook, you cannot use the debugger because the debuggerwould not be able to stop in your application.

-g=nohookis useful when your program abends and you are reading theLanguage Environment dump because you will be able to see the variables andtheir values at the time of the abend in addition to the line number informationthat is always generated by the bytecode binder.

Java always generates source file information in the object module. Thisinformation is used by Language Environment in formatted dumps and traces; themethod call traceback will include the package and class of the method in error.Note: Java never generates block or path hooks.

Notes:1. Local variables are only visible if the class file contains a LocalVariableTable

attribute. This means that your .java file must be compiled (javac) with the -goption. The LocalVariableTable is an optional attribute and there is noguarantee that all Java source compilers generate it. This is also true forLineNumberTable attribute and SourceFileInfo attribute.

2. The inliner is only invoked if the -O option is specified.

Building Java executables and DLLs for debugging

hpj command-compress-O

OS/390 hpj command option: -helpSyntax: -help | ?

Default: If the hpj command is specified without any options or input files, -helpis assumed.

Abbreviated form: -hel

Example: hpj -help

Either -help or ? displays a brief description of the hpj command syntax and itsoptions in the OS/390 shell.

hpj command

OS/390 hpj command option: -inlrptSyntax: -inlrpt | -noinlrpt

Default: -noinlrpt


Abbreviated form: -inl | - noinl

Example: hpj -O -inlrpt -list abc.staff.queryDB.queryMain

Use the -inlrpt with the -Ooption to generate a report on inlined methods in the.lst listing file. This report contains a summary of inlined methods and a detailedmethods call structure. The summary contains information such as:v Name of each defined methodv Action (inline or not inline) on a method and its reasonv Status of original method after inliningv Initial/final relative size of the method

You must specify the -O option with the -inlrpt option. No report is producedwhen your source file contains only one defined method.

If -list option is also specified, the inlined report and the listing are both written tothe same .lst file. The naming and placement of .lst files are described in the -listoption.

hpj command-list=[offset| nooffset]-O

OS/390 hpj command option: -lerunopts=“string”Syntax: -lerunopts=“string”

Default: If this option is not specified, the default Language Environment run-timeoptions are bound with the Java executable. In addition, this option sets theLanguage Environment run-time option ERRCOUNT to 0 (zero) as the default.

Abbreviated form: -ler

Restrictions:Specify the -main option with -lerunopts. You cannot specify the -jlloption with -lerunopts.

Example:hpj -lerunopts=“ stack(,,any,) termthdact(dump)”abc.staff.queryDB.queryMain

Use this option to specify Language Environment run-time options and bind themwith the Java executable. Put double quotation marks around the string ofrun-time options. Separate the run-time options with blanks. A .ro file will begenerated and bound with your Java executable. Specify the -main option whenyou use -lerunopts. The .ro file name is the same as that of the main class. Youcannot specify -lerunopts for Java DLLs; therefore the -lerunopts option cannot bespecified with the -jll option. The .ro file is written to the same directory as the.mo file for the main class.

Language Environment run-time options specified at run time take precedenceover those specified at build time. If they are not specified at run time, theLanguage Environment run-time options specified at build time (hpj command’s-lerunopts option) are used.

128 ET/390

ExampleAn example of using -lerunopts is to bind the Language Environment STORAGErun-time option with the CICS Java program, as follows:cd /home/ts123456hpj -o=“//'FRED.PDSE.LOADLIB(QUERYEMP)'”

abc.staff.queryDB.queryMain-main=abc.staff.queryDB.queryMain

-lerunopts=“STORAGE(FE,FE,FE)” -g -list

When you run this program, heap and stack storage will be set to values of FE,which will help you when you are debugging your application. The doublequotation marks around //’FRED.PDSE.LOADLIB(QUERYEMP)’ are required tocorrectly pass the PDSE name in the OS/390 shell.

Note: Single quotation marks around PDSE dataset name indicate that it is fullyqualified. Double quotation marks are required to correctly pass the PDSE name toOS/390 shell.

OS/390 Java executablesScenarios: Building OS/390 Java applications

Binding Language Environment run-time options

hpj command-exe | -jll-main=classOS/390 Language Environment run-time options

OS/390 hpj command option: -list=[offset | nooffset]Syntax: -list=[offset | nooffset] | -nolist

Default: -nolist

Abbreviated form: -lis=[ offset | noof fset] | -nolis

Example: hpj -list=offset abc.staff.queryDB.queryMain

Use this option to create a pseudo-assembler listing corresponding to bytecode. If-list=offset is specified, offset in the pseudo-assembler listing is from the start ofthe method. If -list=nooffset is specified, the offset addresses are relative to thebeginning of the generated code. If -list is specified without a suboption,-list=nooffset is assumed.

Notes: Information such as registers, pointers, data areas, and control blocksshown in the object listing is not programming interface information.

When -list is specified, one .lst file is created for each class and is named after theclass. The .lst files are placed in the same location as the .o files. The -d and-collapse options affect the placement of these files.


To get the interspersed source lines in the listing when using -list, the location ofthe Java source file must be in the same directory as the class file.

hpj command-collapse-d=path-inlrpt

OS/390 hpj command option: -main=classnameSyntax: -main=classname

Default: The first class found with a main method is used as the entry point forthe Java executable.


Example: hpj -main=abc.staff.queryDB.queryMain abc.staff.queryDB.queryMain

When building a Java executable, use the -main option to specify the class thatcontains the main startup method. That class is used as the main entry point forthe executable. This option is not valid when -jll is specified. The classname is afully qualified class name, for example, -main=abc.staff.queryDB.queryMain.

If -main is not specified when building a Java executable, the system looks in allthe input files for a class with a main method. When the first main method isfound, then its class is used as the entry point for the executable. If a main methodnot found, the system searches through the dependency list of classes. If no mainmethod is found, the bind is aborted and an error message is displayed.

When building a Java executable, one .mo file for the main class is generated.Other classes containing main methods will not cause other .mo files to begenerated.

The -main option should not be used when building Java DLLs.

When -coption is specified without a -main option, the first class with a mainmethod will cause a .mo file to be generated. If none of the classes have a mainmethod, then no .mo file is generated.

OS/390 Java executablesScenarios: Building OS/390 Java applicationsOS/390 Java incremental rebindingBuilding OS/390 Java executables and DLLs with .o files

Building OS/390 Java executables on HFSBuilding OS/390 Java executables in PDSE membersBuilding CICS Java programs

130 ET/390

hpj command-exe | -jll

OS/390 hpj command option: -makeSyntax: -make | -nomake

Default: -nomake

Abbreviated form: -mak

Restrictions:Cannot be specified with -partial option.

Example: hpj -make -o=queryemp -main=abc.staff.queryDB.queryMainabc.staff.queryDB.queryMain

When rebuilding a Java executable or DLL, use the -make option to instruct thebinder to verify that the partially bound program objects (.o files) for the classesexist, and if they do, whether they have an earlier timestamp than their bytecodefiles. -make forces a bytecode bind to generate the .o files if they do not exist or ifthey are out-of-date. In addition, if a class extends or uses another class that isoutdated, it, too, will be rebuilt. If a .class file cannot be found for rebinding, anerror message is displayed and the binding stops.

With the -followand -make options, you let the bytecode binder help you identifyclasses that will require rebinding when you are rebuilding your Java executable orDLL. With -follow, the system also checks the timestamps of all the referencedobjects and will do the necessary bytecode rebinding for you.

Although you can use the -make option when building a Java executable or DLLfor the first time, you would usually use this option when you are doingincremental rebind to refresh an existing Java executable or DLL. See the scenarioslisted in the related topics for more information on the use of the -makeoption.

Scenarios: Building OS/390 Java applicationsOS/390 Java incremental rebinding

hpj commandfollow-partial=name

OS/390 hpj command option: -maxmem=sizeSyntax: -maxmem=size | -nomaxmem

Default: -nomaxmem

Abbreviated form:-max |-nomax

Example: hpj -O -maxmem=1048576 abc.staff.queryDB.queryMain

When compiling with optimization, you can specify a sizeK bytes limit for theamount of memory used for local tables of specific memory intensiveoptimizations. The valid range for size is 0 to 2097152. You can use -maxmem=*to


indicate the highest possible value for size, which is also the same as the default,-nomaxmem. Zero (0), asterisk (*), and 2097152. Enter a size if you want to specifya memory size smaller than the default.

If the memory specified by the -maxmem option is insufficient for a particularoptimization, the compilation is completed in such a way that the quality of theoptimization is reduced, and a warning message is issued. When a large size isspecified for -maxmem, compilation may be aborted because of insufficient virtualstorage, depending on the source file being bound, the size of the subprogram inthe source, and the virtual storage available for the compilation. The advantage ofusing the -maxmem option is that, for large and complex applications, thecompiler produces a slightly less optimized object module and generates a warningmessage instead of terminating the compilation with an error message of“insufficient virtual storage”.

Notes:

1. The limit set by maximum memory size is the amount of memory for specificoptimizations, and not for the compiler as a whole. Tables required during theentire compilation process are not affected by or included in this limit.

2. Setting a large limit has no negative effect on the compilation of source fileswhen the compiler needs less memory.

3. Limiting the scope of optimization does not necessarily mean that the resultingprogram will be slower, only that the compiler may finish before finding allopportunities to increase performance.

4. Increasing the limit does not necessarily mean that the resulting program willbe faster, only that the compiler may be able to find opportunities to increaseperformance.

hpj command

OS/390 hpj command option: -OSyntax: -O

Default: -noO


Restrictions:If you specify -O with the -g option, you will not get full debuggersupport.

Example: hpj hello.class -O

Use the -O option to generate optimized code. The binder optimizes the generatedmachine instructions to produce faster object code. Using -O will increase bindtime and may have greater storage requirements. During optimization, the bindermay move code to increase run-time efficiency; as a result, statement numbers inthe program listing may not correspond to the statement numbers used in run-timemessages. This option interacts with the -g option. See the above restriction.

If you specify -g=hook and -O, only method entry, method exit, method call, andmethod return hooks are generated, and the debugger can only stop at thesepoints. No symbol information is generated whenever -O is specified, and,therefore, you cannot display any variables.

132 ET/390

hpj command-g[=hook|nohook]

OS/390 hpj command option: -o=nameSyntax: -o=name | -o name

Default: If this option is not specified, the default name for the Java executable isa.out, and it is placed in the current directory. This option must be specified whenwriting to PDSE members. It must also be specified when building Java DLLs.


Example: hpj -jll -o=/home/ts123456/abc/staff/queryDB.jll-include=abc.staff.queryDB.*

Use the -o option to explicitly name the Java executable or DLL that you arebuilding.

Relocate your Java executable or DLLYou also use the -o option to place your Java executable or DLL in a directoryother than the current directory, for example:cd /home/ts123456hpj -jll -o=/home/ts123456/abc/staff/queryDB.jll


Writing Java executables or DLLs to PDSE membersWhen you are building a Java executable or DLL that is written to a PDSEmember, you must use the -o option to specify the PDSE data set and membername. You must prefix the PDSE data set and member name with double slashes(//) and put double quotation marks (“) around the whole string, for example:hpj -jll -o=”//LOADLIB(QUERY2A)“

-alias=abc/staff/queryDB.jll-include=abc.staff.queryDB.*

The PDSE member name must be a valid PDSE primary member name. Put fullyqualified data set names within single quotation marks (’) and, again, put doublequotation marks around the whole PDSE specification, for example:hpj -jll -o=”//'TS12345.USER.LOADLIB(QUERY2A)'“

-alias=abc/staff/queryDB.jll-include=abc.staff.queryDB.*

Java executables that are CICS Java programs and DLLs that run in the CICSenvironment must reside in PDSE members.

OS/390 Java executablesOS/390 Java Dynamic Link Libraries (DLLs)

Building OS/390 Java executables on HFSBuilding OS/390 Java executables in PDSE membersBuilding OS/390 Java DLLs on HFSBuilding OS/390 Java DLLs in PDSE members


hpj command

OS/390 hpj command option: -partial=nameSyntax: -partial=name

Default: If this option is not specified, the system rebinds all the classes into .ofiles and rebuilds the Java executable or DLL.

Abbreviated form:-par

Restrictions:Cannot be specified with the -make option.

Example: hpj -o=deptQ -classpath=/home/ts123456/app.zip:$CLASSPATH-main=abc.staff.queryDB.queryMain-include=abc.staff.queryDB.*-partial=abc.staff.queryDB.connectDB-O -list

Binds name class(es) into .o file(s) using the specified options. This option is usedto refresh a Java executable or DLL by adding or updating one or more classes.The Java executable or DLL is rebuilt from:1. The newly generated .o file(s) from name class(es).2. The previous Java executable or DLL

name can be a class name or it can be a package name. It can also contain a wildcard, asterisk (*) to indicate all classes with that prefix. Note:The classes specifiedin the -partial option must have been specified or referenced in the hpj command.You can only specify one name per -partial option. To specify more than one name,specify -partial multiple times in the hpj command.

Note:The name class must be either one of the input files to the hpj command orone of the referenced classes (if -followis assumed). When rebuilding a Javaexecutable or DLL (with -partialor -make), you must specify the complete list ofinput classes as if you are building it for the first time. Make sure that any newclasses named in -partial can be found either in the listed or the referenced inputclasses.

ExampleYou have generated a Java executable, empQ. You want to turn on debugging forone of the classes. -partialoption lets you rebind the specified class with the listedoptions and rebuild the Java executable with a single hpj command. For example:hpj -o=empQ -g -list -include=abc.staff.queryDB.*

-partial=abc.staff.queryDB.readDB

With -partial, the binder rebinds readDB with -g and -list options and rebuildsempQ with the newly generated readDB.o file. The other program objects in empQdo not change.

Scenarios: Building OS/390 Java applicationsOS/390 Java incremental rebinding

134 ET/390

hpj Command-follow-make

OS/390 hpj command option: -resource

Syntax: -resource | -noresource

Default: -noresource

Abbreviated form: -res

Restrictions: -resource option only works with input ZIP or JAR files.

Example: hpj app.zip-main=abc.staff.queryDB.queryMain-o=“//’FRED.PDSE.LOAD(QUERYA)’”

-resource -t=.

The -resource option is used to generate a single program object (resource.bo file)from all the resource files found in the specified ZIP and JAR files that are input tothe hpj command. The resource.bo output file is bound with your Java executableor Java DLL. If you do not specify ZIP or JAR files with the hpj command, the-resource option is ignored.

If the -t option is specified, symbolic links (if the output is in HFS) or externallinks (if the output is in PDSE) to the Java executable or DLL will be created forresource files that are found in the input ZIP and JAR files.

An external link will look like this:

ln -e MYMSGS mymsgs.properties

where MYMSGS is the PDSE member name specified in the -o option of hpjcommand.

A symbolic link will look like this:

ln -s mymsgs mymsgs.properties

where mymsgs is the HFS executable specified in the -o option of hpj command.

The -t option specifies the root directory or run-time CLASSPATH in which thelinks to the resource files will be created. Assuming that links have been created,this root directory should be added to the classpath at run time. The files are thenaccessible at run time via the Java interfaces:v java.beans.Beans.instantiate(ClassLoader, String)v java.lang.Class.getResourceAsStream(String)v java.lang.ClassLoader.getSystemResourceAsStream(String)v java.util.ResourceBundle.getBundle(String)v java.util.ResourceBundle.getBundle(String,Locale)


Note: When the -resource option is specified, the bytecode binder searches throughall the specified ZIP and JAR input files for resource files and generates a singleresource.bo file containing these resources. You will get a warning message if noZIP or JAR files are specified with the hpj command and the -resource option isignored. When -resource option is specified and the application is to be run onOS/390 UNIX, the -t option must also be specified.

.bo fileThe partially bound program object generated by -resource option is resource.bo.The resource.bo file is written to the current directory, or if the -d option isspecified then it is written to the -d directory.

.aliases fileAn intermediate file resource.aliases is created at the compile step. It contains all ofthe resource file names found in the input ZIP and JAR files. This file is written tothe same directory as the resource.bo file.

.link fileA shell script file will be generated by the -t option, and is run automatically bythe translator. The name of the script file looks like app.link, where app is the basename of the Java executable or jll name. It is located in the same directory as the.map file. This script file contains all the OS/390 UNIX commands that were usedto create the links required for accessing the resources.

For example, the following hpj command binds all the Java classes and resourcefiles in app1.zip, app2.zip, and app3.jar into the PDSE memberFRED.PDSE.APPS(APP123):hpj app1.zip app2.zip app3.jar -nofollow

-jll -o=“//'FRED.PDSE.APPS(APP123)'”-resource -alias=abc/staff/queryDB.jll -t=.

The PDSE member, APP123, contains the Java DLL which includes the Java classesin the abc.staff.queryDB package, as well as the resource files in the ZIP and JARfiles. The resource.bo file is in the current directory. In addition to the specifiedabc/staff/queryDB.jll alias name, an alias name for each resource file isautomatically added for the PDSE member. External links pointing to PDSEmember APP123 are generated for all the resource files and the Java DLL underthe current directory. If the jll or Java executable is to be build to a HFS file,symbolic links will be created.

By default, -noresource is assumed; that is the resource files in any ZIP or JAR filesare ignored in the build.

-resource option for CICS Java programsUse the -resource option to migrate resources on HFS to PDSE members. Thismigration is necessary if you want to access resource files from your CICS Javaprogram. When building a Java DLL in a PDSE member, alias names for resourcefiles are automatically generated by the -resource option so that the resource filescan be found at run time.

Resource files in PDSE Java and HFS executablesIf you bind the resources files and other Java classes into a Java executable, thenthese Java resources files are only accessible from this Java executable.

Resource files in PDSE Java DLL and HFS executablesYou can also bind the resource files by themselves, or with other Java classes, into

136 ET/390

a Java DLL that is written to a PDSE member. Then at run time, other Javaapplications can access these Java resources files.

-c option and -resource optionFor some Java applications, you may choose to bind all your bytecode into .o filesfirst, and then, in a separate step, bind the .o files into a Java executable or DLL. Insuch situations, you would also generate the resource.bo file with the other .o filesin the first step (by specifying the -c and -resource options), and, in the secondstep, bind the resource.bo file with other .o files into a PDSE Java executable orDLL. For example,

hpj app1.zip app2.zip app3.jar -c -resource-collapse -d=/home/objects

generates resource.bo file together with other .o files in /home/objects. You cancreate a PDSE Java DLL as follows:cd /home/objectshpj -jll -o=“//'FRED.PDSE.APPS(APP123)'” -nofollow

resource.bo abc.staff.queryDB.*.o -alias=abc/staff/queryDB.jll -t=.

The PDSE member, APP123, contains a Java DLL which includes Java classes inabc.staff.queryDB package, as well as Java resource files in resource.bo. APP123 hasa list of alias names which includes:v The specified alias name, abc/staff/queryDB.jllv The automatically generated alias names for each resource file that is contained

in the resource.bo file

At run time, this PDSE Java DLL can be accessed under OS/390 UNIX andCICS/ESA environments like any other PDSE Java DLL. See related tasks for moreinformation on build scenarios and accessing PDSE Java DLLs.

Note:v -include and -exclude options cannot be used to select resource files.v -make and -partial options do not apply to .ro, .bo, and .mo files.

Hints and tips on -resource usageHere are some tips when using the hpj command’s -resource option:1. Ensure that the zip or jar file is not compressed. This is the same rule as when

zipping or jarring class files.2. For OS/390 UNIX, add the PDSE to your STEPLIB. If the application is running

in the CICS environment, the PDSE need only be added to the DFHRPL DDstatement.

3. For OS/390 UNIX, an external link to the PDSE or a symbolic link to the HFSfile is generated automatically by the hpj command if the -t option is specified.Otherwise, a link must be created manually.

4. When property files are created as flat files they are in the code page of thelocale you are running under. For example, on 370 they would be in IBM-1047.When your resource file is being accessed from an executable or a jll, it must bein UTF8 format (not locale sensitive) for property files or binary. When creatinga zip or jar file which includes property files, the input (property file) shouldbe in UTF8 (or ISO8859-1) code page.

5. Do not include a manifest in the jar file.


OS/390 Java CICS/ESA supportScenarios: Building OS/390 Java applicationsResource files in executables or Java DLLs

Accessing Java resource files under CICSDefining resources to CICS/ESA to access a Java DLL

hpj command-d=path-exclude=name | -include=name-make-partial=name-t=dir

OS/390 hpj command option: -spill=sizeSyntax: -spill=size | -nospill

Default: -spill=128

Abbreviated form:-spi=size | -nospi

Example: hpj -spill=256 abc.staff.queryDB.queryMain

Use this option to specify the size of the spill area to be used for the bind.

When too many registers are in use, the compiler stores the contents of some ofthem into temporary storage called the spill area. You may have to expand thespill area; if so, you will receive a compiler message telling you the size to whichyou should increase the spill area. The maximum spill area size is 3900 bytes.Typically, you will only need to specify this maximum spill area when compilingvery large programs with optimization.

Notes:There is an upper limit of 4096 bytes for the combined area for your spill area,local variables, and arguments passed to called functions for optimized code.

hpj command

OS/390 hpj command option: -stubSyntax: -stub=name

Default: None

Abbreviated form: None

Example: hpj X -stub=a.b.c -stub=d.eWhen the high-performance compiler compiles a class files into an object file, itwill try to locate the classes referenced by the class file being compiled. If it cannotfind these classes, the default behavior is to emit an error message and stop thecompilation. In certain situations, the -stub option can be used to continue the

138 ET/390

compilation. If the reference to the missing class is in the code portion of the classfile (ie., in executable code and not in the metadata for the class), then the-stuboption will cause the compiler to emit code to throw ajava.lang.NoClassDefFoundError when that reference to the missing class isencountered at execution time.The -stub option has the same syntax as the -exclude, -include and -partialoptions. For example, to stub out references to missing classes a.b.c and d.e whencompiling class X:hpj X -stub=a.b.c -stub=d.eTo stub out references to all missing classes in package a.b when compiling class X:hpj X -stub=a.b.*To stub out references to all missing classes when compiling class X:hpj X -stub=*

hpj command-exclude-include-partial

OS/390 hpj command option: -t=dirSyntax: -t=dir

Default: None


Example: hpj -resource -t=/home/userid abc.jar-o=queryMain abc.staff.queryDB.queryMain

Use this option when links are required to access resources created using the-resource option or to access jll’s in PDSEs created using the -alias option.

The -t option enables you to specify the root directory for creating all links. If the -toption is not specified, the links required to access resources in executables or jllwill not be created. Similarily, if -t is not specified when creating a jll in a PDSE,the links required to access the jll will not be created.

The links can be symbolic links for resources within an HFS executable/jll file, orexternal links for both resources within a PDSE member or a jll in a PDSE member.

To create links for resources, specify the -t option with the -resource option.To create links for jlls which are to be created as members of a PDSE specify the -toption with the -alias option(s).The -t option will also generate a file with the links extension. This file contains thecommands used to create the links, and can be rerun if the links are damaged.The -t option is not required if the executable or jll is being run under CICS sinceCICS does not make use of the links.

In the above example, assume the abc.jar file contains a resource fileabc/staff/queryDB.properties, and the current directory is /home/userid . Asymbolic link will be generated by running the UNIX command (or automaticallyby the high-performance compiler):ln -s /home/userid/queryMain /home/userid/abc/staff/queryDB.properties


The following example illustrates the usage of this option when building a jll intoa PDSE:hpj -t=/home/userid -jll -o=“//PDSE(query)” -alias=abc.staff.queryDB-include=abc.staff.queryDB.*

An external link will be generated by the following command:ln -e query /home/userid/abc/staff/queryDB.jll.

Note: At run time, you must add the path specified in the -t option to theCLASSPATH, so that the resources and/or jlls can be found.

hpj command-resource-o=name

OS/390 hpj command option: -targetSyntax: -target=[LE | IMS]

Default: -target=LE

Abbreviated form: -tar=LE

Example: hpj -target=IMS abc.staff.queryDB.queryMain

Use this option to specify the run-time environment for which the executable is tobe generated. This option is only valid for executables.

This option produces the following results:v -target=LE generates an executable to run in the Language Environment. This is

the default.v -target=IMS generates an executable to run under in the IMS subsystem.

When using the -target=IMS option, you can specify run-time environmentvariables in an HPJENVAR DD statement in the JCL as follows://HPJENVAR DD PATH=’/u/user/hpjapp/env.var’where env.var is a file that contains a list of environment variables to be set, suchas:CLASSPATH=/u/user/hpjapp/jllThis has the same effect as specifying the following on the command line:hpj -lerunopts=“ENVAR(CLASSPATH=/u/user/hpjapp/jll)” . . .Note that the syntax for the command line is: environment variable=value (theexport keyword is not required).


140 ET/390

OS/390 hpj command option: -tranSyntax: -tran

Default: None


Example:The -tran option is intended for users who are writing code with transactionsemantics. The code should not be using static data to retain state, but insteadshould use the services of the transaction environment.

If a field is declared static, there exists exactly one incarnation of the field, nomatter how many instances of the class might be eventually created. Static fieldsare created and initialized exactly once when a class or interface is loaded.

In a transaction environment, an application can be executed more than oncewithout re-initializing the static data in the transaction. If the value of the staticfield is changed later in the application, the static field will have the new valueuntil it is re-initialized. If the application is executed a second time withoutre-starting the runtime environment, the static field will contain the new value setby the previous execution of the application, since the static initializer was notexecuted. This might be contrary to your expectation that the static field shouldhave the initial value at the beginning of each execution of the application.

With the -tran option, any assignment to a static field (or an element of a staticarray) in any methods except the static initializer will result in the followingwarning messages at compile time:v If a static field is assigned to a value, the following warning message will be

issued: 3271(W) The static field ’classname.fieldname’ is being updated inmethod ’classname.methodname’. Use of this static field in a transactionalenvironment may not be safe.

v If an static array element is assigned to a value, the following warning messagewill be issued: 3273(W) An element of a static array field ’classname.fieldname’is being updated in method ’classname.methodname’. Use of this static field in atransactional environment may not be safe.

The following example code will produce the warning messages described above:import java.lang.*;import java.io.*;import java.util.*;class hw {

static int i=10; // OK to do static initializationstatic int[ ] iarr;static ss s = new ss(); // OK

static { // OKiarr = new int[10];for (int j=0; j<10; j++)

iarr[j]=j;}

public static void main(String args[ ]) {i +=1 ; // warning HPJ3271(W)

}

public static void foo(){iarr = new int[10]; // warning HPJ3271(W)for (int j=0; j<10; j++)


iarr[j]=j; // warning HPJ3273(W)}

}

LimitationsIn the following cases, the static field might be updated, but no warning will beproduced at compile time. This means that you still need to manually check thetypes of transactions listed below, among others. The -tran option can decrease theamount of manual checking you must perform, but the option does not eliminatemanual checking entirely.1. If a transaction:

v references a method in another class, andv the referenced class is not compiled as part of the transaction (that is, it is

built as a separate jll), andv the method updates a static field either directly or indirectly

then no warning will be produced when the transaction is compiled.2. If your code copies a static member reference to a non-static reference, and

updates the object through the non-static reference, then the translator will notproduce a warning for the update. This copy can happen explicitly through anassignment, or implicitly by passing a static reference as a parameter orreturning a static reference.

The following example code shows how static fields can be updated withoutproducing a warning:import java.lang.*;import java.io.*;import java.util.*;class hw {

static iarr[ ];static Vector v;static Account[ ] arr;Account accnt;

public static void main(String args[ ]) {

accnt = new Account();accnt.setBalance(10); //type 1: this method call causes the static field

//of 'Account' class to be updated; compiler//will not produce any warning here

iarr = new int[5];foo(iarr); //type 2: the reference of the static array

//'iarr' is passed as a parameter

v= new Vector(10);v.addElement(s); //type 2: the reference 'v' is implicitly

//passed as a parameterarr[0].setBalance(0); //type 2: the content of a static array element

//is updated}

public static void foo(int jarr[ ]){for (int j=0; j<5; j++)

jarr[j]=2*j;}

}

class Account {String name;static int balance = 0;

142 ET/390

public static setBalance(int newBalance ) {balance = newBalance;

}

}

hpj command

OS/390 hpj command option: -tune=0|1|2|3Syntax: -tune=0|1|2|3

Default: Depends on -architecture option.

Abbreviated form: -tun=0|1|2|3

Example: hpj -arc=2 -tune=2 abc.staff.queryDB.queryMain

Use this option to specify the architecture for which the program object will beoptimized. The option will allow the optimizer to take advantage of architecturaldifferences such as the scheduling of instructions. The user specifies thearchitecture group to which a model number belongs.

The architecture groups that support current models are:v 0

This option generates code executable on all models but it will not be able totake advantage of architectural differences on the models specified below.

v 1This option generates code that is executable on all models, but is optimized forthe following models:– 9021-520, 9021-640, 9021-660, 9021-740, 9021-820, 9021-860, and 9021-900– 9021-xx1 and 9021-xx2

v 2This option is the default. This option generates code that is optimized for thesemodels and the models that follow on from them:– 9672-Rx2, 9672-Rx3, 9672-Rx4, and 2003– 9672-Rx1, 9672-Exx, and 9672-Pxx

v 3Produces code optimized for the 9672 G5 and follow-on models. This includesgenerating code that exploits IEEE support.

Note: A comment noting the level of the tuning will be generated in your objectmodule to help you diagnose your program.

Default: Tune defaults for architecture groups are:

Architecture Groupin -arch Option

-tune Default

0 3

1 1

2 2

3 3


hpj command-architecture=0|1|2|3

OS/390 hpj command option: -verboseSyntax: -verbose

Default: hpj command is not running in verbose mode.

Abbreviated form: -ver

Example: hpj -verbose abc.staff.queryDB.queryMain

Specify the -verbose option to display a list of the .class files to stdout as they arebound. A name.syslin file containing the list of primary input files to the LinkageEditor is created. The file name is the same as the file name of the Java programobject (executable or DLL), and the file is written to the same location as the Javaprogram object. However, if the program object is written to a PDSE member, thefile name is the subpackage name of its first -alias name, if it is specified;otherwise, the PDSE member name is used as the file name. For PDSE programobjects, the .syslin file is written to the current directory.

The .syslin file provides a useful source of information for you to confirm the listof program objects that were bound into the Java executable or DLL that you built.

hpj command-alias

OS/390 hpj command option: -vSyntax: -v=args

Default: None


Example: hpj -v=class:stub abc.staff.queryDB.queryMainThe -v option controls the amount of information displayed about the progress ofthe compile.v all

Perform all -v suboptions.v none

Perform no -v suboptions.v class| noclass

class displays a list of the .class files to stdout as they are bound. A name.syslinfile containing the list of primary input files to the Linkage Editor is created. Thefile name is the same as the file name of the Java program object (executable orDLL), and the file is written to the same location as the Java program object.However, if the program object is written to a PDSE member, the file name isthe subpackage name of its first -alias name, if it is specified; otherwise, thePDSE member name is used as the file name. For PDSE program objects, the.syslin file is written to the current directory. The .syslin file provides a usefulsource of information for you to confirm the list of program objects that were

144 ET/390

bound into the Java executable or DLL that you built.Note: This has the same effect as using the -verbose option.

v stub| nostubstub diplays all the classes that were stubbed. This suboption works inconjunction with the -stub option.

v depend| nodependdepend displays all class dependencies.

All arguments must be separated by a colon (:); for example:-v=class:stub:dependThe arguments are processed from left to right. Multiple -v specifications cause thearguments to be accumulated in a left-to-right order. The right-most argumentprocessed takes precedence over any contradicting arguments that appear to theleft.

hpj command-alias-stub-verbose

OS/390 shell command syntax to run HFS Java executablesTo run an HFS Java executable, set the PATH environment variable to theexecutable’s location and type the executable’s file name in the OS/390 shell. Forexample, if the executable’s file is /home/ts123456/a.out, run the program asfollows:export PATH=/home/ts123456:$PATHa.out

Syntax:ExecutableFileName [parameters]

ExecutableFileNameThe system uses the PATH environment variable to find the specified Javaexecutable file. The system expects a fully bound program object with a class thathas a main method. For example, to run the Java executable, hello, in/home/programs:export PATH=/home/programs:$PATHhello

parametersSpecify the parameters after the Java executable’s file name. The parameters arepassed to the Java executable’s main method. Use a blank as a separator for eachof the parameters.

If you want to pass a space as an argument, put double quotation marks (“)around the space. For example, if you want to pass Expedite Order as a singleparameter to your program, a.out, you can do so as follows:a.out ”Expedite Order“

Run-time optionsOther than passing Language Environment run-time options with the -lerunoptsbind option or by setting the _CEE_RUNOPTS environment variable, you can passOS/390 run-time options in the IBMHPJ_OPTS environment variable. These are the


same options as the hpjava command’s options. You cannot pass LanguageEnvironment run-time options with IBMHPJ_OPTS. The separator for the optionsin IBMHPJ_OPTS is a blank. Enclose all of the options within double quotationmarks, for example:

export IBMHPJ_OPTS=”-v -classpath /u/ts123456“

Java development on the host (OS/390)OS/390 Java executablesScenarios: Building OS/390 Java applicationsRRBC considerations for interpreted Java and OS/390 program objects

Running HFS Java executables under OS/390 UNIX

hpj commandOS/390 Language Environment run-time options

hpjava command (OS/390)The hpjava command is used in the OS/390 shell to run OS/390 Java DLLs. Youspecify a class name with the command. You cannot use the hpjava command torun Java executables under OS/390 UNIX or to run Java DLLs under CICS/ESA.

Syntax:hpjava [options] classname [parameters]

classnameThe class name must be fully qualified by including its package in the name. Forexample:hpjava -classpath=/home/ts123456 hpjava a.b.c.d.classname

The class name must contain a main method that is defined as follows:package a.b.c.dclass classname {

public static void main (String argv[]) {...

}}

hpjava command runs the main method and then exits unless the main methodcreates one or more threads. If any threads are created by main method, thenhpjava command does not exit until the last thread exits.

ParametersThese are parameters required by your user program. The parameters must followthe classname. Any parameters that appear on the command line after classname arepassed to the main method of the specified class.

OptionsThese are OS/390 Java run-time options that you can specify with the hpjavacommand to control run-time activities. All command options begin with a dash (-)and must be separated from associated arguments by a space. All options must

146 ET/390

precede the classname.

Option Default Description

-classpathpathIf this options is not specified,CLASSPATH environment variable isused.

Specifies the paths that hpjava usesto look up the specified classname andall classes that it loads. Overrides thedefault or the CLASSPATHenvironment variable (if it is set). Thedirectories are separated from eachother with a colon(:). A period byitself indicates to search the currentworking directory.

-Dproperty If this option is not specified, defaultproperty setting apply.

Redefines a property value (wherename is the name ofthe property whose value you wantto redefine, andvalue is the new value that you wantto assign to theproperty).You can specify any number of -Doptions.

-helpor -? If this option is not specified,information is not displayed.

Displays usage information and exits.If invalid run-time options arespecified, then usage information isalso displayed for the hpjavacommand and the applicationimmediately terminates. If applicable,a message is displayed to report thefirst invalid option. Subsequentoptions that are not valid are neitherdetected nor reported on.

-loadDLLfilesIf this option is not specified, nopreloading of DLLs is performed.

Preloads the specified Java DLLsbefore the loading of the specifiedclass. The colon (:) is used as aseparator between the file names. Inthe case where this option is specifiedmore than once, only the last one ishonored. If the specified DLLs arenot found, the execution of the classterminates. For example:

-loadabc/staff/queryDB.jll:abc/staff/verifyDB.jll

Note: Java DLLs in PDSEs cannot bespecified for the -loadoption.

-verbose If this option is not specified,information is not displayed.

Prints a message to stderr each time aDLL is loaded. Displays theCLASSPATH setting and the JavaDLL information whenever one isloaded (user or JDK DLL). The JavaDLL information includes its nameand the initial reason why it wasloaded.



-version If this option is not specified,information is not displayed.

Displays the version of VisualAge forJava, Enterprise Edition for OS/390and exits. If other options are alsospecified, the version information isdisplayed and processing continues.

Java development on the host (OS/390)OS/390 Java Dynamic Link Libraries (DLLs)Scenarios: Building OS/390 Java applicationsRRBC considerations for interpreted Java and OS/390 program objectsNaming and placement of OS/390 Java DLLs on HFSNaming and placement of OS/390 Java DLLs in PDSE members

Running HFS Java DLL under OS/390 UNIX

hpj command

148 ET/390

Chapter 12. Run-time options and environment variables

OS/390 Language Environment run-time optionsYou can specify OS/390 Language Environment run-time options to help youdebug or trace your Java application, or to run it more efficiently.

If your application runs under OS/390 UNIX, Language Environment run-timeoptions can be set using the _CEE_RUNOPTS environment variable. You can setthe _CEE_RUNOPTS environment variable by usingthe export command from the OS/390 shell. The format of the environmentvariable is:

_CEE_RUNOPTS=value

Where value is a null-terminated character string of Language Environmentrun-time options. For example, you could specify the following:

_CEE_RUNOPTS=“stack(,,any,) termthdact(dump)”

For more information on _CEE_RUNOPTS environment variable, read the OS/390Language Environment for OS/390 & VM Programming Guide.

The hpj command’s -lerunopts option allows you to bind Language Environmentrun-time options with the Java executable as you are building it. These options willbe passed to Language Environment at run time.

Refer to the OS/390 Language Environment Programmer’s Reference for acomplete list of run-time options. The following table lists some of the morecommon run-time options:

Run-Time Option Description

ARGPARSE Specify whether command line arguments to the Java program areto be parsed.

ENVAR Set the initial values for the environment variables by typingname=value, where name and value are sequences of characters thatdo not contain null bytes or equal signs. The value can have amaximum of 250 characters. You can specify multiple environmentvariables, separating the name=value pairs with commas. Quotationmarks are required when specifying multiple variables.

EXECOPS Specify whether you can enter run-time options on the commandline.

HEAP Specify the allocation of the initial heap, and control the allocationof additional heaps created with the CEECRHP callable service,and how that storage is managed.

LIBSTACK Specify the allocation of the thread’s library stack storage. Thisstack is used by Language Environment and HLL library routinesthat require save areas below the 16M line.


Run-Time Option Description

NATLANG Select the initial national language to be used for the run-timeenvironment, including error messages, month names, and day ofthe week names.

You can select one of the following:

v ENU

v UEN

v JPN

Note:NATLANG applies to Language Environment NLS anddata/time services and not to Java localization which is controlledby Java System properties.

NONIPTSTACK Specify the stack allocation for each thread, except the initialthread, in a multithread environment.

PROFILE Specify if tracing is to be performed when the application isexecuted. It also passes tracing parameters to the PerformanceAnalyzer.

RPTOPTS Specify that the generation of a report of the run-time options ineffect while the application was running.

RPTSTG Specify the generation of a report of the storage the applicationused. You can use the storage report information to adjust theANYHEAP, BELOWHEAP, HEAP, LIBSTACK, NONIPTSTACK,STACK, and THREADHEAP run-time options.

STACK Specify the allocation of the thread’s stack storage. Typical itemsresiding in the stack are Java variables.

STORAGE Controls the initial content of storage when allocated and freed. Italso controls the amount of storage that is reserved for theout-of-storage condition.

TERMTHDACT Set the level of information that is produced when LanguageEnvironment percolates a condition of severity 2 or greater beyondthe first routine’s stack frame.

TEST TEST specifies the conditions under which the Debugger assumescontrol when the user application is being initialized.

Scenarios: Building OS/390 Java applications


OS/390 bytecode binder and Java run-time environment variablesOS/390 bytecode binder and Java run time use the following OS/390 environmentvariables:v IBMHPJ_HOME

Points to the HFS root directory of OS/390 Java bytecode binder and its JDKclasses.

v IBMHPJ_RTLContains the Language Environment run time libraries.

150 ET/390

v IBMHPJ_OPTSPoints to a list of OS/390 Java run-time options used when running OS/390 Javaexecutables..

v CLASSPATH

– Points to the HFS directory that contains external links to OS/390 Javarun-time DLLs. This information is used when running OS/390 Javaexecutables.

– Points to HFS directories that contain local Java DLLs. This information isused when running OS/390 Java executables.

– Points to HFS directories that contain referenced classes. This information isused by the OS/390 Java bytecode binder when binding Java executables orDLLs.

v PATHPoints to HFS directries that contain OS/390 Java executables. The OS/390 shelluses the PATH environment variable to find the Java executable.

v LIBPATH

– Points to the HFS directory that contains the OS/390 Java run-time library.This information is used by OS/390 Java executables to load HPJDLL.

– Points to the HFS directories that contain native JNI DLLs.v STEPLIB

– Points to OS/390 Java run-time libraries. This information is used whenrnning OS/390 Java executables.

– POints ot the OS/390 Java bytecode binder. This information is used whenbinding Java bytecode objects using the hpj command.

– Points to Language Environment run-time libraries. This information is usedwhen running Java executables or the hpj command.

– Points to the debug tool run-time libraries, and is used when you want todebug Java executables.

– Points to OS/390 Java executables or DLLs that are in PDSE.

Running HFS Java executables

-lerunopts

Improving performance by specifying environment variable optionsThis section describes a couple of different ways you can improve the performanceof your Java executables.

Disabling garbage collection

You can specify the -Xskipgc option in the IBMHPJ_OPTS environment variable,and garbage collection will be disabled. Note that when -Xskipgc is set, thememory occupied by unreferenced objects in the heap will not be reclaimed, andthe finalizer will not be called.

To set environment variables at run time, you can use the export command asfollows:export IBMHPJ_OPTS=“-Xskipgc”

Chapter 12. Run-time options and environment variables 151

You can optionally bind run-time environment variables using the -lerunoptsoption when you are building the Java executable or DLL. You can set the-lerunopts option as follows:-lerunopts=“envar(IBMHPJ_OPTS=-Xskipgc)”

If you want to specify more than one -X option for IBMHPJ_OPTS, use thefollowing syntax:-lerunopts=“(envar('IBMHPJ_OPTS=-Xskipgc -Xskipdupc'))”

Note: The -Xskipgc option is only recommended for short-lived applications.Additionally, the -Xskipgc option is not recommended for use outside of CICS, andit’s use is prohibited in multi-threaded applications.

Disabling duplicate class checking

You can specify the -Xskipdupc option in the IBMHPJ_OPTS environment variable,and duplicate class checking will not be done. By default, this option is NOT setand duplicate class checking in a Java DLL will be done. An error will begenerated if a class is defined more than once in a Java DLL.

-lerunoptsOS/390 bytecode binder and run-time environment variables

Applications targeted for IMSIf you are building an application targeted for IMS using the -target=IMS option ofthe hpj Command, you can specify run-time environment variables in anHPJENVAR DD statement in the JCL as follows://HPJENVAR DD PATH=’/u/user/hpjapp/env.var’where env.var is a file that contains a list of environment variables to be set, suchas:CLASSPATH=/u/user/hpjapp/jllThis has the same effect as specifying the following on the command line:hpj -lerunopts=“ENVAR(CLASSPATH=/u/user/hpjapp/jll)” . . .Note that the syntax for the command line is: environment variable=value (theexport keyword is not required).

-lerunopts-target

152 ET/390

Chapter 13. jport utility

The jport utility is used to identify unsupported Java code for the OS/390 UNIXand CICS/ESA environments. Because of the nature of OS/390 and CICSapplications, parts of the JDK are not supported in those environments; forexample, java.applet package is not supported. The jport utility reads Javabytecode files (.class files) and generates HTML files that list the unsupportedpackages, classes, methods, and fields for the OS/390 UNIX or CICS/ESAenvironments.

Verify portability of Java code inside the VisualAge for Java IDEIf you are using VisualAge for Java to build your OS/390 or CICS Java executableor DLL, select Verify portability of code for OS/390 in the ET/390 properties’ BindOptions panel, and the jport utility is automatically invoked when you select theET/390 export and bind action on the object.

Verify portability of Java code outside of the VisualAge for Java IDEIf you have Java bytecode that is on a local drive at the workstation, you can runthe jport utility on the DOS command line to verify the portability of your code forthe OS/390 UNIX or CICS/ESA environments. The jport package is under theVisualAge for Java root directory in ide/tools/com-ibm-ivj-et390.

Verify portability of Java code on OS/390If you have Java code that is on OS/390 HFS, you can run the jport utility in theOS/390 UNIX shell to verify the portability of your code for the OS/390 UNIX orCICS/ESA environments.

Viewing the output HTML filesTo view the HTML output, use a web browser to view the _StartHere.htm file.

Note: For NT workstations running in the German, French, Italian, Spanish orPortuguese locale, the log file generated by jPort has to be viewed using aWindows editor (such as Notepad) in order for the text to be displayed properly.

SyntaxYou can run the jport utility with the java command, which has the followingsyntax:java com.ibm.ivj.et390.jport.jport [options]

Note: When you run the jport utility in the OS/390 shell, you can optionally usethe following jport command:jport [options]

ScalabilityThe amount of memory required by jport is proportional to the size of the programto be analyzed. If the program is very large, jport may not have enough memoryto analyze it. You can consider the following options, if the jport utility runs out ofmemory during its processing:v Use the java -mx option to give jport more memory, as follows:

java -mx64M com.ibm.ivj.et390.jport.jport [options]


Note: This is not applicable when running the jport command in the OS/390shell.

v Analyze one package at a time instead of the whole application. The -unknownoption should be used to assume that unresolved references are supported.

optionsoptions can be entered sequentially with blank separators. They are:


-unix | -cics Must be specified. Verifies the portability of the Javacode to run under OS/390 UNIX orCICS/ESA.

-html=dir If not specified, the html files arewritten to the current directory.

Use this option to specify theoutput directory for the html files.

Existing files will be overwrittenwithout notification.

154 ET/390


-in=inputdir in=.+All the .class files in the currentdirectory and its subdirectories areverified by jport.

Lists input directories. jportverifies the portability of the codein all the .class files in the specifieddirectories. .class files in JAR andZIP files are ignored.

inputdir can be any one of thefollowing:

v .class fileOnly the specified file is verified.

v directoryAll .class files in the directory areverified. If you do not specify adrive (for example, c:) before thepath, it assumes the commandprompt’s drive.

v directory with a plus (+)All .class files in the specifieddirectory and all itssubdirectories are verified. If youdo not specify a drive (forexample, c:) before the path, thecommand prompt’s drive isassumed.

Period (.) specifies the currentdirectory. To specify more than onedirectory or file, separate the entrieswith semicolons(;) for

and colons (:) for

OS/390 UNIX.

Specify paths with backwardslashes (\) in the Windows

environment and with forwardslashes (/) for

OS/390 UNIX environments.

For example, t o run jport in theOS/390 shell, enter:

jport-in=/home/ts123456/new/query.class:/home/ts1234

-log=file Writes all messages to the console. Writes messages to the specified filein the -html directory, for example:-log=port1.log.

Chapter 13. jport utility 155


-native |-nonative

-native -native assumes that nativemethods are supported in theOS/390 UNIX or CICS/ESAenvironment. The generated HTMLfiles will list the unsupported nativemethods.

-unknown |-nounknown

-nounknown -unknownassumes that unresolvedreferences are supported in theOS/390 UNIX or CICS/ESAenvironment. The generated HTMLfiles will list the unsupportedreferences.

-verbose jport does not run in verbose mode. jport runs in verbose mode.

Using the jport utility with VisualAge for Java, Version 3.5The Integrated Development Environment (IDE) in VisualAge for Java, Version 3.5,is at the Java 1.2 level. The high-performance compiler on the S/390 host is at theJava 1.1 level. Due to these discrepancies in the JDK levels, we recommend thatusers of the high-performance compiler use Version 3.0x of VisualAge for Java,which is based on JDK 1.1.7.

Advanced users who want to develop their application in VisualAge for Java 3.5(Java2 level) and then use ET/390 to export/bind/execute/remotely debug/profileon the S/390 host should develop their programs by using strictly Java 1 API’s. InVisualAge for Java 3.5, the jport utility has been enhanced to determine whetheryour program uses any Java 2 API’s. To check if your code makes any calls to Java2 specific API’s, do the following:1. In the Bind Options properties dialog box for your project/package, select the

Verify the portability of the code checkbox.2. Do an Export and Bind action on the specified project/package/class.

If your code contains any Java 2 specific API’s, a Portability Problem dialog boxwill open to inform you that your application is attempting to use methods orclasses which are not supported by the target platform. This is the same messageyou see if your application calls any Java 1 API’s which are not supported inOS/390 (java.applet.* for example). To get more information about whatunsupported API is being used, and which class and method is calling that API,click the Details button in the Portability Problem dialog box.Unsupported API’s are all new public classes in Java 2, and all new public orprotected methods in any existingclasses.

Identifying OS/390 unsupported Java code

OS/390 bytecode binder’s JDK 1.1.6 support

156 ET/390

Chapter 14. ET/390 Java Install Data file

To perform remote bind, run, and debug actions in an OS/390 shell, VisualAge forJava requires the host session’s ET/390 Java installation information. This filecontains @@HPJfile tags and data set names as follows:v @@HPJHostName:

Is the TCP/IP host session name. The name is case sensitive.v @@HPJBinderExecutablesPDSE:

Is the PDSE containing the bytecode binder. Specify an asterisk (*) if the PDSE isadded to the LPA.

v @@HPJBinderMessagesPDSE:Is the PDSE containing the bytecode binder’s error messages. This is the samePDSE as the HPJBinder Executables PDSE.

v @@HPJLERuntimeBind:Is the statically bound component of Language Environment run time for thebytecode binder.

v @@HPJLERuntimeRun:Is the dynamic component of Language Environment run time for the Javaexecutable. Specify an asterisk (*) if the PDS is added to the LPA.

v @@HPJRuntime:Is the PDSE containing the DLLs for the run time. Specify an asterisk (*) if therun time is added to the LPA.

v @@HPJDebugger:Is the PDS containing the Debugger run time. Specify an asterisk (*) if the PDS isadded to the LPA.

v @@HPJProfiler:Is the PDS containing the Performance Analyzer run time. Specify an asterisk (*)if the PDS is added to the LPA.

v @@HPJJavaHome:Is the home directory containing the JDK bytecode files that are used whenrunning interpreted Java in the JVM on OS/390.

v @@HPJHome:Is the IBMHPJ_HOME directory containing the HFS root directory of bytecodebinder and its the JDK classes.

v @@HPJPICLHome:Is the home directory containing the JDK source files for the OS/390 hostdebugger.

v @@HPJFTPPort:Is the port number for the OS/390 UNIX FTP Server. If not specified, the defaultport of 021 is assumed.

v @@HPJREXECPORT:Is the port number for the REXEC server. If not specified, the default port of 512is assumed.

v @@HPJCICSRegion:Is the VTAM application identifier for the CICS region. It must match the namefield specified in the APPL statement of the VTAM VBUILD TYPE=APPLdefinition. The CICS region is used when user selects Refresh CICS Program inthe ET/390 properties’ Bind Options panel.


v @@HPJCICSEXCI:Is the identifier for the CICS External Interfaces PDS on the host. This tag is onlyrequired if the user selects the ET/390 export and bind action and RefreshCICS program in the ET/390 properties’ Bind Options panel.

v @@HPJCSFROM:Is the identifier for the host’s codepage name. If this tag is not specified,IBM-1047 is used as the default codepage.

v @@HPJCSTO:Is the identifier for the workstation’s codepage name. If this tag is not specified,ISO8859-1 is used as the default codepage.

v @@HPJIconvUCS2Pref:Is the identifier for the OS/390 dataset name prefix that is used by iconv to findthe UCS-2 tables. For more information on this topic, refer to the latest versionof OS/390 V1R3.0 C/C++ Run time Library reference for iconv(), andiconv_open().

v @@HPJFTPTransTable:Is used to specify an FTP translation table. If the tag is not specified in tha JavaInstall Data File, the default FTP translation table (OEMVS311) is used.

Syntax of Entries in ET/390 Install Data File@@HPJfiletags are required. All information following the tag’s colon up to the nextline break is considered the value for the tag. If the component that is specified bythe tag is not installed, you can omit the tag or leave the value blank after the tag.If any of the above system data sets are relocated after installation, you canmanually edit the ET/390 Java Install Data file on the host system.

When you add a host session at the workstation, VisualAge for Java downloadsthe contents of the ET/390 Java Install Data file to the workstation and saves it forall future remote ET/390 bind, run, and debug actions. If the install informationhas been changed in the ET/390 Java Install Data file on the host system, refreshthe host session at the workstation to get the new copy of the ET/390 Java InstallData file.

OS/390 Java development at the workstationET/390 Java properties

Adding OS/390 host sessionRefreshing OS/390 host sessionBuilding Java executables and DLLs to run under CICS/ESA (IDE)

Specifying the host codepage and workstation codepage in the ET/390Java install data file

There are three additional @@HPJ tags in the ET/390 Java install data file that areused by the ET/390 Run Executable and Run Main actions on the workstation:1.

The @@HPJCSFROM tag contains the host’s codepage name. If this tag is notspecified, IBM-1047 is used as the default codepage.

2.

The @@HPJCSTO tag contains the workstation’s codepage name. If this tag isnot specified, ISO8859-1 is used as the default codepage.

158 ET/390

3.

The @@HPJIconvUCS2Pref tag contains the OS/390 dataset name prefix that isused by iconv to find the UCS-2 tables. For more information on this topic,refer to the latest version of OS/390 V1R3.0 C/C++ Run time Library referencefor iconv(), and iconv_open().

ET/390 Java install data file

Chapter 14. ET/390 Java Install Data file 159

160 ET/390

Chapter 15. hpj command options in ET/390 properties

The Enterprise Toolkit for OS/390 (ET/390) allows you to develop OS/390 Javaapplications on the host in an OS/390 shell or at the workstation in the VisualAgefor Java IDE. If you are already familiar with the hpj command, the followingtable provides a quick reference between the hpjoptions and the entries in theET/390 properties panels.

You can also use the F1 key to get help information when you are updating theET/390 properties panels. See the related tasks at the end of this page for details.

hpj Option ET/390 Properties Panel and Options Defaults set byET/390 Properties

-alias=name Bind Options

v PDSE member name

Alias names areautomaticallygenerated for DLLs inPDSE members. Thealias name is basedon the package name.

-architecture=0|1|2|3 Advanced Bind Options

v Code is generated for architecture 0.

Code for hardwarearchitecture.

-BLIST$type$ Advanced Bind Options

v Binder map to include

Binder map is notgenerated.

-BXREF$YES|NO$ Advanced Bind Options

v Binder map cross-reference

Binder mapcross-reference is notgenerated.

-c Advanced Bind Options

v Object files only

Java executable orDLL is generated.

-check args Advanced Bind Options

v Other bind options

Specify the optionyourself.

-classpath=path Export and Bind Session

v Bind CLASSPATH

Set to the bytecodebinder’s JDK classesand the contents ofthe CLASSPATHenvironment variable(in that order).

-collapse Advanced Bind Options

v Objects in one directory

.o and .lst files arewritten to directoriesfollowing the packagestructure.

-comment=“string” Advanced Bind Options

v Comment in program object

No comment string isadded to the programobject.

-d=path Export and Bind Session

v Directory for objects and lists

.o and .lst files arewritten in thespecified rootdirectory.

-exclude=name |-include=name

Advanced Bind Options


Specify the optionyourself.



-exe | -jll Bind Options

v Build a Java executable

v Build a Java DLL

Builds a Javaexecutable.

-follow Bind Options

v Bind referenced classes

Referenced classes arenot bound.

-g[=hook|nohook] Bind Options

v Data for debug and trace

v With hooks

Does not generatedata for debug andtrace.

-help Not available Not applicable.

-inlrpt Advanced Bind Options

v Inline report

Inline report is notgenerated.

-lerunopts=“string” Bind Options

v Bind run-time options

Note: If selected, the run-time options thatare bound are the ones specified in theRun-Time Options, Advanced Run-TimeOptions, Debugging Options, and TracingOptions panels.

LanguageEnvironmentrun-time options arenot bound in the Javaexecutable or DLL.

-list=[offset| nooffset] Advanced Bind Options

v Pseudo-assembler listing

Pseudo-assemblerlisting is notgenerated.

-main=classname Bind Options

v Main class name

Defaults to the firstclass with mainmethod found duringthe binding of a Javaexecutable.

-make Advanced Bind Options


ET/390 generates-make when buildingyour applications.

-maxmem=size Advanced Bind Options

v Maximum memory size

Maximum memorysize is set to2097152K bytes.

-o=name Export and Bind Session

v Directory for executable or DLL

and Bind Options

v Name for executable or DLL

v PDSE member name

There is no defaultname for Java DLLand when creatingprogram objects inPDSE members.

-O Advanced Bind Options

v Optimize

Do not optimize.

-partial=name Advanced Bind Options


Specify this optionyourself.

-resource Bind Options

v Include resources

Does not includeresources.

162 ET/390


-t=dir Bind Options

v Runtime CLASSPATH

If resources areincluded or if a jll isbuilt, then thedefault is the rootdirectory.

-tune=0|1|2|3 Advanced Bind Options

v Tune

Depends on theselection of Code forhardwarearchitecture.

-verbose Advanced Bind Options

v Verbose information

Do not run in verbosemode.


Getting F1 Help for the ET/390 properties windowGetting started with the building of OS/390 Java executables

hpj command

Chapter 15. hpj command options in ET/390 properties 163

164 ET/390

Chapter 16. Specifying the DLL search order when usingSystem.loadLibrary( )

Use the LIBPATH to specify the directories where the library is to be searched. Thelibrary name to be loaded is prefixed by “lib” and suffixed by “.so”.

For example, if you invoke “System.loadLibrary(<libname>)” while the LIBPATHenvironment variable is set to “<path1>:<path2>:<path3>”, an attempt is made toload each DLL in the following list until one is successfully loaded or the list isexhausted:1. <path1>/lib<libname>.so2. <path2>/lib<libname>.so3. <path3>/lib<libname>.so

That is, if you invoke System.loadLibrary(“Myprog”) while LIBPATH is set to“.:/usr/bin”, an attempt to load DLLs in the following sequence until one isfound:1. ./libMyprog.so2. /usr/bin/libMyprog.so

CICS Note: When you use System.loadLibrary() under CICS, the library has to bebound into a PDSE member, and its alias name should be prefixed by “lib” andsuffixed by “.so”. For example, for System.loadLibrary(“user_test_Native”), youhave to create a PDSE member for the library and its alias name should belibuser_test_Native.so. The PDSE must be concatenated to DFHRPL.


166 ET/390

Chapter 17. Euro-currency support

This section describes Euro-currency support provided in VisualAge for Java,Enterprise Edition for OS/390, Version 2.0.

PTFs for new and modified codepages

To provide Euro-currency support, you need to install the new LanguageEnvironment PTFs that support the new and modified codepages.

The APAR numbers are: PQ17423, PQ17424, PQ19414, PQ21715, OW36900.

For details about the Language Environment PTFs, go tohttp://www.s390.ibm.com/le/whatsnew/euro.html.

Running in OS/390 UNIX

If you are using ET/390 to run an executable in OS/390 UNIX, you need to do thefollowing to see the Euro symbol in the output log window:1.

Install Service Pack 4 for Windows NT 4.0. This will add the Euro symbol tothe Windows fonts.

2.

Change the font for the VisualAge for Java log window to be one of the fontsthat have Euro symbol support, as follows:a. In VisualAge for Java, click Windows...Options.b. In the Options notebook, select Appearance...Source.c. Select one of the fonts that have Euro symbol support, such as Courier New,

Arial, or Times New Roman.3. Add the following line to your Pre-Run script:

export LC_ALL=your_euro_locale_on_hostwhere your_euro_locale_on_host is, for example, En_US.IBM-1140. To determineyour Euro locale, refer to the OS/390 C/C++ Programming Guide - Euro-CurrencySupplement available at http://www.s390.ibm.com/le/whatsnew/euro.html.

4. Set the @@HPJCSFROM, @@HPJCSTO and @@HPJIconvUCS2Pref tags in yourET/390 host initialization file. For details, refer to the related references topic atthe bottom of this page.

Displaying or entering the Euro symbol

If you are running an executable on OS/390 by directly connecting to the hostusing a TN3270 session, and you want to enter the Euro symbol from the keyboardor see it on the screen, you need to use one of the following:v

A Telnet 3270 client that supports the new Euro codepagesv

IBM eNetwork Personal Communications V4.3 orIBM Personal Communications Version 4.2 for Windows 95 and Windows NTwith CSD2.


For details about these products, go tohttp://www.software.ibm.com/enetwork/pcomm/.

Default locale

The default locale for OS/390 Java Bytecode Binder and Java run-time is set toEn_US.IBM-1047. This default locale uses codepage IBM-1047, which does notsupport the Euro symbol.

If you want to set the system locale for the high-performance compiler runtime tobe one of the locales that recognize the Euro symbol, you need to export the valuefor environment variable LC_ALL to be this locale. For example, for the US Englishlocale:export LC_ALL=EN_US.IBM-1140You should always use the default locale for binding Java applications. The localeshould be changed only before running the executable.

Examples for using the Euro-currency format

We provide two examples for using the Euro-currency format, both of which arelocated in the examples.mvs directory where the OS/390 Bytecode Binder isinstalled.v

EuroIO demonstrates the use of the Euro symbol in the Console I/O and FileI/O.To run EuroIO with the En_US.IBM-1140 locale, type the following at theOS/390 Unix System Services command line:export LC_ALL=EN_US.IBM-1140 ; exec sh ; chcp -e IBM-1140EuroIO

vEuroFormat demonstrates how to format an amount in a country’s localcurrency format as well as the Euro format.EuroFormat uses the Resource bundle for the Euro locale if it is provided withthe JDK. Otherwise, the formatting is done manually according to the followingstandard rule: The Euro-currency format is the same as the national currencyformat, with two changes::– The currency sign is the Euro sign.– The number of fraction digits is always 2.

Note:In JDK 1.1, the currency symbol is not part of the currency pattern, andthere is no method available to change the currency symbol. The methoddemonstrated in EuroFormat will work for most of the other locales supportedin JDK 1.1.6 that do not have their corresponding Euro locale.

If you are using ET/390 to run your Java application, remember to set the@@HPJCSFROM, @@HPJCSTO and @@HPJIconvUCS2Pref tags in your ET/390host initialization file. For details, refer to the related references topic at the bottomof this page.

ET/390 Java Install Data file

168 ET/390

Chapter 18. Run-time errors

This section lists run-time errors you might encounter and actions to correct them.

Message : HPJ9001SExplanation :DLL HPJDLL could not be loaded.Programmer Response :Verify that the DLL is available in your LIBPATH and yourMVS search order.Return code : 16Message :HPJ9002SExplanation :DLL HPJDLLhas an invalid format.Programmer Response :Verify that the version of the DLL provided by IBM isavailable in your LIBPATH and your MVS search order.Return code :16Message : HPJ9003SExplanation :Unable to obtain the memory to set up a high-performance compilerenvironment.Programmer Response :Verify that enough memory is available to your program.Return code :16Message :HPJ9004EExplanation :The high-performance compiler terminated abnormally.Return code :8


170 ET/390

Chapter 19. Troubleshooting Export and Bind, Run Executableand Debug Ex operations

If you run into problems performing Export and Bind, Run Executable and DebugEx operations, you can use the following command files on OS/390 to determinewhat happened. The command files list the steps that were performed for eachcommand.v

Export and Bind: /tmp/userid.cmdtsv

Run Executable and Debug Executable: /tmp/userid.cmdtsv

Run Main and Debug Main: /tmp/userid.cmdts

When a command file runs, it generates a time stamp that is included in its name,like this:/tmp/ts28977b.cmd910646081636

ET/390 properties

Getting started with the building of OS/390 Java executables



172 ET/390

Chapter 20. MVS batch support

Applications compiled using the high-performance compiler can execute underMVS batch. To do so, you must install the high-performance compiler PTFsUQ90022 and UQ90023, or later.

The following JCL example executes a Java executable called TEST1. It is a memberof the PDSE dataset USER.JAVA.LOAD, which is specified in the STEPLIB. Theoutput, if there is any, is written to DD SYSPRINT.The environment variable is set up using the Language Environment run-timeoption ENVVAR in the PARM statement as follows://HPJBATCH EXEC PGM=TEST1,// PARM='ENVVAR(“_CEE_ENVFILE=DD:MYVARS”) POSIX(ON)/'//STEPLIB DD DSN=HPJAVA.JAV2R0M0.SHPJMOD,DISP=SHR// DD DSN=HPJAVA.JAV2R0M0.SHPOMOD,DISP=SHR// DD DSN=USER.JAVA.LOAD,DISP=SHR//SYSPRINT DD *//MYVARS DD PATH='/u/home/test/env.file'

The environment variable file env.file contains the following statements:IBMHPJ_HOME=/hfs/hpj/CLASSPATH=/u/home/test:$CLASSPATH

When running under batch, you should not export the STEPLIB in theenvironment variable file (in this example, env.file) because it will be ignored. Ifyou need a STEPLIB statement, specify it as shown in the JCL example shownabove.

For information about setting up CLASSPATH searches for PDSE members, refer tothe related tasks at the bottom of this page.

Invoking OS/390 Unix System Services from MVS BatchApplications compiled using the high-performance compiler can execute underOS/390 UNIX System Services using the MVS Batch utility BPXBATCH.BPXBATCH allows you to run shell commands, shell scripts, and executable filesin the hierarchical file system (HFS) through the MVS batch environment. You caninvoke BPXBATCH from a JCL job or from TSO/E (as a command, through aCALL command, or from a CLIST or REXX EXEC).

You can find detailed descriptions of BPXBATCH in the following manuals:v OS/390 UNIX System Services Command Reference

v OS/390 UNIX System Services User’s Guide

For a list of restrictions related to using BPXBATCH, see the “Running Shell Scriptsor Executable Files under MVS Environment” section of the OS/390 UNIX SystemServices Command Reference.

Invoking BPXBATCH from JCLThis JCL example executes a Java executable called test1 in directory home/user1.The output, if there is any, is written to test1.out (DD STDOUT), and errormessages are written to test1.err (DD STDERR).

All environment variables read from env.file (DD STDENV) are set at the start ofthe executable program, and not for BPXBATCH itself. This is worth noting


because setting up a PATH to find test1 in env.file won’t help BPXBATCH find it,unless you explicitly specify the directory information as in this example.

Note that if STEPLIB is exported in env.file, then it takes precedence over all otherSTEPLIB declarations. In this example, the DD STEPLIB specified in this JCL willnot be in effect if env.file also sets STEPLIB.//STEP1 EXEC PGM=BPXBATCH,// PARM='PGM /home/user1/test1'//STEPLIB DD DSN=HPJAVA.JAV2R0M0.SHPJMOD,DISP=SHR// DD DSN=HPJAVA.JAV2R0M0.SHPOMOD,DISP=SHR//STDOUT DD PATH='/home/user1/test1.out',// PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU//STDERR DD PATH='/home/user1/test1.err',// PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU//STDENV DD PATH='/home/user1/env.file',// PATHOPTS=(ORDONLY)

Invoking BPXBATCH from TSO/E READYThis example is similar to the previous one, except that the shell script is invokedusing a REXX exec./* rexx */

“ALLOCATE FILE(STDIN)PATH('/home/user1/test2.sh')PATHOPTS(ORDONLY)”

“ALLOCATE FILE(STDOUT)PATH('/home/user1/test2.out')PATHOPTS(OWRONLY,OCREAT) PATHMODE(SIRWXU)”

“ALLOCATE FILE(STDERR)PATH('/home/user1/test2.err')PATHOPTS(OWRONLY,OCREAT) PATHMODE(SIRWXU)”

“ALLOCATE FILE(STDENV)PATH('/home/user1/env.file')PATHOPTS(ORDONLY)”

“BPXBATCH”

Running a Shell Script using JCLIn this example, BPXBATCH invoke a shell script called test2.sh. This shell scriptin turn compiles and generates an excutable called test2, and then runs it. For thisshell script to run, it assumes that the PATH was previously set up to locate boththe javac and hpj command. This may already be done as your system installationdefault, or you could set up the PATH in your user profile (.profile).

Note that PARM=’SH’ is the default when not specified. SH starts a login shellwhich processes your .profile before running a command or shell script.//STEP2 EXEC PGM=BPXBATCH//STDIN DD PATH='/home/user1/test2.sh',// PATHOPTS=(ORDONLY)//STDOUT DD PATH='/home/user1/test2.out',// PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU//STDERR DD PATH='/home/user1/test2.err',// PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU//STDENV DD PATH='/home/user1/env.file',// PATHOPTS=(ORDONLY)

The shell script test2.shcontains the following statements:cd /home/user1javac test2.javahpj -o test2 test2test2

174 ET/390

Running a Shell Script Using JCL with Inlined STDENVThis example is the same as the previous one except that the environmentvariables are inlined within the JCL, instead of setting them from a file.//STEP3 EXEC PGM=BPXBATCH//STDIN DD PATH='/home/user1/test2.sh',// PATHOPTS=(ORDONLY)//STDOUT DD PATH='/home/user1/test2.out',// PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU//STDERR DD PATH='/home/user1/test2.err',// PATHOPTS=(OWRONLY,OCREAT),PATHMODE=SIRWXU//STDENV DD *PATH=/bin:/home/user1CLASSPATH=/u/usr/classes.zipSTEPLIB=HPJAVA.V2R0M0.SHPJMOD:HPJAVA.V2R0M0.SHPOMODIBMHPJ_HOME=/hfs/hpj//*

Accessing PDSE Java DLLs under OS/390 UNIX

Chapter 20. MVS batch support 175

176 ET/390

Chapter 21. High-performance compiler programming APIs

The high-performance compiler programming APIs are intended for vendors todesign and implement tools that will perform specialized tasks against a programobject generated by the high-performance compiler, or who need to get informationfrom the program object. The APIs are meant to be a programmatic way to obtaininformation, and do not maintain any state information. The APIs will not provideall information required for a particular application. For the information that theAPIs do not provide, system binder interfaces or LE/390 vendor interfaces may berequired.

The high-performance compiler compiles and binds Java applications into one ormore program objects. The program object must reside in a PDSE or the HFS. Eachprogram object bound by the compiler consists of the user’s Java code and a smallamount of statically bound run-time code. No user code from any other languagecan be bound into this program object. If a user wishes to do ILC (inter-languagecall), they need to use the JNI (Java Native Interface) support and build a separateDLL, which can be a program object. There is one exception where Java code andC code are present in the same program object. This is the primaryhigh-performance compiler run-time program object called HPJDLL.

An application generated by the high-performance compiler can be run in anOS/390 USS environment, Batch or a CTS 1.3 environment. No support is currentlyprovided for other environments such as TSO, (IMS), VM, VSE, or TPF. The APIsare grouped in a new load module called HPJPINFO, and are shipped as part ofthe compiler run-time system. Before using the APIs, tool vendors need to load theAPI load module using standard system load services, and call the entry point ofthe module. A vector of function pointers will be returned. You make a call to anAPI through the function pointer in the vector.

Besides shipping the API load module, we also provide a sample C header file,hpjpinfo.h,which describes the APIs in C language. The header file defines thefunction prototypes of the interface and types used by the APIs. A sample Cprogram is also provided to show you how to use the APIs to print outinformation about an application generated by the high-performance compiler.

The following APIs are provided:v obtainModule - Given an address in a high-performance compiler program

object, return a module handle.v modVersion - Given a module handle, return the version level of the module.v modName - Given a module handle, return the fully qualified program object

name, if known.v modLoadPt - Given a module handle, return the load point for the program

object.v modEntryPt - Given a module handle, return the entry point for the program

object.v modSize - Given a module handle, return the size of the program object.v freeModule - Free the module handle created by obtainModule.v obtainCUList - Given a module handle, return the vector of compilation unit

handles associated with the program object.


v cuName - Given a compilation unit handle, return the compilation unit name, ifknown.

v freeCUList - Free the compilation unit handle list created by obtainCUList.v obtainFnList - Given a compilation unit handle, return the vector of function

handles associated with the program object.v fnName - Given a function handle, return the function name, if known.v fnLineTable - Given a function handle, return the line number table, if known.v freeFnList - Free the function handle list created by obtainFnList.

obtainModule

Given an address in a high-performance compiler program object, return a modulehandle. If the address is not contained in an active high-performance compiler Javaprogram object, return 0 (NULL).

Parameters

Name Type Usage Description

svc HPJSvc_T* input Service routines formemory management

entry void* input Address in anhigh-performancecompiler programobject

Return Type

Type Description

HPJModule_T* Module handle for the high-performancecompiler Program Object. This object isallocated by obtainModule() and will befreed only when feeModule() is called.Memory will be allocated (and later freed)using the memory management routinesprovided in the svc parameter.

modVersion

Given a module handle, return the version level of the module.

Parameters


srv HPJSvc_T* input Service routines formemory management

mod HPJModule_T* input Module handleobtained fromprevious call toobtainModule()

Return Type

Type Description

178 ET/390

int Version level of the module in question. Theversion level consists of a version, release,and modification level represented asVVRRMMMM, where VV is the first 8 bits,RR the next 8 bits and MMMM the last 16bits. Currently only Version 1.0.0,(x’01000000’) is returned. Note that onlyobtainModule() and modVersion() areguaranteed to be valid in subsequentreleases of this interface.

The version level of the module isdetermined from the module handle. Ahigh-performance compiler applicationconsisting of multiple modules may havedifferent versions for each module.

modName

Given a module handle, return the fully qualified program object name, if known.

Parameters




Return Type

Type Description

HPJVarStr_T* Variable length name of the program object.The name may either be a fully qualifiedPDSE name or a fully qualified HFS name. Ifthe name is not known, NULL is returned.

modLoadPt

Given a module handle, return the load point for the program object.

Parameters




Chapter 21. High-performance compiler programming APIs 179

Return Type

Type Description

void* Load point of the program object. Note thatthis may not be the same address as theentry point of the program object.

modEntryPt

Given a module handle, return the entry point for the program object. The entrypoint of all high-performance compiler program objects is always CEESTART.

Parameters




Return Type

Type Description

void* Entry point of the program object. Note thatthis may not be the same address as theload point of the program object.

modSize

Given a module handle, return the size of the program object.

Parameters




Return Type

Type Description

unsigned int Size of the program object. The size andload point of the program object can be usedtogether to determine the range of codeassociated with this program object.

freeModule

180 ET/390

Free the module handle created by obtainModule. Memory will be freed using thememory management routines provided in the svc parameter.

Parameters



Return Type

none

obtainCUList

Given a module handle, return the vector of compilation unit handles associatedwith the program object. This service is designed to be called twice - once to obtainthe size of the CU list and a second time with a pre-allocated list. This enables thetool to control storage allocation - for example it could determine that it wouldonly obtain CU information if less than 200K of storage was required.

In high-performance compiler terms, a compilation unit is an OS/390 nativeversion of a Java class file. Here is the process for building an high-performancecompiler application:v A Java source file is written. This source file can consist of many classes. Each

class may additionally contain inner classes.v The source file is compiled using javac, VA Java, or some other technique to

generate a set of byte-code files, called class files. Each class file contains exactly1 Java class. So, 1 Java source file can produce many byte-code files. Thiscompilation may happen on OS/390 or it may happen on another computer.

v The class files are then bound into object decks using the high-performancecompiler on OS/390. Every class file is converted into exactly one extendedobject deck. The object decks can then be bound using the system binder or thehigh-performance compiler into a program object.

An example might be that a user writes the following in the VAJava IDE:

package com.ibm.sample;

class A {int fn1() { ... }int fn2() { ... }

}

class B {int fn1() { ... }int fn2() { ... }

}

The byte-code is then exported to the USS OS/390 environment and the sourcecode exported to the user’s NT 4.0 client. Two class files will be generated - onefile called A.class in directory com/ibm/sample and one file called B.class incom/ibm/sample. Each class file will have the relative name of the source file inthe byte-code stream, namely A.java and B.java respectively.


The byte-code streams are then bound by the high-performance compiler runningon OS/390 into 2 extended object decks, which are then bound by the systembinder into a program object. This program object happens to be calledcom/ibm/sample.jll, but it could have had a different name and may have beenbound into a PDSE instead of the HFS file system. The compilation unit name willbe generated by combining the package and class names, yielding./com/ibm/sample/A.java and ./com/ibm/sample/B.java. The ’./’ at the start ofthe name indicates the name is relative. If the source is compiled on anotherplatform, the original source file may or may not be present on OS/390. In thisscenario, the source is only present on NT 4.0.

If the source code had been written in a text editor instead of VAJava, with bothclasses in MySource.java and javac was used to compile the source code, then therelative name of the source file in the byte-code stream would have beenMySource.java for both class files. If the high-performance compiler was then usedto bind the code, the compilation unit name would have been./com/ibm/sample/MySource.java for both compilation units.

Parameters




cuList HPJCU_T** input/output On output, thisvector will containthe compilation unithandles for thismodule, if the vectoris large enough tohold this information.The size of thisvector is indicated bythe size parameter.Nothing is written onoutput if the vector isnot large enough.

size size_t input size of CU list, inbytes

Return Type

Type Description

size_t Required size of the compilation unit listvector.

cuName

Given a compilation unit handle, return the compilation unit name (also known asthe source file name), if known.

182 ET/390

Parameters



mod HPJCU_T* input Compilation unithandle obtained froma previous call toobtainCUList().

Return Type

Type Description

HPJVarStr_T* Variable length name of the original Javasource file. The name may be either a fullyqualified HFS file name or a relative HFSfile name. If the name can not bedetermined, NULL will be returned. Notethat this name may not be unique since anapplication can have multiple classes in oneJava source file.

freeCUList

Free the compilation unit handle list created by obtainCUList. Memory will befreed using the memory management routines provided in the svc parameter.

Parameters



Return Type

none

obtainFnList

Given a compilation unit (CU) handle, return the vector of function handlesassociated with the program object. This service is designed to be called twice -once to obtain the size of the function list and a second time with a pre-allocatedlist. This enables the tool to control storage allocation - for example it coulddetermine that it would only obtain function information if less than 200K ofstorage was required.

Parameters




mod HPJCU_T* input Compilation Unit(CU) handle obtainedfrom previous call toobtainCUList()

cuList HPJFn_T** input/output On output, thisvector will containthe function handlesfor this module, ifthe vector is largeenough to hold thisinformation. The sizeof this vector isindicated by the sizeparameter. Nothing iswritten on output ifthe vector is notlarge enough.

size size_t input size of function list,in bytes

Return Type

Type Description

size_t Required size of the function list vector.

fnName

Given a function handle, return the function name, if known. No function namewill be available if the compilation unit is build with the -compress option.

Parameters



mod HPJFn_T* input Function handleobtained from aprevious call toobtainFnList().

Return Type

Type Description

HPJVarStr_T* Variable length name of the function name.The name will be a human-readable(demangled) function name. If the namecannot be determined, NULL will bereturned. The function name will not beavailable if the compilation unit has beenbuilt with the -compress option.

fnLineTable

184 ET/390

Given a function handle, return the line number table, if known. Only a truncatedline number table will be available if the compilation unit is built with the-compress option.

Parameters



mod HPJFn_T* input Function handleobtained from aprevious call toobtainFnList().

isTrunc int* output Set to 1 if there is aline number tableand it is truncated.Set to 0 if the linenumber table is nottruncated.

Return Type

Type Description

HPJLineTable_T* Line number table for the function inquestion, or NULL if no line number table isavailable.

freeFnList

Free the function handle list created by obtainFnList. Memory will be freed usingthe memory management routines provided in the svc parameter.

Parameters



Return Type

none

Type Descriptions

Descriptions of types used in the interface follow.

Name Description (type description in C)

HPJModule_T Handle representing the program objectassociated with it.

typedef void* HPJModule_T;


HPJCU_T Handle representing the compilation unit(CU) associated with it.

typedef void* HPJCU_T;

HPJFn_T Handle representing the function associatedwith it.

typedef void* HPJFn_T;

HPJLineTable_T Line number table for a particular function.See Line number Table (page 187) section formore detail description.

typedef _Packed struct HPJLineEntry_S {_Packed struct {

int reserved:1;int offset:14;int hook:1;int linNum:27;int stmtnum:5;

} entry;} HPJLineEntry_T;

typedef _Packed struct {char* nxtEntry; /* one

blockEntry/line entry list per block */HPJLineEntry_T line[1]; /* one entry

per line/stmt in block*/} HPJBlockEntry_T;

/* Line Number table for a function.* The first two fields (fnEntry and fnSize)

are present* in all line number table. There is one* blockEntry/entry section for every block

in a* function, if the table is not truncated.* There is one entry for every statement

in the block.* A Special entry of 0x0e0e0e0e0e0e

indicates the end* of the table*/

typedef struct {char* fnEntry; /* function entry

point */int fnSize; /* function size */

HPJBlockEntry_T block[1]; /* BlockEntry */

} HPJLineTable_T;

186 ET/390

HPJSvc_T Service routines provided to the interfaceroutines to obtain and free storage. The Cservices malloc() and free() would bereasonable candidates.

typedef struct {void * (*getStorage) (size_t bytes);/*

pointer to get storage function */void (freeStorage) (void*p); /*

pointer to free storage function */} HPJSrv_T;

HPJVarStr_T Variable length string.

typedef struct {short len; /* length of the

string */char str[1024]; /* allocate the

string up to 1K */} HPJVarStr_T;

Line Number Table

Each function in a compilation unit has a Line Number Table. There are twoformats of Line Number Table, truncated or full. A full version of line numbertable is generated by default which contains entries for function prologue, normalstatements and debug hooks. If -compress option is specified, the truncatedversion of line number table is generated.

Format

The basic format of the truncated line number table is as follows:

Truncated Line Number Table FormatA (Function Entry) 4 bytes

Size of Code for function (in bytes) 4 bytes

The basic format of the full line number table is as follows:

Truncated Line Number Table FormatA (function entry) 4 bytes

Size of code for function (in bytes) 4 bytesA (end of first section or start of second section) 4 bytes

Line number table entry 6 bytesLine number table entry

——-A(end of second section or start of third section) 4 bytes

Line number table entry 6 bytesLine number table entry

——-etc.

Table end (X’0E0E0E0E0E0E’)


Line Number Table FormatReserved 1 bit

Statement offset (in halfwords) 14 bitsHook bit 1 bitReserved 10 bits

Line number 17 bitsStatement number 5 bits

Line Number Table Entries

Minimally, the line number table contains one entries for function prologue. Theoffset for the prologue entry is always 0x0. If -g=hook or -g option is specified, 2additional line number table entries are generated: one for the function entry hookand one for the function exit hook. These additional entries have offsets equal tothe location of the respective hook from the start of the function. This hook bit isset off and the statement number on line is 0 for these entries.

Each statement has as most one entry in the line number table. If an entry existsfor the statement, the hook bit is set on. There is no entry if the statement hasbeen moved or optimize out. There are never any line number table entries orhooks generated for null statements. The offset field represents either the offset ofthe statement or the offset of the statement hook (if one exists) from the start of thefunction. Since the allocation of statement offset is only 14 bits in halfwords, thislimits the number of offset to 32K. If the limit is reached, a new block entry iscreated with the statement number increment by one.

Additional line number table entries exist for block hooks. Since thehigh-performance compiler generates no special or additional code for blocks theseentries describe the hook only. The abnormal bit and hook bit are never on forsuch entries. The statement number on line is 0 for such entries.

The line number field represents the actual line on which the statement started.

Example

The following sample will be shipped to illustrate how to get information of ahigh-performance compiler program object reside in PDSE. The sample containsone header file, hpjpinfo.h, and one C program, hpjtstx.c and one assembler file,modload.asm.

hpjpinfo.h:

This header file contain the definition of types used by the interface and thefunction prototypes of the interface in C.

hpjtstx.c:

This is the main program of the sample. The following is a high level descriptionof the sample:v Take a high-performance compiler program object as an input from the

argument list and call MODLOAD assemble routine to load and get the addressof the program object.

188 ET/390

v Fetch the interface module, HPJPINFO in the same address space that thehigh-performance compiler program object is running in.

v Call the entry point of the module which will return a vector of functionpointers. The interface is called through the function pointer from the vector.

v Call obtainModule() to get a module handle for the program object.v Call modVersion() to get the version of the program object.v Call modName(), modLoadPt(), modEntryPt() and modSize() to get the module

name, load point, entry point and size.v Call obtainCUList() twice to find out how many compilation units and which

compilation units are in the program object with a module handle. The first callreturns the size of the CU list and the second call returns an array ofcompilation unit handles with the preallocated CU list.

v Call obtainFnList() twice to find out how many functions and which functionsare in the compilation unit with the compilation unit handle. The first callreturns the number of functions in the compilation unit and the second callreturns an array of function handlers with the preallocated function list.

Note that it will vary depending on the tool to determine an address in a loadedprogram object that you want information on. When the module handle is nolonger needed, it should be free by calling freeModule().

modload.asm:

This assembler program calls LOAD macro to load a program object from a PDSEin the address space and return the entry of the program object in R0. Thisaddress will be passed to obtainModule() interface to obtain the module handle.

Note that the LOAD assembler marco doesn’t work on a HFS program object. Youmay want to use another way, e.g. CEEPLOAD CWI, to determine the address aHFS program object.


190 ET/390

Chapter 22. Samples

Example JNI: Java calling C native method and C calling Java methodThis example contains Java and C programs. It demonstrates native C calls from aJava program and Java calls from a C program. There are three Java programs andone C program. The sample programs are shipped with the product. You canaccess it in example.mvs/jni directory under the installation root specified by theIBMHPJ_HOME environment variable. To build any JNI examples, type make inthe directory where the examples are located.

The source files and build files are:v HelloJNIMain.java

Sets the variables w, x, y, z,and d. It instantiates the object myHelloJNI fromclass HelloJNI. It calls three methods in myHelloJNI (which happen to be calls tonative methods) and passes parameters. Parameters include d which is IEEEfloating format and y which is a char in Unicode format.

v HelloJNI.javaDeclares three native methods, displayHelloJNI1, displayHelloJNI2, anddisplayHelloJNI3. It also explicitly calls java.lang.System.load to load the C DLL,libmyJNI.so, which contains the C native methods.

v HelloJNIImp.cImplements the native code in C language. It includes header file jni_convert.h,which support string conversions between Unicode and EBCDIC.It has three functions:– displayHelloJNI1

- Accepts jlong, jint, jshort, and jchar parameters and prints them. It convertsjlong data to EBCDIC string for printing.

- Calls another Java method, HelloJNIAPI.Display. It uses jni_convertfunction, NewString Platform, to convert the C strings that contain thename of the Java class and the Java method to Java string objects beforecalling the Java method.

– displayHelloJNI2Accepts jdouble parameters. It demonstrates the use of float_md.h functions,for example, dbl_sub() to perform operations on jdouble data.

– displayHelloJNI3Accepts a jlong parameter. It demonstrates the use of longlong_md.hfunctions, for example, ll_add() and ll2str() to perform operations on jlongdata.

v HelloJNIAPI.javaContains a java method (HelloJNIAPI.Display) which accepts a Java int and aJava long and prints them. This method will be invoked from C.

v MakefileBuilds the Java executable, HelloJNIMain, and calls makefile.dll to build the CDLL.

v makefile.dllBuilds the C DLL, libmyJNI.so.

To run the example, type HelloJNIMain.



Example JNI_JVM: C program invoking JVM and a Java methodThis example shows how to start the JVM and call a Java method from C program.There is one Java program and one C program. The sample programs are shippedwith the product. You can access it in example.mvs/jni_jvm directory under theinstallation root specified by the IBMHPJ_HOME environment variable. Thisexample demonstrates how to invoke the JVM and call a Java method in a Cprogram. To build any JNI examples, type make in the directory where theexamples are located.

The source files and build files are:v HelloJNIAPI.java

HelloJNIAPI.java has a method, Display, which accepts an integer and displaysit.

v HelloJNIAPIMain.cLoads and initializes a JVM and then calls a Java method. It uses jni_convertfunctions.

v MakefileBuilds the Java DLL, HelloJNIAPI.dll.

v makefile.dllBuilds the C load module.


Example JNIETYPES: Java program calling C function and passingdifferent emulated data types

This example contains a Java program and a C program. It demonstrates native Ccalls from a Java program. The sample programs are shipped with the product.You can access it in example.mvs/jnietypes directory under the installation rootspecified by the IBMHPJ_HOME environment variable. To build any JNI examples,type make in the directory where the examples are located.

The source files and build files are:v jnietypesMain.java

Makes use of JNI native methods which return emulated data types.v jnietypes.c

Uses emulated data types and some math library functions.v Makefile

Builds the Java executable, jnietypesMain, and calls makefile.dll to build the CDLL.

v makefile.dllBuilds the C DLL, libjnietypes.so.


192 ET/390

Notices

Note to U.S. Government Users Restricted Rights — Use, duplication or disclosurerestricted by GSA ADP Schedule Contract with IBM Corp.

This information was developed for products and services offered in the U.S.A.IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user’s responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OR CONDITIONS OF NON-INFRINGEMENT,MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some statesdo not allow disclaimer of express or implied warranties in certain transactions,therefore, this statement may not apply to you.This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.


Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

Lab DirectorIBM Canada Ltd.1150 Eglinton Avenue EastToronto, Ontario M3C 1H7Canada

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.The licensed program described in this document and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement or any equivalent agreementbetween us.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples may includethe names of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:This information contains sample application programs in source language, whichillustrates programming techniques on various operating platforms. You may copy,modify, and distribute these sample programs in any form without payment toIBM, for the purposes of developing, using, marketing or distributing applicationprograms conforming to the application programming interface for the operatingplatform for which the sample programs are written. These examples have notbeen thoroughly tested under all conditions. IBM, therefore, cannot guarantee orimply reliability, serviceability, or function of these programs. You may copy,modify, and distribute these sample programs in any form without payment toIBM for the purposes of developing, using, marketing, or distributing applicationprograms conforming to IBM’s application programming interfaces.

Each copy or any portion of these sample programs or any derivative work, mustinclude a copyright notice as follows:© (your company name) (year). Portions of this code are derived from IBM Corp.Sample Programs. © Copyright IBM Corp. 1997, 2000. All rights reserved.

194 ET/390

Programming interface information

Programming interface information is intended to help you create applicationsoftware using this program.

General-use programming interfaces allow the customer to write applicationsoftware that obtain the services of this program’s tools.

However, this information may also contain diagnosis, modification, and tuninginformation. Diagnosis, modification and tuning information is provided to helpyou debug your application software.

Warning: Do not use this diagnosis, modification, and tuning information as aprogramming interface because it is subject to change.


196 ET/390

Trademarks and service marks

The following terms are trademarks of International Business MachinesCorporation in the United States, or other countries, or both:v AIXv AS/400v DB2v CICSv CICS/ESAv IBMv IMSv Language Environmentv MQSeriesv Network Stationv OS/2v OS/390v OS/400v RS/6000v S/390v VisualAgev VTAMv WebSphere

Lotus, Lotus Notes and Domino are trademarks or registered trademarks of LotusDevelopment Corporation in the United States, or other countries, or both.

Tivoli Enterprise Console and Tivoli Module Designer are trademarks of TivoliSystems Inc. in the United States, or other countries, or both.

Encina and DCE Encina Lightweight Client are trademarks of Transarc Corporationin the United States, or other countries, or both.

Java and all Java-based trademarks and logos are trademarks or registeredtrademarks of Sun Microsystems, Inc. in the United States and other countries.

ActiveX, Microsoft, SourceSafe, Visual C++, Visual SourceSafe, Windows, WindowsNT, Win32, Win32s and the Windows logo are trademarks or registered trademarksof Microsoft Corporation in the United States, or other countries, or both.

UNIX is a registered trademark in the United States and other countries licensedexclusively through X/Open Company Limited.

Intel and Pentium are trademarks of Intel Corporation in the United States, orother countries, or both.

Other company, product, and service names, which may be denoted by a doubleasterisk(**), may be trademarks or service marks of others.


enterprise toolkit for os/390 · getting started with the building of java executables .....81...

Documents