README File for DB2 WWW Connection Version 1 for VM

The instructions on this page cause the following to be installed on your VM system:

This page contains the following sections:

Requirements

You need the following to install DB2 WWW for VM:

Downloading DB2 WWW for VM

  1. You will use the VMARC compression utility to unpack the software you download. If you need the VMARC MODULE, follow the instructions on the http://www.vm.ibm.com/download page to obtain it.
  2. Download the compressed file containing DB2 WWW Connection for VM from the IBM web site to your PC. This compressed file contains multiple files that you must unpack.
  3. LOGON to the web server virtual machine and bring down the server to the CMS READY; prompt.
  4. Create an empty temporary work minidisk or directory at least 750 4Kb blocks in size. Access the temporary work area as the A filemode.
  5. Upload the compressed file from your PC to the A filemode in BINARY.
  6. Run the compressed file through this pipeline to restore a fixed record format:
  7. PIPE < DB2WWW VMARC A ¦ fblock 80 00 ¦ > DB2WWW VMARC A F 80

    This pipeline produces a file named DB2WWW VMARC.

  8. Unpack DB2WWW VMARC using the VMARC utility:
  9. VMARC UNPK DB2WWW VMARC A

Installing DB2 WWW for VM

The instructions in this section make these assumptions about the file system structure on your server:

If your system's file structure is different, you will need to change the instructions to match your environment.

  1. Copy files from the temporary minidisk or directory to your web server:
  2. Which files to move where is specific to the way your web server is configured. Possible configurations follow:

    If You Are Using VM:Webserver

    1. Copy all files with filetypes HTM, GIF, and VIWEXEC from the temporary minidisk or directory to the current minidisk or SFS directory defined by the CONFIG PORT command. (Note: If you are using a VM:Webserver worker, copy DB2WWW WRKEXEC instead of DB2WWW VIWEXEC.)
    2. Add these lines to the VMWEBSRV DIRMAP file on that minidisk or SFS directory:

      DIR cgi-bin CGIBIN
      DIR images IMAGES

      Use those lines to create VMWEBSRV DIRMAP if it doesn't exist.
    3. Create the IMAGES DIRMAP file with these contents:

      FILE *.gif      = GIF
    4. Create the CGIBIN DIRMAP file with these contents:

      FILE DB2WWW     = VIWEXEC
      FILE DB2WWW.EXE = VIWEXEC

    If You Are Using Webshare

    1. Copy all files with filetypes HTM, GIF, or CGI from the temporary minidisk or directory to the web root minidisk or SFS directory.
    2. In the WEBSHARE FILELIST file, add a line for each HTM file copied from the temporary area. Specify the filename, filetype, and filemode.
    3. In the WEBSHARE FILELIST file, add a line for the IMAGES directory. It has this form: IMAGES * *
    4. Create an IMAGES FILELIST file containing a line for each GIF file copied from the temporary area. Specify the filename, filetype, and filemode.
    5. Add this line to the HTBIN FILELIST file to serve the DB2WWW REXX CGI program:

      DB2WWW *CGI * db2www.exe

  3. Copy the files with filetype D2W to a minidisk present in the CMS search order, or to an SFS directory. If SFS is used, insure that the web server machine or VM:Webserver worker machine has read access to the D2W files. An SFS directory holding the D2W files does not have to be accessed in the server search order. The location of the D2W files is specified as a parameter in the DB2WWW INI file as described below.
  4. Copy the files listed below to your web server machine. Place them on any minidisk or directory present in the CMS search order.
  5. If VM:Webserver worker machines are to be used, copy the files listed above to your VM:Webserver worker machine. Place them on any minidisk or directory present in the CMS search order.

  6. Modify the DB2WWW INI file so that the MACRO_PATH line reflects the location of the D2W macro files. Place the INI file on any minidisk or directory present in the CMS search order. If a VM:Webserver worker machine is used, the DB2WWW INI file must be present in that machine's search order.

    If the macro files are on a specific minidisk or directory:
    MACRO_PATH cms:filemode (Example: MACRO_PATH cms:B)

    If the macro files are in CMS search order:
    MACRO_PATH cms:* (Example: MACRO_PATH cms:*)

    If the macro files are on an accessed or unaccessed SFS directory:
    MACRO_PATH sf:dirid (Example: MACRO_PATH sf:VMSYSU:VMUSER.TEST.WEBROOT)
  7. Place these commands in the PROFILE EXEC of the web server machine so that they are issued when the web server virtual machine is initialized:

    'CPIPE'             /* Initialize the CPIPE pipeline stage */
    'CP LINK ....'      /* Link to the SQL PRODUCTION disk */
    'ACCESS ....'       /* Access the SQL PRODUCTION disk (or SFS directory) */
    'SET LANGUAGE ( USER ADD ARI'  /* Associate SQL message repository */
    'EXEC SQLINIT DBNAME(mydb)'    /* Initialize the SQL connection */
                                   /* with default server mydb */

    By convention, the PRODUCTION disk is linked at virtual address 195, and is ACCESSed as filemode Q. Your conventions may be different.

    If a VM:Webserver worker machine is used, place the same commands in that machine's PROFILE EXEC.
  8. If the DB2/VM database is not available when the web server is initialized, simply re-issue the SQLINIT command in the web server machine, when the DB2/VM database machine does become available.
  9. The demonstration programs contain code that assumes your system's directory structure follows the model described above. If your environment is different, you must modify the URL paths in the sample HTM and D2W files to reflect your system's directory structure.

