Hosting IBM Product Infocenters on z/os

Transcription

1

2 Hosting IBM Product Infocenters on z/os Many IBM products ship their information as an Eclipse plugin, for example CICS and WebSphere. Customers have asked how they can host the Infocenters on z/os. This document will provide step by step instructions for installing Eclipse on z/os, installing the Infocenter plugins into Eclipse, and starting the Eclipse help system which will serve up the Infocenter information to be accessed by the browser of your choice. Step 1: Create a HFS or zfs with 1000 cylinders primary space and 250 cylinders secondary space. This filesystem will be used to hold the *.zip files that are downloaded from various websites as well as the installed eclipse system, hence it needs to be spacious. For our example, the dataset is created with the name OMVS.ECLIPSE.HFS. Step 2: Create a mount point in the root filesystem to mount the newly allocated filesystem. In our example the new mount point will be created and named eclipse and hung from the /shared directory in the root file system. In our sysplex environment, this will allow easy relocation of the server to any z/os image. We choose this name since the Eclipse package uses eclipse as the top level path. So the idea is to: su to root from my id (i.e., mccox for this exercise) change the root filesystem to R/W mode create the eclipse directory off of /shared change the permissions to 755 and the ownership to the desired userid (i.e. mccox) mount the filesystem remount the root filesystem to R/O exit from root back to your userid, and create a directory in this filesystem (i.e. staging) to hold all the zip files we will move to z/os. Here are the commands that were issued: -> su -> chmount -w. -> mkdir eclipse -> mount -f omvs.eclipse.hfs eclipse -> chown mccox eclipse -> chmod 755 eclipse -> exit -> cd eclipse /eclipse -> ll total 32 drwxr-xr-x 2 MCCOX SYS Dec 21 07:24. drwxr-xr-x 47 OMVSKERN SYS Dec 20 17:32.. /eclipse -> touch mcc.was.here /eclipse IBM Corporation ibm.com/support/techdocs

3 -> ll total 32 drwxr-xr-x 2 MCCOX SYS Dec 21 07:26. -rw-r--r-- 1 MCCOX SYS1 0 Dec 21 07:26 mcc.was.here drwxr-xr-x 47 OMVSKERN SYS Dec 20 17:32.. /eclipse -> df -v. Mounted on Filesystem Avail/Total Files Status /shared/eclipse (OMVS.ECLIPSE.HFS) / Available HFS, Read/Write, Device:2063, ACLS=Y File System Owner : SYSD Automove=Y Client=N Filetag : T=off codeset=0 /eclipse -> cd.. -> df -v. Mounted on Filesystem Avail/Total Files Status / (OEHFS.WSCPLEX.SYSPLEX.ROOT.HFS) / Available HFS, Read/Write, Device:1, ACLS=Y File System Owner : SYSC Automove=Y Client=Y Filetag : T=off codeset=0 -> chmount -r. -> exit -> cd eclipse /eclipse -> mkdir staging /eclipse Not shown, but a good practice, is updating BPXPRMxx in SYS1.PARMLIB to have this file system mounted at the correct mount point following a system restart. Step 3: Now we need to acquire all the parts of interest. First, using the browser of you choice, download Eclipse Classic for 32-bit Windows 1. This download is packaged in.zip file format and contains all the Eclipse parts that are needed and can be easily installed on z/os without any intermediate repackaging. Next, visit the product sites of your choice and download the Infocenter plugin.zip files of your choice. For this example, we obtained the CICS plugins, the IHS plugins, and the WebSphere plugins. All of the files are on my workstation in the following directory: :/Users/mccox/Downloads/mcc_eclipse -> ls -1 com.ibm.websphere.ihs.doc.zip com.ibm.websphere.javadoc.doc.zip com.ibm.websphere.zseries.doc.zip eclipse-sdk win32.zip cics-plugin.zip :/Users/mccox/Downloads/mcc_eclipse -> Step 4: FTP all of the *.zip files to the z/os system in binary format into the /shared/eclipse/staging directory. 1 IBM Corporation ibm.com/support/techdocs

