IBM WebSphere Real Time on AIX 32-bit version 2 SR 2 =============================================================================== For late breaking news, please see the end of this document. Introduction =============================================================================== IBM WebSphere Real Time on AIX 32-bit is an extension to the IBM Java Runtime Environment and Software Development Kit with Metronome garbage collection. 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. 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. Updating an existing Beta Installation =============================================================================== An interim fix is available for the beta code, to fix problems that were discovered during the beta program. Before installing the interim fix, a number of configuration changes are necessary to restore the original settings. Follow these instructions to remove the changes that were made to access the realtime clock, and remove the workaround that changed the values for syscorepath. Note: refers to the non-root user who was granted the security privileges. 1. Edit the /etc/security/privcmds file and remove the following lines that were appended to the original file: /bluebird//bin/platform/aix/bash: authprivs = realtime_auth=PV_PROC_RTCLK accessauths = ALLOW_ALL inheritprivs = PV_PROC_RTCLK secflags = FSF_EPS /bluebird//bin/platform/aix/tcsh: authprivs = realtime_auth=PV_PROC_RTCLK accessauths = ALLOW_ALL inheritprivs = PV_PROC_RTCLK secflags = FSF_EPS /usr/bin/sh: authprivs = realtime_auth=PV_PROC_RTCLK accessauths = ALLOW_ALL inheritprivs = PV_PROC_RTCLK secflags = FSF_EPS /usr/bin/ksh: authprivs = realtime_auth=PV_PROC_RTCLK accessauths = ALLOW_ALL inheritprivs = PV_PROC_RTCLK secflags = FSF_EPS /usr/bin/csh: authprivs = realtime_auth=PV_PROC_RTCLK accessauths = ALLOW_ALL inheritprivs = PV_PROC_RTCLK secflags = FSF_EPS 2. Edit the /etc/security/user file, and search for the non-root user account. Remove the following line: default_roles = realtime_role The section containing this line will be similar to the following: : admin = false capabilities = CAP_NUMA_ATTACH,CAP_PROPAGATE default_roles = realtime_role Note: is the non-root user account. 3. Edit the /etc/security/user.roles file and remove the following line: : roles = realtime_role Note: is the non-root user account. 4. Rebuild the security tables by running the command setkst 5. Remove the syscorepath workaround that was applied by typing the following command: syscorepath -c 6. Proceed to the section "Installing a system for the first time" later in this document. Installing a system for the first time =============================================================================== Note: These instructions assume you are working with the runtime environment file or compressed SDK package file. In the steps outlined in this section, the compressed file is called: ibm-wrt32-2.0.aix.tar.gz The file you download might have a different name, particularly if you are accessing Passport Advantage. 1. Choose a suitable installation directory on your system, such as $HOME/ibm-srt-sdk 2. Copy the installation file to your chosen directory: cp ibm-wrt32-2.0.aix.tar.gz $HOME/ibm-srt-sdk 3. Change to the $HOME/ibm-srt-sdk directory: cd $HOME/ibm-srt-sdk 4. Extract the tar file using the following command: gunzip ibm-wrt32-2.0.aix.tar.gz 5. Extract the filesets from the tar file using the following command: tar xvf ibm-wrt32-2.0.aix.tar 6. Use the AIX installp command to install WebSphere Real Time for AIX on 64-bit POWER. 7. When the installation process is completed, you must change the user account to allow access to high resolution timers. Run the following command as root user: chuser "capabilities=CAP_NUMA_ATTACH,CAP_PROPAGATE" where is the non-root AIX user account. Note: This change needs to made to the user account only once. However, the user must log out and log back in for the change to take effect. The following step must be completed in every shell before starting Java: 1. Set the AIXTHREAD_HRT environment variable to true. This environment variable allows a process to use high resolution time-outs with clock_nanosleep(). You must set this environment variable each time the process is started, using: AIXTHREAD_HRT=true This setting can be added to a user's .profile file, so that it is set each time the user logs in. Do this by adding the line: export AIXTHREAD_HRT=true The command "java -Xgcpolicy:metronome -version" displays a result similar to the following if the install was successful: java version "1.6.0" Java(TM) SE Runtime Environment (build pap3260srtsr2-20090630_01(SR2)) IBM J9 VM (build 2.5, JRE 1.6.0 IBM J9 real-time 2.5 AIX ppc-32 jvmap32srt60sr2-20090629_38050 (JIT enabled, AOT enabled) J9VM - 20090629_038050 JIT - r10_20090625_2031 GC - 20090616_AA) JCL - 20090624_01 The specific version information in this example might be different from those shown. Documentation =============================================================================== In the docs directory, you will find readmeFirst.aix32.txt, rt_quick_start.aix32.pdf, com.ibm.softrt.aix32.doc.jar, com.ibm.softrt.aix32.doc.zip, and softrt_aix32.pdf files. - readmeFirst.aix32.txt is this file. - rt_quick_start.aix32.pdf is the IBM WebSphere Quick Start Guide for use with the Adobe Acrobat Reader. - com.ibm.softrt.aix32.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.aix32.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_aix32.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.aix32.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.1.1 and earlier: Extract the files from com.ibm.softrt.aix32.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. For Eclipse Help System versions 3.1.2 or more recent: Copy com.ibm.softrt.aix32.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_aix32.pdf). The information has not been fully optimized for this format. Late breaking news ------------------- The shared caches used by other IBM Java or WebSphere Real Time releases are not compatible with the caches used by this release of WebSphere Real Time on AIX 32-bit. Shared caches cannot be shared between WebSphere Real Time on AIX 32-bit and WebSphere Real Time on AIX 64-bit. You must regenerate the contents of the caches. Shared cache names must not exceed 53 characters.