Optimizing DB2 WWW Performance VM

The DB2WWW MODULE runs at least twice for every DB2WWW transaction. The overhead of bringing the MODULE file into virtual memory and establishing a C run-time execution environment for each execution can be excessive.

However, if sufficient virtual memory is available in the web server virtual machine, the program modules can be preloaded in such a way that the execution overhead is minimized. To preload the program modules, place these commands in the PROFILE EXEC of the web server machine:

'NUCXLOAD DB2WWW ( PERM'

'NUCXLOAD DB2WWWA ( PERM'

These commands ensure that the modules stay resident in the server address space and the C execution environment is retained across module invocations.

Installing the DB2 WWW Database Package

  1. ACCESS the SQL PRODUCTION minidisk or SFS directory and issue the SQLINIT command using the DBNAME parameter for the database to be used by DB2WWW.
  2. Install the supplied DB2WWW PACKAGE file by modifying the DBSETUP SYSIN file to set the correct SQLDBA password and running the DBSETUP EXEC. Change the SQLDBAPW token on the first line of the DBSETUP SYSIN file to the correct password for your environment.

    Running this EXEC creates two SQL userids. The first, D2WUSER, is used to access the database from the sample programs. The second, D2WOWNER, owns the demonstration program tables and the DB2WWW package.
  3. Repeat this step for every database to be used by a DB2WWW application.

Installing a Sample DB2 WWW Database

  1. Create the DB2WWW demonstration program database tables by running TABCREAT EXEC. Access to the tables is granted to PUBLIC.
  2. Load the DB2SQL demonstration table data by running TABLOAD EXEC.
  3. ACCESS the minidisk or directory where you loaded the D2W files. Set the database variable in the sample programs by running the
    SETDBNAM filemode dbname
    command, where filemode contains the installed D2W files and dbname contains the name of the database.
  4. Re-IPL CMS in the web server virtual machine to execute the new lines in the PROFILE EXEC and start up the web server system.
  5. If running VM:Webserver, issue this command to define the VIWEXEC filetype that the DB2WWW REXX CGI program uses:

    CONFIG FILETYPE ADD VIWEXEC CGI ENVIRONMENT SVMMACRO AUTHHEADERPASSED YES

Post-Installation

  1. Discard the temporary minidisk or SFS directory which was used during the installation process.
  2. Run the demonstration programs by pointing your web browser at URL
    http://your_server/celdemo.htm.
  3. Read the Application Developer's Guide by pointing your web browser at URL
    http://your_server/db2wdoc.htm.