4 The following commands were issued: WP Hosting IBM Product InfoCenters on z/os :/Users/mccox/Downloads/mcc_eclipse -> wscftp 4 Connected to wsc4.wsclab.washington.ibm.com. 220-FTPSERVE IBM FTP CS V1R11 at wsc4, 12:34:32 on Connection will not timeout. Name (wsc4.washington.ibm.com:mccox): mccox 331 Send password please. Password: 230 MCCOX is logged on. Working directory is "/u/mccox". Remote system type is UNIX. ftp> cd /shared/eclipse 250 HFS directory /shared/eclipse is the current working directory ftp> ls 229 Entering Extended Passive Mode ( ) 125 List started OK total 16 -rw-r--r-- 1 MCCOX SYS1 0 Dec 21 12:26 mcc.was.here drwxr-xr-x 2 MCCOX SYS Dec 21 12:34 staging 250 List completed successfully. ftp> cd staging 250 HFS directory /shared/eclipse/staging is the current working directory ftp> prompt Interactive mode off. ftp> bin 200 Representation type is Image ftp> mput *zip local: com.ibm.websphere.ihs.doc.zip remote: com.ibm.websphere.ihs.doc.zip 229 Entering Extended Passive Mode ( ) 125 Storing data set /shared/eclipse/staging/com.ibm.websphere.ihs.doc.zip 100% *************************************************************************************** ****************** 8459 KiB KiB/s 00:00 ETA 250 Transfer completed successfully bytes sent in 00:22 ( KiB/s) local: com.ibm.websphere.javadoc.doc.zip remote: com.ibm.websphere.javadoc.doc.zip 229 Entering Extended Passive Mode ( ) 125 Storing data set /shared/eclipse/staging/com.ibm.websphere.javadoc.doc.zip 100% *************************************************************************************** ****************** 6907 KiB KiB/s 00:00 ETA 250 Transfer completed successfully bytes sent in 00:20 ( KiB/s) local: com.ibm.websphere.zseries.doc.zip remote: com.ibm.websphere.zseries.doc.zip 229 Entering Extended Passive Mode ( ) 125 Storing data set /shared/eclipse/staging/com.ibm.websphere.zseries.doc.zip 100% *************************************************************************************** ****************** KiB KiB/s 00:00 ETA 250 Transfer completed successfully bytes sent in 05:24 ( KiB/s) local: eclipse-sdk win32.zip remote: eclipse-sdk win32.zip 229 Entering Extended Passive Mode ( ) 125 Storing data set /shared/eclipse/staging/eclipse-sdk win32.zip 100% *************************************************************************************** ****************** 170 MiB KiB/s 00:00 ETA 250 Transfer completed successfully bytes sent in 12:00 ( KiB/s) local: cics-plugin.zip remote: cics-plugin.zip 229 Entering Extended Passive Mode ( ) 125 Storing data set /shared/eclipse/staging/cics-plugin.zip IBM Corporation ibm.com/support/techdocs

5 100% *************************************************************************************** ****************** 251 MiB KiB/s 00:00 ETA 250 Transfer completed successfully bytes sent in 17:41 ( KiB/s) ftp> quit 221 Quit command received. Goodbye. :/Users/mccox/Downloads/mcc_eclipse -> Step 5: Now all the parts are safely on z/os in directory /shared/eclipse/staging. The next task is to unjar the Eclipse.zip file (i.e. eclipse-sdk win32.zip). To do this task, position yourself in the /shared directory, and issue the jar -xf command as follows using your userid (since you own this directory): :/u/mccox -> cd /shared -> jar -xf./eclipse/staging/eclipse-sdk win32.zip eclipse Now that the Eclipse runtime is installed on z/os, all we need is a script to start the Infocenter. Using the editor of your choice create a shell script named startinfocenter.sh with the following content in the /shared/eclipse directory: #!/bin/sh JAVA_HOME=/shared/java/J6.0_64 ECLIPSE_HOME=/shared/eclipse PORT=8888 ENCODING_OPTIONS="-Dfile.encoding=ISO Xnoargsconversion " JAVA_OPTIONS="-Xms256m -Xmx512m -Xcompressedrefs" _HELPNAME=`ls $ECLIPSE_DIR/plugins/*help.base_* ` HELP_JAR=`basename $_HELPNAME` $JAVA_HOME/bin/java $ENCODING_OPTIONS $JAVA_OPTIONS \ -cp $ECLIPSE_HOME/plugins/$HELP_JAR \ org.eclipse.help.standalone.infocenter \ -eclipsehome $ECLIPSE_HOME \ -plugincustomization plugins/com.ibm.help.doc/plugin_customization.ini \ -port $PORT \ -command start -noexec The key customization points for this script are: JAVA_HOME, ECLIPSE_HOME, and PORT. You must provide the location for the code components and the port you want the server to open in order to serve up the Infocenter documentation. This script uses Java 6 64-bit, but it is not required. Also this script determines the exact name of the.jar file that will be placed on the classpath (i.e., org.eclipse.help.base_3.5.2.v jar) which could change if you install a different level of Eclipse classic. I previously created this shell script in my home directory and just copied it to the /shared/eclipse directory, setting the file permissions and ownership, and then invoke the script with the following commands: IBM Corporation ibm.com/support/techdocs

