|
|
 |
|
|
| |
Hints and Tips
(last updated May, 2008)
|
 |
|
|
There are six areas of information.
Is there a newsgroup for Java on OS/390 and z/OS? YES
There is also a OS/390 newsgroup.
We welcome additional tips. Please send them to us through the contact us page.
Please specify performance or hints and tips in the comment on: section.
|
 |
|
|
Considerations
JDK 1.1 applications and Java 2
In most cases, applications will run with no changes from JDK1.1. However, there are
some incompatibilities in some (particularly JNI) functions moving from Java 1.1 to Java 2.
For more information, see the following papers:
|
|
Optional command line parameters
The optional parameter -Djava.awt.headless=true is supported on
IBM SDK for z/OS, Java 2 Technology Edtion at PTF UQ90449 or above
and on IBM 64-Bit SDK for z/OS, Java 2 Technology Edition.
|
|
ASCII File Tagging
With the application of PTF UQ81134 on the SDK1.4 product, the following new environment
variable will be recognized by the JVM for z/OS:
IBM_JAVA_ENABLE_ASCII_FILETAG
When IBM_JAVA_ENABLE_ASCII_FILETAG is defined and file.encoding has been specified
to be an ASCII codepage recognized by z/OS, then all new files created by the JVM will be
tagged with a CCSID that corresponds to this codepage.
If the OS can determine that file.encoding is for an ASCII codepage but is unable to
map it to a CCSID, then the JVM will exit with error message:
Unable to obtain CCSID for file encoding
<file.encoding value>
|
|
Supplementing command line options
A new feature in JDK 1.3.0 on all IBM platforms is the environment variable:
IBM_JAVA_OPTIONS=. This variable can be used as an alternative to specifying options
on the command line.For example, the maximum heap size and MMI behavior for the MyClass
application can be specified as follows:
> export IBM_JAVA_OPTIONS="-Xmx64m -Xcomp" > java MyClass
The options in the above example supplement any specified on the command line. They do not
override them. Specifying options through this environment variable is useful for
JNI applications started via the JNI Invocation API.
|
|
Controlling Mixed Mode Interpretation
Mixed mode technology is incorporated into the interpreter and JIT. The consequence
of this is that methods are not unilaterally translated by the JIT at first invocation.
Therefore, in some cases, costs associated with additional method interpretation and due
to untranslated methods can occur.
An additional command line option is available to give users some control over
this behavior. By specifying the command line option -Xcomp, the JIT compiles
all methods immediately. This will increase startup time and memory use. It can provide
higher performance for some applications for which these are not a concern, and want
to avoid any bytecode interpreter activity. Use of -Xcomp can also make debugging
easier as the behavior of the JVM is completely determined. Note however, some
optimizations done by the JIT depend on information generated by the interpreter
being passed to it. Thus, specifying - will result in somewhat less efficient
machine instructions being generated with the JIT, since the interpreter is preempted
from running.
Note: -Xcomp is not supported in Java SDK 5.
|
|
Websphere and Java 2
Websphere 3.5 and later editions require the IBM Developer Kit for OS/390, Java 2 Technology
Edition.
|
|
Java Database Connectivity (JDBC)
Users of JDBC need to insure that they are at the appropriate DB2 for OS/390 service level:
- If you have DB2 for OS/390, Version 6, Java JDBC and SQLJ, APAR PQ39411 is required.
- If you have DB2 for OS/390 Version 5, APAR PQ39420 is required.
- DB2 for OS/390 Version 7 contains the appropriate Java 2 JDBC driver.
These APARs make changes to the DB2 for OS/390 JDBC driver to allow for execution under
the SDK 1.3 (Java 2) environment. These APARs will not add any JDBC 2.0 specification functionality,
but instead will allow existing JDBC 1.2 applications using the DB2 for OS/390 JDBC driver to
continue to run under the SDK 1.3 (Java 2) environment. For complete information, please see the APAR.
|
|
Using the Java Debugger (jdb) with IBM Developer Kit for OS/390, Java 2 Technology Edition
On many non-IBM platforms, the Java Virtual Machine (JVM) runs by default as a HotSpot JVM.
On OS/390 and z/OS it runs as a Classic JVM. Sun's documentation on jdb assumes that the JVM to be
debugged is a default HotSpot JVM. Therefore, when using jdb, always assume that the -classic
option has been implicitly specified and follow the guidance for debugging a Classic JVM.
This requires that either the -Xnoagent option should be specified or, if the agent
class is required, the -Xbootclasspath option should be specified to explicitly locate it.
|
|
Enqueuing of PhantomReference objects
A PhantomReference object contains a reference to another object (the referent).
When the referent is detected as being available for garbage collection, the PhantomReference
object is enqueued.
The referent does not become available for garbage collection until no references to it
(other than phantom references) exist. It is important to realise that, even after any explicit
references from the Java code have been cleared, pointers might still exist from the program
stack within the Java virtual machine. While such pointers exist, the referent will not become
available for garbage collection. You might perceive this as a delay in a PhantomReference object
being enqueued after you have cleared all explicit references.
The semantics of PhantomReference objects do not define when the object will be enqueued.
Any program written to detect a phantom reference being enqueued must take this into account.
|
|
Tuning Java and LE runtime options with Java 2
Additional information on tuning Java and LE runtime options can be found on the
LE Web pages.
java -ss option (-Xss in 1.3)
In 1.3 it is not used to set the initial stack size, but it is checked whenever LE extends
the stack, and StackOverflowError will be raised if it is exceeded (the default is 512K,
and there is some leeway before overflow is raised).
java -oss option (-Xoss in 1.3)
The Java stack is hardly used any more in the OS/390 JVM. Most Java stack variables are
kept on the native stack for better performance. The java stack requested by this size will be
malloc'ed from the LE heap.
java -mx option (-Xmx in 1.3)
The Java heap is managed by the Garbage Collector, and is malloc'ed from the LE heap.
Some JVMs initially allocate the minimum (-ms option, -Xmx in 1.3) size, and allow the heap to
grow as required, but the OS/390 JVM allocates the maximum requested size heap immediately.
The Garbage Collector's behaviour is somewhat affected by the Java heap size. With a smaller
heap you will see more frequent but shorter GC cycles; with a larger heap you will see less
frequent but longer GC cycles. This may be noticeable as erratic response times and possibly peaks
in paging. You may need to investigate your system tuning with a view to making sure your production
Java system(s) get enough real storage to keep paging low.
|
|
Java 2 and LE runtime options
These are described in the LE Programming Reference manual.
The java executables (java, javac, javah, etc.) are built with a standard set of runtime options
using #pragma statements, as follows:
- STACK(48K,16K,ANYWHERE,KEEP)
- STORAGE(NONE,NONE,NONE,1K)
- LIBSTACK(1K,1K,FREE)
- HEAP(8M,2M,ANYWHERE,KEEP)
- ALL31(ON)
- ANYHEAP(2M,512K,ANYWHERE,KEEP)
- BELOWHEAP(8K,2K,KEEP)
These values are carefully tailored to minimize stack usage while at the same time maximizing
the number of threads that can be created.
The STACK option defines the initial stack segment size (48K) and increment size (16K)
if a segment overflows. ANYWHERE is a *must* as otherwise it will be allocated BELOW the 16M line.
The first other suboptions of STORAGE should not be set to a value other than NONE as this may
affect performance. The final suboption specifies the size of the emergency stack in case of LE being
unable to extend the stack any further. The emergency stack is allocated *per thread* BELOW
the 16M line, so it should be kept to a minimum - if LE is unable to extend the stack, your chances
of recovery are slim.
LIBSTACK storage is always BELOW the 16M line, so keep it as small as possible.
HEAP is problematic, as it depends very much on the application load. HelloWorld needs much less
heap space than a WAS system with dozens of threads. The initial heap size (8M) should be at least
as large as the sum of the -mx and -oss options, plus it will also be used for malloc'ed storage
for internal control blocks and JITted code. A large enough initial size avoids the overhead
of LE stack expansion.
Any and all of these runtime options can be overridden using the _CEE_RUNOPTS environment variable.
Also, note that the values above apply to IBM-supplied executables, *not* DLLs. This means that,
if you write your own launcher to start up the JVM using JNI_CreateJavaVM(), you will not pick up
these values. You need to build in the values with #pragma statements, or make sure that reasonable
values are set via the envvar.
You can use the runtime option RPTSTG(ON) to produce a storage report that will enable you
to judge your requirements better.
|
|
JCL REGION size parameter
This needs to be large enough to allow for all of the heap and stack storage requirements,
plus LE and Java code, and LE internal control blocks. OutOfMemoryError is not very granular.
You may be able to get further useful information by inspecting the Java stack traceback.
|
| public static Properties getProperties() |
Determines the current system properties |
| public static String getProperty(String key)() |
Gets the system property indicated by the specified key. |
| public static String getProperty(String key, String def) |
Gets the system property indicated by the specified key. |
|
Among the properties that can be retrieved are values reflecting the name, version and
release of the operating system:
|
| os.name |
Name of the operating system, for example "OS/390" |
| os.version |
Version and release of the operating system, for example "02.08.00" (version 2 release 8.00) |
|
This table shows the values returned by IBM Developer Kit for OS/390, JavaTM 2 Technology Edition,
for certain levels of operating system:
|
| os.name |
os.version |
| OS/390 V2R8 |
OS/390 02.08.00 |
| OS/390 V2R9 |
OS/390 02.09.00 |
| OS/390 V2R10 |
OS/390 02.10.00 |
| z/OS V1R1 |
z/OS 01.01.00 |
| z/OS V1R2 |
z/OS 01.02.00 |
|
If you have a Java application that relies on these properties, you might have a compatibility
problem when you move from OS/390 to z/OS.
For example, application MyApp uses the test
System.getProperty("os.name").equals("OS/390")
to distinguish between the mainframe and workstation platforms. This test does not work
as intended when the application is run under z/OS.
There are two solutions. The first, and more difficult, is to recode the application to
handle the value "z/OS" . The second is to manually force the needed property to a particular value.
Some system properties, including os.name and os.version, may be overridden using a command line option:
java -Dsystemproperty=value ... class
In the example, the os.name property could be overridden in the startup script for the
application on the mainframe:
java -Dos.name=OS/390 MyApp
The application will now function as intended on both OS/390 and z/OS.
|
|
|
|
Performance
Performance is a key requirement for Java on OS/390. With the upgrade to SDK1.4.0,
we have again substantially improved performance. The improvements apply to a broad range of
applications from long running server applications to
short standalone applications.
The improvements are largely a result of using a new linkage convention (XPLINK) and additional
changes in the Just in Time compiler (JIT) where additional optimizations to cade generation
were added, and Allocation and Garbage Collection (GC) where Java on OS/390 moved to a
common technology with other IBM eServer platforms. For more information,
see z/OS Garbage Collection.
Java on OS/390 has a history of performance improvements, particularly
for server applications. This has continued through SDK1.4.2.
Apart from improvements within the JVM, there are many things that you can do to improve your
performance while you are developing applications for Java or installing and setting up Java on
your system. Often these provide the large gains. Java applications which are well designed independent
of platforms will run well on OS/390 and z/OS. See the following sites for additional information:
The following are performance considerations for developing or running applications on OS/390.
There are two areas of information:
System environments
There are performance considerations regarding your system environment. The system environment
is made up of:
Hardware
The Generation 5 and above S/390 processors contain native support for IEEE754 instructions.
Java for OS/390 at the JDK 1.1.8 level checked the hardware level and used these instructions
when they were available. This check is not done for Java 2. Instead, in the absence of
hardware IEEE754 intructions, the JVM relies on software emulation. This emulation is slower
than the previous Java library routines used with JDK1.1. For details,
see Architecture and software support in IBM S/390 Parallel Enterprise Servers for IEEE Floating-Point arithmetic.
In addition, see the sample Java application results
The Java for OS/390 JIT takes advantage of the Immediate and Relative instructions introduced
with the G2 processor. For details, see
Building a Java virtual machine for server applications: The JVM on OS/390
|
|
Installation and setup on OS/390
This section contains suggestions that may improve the run time performance of a Java application
on OS/390 without having to alter Java source code.
You need to be aware of several components of the total JVM environment. Each component has
a separate set of tuning suggestions:
|
|
JVM
The following is a list of performance suggestions for the Java Virtual Machine (JVM) runtime
environment:
|
|
OS/390 UNIX System Services (USS)
The JVM uses UNIX System Services for OS/390 (USS) for base operating system functions. For this reason, USS must be correctly installed and tuned in order to get optimum performance from the JVM. See the USS performance web page for detailed tuning suggestions.
For additional information, see:
A number of Unix based tools for z/OS are available for free via download. Some of these are
Java specific. These tools were designed for OS/390 UNIX, by IBM developers and testers.
There are no warranties of any kind, and there is no service or technical support
available for these from IBM. See the
z/OS UNIX Tools.
|
|
TCP/IP
Since TCP/IP is a very common networking protocol for web and Java based applications,
the TCP/IP component of OS/390 must be installed and tuned properly
The following documents have performance suggestions for tuning CS/390:
|
|
WebSphere
OS/390 Java web-based applications need a properly installed HTTP server.
The following links provide information on properly tuning the Websphere HTTP server.
|
|
Applications and environments
Using Java 2 Technology Edition with your existing data and applications
Access to relational data is available through a Java Database Connectivity (JDBC) interface.
DB2 JDBC drivers for Java applications and applets for several platforms are distributed
as a no charge feature to all DB2 for OS/390 Version 5 and higher customers. CICS and IMS support
is currently available to enable access to transactions on OS/390 or z/OS directly from a browser.
MQSeries can be an integral part of your Java server application through the JMQI facility.
Java record I/O (JRIO) is a part of the Java for OS/390 product and allows access to record data.
There is information and code that enables you to access your existing OS/390 or z/OS data
and transactions:
|
|
Running IMS and DB2
To allow IMS to run with the SDK1.4 Java product in addition to running with the SDK1.3 Java product:
- The SDK1.3 product must be at PTF UQ76273 or later
- The SDK1.4 product must be at PTF UQ77468 or later
- For IMS V7, install PTF=UQ80879 (APAR=PQ76609)
- For IMS V8, install PTF UQ82427
Note: for running with the SDK1.4 product, follow the IMS instructions to specify
the XPLINK environment.
To allow DB2 to run with the SDK1.4 Java product in addition to running with
the SDK1.3 Java product:
- The SDK1.3 product must be at PTF UQ76273 or later
- The SDK1.4 product must be at PTF UQ77468 or later
- For DB2 V7, install PTF=UQ81669 (APAR= PQ76769)
- For DB2 V8, the support is included in the base.
|
|
Running Java applications as batch jobs
Java applications can be run as traditional batch jobs by placing the program executable
(bytecode) in an HFS. Program execution occurs under
z/OS UNIX System Services (USS).
An example of JCL used to run a Java application as a batch job:
//JBATCH JOB ' ','JDOE',CLASS=A,MSGCLASS=H,
//MSGLEVEL=(1,1),
// REGION=0M,TIME=1440,NOTIFY=&SYSUID
//*******************************************
//* RUN AN OE PROGRAM FROM BATCH
//*
//*******************************************
//STEP1 EXEC PGM=BPXBATCH,
// PARM='SH java JavaPgmName'
//STDOUT DD PATH='/tmp/stdout',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
//STDERR DD PATH='/tmp/stderr',
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),
// PATHMODE=SIRWXU
Notes:
The job gets the environment vars from the etc/profile and personal profile.
The PROFILE needs to have the correct CLASSPATH and PATH statements. When running under
a specific batch userid (for instance OPC), you may want to create a personal UNIX profile
for that userid. For additional information, see
z/OS batch in Java.
An alternative to using BPXBATCH for running Java applications is described at
Java batch jobs on z/OS and OS/390.
|
|
Running threads in parallel on an S/390 SMP (symmetric multiprocessor) machine
Java threads are Pthreads, so they will be scheduled as any other multi-threaded
application on OS/390. Threads will be scheduled to any available processor and run
concurrently within an SMP machine by OS/390.
There are limitations to the number of threads running in parallel. You can only run as
many threads (have as many threads active) as the number of processors you have. Currently,
the opportunity to run threads within a single application is limited to an SMP. Concurrent
execution across Sysplex nodes is not supported.
For more information, see
Tuning Java and LE runtime options with Java 2
|
|
Support for Java Naming and Directory Interface (JNDI)
Beginning with OS/390 Version 2 Release 7, Java Naming and Directory Interface (JNDI)
is shipped as part of OS/390. JNDI provides access to Directory Services from Java applications
that run on OS/390. For OS/390 it is provided as an extension to Lightweight Directory Access Protocol
(LDAP) support, used to communicate with the Directory Service, which can be running on OS/390,
as well as other platforms. Additional information is contained in chapter 1 Section 13 of the
OS/390 V2R7.0 LDAP Client Appl Dev Guide and Ref (SC24-5878-00) .
|
|
ASCII to EBCDIC
One important aspect of the S/390 environment that can sometimes raise portability issue
with Java code is that OS/390 uses the EBCDIC character encoding instead of the more common ASCII.
Within the scope of the JVM, all character and string data is stored and manipulated in Unicode,
and I/O data outside of the virtual machine (disk, network, and so forth) is converted to the
native platform encoding. However, Java applications that implicitly assume ASCII in specific
situations might require some alterations to run as expected under OS/390.
There are a number of environmental tricks that are often useful to test whether implicit
ASCII assumptions are in effect. For instance, for config files read in during start-up
(or other 'adminstrative' file manipulation), you can use a simple command-line utility to
convert those files to the appropriate encoding that you require.
In some cases, changing JVM properties can also allow successful functionality tests,
but because this can produce other side effects, the long term solution is sometimes best
addressed in code. The Java language contains the abstractions necessary to handle the
switch between character encodings. Most important are the various Reader and Writer classes
in the java.io package, which provide alternate constructors with a specified codepage.
This mechanism is used for internationalization support, and it can also be used to force
ASCII (or other) I/O where required. It is important to consider that all I/O does not need
to be overridden; for example, character output to the display should remain in the native encoding.
In addition to the Reader and Writer classes, there are a few specific situations that
might require additional care. For example, there is an overloaded getBytes() method in the
String class that takes an encoding as an additional parameter. This is useful for direct
string manipulation when implementing custom data streams or network protocols directly in Java.
Some Java applications explicitly assume ASCII encoding and therefore require some
alterations to run as expected under OS/390. For example, a platform neutral application
might have hard coded dependencies, such as literals in ASCII.
In general, straightforward workarounds are available for character encoding problems.
Some encoding problems are not visible to the application because they are handled within
products running on OS/390. An example of this is Java Database Connectivity (JDBC).
It is often best to deal with codepage issues by
running the JVM with default encoding of ASCII
(-Dfile.encoding=ISO8859-1) and then to specifically call out the
codepage that you need when you are writing to MVS files and datasets
that are in EBCDIC. This makes porting of code easier, which
is a reason Websphere now runs this way.
For your information, the JZOS function now incorporated into z/OS Java SDK5 and SDK6 products may also help in ASCII-EBCDIC questions. The JZOS ZUtil class has a method "getDefaultPlatformEncoding()"
that returns the EBCDIC codepage that is being used by the process
running the JVM. Also, the FileFactory class can be used to read and
write text files - if the file is a //DATASET name then JZOS uses this
encoding under the covers automatically.
For more information, see
JZOS Java Launcher and Toolkit Overview.
|
|
JAR file considerations
A jar is an archive of files used by a java applet. Many or all of the files that an
applet needs can be combined into a single jar file, which an appletviewer can download
in a single http request.
We expect that jar files downloaded from other platforms will contain text data in
ASCII (8859-1), and therefore have enabled the appletviewer to expect text files in a
jar file to be in ASCII. This means however, that if the jar tool is used on OS/390 to create
a jar file, then text files must be converted to ASCII before being added. Of course this
also means that any jar files you create on OS/390 can be transported and used on other platforms.
Equally, any text files extracted from a jar file will not be converted from their original encoding.
|
|
OS/390 UNIX System Services(USS)
The JVM uses OS/390 UNIX System Services (USS) for base operating system functions.
For this reason, USS must be correctly installed and tuned in order to get optimum performance
from the JVM. See the USS performance web page for detail tuning suggestions.
|
|
Troubleshooting
IBM JVM Diagnostic Guides
Guides to problem diagnosis
for IBM's 1.4.1 and 1.3.1 SDKs are available. These guides include a description of IBM-specific
facilities and their use.
These guides include sections on the garbage collector, the JIT compiler, the class loader,
the ORB and covers many aspects of problem determination in all the supported platforms.
They also reflect changes to the JAVA_DUMP_OPTS environment variable that are introduced
into this service refresh, including suppression of dumps.
|
|
Using Java dump options
Options may be separated by blanks or commas. Some options have suboptions, which are
contained in parentheses. The syntax is compatible with the LE CEE3DMP function.
ONINTERRUPT(JAVADUMP|CEEDUMP|ALL)
- This will generate a JAVADUMP, a CEEDUMP or both when a SIGINT or SIGTERM signal is received.
USERABEND(n|4094)
- This option throws user abend code 'n' when a signal in the following list is received:
- SIGINT
- SIGTERM
- SIGILL
- SIGFPE
- SIGSEGV
- SIGBUS
- SIGSYS
- SIGABRT
- SIGUSR2
- SIGQUIT
- SIGTRAP
- SIGXCPU
- SIGXFSZ
The abend is thrown after the dumps, if any, have been generated. 'n' should be
in the range 0 to 4095; if not, the default is used.
ceedumpoption
- This option controls the format of the CEEDUMP. If no option other than ONINTERRUPT
or USERABEND is specified, any CEEDUMP is made by calling csnap and contains the traceback
for the current thread the registers of each active function in the current thread.
Specifying additional options means that CEE3DMP is called in place of csnap. The additional
options are passed unchanged to CEE3DMP.
These options request a user abend 3456 to
be thrown:
export JAVA_DUMP_OPTS="USERABEND(3456)"
These options generate a CEEDUMP containing
a traceback of all native threads:
export JAVA_DUMP_OPTS="THREAD(ALL) NOFILE
NOVARIABLE PAGESIZE(0)"
Note:
If an SVC dump is required by other groups,
use the export JAVA_DUMP_OPTS="USERABEND(3456)"
to generate
a userabend that can be slip'd. This removes the need
for any switching off of signals.
In SDK 1.3, the dumps are always written to the same place in the following search order:
- The directory found in environment variable _CEE_DMPTARG.
- The current working directory (if it is not the root directory and if it is writable).
- The directory found in environment variable TMPDIR.
- The /tmp directory.
|
|
Trace file
A trace file is produced each time that java is run. It contains the last five traces
and resides in /tmp/javatrace. Information inside the file includes:
- environment variables
- java fullversion
- what signal was processed
- what directory was used to store the javadump
|
|
Obtaining JIT traces from Websphere
The following steps need to be followed in order to obtain the documentation that
is required when a problem is suspected to be related to the JIT.
In the jvm.properties file (or equivalent) the following must be set:
java.compiler=jitc
ncf.jvm.verbose=true
ncf.jvm.javalib=libjava_g.a
The entry
ncf.jvm.debugging=true
MUST be commented out or else you must set:
ncf.jvm.debugging=false
Otherwise the JIT will be disabled. In the httpd.envvars
file (or equivalent), the following must be set:
JAVA_COMPILER=jitc
JITC_LISTFILE=<listfile filename>
JITC_MAPFILE=<mapfile filename>
JITC_ILFILE=<ilfile filename>
JITC_DEBUGFILE=<debugfile filename>
The filenames for the JITC_xxxx files must be HFS files to which the
running userid has access. The JIT traces can become very large and do
slow down the running application.
|
|
Command line debugging tool
The java command invokes the java interpreter from the command line (java_g is
a debugging version). The java interpreter provides application tracing information
by specifying the -verbose option. This option will display classes loaded
each time they occur. It will also show which .zip or .jar files the classes come from.
The following is an example of the type of output received from using
the -verbose option:
[Loaded java/lang/Thread.class from /usr/lpp/
java/J1.1.8/
bin/../lib/classes.zip
[Initializing java/lang/Thread]
[Loaded java/lang/Object.class from /usr/lpp/
java/J1.1.8/
bin/../lib/classes.zip
[Initializing java/lang/Object]
(CPU, DASD, and storage)
By specifying the -verbosegc option with the java command,
garbage collector's freeing of memory is displayed. This trace can help
you determine the proper heap size for your application. If too much
garbage collection is taking place an increased heap size may rectify the situation.
|
|
Java command line traces
This trace can help you determine the proper heap size for your application.
The java interpreter provides application tracing information. By specifying the
-verbose:gc option on the Java command line, class loads are displayed.
By specifying the -verbosegc:gc option garbage collector's freeing of memory
is displayed. If too much garbage collection is taking place an increase heap size may
rectify the situation.
|
|
WebSphere logs and traces
There are many logs available for the HTTP server: access, agent, cache, CGI, Error,
Referer, Trace logs, etc. Logging is controlled through the httpd.conf file.
httpd.conf can be managed by using online Configuration and Administration form or
manually. Probably Access Logs, Error Logs or Trace Logs are most interesting depending on your
current problem.
For details on setting up logging see
IBM HTTP Server for OS/390 R7 Planning, Installation and Using V5.1, SC31-1869 (See Customizing logs and reports chapter).
The Trace log is most useful for debugging any server or configuration problems.
The Access log is most useful in determining web traffic. It records IP addresses,
access time, URL, file size, etc. Here is a
list of generally available log analysis tools .
If your application is a servlet you may want to use the logs and traces available
through WebSphere Application Server.
The jvm.properties file is used to control the functionality of the WebSphere Application Server.
Native DLL logging and Java standard out logging are supported. Native DLL logging logs
messages produced by the webserver before Java is invoked. "Standard output", a C library
concept that has been incorporated into Java, allows System.out and System.err generated print
to be displayed as text. "Standard output" is very useful for adding logic in Java servlets for
debugging purposes.
Remember these are primarily debugging tools and should not be used to the same extent
in a production environment. Your use of logs in production should be reviewed for application
business needs because, in general, they require extra resource CPU, DASD, and storage).
|
|
APAR PK07529 describes the error reported if the LE library SYS1.SCEERUN2 is not
program controlled (default)
The APAR details are:
ERROR DESCRIPTION:
In JDK 1.4 environment, running compiled Java program in JDK 1.4 will produce
the following messages if SYS1.SCEERUN2 is not program controlled:
EDC5157I An internal error has occurred,
errno 157 errno2 151782063
ICH420I PROGRAM CELHV003 FROM LIBRARY SYS1.SCEERUN2
CAUSED THE ENVIRONMENT TO BECOME UNCONTROLLED.
BPXP014I ENVIRONMENT MUST BE CONTROLLED FOR DAEMON
(BPX.DAEMON)
The reported problem is not seen in Java 1.3 SDK because JDK 1.3 is
non-XPLINK, whereas the 1.4 SDK is XPLINK which need to access the
XPLINK-specific code in SCEERUN2. To get around this problem, users
will need to have SCEERUN2 APF-authorized via their Security product (RACF or other).
PROBLEM SUMMARY:
The LE library SCEERUN2 is not program controlled. This may result in the message:
EDC5157I An internal error has occurred,
errno 157, errno2 151782063
errno 157, errno2 151782063
Java SDK 1.4 is XPLINK and needs access to the XPLINK specific code in SCEERUN2.
PROBLEM CONCLUSION:
Users will need to make SCEERUN2 APF-authorized via their security product
(RACF or other).
|
|
Error message EDC5751I received while logged on through OMVS/TSO
This message is received when the BPX.DAEMON FACILITY class profile has been defined
and the USS modules used during OMVS login do not have the +p bit (program controll bit) set.
To fix the problem, use OMVS NOSHAREAS or issue the following command which will
create a new address space when JAVA is invoked:
export _BPX_SHAREAS=NO
Alternatively, the +p bit could be set.
|
|
Information APAR II13291:
EZYXW12W XtlibWarning: badValue cvtStringToPixel XtToolkitError Color name "#B648B600B600" is not defined (5/20/02)
ERROR DESCRIPTION:
When an applet or application uses AWT on OS/390, a message similar to this may be produced:
EZYXW12W XtlibWarning: badValue cvtStringToPixel
XtToolkitError Color name "#B648B600B600" is not defined
On OS/390 the AWT uses X Windows to display windows. X Windows fetches certain resources
from the workstation (or "X server") on which the windows are displayed. One such resource is
*background, the default background color for windows.
*background may specify a color name (for example: black) or a hex RGB value
(for example: #8a008a008a00). X Windows on OS/390 fails to recognize uppercase A
through F as valid hex digits so a value such as #B648B600B600 is treated not
as a hex RGB value but as a color name. The X server is unlikely to find such a color name
in its color database and issues the above warning.
SUGGESTED SOLUTION:
To eliminate the message change the value of the *background resource on the X server on
the desktop to a known color name or a hex RGB value using lowercase a through f.
For example, on an AIX desktop, a value such as #B648B600B600 probably originates from
the CDE desktop manager. One possible solution is to run the following command:
xrdb -query | grep "*background:" | tr ABCDEF abcdef
| xrdb -mer
ge
Note that adding this command to your .profile won't necessarily work as CDE sets
its resources including *background after running .profile. One way around this
would be to run .profile manually using . .profile.
|
|
Information APAR II12887:
Suggested values for USS BPXPRMXX SHRLIBMAXPAGES for OS/390 R10 and higher (7/12/01)
ERROR DESCRIPTION:
Failure to configure enough private storage may lead to load failures, for example:
EDC5204E Not enough storage to load DLL module.
(libjitcBFP.so) msgEDC5204E
SUGGESTED SOLUTION:
At OS/390 2.10.0 (HBB7703, R703)OS/390 UNIX System Services introduced a change in the load
process for user dlls. Eligible dlls, those with filename suffix .so can be loaded via
a dataspace, rather than direct to private storage. The SHRLIBMAXPAGES parameter in BPXPRMxx
controls the number of pages made available in this dataspace for this purpose.
The following values should be added to values calculated for other products for use
with the debug and regular builds of the various dlls supplied with SDK 1.3.
If you are using the regular build, add 359 pages to the number currently in SHRLIBMAXPAGES.
If you are using the debug build (that is, the dlls ending in the suffix _g.so),
add 10138 pages to SHRLIBMAXPAGES.
|
|
Information APAR II12985:
How JAVA_PROPAGATE changes JVM operation (10/25/01)
Application programs and middleware products can use the JNI calls AttachCurrentThread
and DetachCurrentThread to Attach and Detach respectively the current z/OS native thread to a JVM.
These calls result in internal JVM data areas associated with the thread being created and destroyed.
During normal thread creation within the JVM, that is when a Java program creates a new thread,
the security and workload (WLM) context associated with the parent thread is propagated to the
new thread. In the case of a thread being attached to the JVM from native code, as described above,
the thread is treated as a new parent and a token to it's security and workload context is saved
and propagated to any threads this thread creates while running in the JVM.
This default behavior closes a potential security problem caused by the fact that by default,
when Java code creates a new thread a new z/OS USS pthread is created without a security context
associated with it, which in turn means it inherits the authority of the address space.
This is not always a desirable thing.
To support those cases where middleware is handling security concerns, the envvar JAVA_PROPAGATE
can be set to NO prior to starting the JVM, turning off the default propagation of context behavior.
The envvar JAVA_PROPAGATE is tested by the JVM code concerned with thread creation only during JVM
initialization to assure this behavior cannot be modified by Java application code during JVM operation.
For performance reasons, WebSphere supports a nodetach mode of operation - in this case threads
are not detached from the JVM between separate units of work. In general, nodetach will not work
with the JVM's default propagation because it is the DetachCurrentThread that causes the JVM to
unset the osenv USS block on changing of thread identity. This means if the middleware,
i.e. WebSphere, wants to change the userid associated with the thread between units of work
(JVM invocations), it cannot.
When WebSphere was initially available this was the operation:WebSphere didn't use the
default propagation behaviour of the JVM, and so detach and nodetach both worked. In later
releases WebSphere began to use JVM propagation for the case where a client or surrogate id
needed to be used for a thread accessing DB2, for example.
As of WebSphere 4.0 the envvar JAVA_PROPAGATE is set to NO prior to starting the JVM,
so that propogation of context behavior is turned off.
|
|
Information APAR II13212:
PAX: FSUM7170
/TMP/IBMOS390_USTAR_SUMMARY_1013093750:
CANNOT SET MODE (3/21/02)
ERROR DESCRIPTION:
Customers using OS390 2.9 and 2.10 may experience problems when trying to unpax the ptf uq99325
or later pax file.
This is due to an incompatability with the pax code. APAR OW46528 documents more detail
on the pax enhancements.
SUGGESTED SOLUTION:
As documented in APAR OW46528, customers need to apply the PTF corresponding to their OS390 release.
Release 609 : UW75985 available 00/12/08 (F012 )
Release 703 : UW75986 available 00/12/08 (F012 )
Information APAR II13292:
JVM USE OF TRANSACTION DUMP (TDUMP)(06/17/02)
ERROR DESCRIPTION:
After SR14 the default dumping action for the JVM changes to Transaction Dump, in addition
to the data currently requested at GA or in earlier service refreshes. This FAQ exists to
answer some common queries.
- Q1.
- My users are writing JNI code in the shell, we don't want TDUMPs everytime a program
check occurs, how can I turn this off ?
- A1.
- By coding envvar IBM_JAVA_ZOS_TDUMP=NO the behaviour reverts to the behaviour at GA thru SR13.
No TDUMP will be taken. A confirmatory message
JVMHP003: No transaction dump requested
will be written to stderr
- Q2.
- My TDUMP was created with a HLQ I didn't expect, where did it come from ?
- A2.
- The HLQ used for the TDUMP data/set comes from the USS call
pwd = getpwuid(getuid());
pwd->pw_name;
Depending on the uid for the thread on which the program check is handled you might see
data/sets created with different HLQs.
- Q3.
- The default pattern name / hlq conflicts with standards at our installation, can I change it ?
- A3.
- By coding envvar
IBM_JAVA_ZOS_TDUMP_PATTERN=string
you can specify a pattern name of your choice. For example
IBM_JAVA_ZOS_TDUMP_PATTERN="DUMP.MVJ1.&JOBNAME..T&HHMMSS."
The pattern string is passed unchanged through to the IEATDUMP service, so anything that's
valid for IEATDUMP will work. A confirmatory message
JVMHP011: User specified dump data/set name pattern for
IEATDUMP was DUMP.MVJ1.&JOBNAME..T&HHMMSS.
will be written to stderr
- Q4.
- I passed a valid pattern name, but I still didn't get a TDUMP ?
- A4.
- When the TDUMP fails, you'll see both a message on the console (msgIEA820I) and the return code
and reason code frkm IEATDUMP are externalized by the JVM in message JVMHP004.
For example, (in syslog)
IEA820I TRANSACTION DUMP REQUESTED BUT NOT TAKEN
DUMP DATA SET NAME NOT VALID
and (in stderr)
JVMHP004: Transaction Dump service IEATDUMP failed with
rc=0x8 (8), reason code=0x21 (33)
Be aware that not all manuals have the latest return and reason codes. Try looking them up in
DOC APAR OW47548. (Available through RETAIN) The message JVMHP011 prints the exact name of the
pattern as passed, so check that closely. Common problems include
- not getting the right coding for the system symbol names, e.g.
IBM_JAVA_ZOS_TDUMP_PATTERN="DUMP.MVJ1.&JOBNAME..T&HHMMSS.."
and
IBM_JAVA_ZOS_TDUMP_PATTERN="DUMP.MVJ1.&JOBNAME..T&HHMMSS"
are both invalid
- and coding the envvar with quotes in a WebSphere environment. e.g.
IBM_JAVA_ZOS_TDUMP_PATTERN="DUMP.MVJ1.&JOBNAME..T&HHMMSS."
is coded in a Websphere env file and msgJVMHP011 reports JVMHP011: User specified dump
data/set name pattern for IEATDUMP was "DUMP.MVJ1.&JOBNAME..T&HHMMSS." since the
double quotes are being passed, the allocation fails the env file should have
IBM_JAVA_ZOS_TDUMP_PATTERN=DUMP.MVJ1.&JOBNAME..T&HHMMSS.
- Q5.
- More that one TDUMP was requested, can I limit it to one ?
- A5.
- This can happen if a program check occurs whilst getting diagnostic data following the initial
program check. For example, if a program check occurs in CEEDUMP processing or whilst the JAVADUMP
is being created. Envvar IBM_JAVA_ZOS_TDUMP_COUNT=n where n is an integer can be set to the limit
the maximim number of TDUMPs to request. For example,
export IBM_JAVA_ZOS_TDUMP_COUNT=1
will restrict the number to taken to 1. During processing of any subsequent program checks message
JVMHP010: No TDUMP requested, request threshold
of n reached
where n is the specified count. The default is 2, to allow for the diagnosis of those cases
where a problem occurs in CEEDUMP or JAVADUMP processing.
- Q6.
- Can I change the storage ranges that are being requested ?
- A6.
- Not at this time. The storage ranges requested are
SDATA=(GRSQ,LSQA,RGN,SUM,SWA,TRT,LPA,NUC,SQA)
Note that the actual storage dumped depends on whether the JVM is running unauthorized or not.
In most cases the JVM is running unauthorized in key 8.
- Q7.
- When I analyze the TDUMP using IPCS I'm unable to format out the system trace using
command "ip systrace", any ideas ?
- A7.
- This is a bug in the dumping code, see OW54876. Please install the PTFs for this APAR
to resolve the problem. The fixing PTFs are as follows
- UW89731 - R608 (OS/390 2.8.0)
- UW89732 - R703 (z/OS 1.1)
- UW89733 - R705 (z/OS 1.2)
- UW89734 - R706 (z/OS 1.3)
- UW89735 - R707 (z/OS 1.4)
|
|
Long JSP Compile Time Caused by Malformed Jar File (12/03)
Elongated compile time for JSPs or .java files can be caused by specifying jar files
in the classpath that are missing directory entries. The following form of the jar command will
result in lack of directory entries.
jar cvf WebApPo_utils.jar it/myapp/appo/utils/*
Use this form:
jar cvf WebApPo_utils.jar itdir
(where itdir is a directory containing all the classes to be archived in the jar file)
The original jar file was missing the following entries
0 Tue Nov 12 11:36:30 EST 2002 it/
0 Tue Nov 12 11:36:30 EST 2002 it/myapp/
0 Tue Nov 12 11:36:30 EST 2002 it/myapp/ims/
0 Tue Nov 12 11:36:30 EST 2002 it/myapp/ims/utils/
.....and contained only files that looked like this
1041 Tue Nov 12 11:36:30 EST 2002
it/myapp/ims/utils/DataRW.class
1867 Tue Nov 12 11:36:30 EST 2002
it/myapp/ims/utils/IMSBOManager.class
2513 Tue Nov 12 11:36:30 EST 2002
it/myapp/ims/utils/IMSConnectionManager.class
13473 Tue Nov 12 11:36:30 EST 2002
it/myapp/ims/utils/TrxExec.class
When the jar was rebuilt with the second form of the command, the directory entries shown
above were added. This reduces the compile time by tenfold, for this particular example.
|
|
FSUMF073 J1.3/bin/libawt.so: user not authorized to restore extended attribute
ERROR DESCRIPTION:
The user is not authorized to restore extended attribute "l" on libawt.so and some other modules
during the installation of PTF UQ73928 or higher
SUGGESTED SOLUTION:
The installing userid must have READ access or higher to BPX.FILEATTR.SHARELIB facility classes.
To ensure restoring of all the program attribute bits set when the product is delivered,
the userid under which the installation is done must have the following:
- UID(0) or READ access or higher to the BPX.SUPERUSER facility class
- be connected to a group that has a GID
- have READ access or higher to the BPX.FILEATTR.PROGCTL and BPX.FILEATTR.APF facility classes
With the installation of PTF UQ73928 or above, the userid must also have READ access or
higher to BPX.FILEATTR.SHARELIB facility classes.
If access to BPX.FILEATTR.SHARELIB is not available, there will be a warning message.
The JVM will still be usable, but performance with IMS will not be optimized.
|
java.net.SocketException:
setsockopt IPV6_ADD_MEMBERSHIP failed:
A system call received a parameter that is not valid.
at java.net.PlainDatagramSocketImpl.join(Native Method)
at java.net.PlainDatagramSocketImpl.join
(PlainDatagramSocketImpl.java:164)
at java.net.MulticastSocket.joinGroup(MulticastSocket.ja
|
|
SUGGESTED SOLUTION:
On z/OS, you need to use an interface address as part of the multicastsocket definition in your code.
This is best explained the following steps:
|
- First check that you have addresses on your system available multicast.
TSO NETSTAT HOME will show you the available interface addressses ex.
Address Link
------- ----
X.XXX.253.82 VLINK2
X.XXX.253.83 VLINK3
X.XXX.253.84 VLINK4
X.XXX.253.85 VLINK5
X.XXX.253.86 VLINK6
X.XXX.253.81 VLINK1
X.XXX.222.48 ETH5 <-- Interface
X.XXX.223.48 ETH7 <-- Interface
XXX.0.0.1 LOOPBACK
- If you do not have any interfaces setup, you need to do so.
- Sample code should look like this:
We needed to add the setInterface because for z/OS, whenever a multicast address is to be
joined, the interface ip address must be specified.
|
|
|
|
|
|
