IBM WebSphere Real Time for Linux version 2 SR 3 =============================================================================== For late breaking news, please see the end of this document. Introduction =============================================================================== IBM WebSphere Real Time for Linux is an extension to the IBM Java Runtime Environment and Software Development Kit with Metronome garbage collection, ahead-of-time compilation. The benefits of the real-time environment are that Java applications run with a greater degree of predictability than with the standard Java Virtual Machine (JVM) and provide a consistent timing behavior for your Java application. Metronome garbage collection occurs at regular intervals and removes the occurrence of any unexpected peaks of background activity during an application's execution. In addition, Just-In-Time (JIT) compilation can be replaced with Ahead-Of-Time (AOT) compilation thus removing unpredictable background activity when your application is run. If you have previously used precompiled code or classes, you must rebuild that code and those classes for use with this version of WebSphere Real Time. In particular, if you have previously used version 2 shared caches to store precompiled code or classes, you must regenerate the shared caches to use this version of WebSphere Real Time. Installation =============================================================================== The SDK is supplied in a file called ibm-srt-sdk--linux-.tgz. The JRE is supplied in a file called ibm-srt-jre--linux-.tgz. For Linux x86 32-bit, the value is i386. For Linux AMD64 64-bit, the value is x86_64. The SDK can be installed into any directory by running the following command: tar xzf ibm-srt-sdk--linux-.tgz -C Replace with the directory where you want to unpack the JVM. The following directory, and immediate files and directories will be present in the target directory for the i386 platform: sdk/ bin/ copyright demo/ docs/ include/ jre/ lib/ license_en.html readmeFirst.txt sample/ src.zip The following directory, and immediate files and directories will be present in the target directory for the x86_64 platform: sdk/ bin/ copyright demo/ docs/ include/ jre/ lib/ license_en.html readmeFirst.txt src.zip The command "java -Xrealtime -version" displays the following if the install on Linux x86 32-bit was successful: java version "1.6.0" Java(TM) SE Runtime Environment (build pxi3260srtsr3-20100419_01(SR3)) IBM J9 VM (build 2.5, JRE 1.6.0 IBM J9 real-time 2.5 Linux x86-32 jvmxi32srt60sr3-20100410_56308 (JIT enabled, AOT enabled) J9VM - 20100410_056308 JIT - r10_20100410_15441 GC - 20100408_AA) JCL - 20100416_01 The command "java -Xrealtime -version" displays the following if the install on Linux AMD64 64-bit was successful: java version "1.6.0" Java(TM) SE Runtime Environment (build pxa6460srtsr3-20100419_01(SR3)) IBM J9 VM (build 2.5, JRE 1.6.0 IBM J9 real-time 2.5 Linux amd64-64 jvmxa64srt60sr3-20100410_56308 (JIT enabled, AOT enabled) J9VM - 20100410_056308 JIT - r10_20100410_15441 GC - 20100408_AA_CMPRSS) JCL - 20100416_01 The specific version information in these examples might be different from those shown. Documentation =============================================================================== In the docs directory, you will find readmeFirst.txt, rt_quick_start.pdf, com.ibm.softrt.doc.jar, com.ibm.softrt.doc.zip, and softrt_jre.pdf files. - readmeFirst.txt is this file. - rt_quick_start.pdf is the IBM WebSphere Quick Start Guide for use with the Adobe Acrobat Reader. - com.ibm.softrt.doc.zip can be extracted into the plugin directory of your Eclipse Help System, if the version is earlier than 3.1.1. - com.ibm.softrt.doc.jar can be installed in the plugin directory of your Eclipse Help System version 3.1.1 or Eclipse SDK 3.1.2 or later. - The softrt_jre.pdf is the WebSphere Real Time User Guide for use with the Adobe Acrobat Reader. To access this information using a Web browser, open docs/startHere.htm From this panel, you can view the PDF files and download the plug-ins to use with the Eclipse Help System that you can install locally on your system or on your network. Introduction to the Information Center -------------------------------------- You can access the Information Center on your local machine or by visiting http://publib.boulder.ibm.com/infocenter/realtime/v2r0/index.jsp To use the information center on your local machine, you need to install the Eclipse Help system. A configured and installed copy of the Eclipse Help System version 3.1.1 is on the ISO image under the /help_ibm directory. Although this copy of the help text is not updateable and the CD medium makes it run rather slowly, it is provided for convenience. See "Running the Eclipse Help System from the ISO image" for more details. If you are already running Eclipse SDK, you can copy com.ibm.softrt.doc.jar to the plugin directory. You have to stop and start Eclipse SDK to view the Information Center. The remainder of the information in this readme describes how to install and run the Eclipse Help system for WebSphere Real Time information center. Installing the Eclipse Help System ---------------------------------- 1. Download the latest version of the Eclipse Help System from http://www.alphaworks.ibm.com/tech/iehs/download. 2. Select the zip or tgz file that is appropriate for your operating system. 3. Create a new directory where you plan to install the Eclipse Help System. This is referred to as in the rest of this document. 4. Unpack the zip or tgz file into, for example, /opt/ directory depending on your operating system. This creates a directory called /opt//IBM_Help_301_Win\ibm_help on Windows. Starting and stopping the help system ------------------------------------- You can start the IBM Eclipse Help System in two different modes, information center mode and stand-alone mode. Stand-alone mode. IBM Eclipse Help System acts as a private documentation server, and automatically opens a Web browser to view the documentation on a randomly generated port. Only browsers on the same system can access this server. Information center mode. IBM Eclipse Help System acts as a public documentation server and allows other Web browsers on your network to connect to the help system on a defined port. Adding the WebSphere Real Time information center to your Eclipse Help System ----------------------------------------------------------------------------- For Eclipse Help System versions 3.0.1 and earlier 1. Extract the files from com.ibm.softrt.doc.zip into either the /opt//ibm_help/eclipse/plugins directory or C:\/IBM_Help_301_Win\ibm_help\eclipse\plugins depending on your operating system. 1. Copy com.ibm.softrt.doc.jar into either the /opt//ibm_help/eclipse/plugins directory or the C:\/IBM_Help_301_Win\ibm_help\eclipse\plugins depending on your operating system. Starting and stopping the help system in stand-alone mode --------------------------------------------------------- 1. Navigate to the ibm_help directory. 2. To start and view the Eclipse Help System: Run /opt//ibm_help/help_start.sh file. 3. To stop the help system: Run /opt//ibm_help/help_end.sh file. Starting and stopping the help system in information center mode ---------------------------------------------------------------- 1. Navigate to the ibm_help directory. 2. To start and view the Eclipse Help System: Run /opt//ibm_help/IC_start.sh file. 3. Enter the URL for the information center using the following syntax: http://:/help 4. To stop the help system: Run /opt//ibm_help/IC_end.sh file. Running the Eclipse Help System from the ISO image -------------------------------------------------- To access the WebSphere Real Time information center from the ISO image: 1. Mount the ISO image in your Linux system. 2. Change directory to ibm_help 3. To run the information center, enter: help_cd_start.sh After a short time, your browser opens showing the home page of the WebSphere Real Time information center. An alternative way to start the Eclipse Help System is as follows: 1. Mount the ISO image in your Linux system. 2. Change directory to ibm_help 3. To run the information center, enter: IC_start.sh 4. Open your browser and enter the URL: http://machine_name:8888 where machine_name is the name of your your machine. IC_start.sh does not start your browser automatically. Note: You must be running within the X Window system in order for a web browser to open successfully. To stop the Eclipse help system enter help_cd_end.sh or IC_end.sh depending on the method that you chose to start the help system. You can use the ISO image to burn a CD. The PDF ------- The information center is also provided as PDF (softrt_jre.pdf). The information has not been fully optimized for this format. Late breaking news ------------------- You might see an error message "java.util.zip.ZipException: error in opening zip file" or some other form of IOException when trying to open a file, when using a large number of file descriptors to load different instances of classes. The solution is to increase the provision for file descriptors, using the ulimit command. To find the current limit for open files, use the command: ulimit -a To allow more open files, use the command: ulimit -n 8196 Eclipse 3.3.2 xulrunner compatibility issue There is an incompatibility issue with Eclipse 3.3.2 and Red Hat Enterprise Linux 5.2. If you experience problems launching Eclipse 3.3.2 due to errors in library "/usr/lib/xulrunner-1.9/libxul.so", the solution is to upgrade to Eclipse 3.4. The shared caches used by earlier WebSphere Real Time for Linux Version 2 releases to store precompiled code and classes are not compatible with the caches used by this release of WebSphere Real Time for Linux version 2. You must regenerate the contents of the caches. Shared cache names must not exceed 53 characters. Performance issues on Linux Red Hat MRG kernels: A configuration issue with Red Hat MRG kernels can cause unexpected pauses to application threads when WebSphere Real Time starts with verbose garbage collection enabled. These pauses are not reported in the verbose GC output, but can last several milliseconds, depending on the network configuration. JVMs started from remotely-defined LDAP users are impacted the most, because the name service cache daemon (nscd) is not started, causing network delays. Solve the problem by starting nscd. Follow these steps to check on the status of the nscd service and correct the problem: Check that the nscd daemon is running by typing the command: /sbin/service nscd status If the daemon is not running you see a message similar to: nscd is stopped As root user, start the nscd service with the following command: /sbin/service nscd start As root user, change the startup information for the nscd service with the following command: /sbin/chkconfig nscd on The nscd process is now running, and starts automatically after reboot.