6 :/u/mccox -> cd /shared/eclipse /eclipse -> cp ~/startinfocenter.sh. /eclipse -> chmod 755 st*sh /eclipse -> chown mccox st*sh /eclipse ->./startinfocenter.sh At this point, the Eclipse Infocenter server should be taking requests. Pointing the browser of your choice to (where <host_name>:<port> in this example is wsc4.washington.ibm.com:8888 ) should yield: Amazing, Eclipes is running on z/os and serving up the information. Step 6: Terminate the shell script so additional plugins can be installed. We will install all the plugin zip files that we placed into the staging directory by simply unjarring them into the /shared/eclipse/plugins directory with the following commands, after which we will restart the server. IBM Corporation ibm.com/support/techdocs

7 /eclipse/ -> cd plugins /eclipse/plugins -> ls -1../staging/*../staging/cics-plugin.zip../staging/com.ibm.websphere.ihs.doc.zip../staging/com.ibm.websphere.javadoc.doc.zip../staging/com.ibm.websphere.zseries.doc.zip../staging/eclipse-SDK win32.zip /eclipse -> jar -xf../staging/com.ibm.websphere.zseries.doc.zip /eclipse/plugins -> jar -xf../staging/com.ibm.websphere.javadoc.doc.zip /eclipse/plugins -> jar -xf../staging/com.ibm.websphere.ihs.doc.zip /eclipse/plugins -> jar -xf../staging/cics-plugin.zip /eclipse/plugins -> cd.. /eclipse ->./startinfocenter.sh All the plugins for WebSphere for z/os, his and CICS are now installed, and the server has restarted. Point your browser at the URL again, and you will see: Voilà! All of the Infocenters are visible and can be navigated and searched. IBM Corporation ibm.com/support/techdocs

8 Step 7: WP Hosting IBM Product InfoCenters on z/os At this point, we would really like to have a started task to run the Infocenter rather than beef up the shell script. Once again, terminate the startinfocenter.sh script so the port will be available for the started task we will construct and start. We will create a procedure named ECLIPSE in SYS1.PROCLIB, with a configuration member named ECLIPSEZ, also in SYS1.PROCLIB, utilizing the JZOS launcher which ships with the IBM Java 6 SDK on z/os. This task involves creating a STARTED class profile, the PROC and its configuration file, and perhaps a PDSE, if you do not already have one, and copying the JZOS launcher module to the PDSE. As I had already created a PDSE or LIBRARY dataset named MCCOX.JES.LIBRARY I will use it and will leave that step to the reader. The started task will run under my userid, so I will create the RACF STARTED class profile with the following commands: RDEFINE STARTED ECLIPSE.* STDATA(USER(MCCOX) GROUP(SYS1) TRUSTED(NO)) SETROPTS RACLIST(STARTED) REFRESH If you want to use a different userid/group to run the started task under, then customize the above command. In this example we will use the Java 6 64-bit JVM, and thus need to copy the JZOS launcher that comes with that level of the SDK into the PDSE named MCCOX.JES3.LIBRARY. From a USS command prompt, cd to the Java 6 64-bit home directory and copy the JZOS executable to the PDSE by issuing the following: :/u/mccox -> cd /shared/java/j6.0_64 /java/j6.0_64 -> cd mvstools /java/j6.0_64/mvstools -> ls JVMLDM66 samples -> cp -X JVMLDM66 "//'mccox.jes3.library(jvmldm66)'" /java/j6.0_64/mvstools -> Now, we need to create the ECLIPSE procedure in SYS1.PROCLIB, here is the procedure cut and paste. ******************************************************************** Started task PROC for executing the Eclipse Infocenter server with the JZOS launcher. Tailor the proc to your installation: 1.) Replace '<hlq>.jzos.loadlib' with the pdse that contains the JVMLDMxx modules that are needed for the level of Java that is being used. 2.) Provide the input script in the STDENV DD statement. I use a PDS with attributes RECFM=FB,LRECL=80. Make certain that there are no sequence numbers in column If you use ISPF to edit the member set CAPS OFF and NUM OFF on the IBM Corporation ibm.com/support/techdocs

9 command line. Alternatively, point to a file in the HFS. The dataset used to hold the input script must be able to be read by the userid under which the started task runs The userid for the started task must have an OMVS segment, and the maxfileproc for the userid should be sizeable. History 12/21/ created by MCC ******************************************************************** //ECLIPSE PROC REGSIZE='0M', // JAVACLS='org.eclipse.help.standalone.Infocenter', // ARGS='', // LIBRARY='MCCOX.JZOS.LOADLIB', < STEPLIB FOR JZOSVM MODULE // LOGLVL='+T', < DEBUG LVL: +I(INFO) +T(TRC) // REGSIZE='0M', < EXECUTION REGION SIZE // PARMS='', < Fake PARMS foron SIZE // LEPARM='' //IEFPROC EXEC PGM=JVMLDM66,REGION=&REGSIZE, // PARM='&LEPARM/&LOGLVL &JAVACLS &ARGS &PARMS' //STEPLIB DD DSN=&LIBRARY,DISP=SHR //SYSPRINT DD SYSOUT=* < SYSTEM STDOUT //SYSOUT DD SYSOUT=* < SYSTEM STDERR //STDOUT DD SYSOUT=* < JAVA SYSTEM.OUT //STDERR DD SYSOUT=* < JAVA SYSTEM.ERR //CEEDUMP DD SYSOUT=* //ABNLIGNR DD DUMMY This is where the configuation information is located.l //STDENV DD DISP=SHR,DSN=SYS1.PROCLIB(ECLIPSEZ) // PEND And here is the configuration file, ECLIPSEZ again cut and paste. # This is a shell script which configures # any environment variables for the Java JVM. # Variables must be exported to be seen by the launcher. export JAVA_HOME=/shared/java/J6.0_64 export ECLIPSE_HOME=/shared/eclipse export HELP_JAR=org.eclipse.help.base_3.5.2.v jar export PORT=8888 export PATH=/bin:"${JAVA_HOME}"/bin LIBPATH=/lib:/usr/lib:"${JAVA_HOME}"/bin LIBPATH="$LIBPATH":"${JAVA_HOME}"/lib/s390x LIBPATH="$LIBPATH":"${JAVA_HOME}"/lib/s390x/j9vm LIBPATH="$LIBPATH":"${JAVA_HOME}"/bin/classic export LIBPATH="$LIBPATH": CLASSPATH="${JAVA_HOME}/lib/tools.jar" CLASSPATH="$CLASSPATH":"${ECLIPSE_HOME}"/plugins/"${HELP_JAR}" export CLASSPATH="$CLASSPATH" # Set JZOS specific options # Use this variable to specify encoding for DD STDOUT and STDERR IBM Corporation ibm.com/support/techdocs

10 #export JZOS_OUTPUT_ENCODING=Cp1047 WP Hosting IBM Product InfoCenters on z/os # Use this variable to prevent JZOS from handling MVS operator commands #export JZOS_ENABLE_MVS_COMMANDS=false # Use this variable to supply arguments to the main() ARGS="-eclipsehome $ECLIPSE_HOME" ARGS="$ARGS -plugincustomization" ARGS="$ARGS plugins/com.ibm.help.doc/plugin_customization.ini" ARGS="$ARGS -port $PORT" ARGS="$ARGS -command start -noexec" export JZOS_MAIN_ARGS="$ARGS" # Configure JVM options # Note that Eclipse requires default ASCII file.encoding IJO="-Xms256M -Xmx1024M" IJO="$IJO -Xnoargsconversion -Dfile.encoding=ISO8859-1" #IJO="$IJO -showversion" #IJO="$IJO -Xcompressedrefs" #IJO="$IJO -verbose:gc" IJO="$IJO -Xgcpolicy:gencon" #IJO="$IJO -Xverbosegclog:/tmp/eclipse_gclog_%p" export IBM_JAVA_OPTIONS="$IJO" export JAVA_PROPAGATE=NO Once these members are in SYS1.PROCLIB, issue the MVS command: S ECLIPSE and the Infocenter will be available on the designated port. To terminate the started task, issue the MVS cancel command: C ECLIPSE The Eclipse based Infocenter server is pure Java and is 100% zaap eligible. Document Change History Dec 23, 2010 Dec 27, 2010 Original Document Republish with assigned Techdoc number. End of WP IBM Corporation ibm.com/support/techdocs