HP 3000 Web Starter Kit 2 -- installation instructions (draft) ________ Overview The Web Starter Kit brings a couple of components that are meant to be installed on the HP 3000 side. Some of them are optional, others are recommended or even required. This installation instruction assumes that those components are available on a PC (or Mac ;-) from the CD or have been downloaded to a "temporary" disk directory. The files will be copied to the 3000 as part of the installation. Phase 1 of the installation is performed as MANAGER.SYS (for example, to create the WEBKIT account) and phase 2 is performed as DEMO.WEBKIT (for example to install the web server and web pages). The Web Starter Kit should work on MPE/iX 5.5 and later releases. Installing the various components requires a number of manual actions, copying files, uncompressing or unpacking archive files, streaming jobs and the like. To make this a little more convenient, a command file is supplied that performs these steps (feel free to examine it to get an idea about the detailed steps or customize it for specific needs). You can upload the command file and the desired Web Kit components to the 3000 using FTP or Samba/iX or your favorite file transfer method. If you are using WRQ Reflection 1 or Minisoft WS92, it is sufficient to upload the command file only, as it is able to perform the remaining file transfers for you. Find terminal emulator specific sections later in this document. Here is a brief overview of the installation steps. Some of them might be optional on your system, for example, if Java or JDBC have already been installed in the past. Additional notes on the individual steps can be found in a later section of this document. Tasks for MANAGER.SYS logon . fixup posix permissions if on mpe/ix 5.5 . install gnu zip and infozip utils . install jdk 1.1.7 or 1.2.2 or both . add A1703 patch if jdk 1.1.7 installed . create .sl libs from .a libs if missing . install hp jdbc driver and server job . create webkit account and demo user . adjust command file security for phase 2 Tasks for DEMO.WEBKIT logon . install apache 1.3.9 and jserv 1.1 . add web kit specific pages and files . customize the apache jserv config . create the music sample database . copy jdbc driver for the examples . download and install jsdk.jar . download and install swing.jar . start the relevant server jobs . purge the wkinst command file Please notice that the HP 3000 Web Starter Kit is not an HP supported product, contains several pieces of unsupported freeware and is used at your own risk. It worked fine on the systems that I used, but your milage may -of course- vary. While there is no official HP support, you might still be able to find help in the HP3000-L internet forum (also known as comp.sys.hp.mpe in newsgroup land). Even the HP Response Center might be able and willing to help (on best-effort basis), but they would probably have to charge you for time and materials of such a service. ____________________ Using WRQ Reflection Upload the WKINST command file (in ASCII mode) to the 3000, for example into the home directory of MANAGER.SYS (or /tmp in case you prefer that). It will first be run by MANAGER.SYS and then be run by DEMO.WEBKIT (it has two "entry points"). Please upload WKINST.txt with ASCII file transfer (it is in DOS format, i.e. with carriage return plus linefeed as delimiters). Logon as MANAGER.SYS and execute the WKINST command file. It will first prompt you for the PC (or Mac) directory that contains the components to be uploaded (typically the CD drive) and then prompt you for a temporary directory on the 3000 (for example /tmp) that will be used during the file transfers and installation. Then it will prompt you for the different Web Starter Kit components and whether your wish to install them or not. For those components that you select, it will perform the upload from the PC directory to the auxiliary host directory (unless the file is already there from a previous run) and then perform the neccessary unpack/install steps. When done with phase 1, it will prompt you to logon as DEMO.WEBKIT and re-execute the WKINST command file for additional setup activities. The prompt-and-response dialog during phase 2 is similar to phase 1. The passwords for account and user are SECRET and NOT. When phase 2 has been completed successfully, you can purge the WKINST command file and (optionally) clean up the auxiliary host directory that was used during the installation (typically /tmp). Two jobs are used to launch Apache server and JServ engine. For the examples using JDBC to access Image/SQL you will need a third one: :stream /WEBKIT/PUB/lib/httpd.job :stream /WEBKIT/PUB/lib/jserv.job :stream jstrtmon.jdbc.sys To stop the Apache and JServ jobs, you can use the following two jobs. There is a third one for shutting down the JDBC listener: :stream /WEBKIT/PUB/lib/httpd.stop :stream /WEBKIT/PUB/lib/jserv.stop :stream jstopmon.jdbc.sys In case of problems, you might want to examine the /WEBKIT/PUB/logs subdirectory, which contains several log files of Apache and JServ. ___________________ Using Minisoft WS92 Same steps as using WRQ Reflection 1. The WKINST command file tries to automatically detect whether your terminal emulator is Reflection or WS92. _____________________ Using other emulators The installation steps are similar to those decribed in the section "Using WRQ Reflection", however the WKINST command file will not be able to upload the Web Starter Kit components automatically. It will prompt you to transfer the files manually and then press Return to continue. You can upload the WKINST command file to the 3000 using FTP (using either ASCII mode or bytestream/tenex mode) or copy it to a Samba/iX share (which automatically creates a bytestream file). Here are two examples, in case you want to use the DOS window FTP client... ftp> ascii ftp> put WKINST.txt WKINST ftp> quote type L 8 ftp> put WKINST.byt WKINST For uploading the desired Web Starter Kit components from the upload subdirectory on the PC (or Mac), you should use a binary file transfer mode and create bytestream format files on the 3000 side. With Samba/iX this is automatic, with FTP you have to specify appropriate options and commands. Here are two examples for the DOS Window FTP client... ftp> quote type L 8 ftp> put D:\upload\gnuzip.tar.Z /tmp/gnuzip.tar.Z ftp> binary ftp> put D:\upload\gnuzip.tar.Z /tmp/gnuzip.tar.Z;REC=,,B;DISC=123456789 You can either upload all the desired components first and then execute the WKINST command file on the 3000 side, or else upload WKINST, launch it and perform additional uploads as prompted. _______________________________________ Details on Component Installation Steps Tasks during MANAGER.SYS logon . fixup posix permissions if on mpe/ix 5.5 The default permissions of various Posix Shell and Utils were r--r----- instead of r--r--r-- on MPE/iX 5.5 only. This has been corrected as of MPE/iX 6.0 and later releases. So, if you are on 5.5 and have not yet adjusted this, users without SM capability might be unable to access the Posix Shell or Utils successfully. This would include DEMO.WEBKIT who does not have any special capabilities beyond PH (process handling). . install gnu zip and infozip utils These two (different) file compression/packaging tools are used during the installation process as some components come as .gz files and some come as .zip or .jar files. GNU gzip/gunzip is only for compressing or decompressing files, so you will typically see it in conjunction with tar (which combines multiple files into a single "TapeARchive"). The InfoZIP zip/unzip tools (freeware, not shareware) handle both aspects, file packaging and compression. Other well-known tools that handle zip archives are PKZIP or WinZIP (which are not freeware, though). Notice that Java .jar files are compatible with the .zip file format. . install jdk 1.1.7 or 1.2.2 or both You can either install JDK 1.1.7 or JDK 1.2.2 for MPE/iX. Apache JServ and all the example programs that come with the Web Starter Kit should work with both. Different Java versions can coexist on the same system as they reside in different subdirectories of /usr/local/java. On my system, JDK 1.1.7 seems to be more "lightweight" when launching compiler or other Java programs, so I prefer to use that. However, when needing features (or fixes) that come with the JDK 1.2.2 version, I also use that Virtual Machine (or its compiler/libraries). This is a matter of setting the PATH inside the Shell or using SETVAR JAVA_HOME, when using JDK 1.1.7 and JDK 1.2.2 from the MPE command interpreter. . add A1703 patch if jdk 1.1.7 installed There are several slightly different versions of JDK 1.1.7 available. MPE/iX 6.0 PowerPatch 1 brings a flavor of JDK 1.1.7 that is slightly less current than the version on Jazz, so you might want to apply this "patch" that simply replaces two shared libs. One issue that this fix addresses relates to loading Java classes from compressed .jar files. . create .sl libs from .a libs if missing If you already installed other GNU freeware from Jazz (especially the GNUCORE package) then this step might be optional for you. If you are on 6.0 or later releases, the update should already have created these libraries for you. If you are not sure, it shouldn't do any harm to repeat this step. It basically processes .a archive libs in /usr/lib and /lib and generates matching .sl shared libs for them. These shared libs are used by Java (and also other freeware/software). . install hp jdbc driver and server job The HP JDBC Driver for IMAGE/SQL and Allbase/SQL has been delivered on the MPE/iX 6.0 Express-1 SUBSYS media, but it seems that not all customers with IMAGE/SQL or Allbase did receive that (together with 6.0 PowerPatch 1). Some of the Web Starter Kit examples use JDBC to access and IMAGE/SQL sample database. They won't work if you don't have/install this component. . create webkit account and demo user Besides "infrastructure" like Java Developer Kit or JDBC Driver, the main part of the Web Starter Kit resides in a dedicated WEBKIT account and uses a dedicated (non-privileged) DEMO.WEBKIT user, to help you identify it in SHOWJOB, LISTF, REPORT, etc. This also helps in case you decide to cleanup and remove the Web Starter Kit from your system. . adjust command file security for phase 2 The second phase of the installation is performed by DEMO.WEBKIT and needs to access the WKINST command file again. The last step of phase 1 is thus to apply an ACD to open the security a bit. Tasks during DEMO.WEBKIT logon . install apache 1.3.9 and jserv 1.1 This step will install my MPE/iX versions of Apache 1.3.9 and Apache JServ 1.1 inside the WEBKIT account. By having them inside the WEBKIT account, they can peacefully coexist with other Apache or JServ copies on your system. In fact, you can use the files of this step to install Apache 1.3.9 JServ 1.1 on your system for permanent usage (e.g. into a dedicated group in the APACHE account, or into an APACHE.IX group, as I typically do). . add web kit specific pages and files This step will insert Web Starter Kit specific files into the directory tree built by the previous step. This includes web pages, Java sources, compiled Java bytecode, CGI scripts/programs, native programs, etc. You could probably install these files under your regular web server as well, however, some of the demos have "hardcoded" logon names or passwords in config files or web pages, so you would need to make some adjustments. . customize the apache jserv config This step applies a couple of changes to the default Apache and JServ configuration files from a previous installation step. It uses /bin/patch for this purpose, which can roll /bin/diff ouptut into a "base file" to apply the equivalent modifications. . create the music sample database Several of the Web Starter Kit examples show access to TurboIMAGE or IMAGE/SQL (via native server programs or JBDC). This step installs the well known MUSIC sample database and attaches it to the MUSICDBE sample Allbase DBE. See "Getting started with IMAGE/SQL" at docs.hp.com, if you have never heard about the MUSIC/MUSICDBE database. Notice that the step assumes that your system has Image/SQL, not just TurboIMAGE. . copy jdbc driver for the examples During phase 1 you installed the JDBC driver and server job into the SYS account. In this step, we get a local copy of the JDBC driver classes and supply them to the demo applets/servlets/programs that use them. . download and install jsdk.jar The jsdk.jar file comes with the Sun Java Servlet Developer Kit 2.0 and is needed for all Java Servlet examples. The Sun JSDK 2.0 does contain more than this jsdk.jar file (e.g. documentation and examples), however for the Web Starter Kit we only need this single file. . download and install swing.jar The swing.jar file comes with Sun JDK 1.2.x and is also available as a separate download for users of JDK 1.1.x versions. Swing is also called Java Foundation Classes (JFC) and provides enhanced GUI classes compared to the old Abstract Windowing Toolkit (AWT). Some of the Web Starter Kit examples provide a Swing based GUI and thus need the swing.jar file. . start the relevant server jobs There are basically two server jobs for the Web Starter Kit, one to launch the Apache httpd listener/server and the other to launch the Apache JServ servlet engine. In addition to these two, we also launch the JDBC monitor job, as some of the examples show how to use JDBC in a Java applet/servlet/program to access Image/SQL data. . purge the wkinst command file When phase 2 of the installation is completed, you can purge the WKINST command file and also cleanup the temporary directory (typically /tmp). You might want to defer this step until you confirmed that all examples are working properly and that there are no components missing. ________________ Removing Web Kit The Web Starter Kit specific files reside inside the WEBKIT account, so it is typically sufficient to stop the server jobs and purge that account. You should also check if the WKINST command file has been purged already. However, during the MANAGER.SYS phase, you also install several pieces of infrastructure that the Web Starter Kit relies on. Here is a brief list in case you also want to remove those again: . JDBC driver and server job in @.JDBC.SYS . Java Developer Kit in /usr/local/java/jdk1.1.7 or jdk1.2.2 . Shared libraries in /lib/@.sl and /usr/lib/@.sl . GNU gzip/gunzip and InfoZIP zip/unzip in /usr/local/bin Before purging any of the above, you should make sure that these were actually installed by yourself and have not been in place already. Some of the above software pieces comes with MPE/iX 6.0 or 6.5 FOS; JDBC and Java for example, come with 6.0 Express-1 or PowerPatch-1 (and later). _______________________________________________ Appendix A: Components of the Web Starter Kit 2 The following reference shows the various Web Starter Kit components, their original location on the Internet (in case you want to check for a more current version), their relative location on the CD (or where to place them on the PC/Mac when downloading) and their temporary host location during the installation phases. The symbolic !srcdir and !tmpdir represent the drive/directory names that you supply to the WKINST command file when it prompts you during installation phase 1 and 2. inf = Command File to fix 5.5 Posix permissions org = src = !srcdir\upload\fix55sh dst = !tmpdir/fix55sh inf = GNU gzip and gunzip tools for MPE/iX org = src = !srcdir\upload\gnuzip.tar.Z dst = !tmpdir/gnuzip.tar.Z inf = InfoZIP zip and unzip tools for MPE/iX org = src = !srcdir\upload\infozip.tar.Z dst = !tmpdir/infozip.tar.Z inf = Java Developer Kit 1.1.7 for MPE/iX org = http://jazz.external.hp.com/src/java/jdks/JDK117/JDK117.web60.tar src = !srcdir\upload\jdk117.tar dst = !tmpdir/jdk117.tar inf = Java Developer Kit 1.2.2 for MPE/iX org = http://jazz.external.hp.com/src/java/jdks/JDK122/JDK122.web60.tar src = !srcdir\upload\jdk122.tar dst = !tmpdir/jdk122.tar inf = A.17.03(b) patch for JDK 1.1.7/iX org = http://jazz.external.hp.com/src/java/jdks/JDK117/A1703.tar src = !srcdir\upload\fix117.tar dst = !tmpdir/fix117.tar inf = Shell Script to create .sl libs from .a libs org = http://jazz.external.hp.com/src/java/jdks/LIBS.hp3000 src = !srcdir\upload\LIBS.hp3000 dst = !tmpdir/LIBS.hp3000 inf = HP JDBC Driver from MPE/iX 6.0 Express 1 Subsys org = src = !srcdir\upload\jdbc60.tar dst = !tmpdir/jdbc60.tar inf = Apache 1.3.9 with JServ 1.1 for MPE/iX org = http://www.editcorp.com/Personal/Lars_Appel/ajs/ajs-139-11-mod.tar.gz src = !srcdir\upload\ajs-139-11.tar.gz dst = !tmpdir/ajs-139-11.tar.gz inf = HP 3000 Web Kit 2 specific docs and examples org = src = !srcdir\upload\webkit2.tar.Z dst = !tmpdir/webkit2.tar.Z inf = Sun Java Servlet Developer Kit 2.0 classes org = http://java.sun.com/products/servlet/download.html src = !srcfile (extracted from jsdk20-win32.exe) dst = !tmpdir/jsdk.jar inf = Sun Java Foundation Classes (Swing) 1.1.x org = http://java.sun.com/products/jfc/download.html src = !srcfile (extracted from ?????.exe) dst = !tmpdir/swingall.jar Please notice that all files should be transfered in binary mode and ideally be created as bytestream files on the HP 3000 side.